



Run-Time  Library  (RTL)  :

Reference  guide.

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

                                                                                   Free Pascal version 3.0.0:

                                                                          Reference guide for RTL units.

                                                                                         Document version 2.6

                                                                                                   November 2015



Micha"el Van Canneyt
______________________________________________________________________________________________________________________________




Contents



     0.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  112


1    Reference for unit 'BaseUnix'                                                                                       113

     1.1      Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  113

     1.2      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  113

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

             1.3.1        Constants        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  113

             1.3.2        Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  137

     1.4      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  155

             1.4.1        CreateShellArgV            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  155

             1.4.2        FpAccess      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  155

             1.4.3        FpAlarm       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  156

             1.4.4        FpChdir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  157

             1.4.5        FpChmod          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  157

             1.4.6        FpChown       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  159

             1.4.7        FpClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  160

             1.4.8        FpClosedir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  160

             1.4.9        FpDup       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  160

             1.4.10       FpDup2        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  161

             1.4.11       FpExecv       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  162

             1.4.12       FpExecve         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  163

             1.4.13       FpExit      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  164

             1.4.14       FpFcntl       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  164

             1.4.15       fpfdfillset   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  165

             1.4.16       fpFD_CLR         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  165

             1.4.17       fpFD_ISSET         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  166

             1.4.18       fpFD_SET         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  166

             1.4.19       fpFD_ZERO          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  166

             1.4.20       FpFork      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  166

             1.4.21       FPFStat       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  167

             1.4.22       FpFtruncate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  168



                                                              1

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             1.4.23       FpGetcwd        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  168

             1.4.24       FpGetegid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  168

             1.4.25       FpGetEnv        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  169

             1.4.26       fpgeterrno      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  169

             1.4.27       FpGeteuid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  170

             1.4.28       FpGetgid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  170

             1.4.29       FpGetgroups       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  171

             1.4.30       FpGetpgrp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  171

             1.4.31       FpGetpid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  171

             1.4.32       FpGetppid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  172

             1.4.33       fpGetPriority        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  172

             1.4.34       FpGetRLimit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  172

             1.4.35       FpGetsid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  173

             1.4.36       FpGetuid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  173

             1.4.37       FpIOCtl       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  174

             1.4.38       FpKill     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  174

             1.4.39       FpLink     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  175

             1.4.40       FpLseek       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  176

             1.4.41       fpLstat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  176

             1.4.42       FpMkdir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  178

             1.4.43       FpMkfifo      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  178

             1.4.44       Fpmmap        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  178

             1.4.45       Fpmunmap        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  180

             1.4.46       FpNanoSleep       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  180

             1.4.47       fpNice     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  181

             1.4.48       FpOpen        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  182

             1.4.49       FpOpendir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  183

             1.4.50       FpPause       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  184

             1.4.51       FpPipe     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  184

             1.4.52       FpPoll     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  185

             1.4.53       FppRead       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  186

             1.4.54       FppWrite      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  186

             1.4.55       FpRead     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  186

             1.4.56       FpReaddir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  187

             1.4.57       fpReadLink        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  188

             1.4.58       FpReadV       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  189

             1.4.59       FpRename        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  189

             1.4.60       FpRmdir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  190

             1.4.61       fpSelect   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  190

             1.4.62       fpseterrno      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  192



                                                                  2

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             1.4.63       FpSetgid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  192

             1.4.64       fpSetPriority     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  192

             1.4.65       FpSetRLimit       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  193

             1.4.66       FpSetsid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  193

             1.4.67       fpsettimeofday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  193

             1.4.68       FpSetuid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  194

             1.4.69       FPSigaction       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  194

             1.4.70       FpSigAddSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  195

             1.4.71       FpSigDelSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  195

             1.4.72       FpsigEmptySet          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  196

             1.4.73       FpSigFillSet      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  196

             1.4.74       FpSigIsMember          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  196

             1.4.75       FpSignal      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  197

             1.4.76       FpSigPending         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  197

             1.4.77       FpSigProcMask          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  198

             1.4.78       FpSigSuspend         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  198

             1.4.79       FpSigTimedWait            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  198

             1.4.80       FpSleep       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  199

             1.4.81       FpStat     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  199

             1.4.82       fpSymlink       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  200

             1.4.83       fpS_ISBLK       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  202

             1.4.84       fpS_ISCHR       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  202

             1.4.85       fpS_ISDIR       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  202

             1.4.86       fpS_ISFIFO        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  202

             1.4.87       fpS_ISLNK       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  203

             1.4.88       fpS_ISREG       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  203

             1.4.89       fpS_ISSOCK        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  204

             1.4.90       fptime     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  204

             1.4.91       FpTimes       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  204

             1.4.92       FpUmask       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  205

             1.4.93       FpUname         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  205

             1.4.94       FpUnlink      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  205

             1.4.95       FpUtime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  206

             1.4.96       FpWait     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  207

             1.4.97       FpWaitPid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  207

             1.4.98       FpWrite       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  208

             1.4.99       FpWriteV        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  208

             1.4.100      FreeShellArgV        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  209

             1.4.101      wexitStatus       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  209

             1.4.102      wifexited     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  209



                                                                  3

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             1.4.103      wifsignaled     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  209

             1.4.104      wstopsig      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  210

             1.4.105      wtermsig      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  210


2    Reference for unit 'character'                                                                                     211

    2.1      Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  211

    2.2      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  211

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

             2.3.1        Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  211

    2.4      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  213

             2.4.1        ConvertFromUtf32            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  213

             2.4.2        ConvertToUtf32         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  213

             2.4.3        GetNumericValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  213

             2.4.4        GetUnicodeCategory             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  214

             2.4.5        IsControl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  214

             2.4.6        IsDigit    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  214

             2.4.7        IsHighSurrogate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  214

             2.4.8        IsLetter   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  215

             2.4.9        IsLetterOrDigit        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  215

             2.4.10       IsLower    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  215

             2.4.11       IsLowSurrogate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  215

             2.4.12       IsNumber        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  216

             2.4.13       IsPunctuation        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  216

             2.4.14       IsSeparator     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  216

             2.4.15       IsSurrogate     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  216

             2.4.16       IsSurrogatePair        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  217

             2.4.17       IsSymbol      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  217

             2.4.18       IsUpper       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  217

             2.4.19       IsWhiteSpace         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  217

             2.4.20       ToLower       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  218

             2.4.21       ToUpper       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  218

    2.5      TCharacter       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  218

             2.5.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  218

             2.5.2        Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  219

             2.5.3        TCharacter.Create           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  219

             2.5.4        TCharacter.ConvertFromUtf32                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 219

             2.5.5        TCharacter.ConvertToUtf32               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 220

             2.5.6        TCharacter.GetNumericValue                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 220

             2.5.7        TCharacter.GetUnicodeCategory                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *221

             2.5.8        TCharacter.IsControl           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  221



                                                                  4

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.5.9        TCharacter.IsDigit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  221

             2.5.10       TCharacter.IsSurrogate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  222

             2.5.11       TCharacter.IsHighSurrogate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 222

             2.5.12       TCharacter.IsLowSurrogate               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 223

             2.5.13       TCharacter.IsSurrogatePair              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 223

             2.5.14       TCharacter.IsLetter         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  223

             2.5.15       TCharacter.IsLetterOrDigit              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 224

             2.5.16       TCharacter.IsLower          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  224

             2.5.17       TCharacter.IsNumber            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  225

             2.5.18       TCharacter.IsPunctuation              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  225

             2.5.19       TCharacter.IsSeparator           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  225

             2.5.20       TCharacter.IsSymbol            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  226

             2.5.21       TCharacter.IsUpper          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  226

             2.5.22       TCharacter.IsWhiteSpace               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  227

             2.5.23       TCharacter.ToLower             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  227

             2.5.24       TCharacter.ToUpper             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  227


3    Reference for unit 'charset'                                                                                       229

    3.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  229

    3.2      Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  229

             3.2.1        Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  229

             3.2.2        Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  229

    3.3      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  231

             3.3.1        getascii   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  231

             3.3.2        getmap     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  231

             3.3.3        getunicode      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  232

             3.3.4        loadbinaryunicodemapping              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  232

             3.3.5        loadunicodemapping             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  233

             3.3.6        mappingavailable          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  233

             3.3.7        registerbinarymapping            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  233

             3.3.8        registermapping        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  233


4    Reference for unit 'Classes'                                                                                       235

    4.1      Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  235

    4.2      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  235

    4.3      Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  235

             4.3.1        Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  235

             4.3.2        Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  238

             4.3.3        Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  251

    4.4      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  252

             4.4.1        ActivateClassGroup          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  252



                                                                  5

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.4.2        BeginGlobalLoading          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  252

             4.4.3        BinToHex        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  252

             4.4.4        Bounds     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  253

             4.4.5        CheckSynchronize          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  253

             4.4.6        ClassGroupOf         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  253

             4.4.7        CollectionsEqual       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  254

             4.4.8        EndGlobalLoading            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  254

             4.4.9        ExtractStrings       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  254

             4.4.10       FindClass       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  254

             4.4.11       FindGlobalComponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  255

             4.4.12       FindIdentToInt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  255

             4.4.13       FindIntToIdent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  255

             4.4.14       FindNestedComponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  255

             4.4.15       GetClass      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  256

             4.4.16       GetFixupInstanceNames               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  256

             4.4.17       GetFixupReferenceNames                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  256

             4.4.18       GlobalFixupReferences            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  256

             4.4.19       GroupDescendentsWith             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  257

             4.4.20       HexToBin        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  257

             4.4.21       IdentToInt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  257

             4.4.22       InitComponentRes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  258

             4.4.23       InitInheritedComponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  258

             4.4.24       IntToIdent      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  258

             4.4.25       InvalidPoint      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  258

             4.4.26       LineStart     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  259

             4.4.27       NotifyGlobalLoading            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  259

             4.4.28       ObjectBinaryToText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  259

             4.4.29       ObjectResourceToText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  259

             4.4.30       ObjectTextToBinary             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  259

             4.4.31       ObjectTextToResource             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  260

             4.4.32       Point    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  260

             4.4.33       PointsEqual       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  260

             4.4.34       ReadComponentRes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  260

             4.4.35       ReadComponentResEx               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  261

             4.4.36       ReadComponentResFile                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  261

             4.4.37       Rect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  261

             4.4.38       RedirectFixupReferences             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  261

             4.4.39       RegisterClass        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  262

             4.4.40       RegisterClassAlias        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  262

             4.4.41       RegisterClasses        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  262



                                                                  6

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.4.42       RegisterComponents             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  263

             4.4.43       RegisterFindGlobalComponentProc                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *63

             4.4.44       RegisterInitComponentHandler                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *263

             4.4.45       RegisterIntegerConsts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  263

             4.4.46       RegisterNoIcon         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  264

             4.4.47       RegisterNonActiveX             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  264

             4.4.48       RemoveFixupReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  264

             4.4.49       RemoveFixups         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  265

             4.4.50       SmallPoint      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  265

             4.4.51       StartClassGroup        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  265

             4.4.52       UnRegisterClass        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  265

             4.4.53       UnRegisterClasses         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  266

             4.4.54       UnregisterFindGlobalComponentProc                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *66

             4.4.55       UnRegisterModuleClasses               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  266

             4.4.56       WriteComponentResFile               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  266

    4.5      EBitsError       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  267

             4.5.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  267

    4.6      EClassNotFound          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  267

             4.6.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  267

    4.7      EComponentError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  267

             4.7.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  267

    4.8      EFCreateError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  267

             4.8.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  267

    4.9      EFilerError      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  267

             4.9.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  267

    4.10     EFOpenError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  268

             4.10.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  268

    4.11     EInvalidImage         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  268

             4.11.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  268

    4.12     EInvalidOperation          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  268

             4.12.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  268

    4.13     EListError       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  268

             4.13.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  268

    4.14     EMethodNotFound              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  268

             4.14.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  268

    4.15     EObserver        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  269

             4.15.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  269

    4.16     EOutOfResources            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  269

             4.16.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  269

    4.17     EParserError       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  269



                                                                  7

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.17.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  269

    4.18     EReadError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  269

             4.18.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  269

    4.19     EResNotFound          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  269

             4.19.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  269

    4.20     EStreamError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  269

             4.20.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  269

    4.21     EStringListError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  270

             4.21.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  270

    4.22     EThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  270

             4.22.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  270

    4.23     EThreadDestroyCalled              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  270

             4.23.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  270

    4.24     EThreadExternalException               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  270

             4.24.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  270

    4.25     EWriteError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  271

             4.25.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  271

    4.26     IDesignerNotify         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  271

             4.26.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  271

             4.26.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  271

             4.26.3       IDesignerNotify.Modified            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  271

             4.26.4       IDesignerNotify.Notification            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 271

    4.27     IFPObserved        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  272

             4.27.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  272

             4.27.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  272

             4.27.3       IFPObserved.FPOAttachObserver                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *272

             4.27.4       IFPObserved.FPODetachObserver                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *272

             4.27.5       IFPObserved.FPONotifyObservers                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *73

    4.28     IFPObserver        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  273

             4.28.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  273

             4.28.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  273

             4.28.3       IFPObserver.FPOObservedChanged                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *73

    4.29     IInterfaceComponentReference                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  274

             4.29.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  274

             4.29.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  274

             4.29.3       IInterfaceComponentReference.GetComponent                        .  .  .  .  .  .  .  .  .  .  .  .  274

    4.30     IInterfaceList     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  274

             4.30.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  274

             4.30.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  275

             4.30.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  275



                                                                  8

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.30.4       IInterfaceList.Get        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  275

             4.30.5       IInterfaceList.GetCapacity            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  275

             4.30.6       IInterfaceList.GetCount             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  276

             4.30.7       IInterfaceList.Put        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  276

             4.30.8       IInterfaceList.SetCapacity            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  276

             4.30.9       IInterfaceList.SetCount          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  276

             4.30.10      IInterfaceList.Clear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  277

             4.30.11      IInterfaceList.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  277

             4.30.12      IInterfaceList.Exchange          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  277

             4.30.13      IInterfaceList.First        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  277

             4.30.14      IInterfaceList.IndexOf           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  278

             4.30.15      IInterfaceList.Add        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  278

             4.30.16      IInterfaceList.Insert       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  278

             4.30.17      IInterfaceList.Last       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  278

             4.30.18      IInterfaceList.Remove          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  278

             4.30.19      IInterfaceList.Lock         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  279

             4.30.20      IInterfaceList.Unlock          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  279

             4.30.21      IInterfaceList.Capacity          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  279

             4.30.22      IInterfaceList.Count        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  279

             4.30.23      IInterfaceList.Items        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  280

    4.31     IStreamPersist        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  280

             4.31.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  280

             4.31.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  280

             4.31.3       IStreamPersist.LoadFromStream                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *280

             4.31.4       IStreamPersist.SaveToStream                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 280

    4.32     IStringsAdapter         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  281

             4.32.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  281

             4.32.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  281

             4.32.3       IStringsAdapter.ReferenceStrings                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *281

             4.32.4       IStringsAdapter.ReleaseStrings               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *281

    4.33     IVCLComObject           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  281

             4.33.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  281

             4.33.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  281

             4.33.3       IVCLComObject.GetTypeInfoCount                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *82

             4.33.4       IVCLComObject.GetTypeInfo                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 282

             4.33.5       IVCLComObject.GetIDsOfNames                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *282

             4.33.6       IVCLComObject.Invoke                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  282

             4.33.7       IVCLComObject.SafeCallException                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *83

             4.33.8       IVCLComObject.FreeOnRelease                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *283

    4.34     TAbstractObjectReader             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  283



                                                                  9

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.34.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  283

             4.34.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  284

             4.34.3       TAbstractObjectReader.NextValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *84

             4.34.4       TAbstractObjectReader.ReadValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *84

             4.34.5       TAbstractObjectReader.BeginRootComponent                         .  .  .  .  .  .  .  .  .  .  .  .  285

             4.34.6       TAbstractObjectReader.BeginComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  285

             4.34.7       TAbstractObjectReader.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  285

             4.34.8       TAbstractObjectReader.Read                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 285

             4.34.9       TAbstractObjectReader.ReadBinary                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *86

             4.34.10      TAbstractObjectReader.ReadFloat                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *86

             4.34.11      TAbstractObjectReader.ReadSingle                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *86

             4.34.12      TAbstractObjectReader.ReadDate                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *287

             4.34.13      TAbstractObjectReader.ReadCurrency                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  287

             4.34.14      TAbstractObjectReader.ReadIdent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *87

             4.34.15      TAbstractObjectReader.ReadInt8                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *288

             4.34.16      TAbstractObjectReader.ReadInt16                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *88

             4.34.17      TAbstractObjectReader.ReadInt32                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *88

             4.34.18      TAbstractObjectReader.ReadInt64                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *89

             4.34.19      TAbstractObjectReader.ReadSet                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *289

             4.34.20      TAbstractObjectReader.ReadSignature                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  289

             4.34.21      TAbstractObjectReader.ReadStr                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *290

             4.34.22      TAbstractObjectReader.ReadString                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *90

             4.34.23      TAbstractObjectReader.ReadWideString                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  290

             4.34.24      TAbstractObjectReader.ReadUnicodeString                       .  .  .  .  .  .  .  .  .  .  .  .  .  290

             4.34.25      TAbstractObjectReader.SkipComponent                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  291

             4.34.26      TAbstractObjectReader.SkipValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *91

    4.35     TAbstractObjectWriter             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  291

             4.35.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  291

             4.35.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  292

             4.35.3       TAbstractObjectWriter.BeginCollection                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  292

             4.35.4       TAbstractObjectWriter.BeginComponent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  292

             4.35.5       TAbstractObjectWriter.WriteSignature                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  292

             4.35.6       TAbstractObjectWriter.BeginList                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *293

             4.35.7       TAbstractObjectWriter.EndList                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *293

             4.35.8       TAbstractObjectWriter.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  293

             4.35.9       TAbstractObjectWriter.EndProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *93

             4.35.10      TAbstractObjectWriter.Write                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 293

             4.35.11      TAbstractObjectWriter.WriteBinary                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *94

             4.35.12      TAbstractObjectWriter.WriteBoolean                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *94

             4.35.13      TAbstractObjectWriter.WriteFloat                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *94



                                                                 10

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.35.14      TAbstractObjectWriter.WriteSingle                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *94

             4.35.15      TAbstractObjectWriter.WriteDate                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *294

             4.35.16      TAbstractObjectWriter.WriteCurrency                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  295

             4.35.17      TAbstractObjectWriter.WriteIdent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *95

             4.35.18      TAbstractObjectWriter.WriteInteger                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *95

             4.35.19      TAbstractObjectWriter.WriteUInt64                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *95

             4.35.20      TAbstractObjectWriter.WriteVariant                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *95

             4.35.21      TAbstractObjectWriter.WriteMethodName                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  296

             4.35.22      TAbstractObjectWriter.WriteSet                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *296

             4.35.23      TAbstractObjectWriter.WriteString                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *96

             4.35.24      TAbstractObjectWriter.WriteWideString                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  296

             4.35.25      TAbstractObjectWriter.WriteUnicodeString                      .  .  .  .  .  .  .  .  .  .  .  .  .  296

    4.36     TBasicAction          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  297

             4.36.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  297

             4.36.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  297

             4.36.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  297

             4.36.4       TBasicAction.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  297

             4.36.5       TBasicAction.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  297

             4.36.6       TBasicAction.HandlesTarget              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 298

             4.36.7       TBasicAction.UpdateTarget               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 298

             4.36.8       TBasicAction.ExecuteTarget              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 298

             4.36.9       TBasicAction.Execute             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  299

             4.36.10      TBasicAction.RegisterChanges               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 299

             4.36.11      TBasicAction.UnRegisterChanges                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *299

             4.36.12      TBasicAction.Update            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  299

             4.36.13      TBasicAction.ActionComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *300

             4.36.14      TBasicAction.OnExecute              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  300

             4.36.15      TBasicAction.OnUpdate               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  300

    4.37     TBasicActionLink           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  301

             4.37.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  301

             4.37.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  301

             4.37.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  301

             4.37.4       TBasicActionLink.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  301

             4.37.5       TBasicActionLink.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  301

             4.37.6       TBasicActionLink.Execute              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  302

             4.37.7       TBasicActionLink.Update               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  302

             4.37.8       TBasicActionLink.Action             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  302

             4.37.9       TBasicActionLink.OnChange                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 303

    4.38     TBinaryObjectReader            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  303

             4.38.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  303



                                                                 11

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.38.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  304

             4.38.3       TBinaryObjectReader.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 304

             4.38.4       TBinaryObjectReader.Destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 304

             4.38.5       TBinaryObjectReader.NextValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *305

             4.38.6       TBinaryObjectReader.ReadValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *305

             4.38.7       TBinaryObjectReader.BeginRootComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  305

             4.38.8       TBinaryObjectReader.BeginComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  305

             4.38.9       TBinaryObjectReader.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *06

             4.38.10      TBinaryObjectReader.Read                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 306

             4.38.11      TBinaryObjectReader.ReadBinary                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *06

             4.38.12      TBinaryObjectReader.ReadFloat                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *306

             4.38.13      TBinaryObjectReader.ReadSingle                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *306

             4.38.14      TBinaryObjectReader.ReadDate                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *307

             4.38.15      TBinaryObjectReader.ReadCurrency                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *07

             4.38.16      TBinaryObjectReader.ReadIdent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *307

             4.38.17      TBinaryObjectReader.ReadInt8                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *307

             4.38.18      TBinaryObjectReader.ReadInt16                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *307

             4.38.19      TBinaryObjectReader.ReadInt32                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *308

             4.38.20      TBinaryObjectReader.ReadInt64                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *308

             4.38.21      TBinaryObjectReader.ReadSet                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *308

             4.38.22      TBinaryObjectReader.ReadSignature                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *08

             4.38.23      TBinaryObjectReader.ReadStr                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *308

             4.38.24      TBinaryObjectReader.ReadString                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *309

             4.38.25      TBinaryObjectReader.ReadWideString                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  309

             4.38.26      TBinaryObjectReader.ReadUnicodeString                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  309

             4.38.27      TBinaryObjectReader.SkipComponent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  309

             4.38.28      TBinaryObjectReader.SkipValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *310

    4.39     TBinaryObjectWriter            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  310

             4.39.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  310

             4.39.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  310

             4.39.3       TBinaryObjectWriter.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 310

             4.39.4       TBinaryObjectWriter.Destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 311

             4.39.5       TBinaryObjectWriter.WriteSignature                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *11

             4.39.6       TBinaryObjectWriter.BeginCollection                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *11

             4.39.7       TBinaryObjectWriter.BeginComponent                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  311

             4.39.8       TBinaryObjectWriter.BeginList                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *311

             4.39.9       TBinaryObjectWriter.EndList                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 311

             4.39.10      TBinaryObjectWriter.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *12

             4.39.11      TBinaryObjectWriter.EndProperty                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *12

             4.39.12      TBinaryObjectWriter.Write               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 312



                                                                 12

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.39.13      TBinaryObjectWriter.WriteBinary                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *12

             4.39.14      TBinaryObjectWriter.WriteBoolean                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *12

             4.39.15      TBinaryObjectWriter.WriteFloat                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *312

             4.39.16      TBinaryObjectWriter.WriteSingle                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *313

             4.39.17      TBinaryObjectWriter.WriteDate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *313

             4.39.18      TBinaryObjectWriter.WriteCurrency                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *13

             4.39.19      TBinaryObjectWriter.WriteIdent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *313

             4.39.20      TBinaryObjectWriter.WriteInteger                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *13

             4.39.21      TBinaryObjectWriter.WriteUInt64                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *13

             4.39.22      TBinaryObjectWriter.WriteMethodName                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  314

             4.39.23      TBinaryObjectWriter.WriteSet                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *314

             4.39.24      TBinaryObjectWriter.WriteStr               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 314

             4.39.25      TBinaryObjectWriter.WriteString                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *314

             4.39.26      TBinaryObjectWriter.WriteWideString                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  314

             4.39.27      TBinaryObjectWriter.WriteUnicodeString                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  314

             4.39.28      TBinaryObjectWriter.WriteVariant                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *15

    4.40     TBits     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  315

             4.40.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  315

             4.40.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  315

             4.40.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  316

             4.40.4       TBits.Create      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  316

             4.40.5       TBits.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  316

             4.40.6       TBits.GetFSize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  316

             4.40.7       TBits.SetOn       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  317

             4.40.8       TBits.Clear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  317

             4.40.9       TBits.Clearall       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  317

             4.40.10      TBits.AndBits        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  317

             4.40.11      TBits.OrBits      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  318

             4.40.12      TBits.XorBits        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  318

             4.40.13      TBits.NotBits        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  318

             4.40.14      TBits.Get       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  319

             4.40.15      TBits.Grow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  319

             4.40.16      TBits.Equals      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  319

             4.40.17      TBits.SetIndex         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  319

             4.40.18      TBits.FindFirstBit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  320

             4.40.19      TBits.FindNextBit           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  320

             4.40.20      TBits.FindPrevBit           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  320

             4.40.21      TBits.OpenBit        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  321

             4.40.22      TBits.Bits      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  321

             4.40.23      TBits.Size      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  321



                                                                 13

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    4.41     TBytesStream          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  322

             4.41.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  322

             4.41.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  322

             4.41.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  322

             4.41.4       TBytesStream.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  322

             4.41.5       TBytesStream.Bytes             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  322

    4.42     TCollection      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  322

             4.42.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  322

             4.42.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  323

             4.42.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  323

             4.42.4       TCollection.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  323

             4.42.5       TCollection.Destroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  323

             4.42.6       TCollection.Owner           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  324

             4.42.7       TCollection.Add        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  324

             4.42.8       TCollection.Assign          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  324

             4.42.9       TCollection.BeginUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  324

             4.42.10      TCollection.Clear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  325

             4.42.11      TCollection.EndUpdate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  325

             4.42.12      TCollection.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  325

             4.42.13      TCollection.GetEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 326

             4.42.14      TCollection.GetNamePath               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  326

             4.42.15      TCollection.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  326

             4.42.16      TCollection.FindItemID              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  327

             4.42.17      TCollection.Exchange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  327

             4.42.18      TCollection.Sort       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  327

             4.42.19      TCollection.Count         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  327

             4.42.20      TCollection.ItemClass            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  328

             4.42.21      TCollection.Items         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  328

    4.43     TCollectionEnumerator             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  328

             4.43.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  328

             4.43.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  329

             4.43.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  329

             4.43.4       TCollectionEnumerator.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 329

             4.43.5       TCollectionEnumerator.GetCurrent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *29

             4.43.6       TCollectionEnumerator.MoveNext                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *329

             4.43.7       TCollectionEnumerator.Current                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *330

    4.44     TCollectionItem         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  330

             4.44.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  330

             4.44.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  330

             4.44.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  330



                                                                 14

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.44.4       TCollectionItem.Create           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  330

             4.44.5       TCollectionItem.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  331

             4.44.6       TCollectionItem.GetNamePath                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *331

             4.44.7       TCollectionItem.Collection            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  331

             4.44.8       TCollectionItem.ID          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  331

             4.44.9       TCollectionItem.Index            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  332

             4.44.10      TCollectionItem.DisplayName                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 332

    4.45     TComponent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  333

             4.45.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  333

             4.45.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  333

             4.45.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  333

             4.45.4       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  334

             4.45.5       TComponent.Notification             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  334

             4.45.6       TComponent.WriteState               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  334

             4.45.7       TComponent.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  335

             4.45.8       TComponent.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  335

             4.45.9       TComponent.BeforeDestruction                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *335

             4.45.10      TComponent.DestroyComponents                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *335

             4.45.11      TComponent.Destroying               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  336

             4.45.12      TComponent.ExecuteAction                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 336

             4.45.13      TComponent.FindComponent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 336

             4.45.14      TComponent.FreeNotification                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 336

             4.45.15      TComponent.RemoveFreeNotification                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *37

             4.45.16      TComponent.FreeOnRelease                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 337

             4.45.17      TComponent.GetEnumerator                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 337

             4.45.18      TComponent.GetNamePath                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 337

             4.45.19      TComponent.GetParentComponent                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *37

             4.45.20      TComponent.HasParent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  338

             4.45.21      TComponent.InsertComponent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *338

             4.45.22      TComponent.RemoveComponent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *338

             4.45.23      TComponent.SafeCallException                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *338

             4.45.24      TComponent.SetSubComponent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *339

             4.45.25      TComponent.UpdateAction                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 339

             4.45.26      TComponent.IsImplementorOf                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 339

             4.45.27      TComponent.ReferenceInterface                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *339

             4.45.28      TComponent.ComObject                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  340

             4.45.29      TComponent.Components                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  340

             4.45.30      TComponent.ComponentCount                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *340

             4.45.31      TComponent.ComponentIndex                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 340

             4.45.32      TComponent.ComponentState                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 341



                                                                 15

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.45.33      TComponent.ComponentStyle                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 341

             4.45.34      TComponent.DesignInfo               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  341

             4.45.35      TComponent.Owner               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  342

             4.45.36      TComponent.VCLComObject                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 342

             4.45.37      TComponent.Name             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  342

             4.45.38      TComponent.Tag            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  343

    4.46     TComponentEnumerator                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  343

             4.46.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  343

             4.46.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  343

             4.46.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  343

             4.46.4       TComponentEnumerator.Create                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *343

             4.46.5       TComponentEnumerator.GetCurrent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *44

             4.46.6       TComponentEnumerator.MoveNext                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *44

             4.46.7       TComponentEnumerator.Current                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *344

    4.47     TCustomMemoryStream                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  344

             4.47.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  344

             4.47.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  345

             4.47.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  345

             4.47.4       TCustomMemoryStream.Read                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 345

             4.47.5       TCustomMemoryStream.Seek                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 345

             4.47.6       TCustomMemoryStream.SaveToStream                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  345

             4.47.7       TCustomMemoryStream.SaveToFile                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *46

             4.47.8       TCustomMemoryStream.Memory                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *346

    4.48     TDataModule           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  347

             4.48.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  347

             4.48.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  347

             4.48.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  347

             4.48.4       TDataModule.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  347

             4.48.5       TDataModule.CreateNew               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  348

             4.48.6       TDataModule.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  348

             4.48.7       TDataModule.AfterConstruction                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *348

             4.48.8       TDataModule.BeforeDestruction                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *348

             4.48.9       TDataModule.DesignOffset              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  349

             4.48.10      TDataModule.DesignSize              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  349

             4.48.11      TDataModule.OnCreate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  349

             4.48.12      TDataModule.OnDestroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  349

             4.48.13      TDataModule.OldCreateOrder                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 350

    4.49     TFiler    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  350

             4.49.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  350

             4.49.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  350



                                                                 16

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.49.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  350

             4.49.4       TFiler.DefineProperty            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  350

             4.49.5       TFiler.DefineBinaryProperty             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 351

             4.49.6       TFiler.Root       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  351

             4.49.7       TFiler.LookupRoot           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  351

             4.49.8       TFiler.Ancestor        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  351

             4.49.9       TFiler.IgnoreChildren          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  352

    4.50     TFileStream        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  352

             4.50.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  352

             4.50.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  352

             4.50.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  352

             4.50.4       TFileStream.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  352

             4.50.5       TFileStream.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  353

             4.50.6       TFileStream.FileName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  353

    4.51     TFPList       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  353

             4.51.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  353

             4.51.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  354

             4.51.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  354

             4.51.4       TFPList.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  354

             4.51.5       TFPList.AddList           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  354

             4.51.6       TFPList.Add          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  355

             4.51.7       TFPList.Clear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  355

             4.51.8       TFPList.Delete         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  355

             4.51.9       TFPList.Error        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  355

             4.51.10      TFPList.Exchange            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  356

             4.51.11      TFPList.Expand            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  356

             4.51.12      TFPList.Extract        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  356

             4.51.13      TFPList.First        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  356

             4.51.14      TFPList.GetEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  357

             4.51.15      TFPList.IndexOf           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  357

             4.51.16      TFPList.IndexOfItem            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  357

             4.51.17      TFPList.Insert       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  357

             4.51.18      TFPList.Last         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  358

             4.51.19      TFPList.Move         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  358

             4.51.20      TFPList.Assign         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  358

             4.51.21      TFPList.Remove            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  358

             4.51.22      TFPList.Pack         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  359

             4.51.23      TFPList.Sort         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  359

             4.51.24      TFPList.ForEachCall            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  359

             4.51.25      TFPList.Capacity          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  359



                                                                 17

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.51.26      TFPList.Count          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  360

             4.51.27      TFPList.Items        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  360

             4.51.28      TFPList.List      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  360

    4.52     TFPListEnumerator            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  361

             4.52.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  361

             4.52.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  361

             4.52.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  361

             4.52.4       TFPListEnumerator.Create                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 361

             4.52.5       TFPListEnumerator.GetCurrent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *361

             4.52.6       TFPListEnumerator.MoveNext                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *361

             4.52.7       TFPListEnumerator.Current               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 362

    4.53     THandleStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  362

             4.53.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  362

             4.53.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  362

             4.53.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  362

             4.53.4       THandleStream.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  363

             4.53.5       THandleStream.Read             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  363

             4.53.6       THandleStream.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  363

             4.53.7       THandleStream.Seek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  363

             4.53.8       THandleStream.Handle             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  364

    4.54     TInterfacedPersistent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  364

             4.54.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  364

             4.54.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  364

             4.54.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  364

             4.54.4       TInterfacedPersistent.QueryInterface                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *64

             4.54.5       TInterfacedPersistent.AfterConstruction                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  364

    4.55     TInterfaceList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  365

             4.55.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  365

             4.55.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  365

             4.55.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  365

             4.55.4       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  365

             4.55.5       TInterfaceList.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  365

             4.55.6       TInterfaceList.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  366

             4.55.7       TInterfaceList.Clear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  366

             4.55.8       TInterfaceList.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  366

             4.55.9       TInterfaceList.Exchange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  366

             4.55.10      TInterfaceList.First        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  367

             4.55.11      TInterfaceList.GetEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 367

             4.55.12      TInterfaceList.IndexOf           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  367

             4.55.13      TInterfaceList.Add          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  367



                                                                 18

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.55.14      TInterfaceList.Insert          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  368

             4.55.15      TInterfaceList.Last         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  368

             4.55.16      TInterfaceList.Remove            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  368

             4.55.17      TInterfaceList.Lock         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  368

             4.55.18      TInterfaceList.Unlock          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  369

             4.55.19      TInterfaceList.Expand            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  369

             4.55.20      TInterfaceList.Capacity          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  369

             4.55.21      TInterfaceList.Count           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  369

             4.55.22      TInterfaceList.Items           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  370

    4.56     TInterfaceListEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  370

             4.56.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  370

             4.56.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  370

             4.56.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  370

             4.56.4       TInterfaceListEnumerator.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *370

             4.56.5       TInterfaceListEnumerator.GetCurrent                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  371

             4.56.6       TInterfaceListEnumerator.MoveNext                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *71

             4.56.7       TInterfaceListEnumerator.Current                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *371

    4.57     TList     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  371

             4.57.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  371

             4.57.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  372

             4.57.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  372

             4.57.4       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  372

             4.57.5       TList.Create      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  372

             4.57.6       TList.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  373

             4.57.7       TList.FPOAttachObserver               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  373

             4.57.8       TList.FPODetachObserver               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  373

             4.57.9       TList.FPONotifyObservers              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  373

             4.57.10      TList.AddList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  374

             4.57.11      TList.Add       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  374

             4.57.12      TList.Clear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  374

             4.57.13      TList.Delete      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  374

             4.57.14      TList.Error       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  375

             4.57.15      TList.Exchange         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  375

             4.57.16      TList.Expand         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  375

             4.57.17      TList.Extract        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  375

             4.57.18      TList.First     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  376

             4.57.19      TList.GetEnumerator            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  376

             4.57.20      TList.IndexOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  376

             4.57.21      TList.Insert      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  376

             4.57.22      TList.Last      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  377



                                                                 19

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.57.23      TList.Move      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  377

             4.57.24      TList.Assign      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  377

             4.57.25      TList.Remove         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  377

             4.57.26      TList.Pack      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  378

             4.57.27      TList.Sort      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  378

             4.57.28      TList.Capacity       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  378

             4.57.29      TList.Count       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  379

             4.57.30      TList.Items       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  379

             4.57.31      TList.List      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  379

    4.58     TListEnumerator            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  379

             4.58.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  379

             4.58.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  379

             4.58.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  380

             4.58.4       TListEnumerator.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  380

             4.58.5       TListEnumerator.GetCurrent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 380

             4.58.6       TListEnumerator.MoveNext                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 380

             4.58.7       TListEnumerator.Current               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  380

    4.59     TMemoryStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  381

             4.59.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  381

             4.59.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  381

             4.59.3       TMemoryStream.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  381

             4.59.4       TMemoryStream.Clear              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  381

             4.59.5       TMemoryStream.LoadFromStream                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *81

             4.59.6       TMemoryStream.LoadFromFile                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *382

             4.59.7       TMemoryStream.SetSize               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  382

             4.59.8       TMemoryStream.Write              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  383

    4.60     TOwnedCollection           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  383

             4.60.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  383

             4.60.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  383

             4.60.3       TOwnedCollection.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  383

    4.61     TOwnerStream            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  383

             4.61.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  383

             4.61.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  384

             4.61.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  384

             4.61.4       TOwnerStream.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  384

             4.61.5       TOwnerStream.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  384

             4.61.6       TOwnerStream.Source              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  384

             4.61.7       TOwnerStream.SourceOwner                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 385

    4.62     TParser     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  385

             4.62.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  385



                                                                 20

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.62.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  385

             4.62.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  386

             4.62.4       TParser.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  386

             4.62.5       TParser.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  386

             4.62.6       TParser.CheckToken             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  386

             4.62.7       TParser.CheckTokenSymbol                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 386

             4.62.8       TParser.Error        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  387

             4.62.9       TParser.ErrorFmt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  387

             4.62.10      TParser.ErrorStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  387

             4.62.11      TParser.HexToBinary            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  387

             4.62.12      TParser.NextToken           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  388

             4.62.13      TParser.SourcePos           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  388

             4.62.14      TParser.TokenComponentIdent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *388

             4.62.15      TParser.TokenFloat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  389

             4.62.16      TParser.TokenInt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  389

             4.62.17      TParser.TokenString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  389

             4.62.18      TParser.TokenWideString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  390

             4.62.19      TParser.TokenSymbolIs            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  390

             4.62.20      TParser.FloatType           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  390

             4.62.21      TParser.SourceLine          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  391

             4.62.22      TParser.Token        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  391

    4.63     TPersistent      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  391

             4.63.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  391

             4.63.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  392

             4.63.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  392

             4.63.4       TPersistent.Destroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  392

             4.63.5       TPersistent.Assign          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  392

             4.63.6       TPersistent.FPOAttachObserver                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *393

             4.63.7       TPersistent.FPODetachObserver                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *393

             4.63.8       TPersistent.FPONotifyObservers                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *393

             4.63.9       TPersistent.GetNamePath               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  394

    4.64     TProxyStream          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  394

             4.64.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  394

             4.64.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  394

             4.64.3       TProxyStream.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  394

             4.64.4       TProxyStream.Read              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  394

             4.64.5       TProxyStream.Write             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  395

             4.64.6       TProxyStream.Seek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  395

             4.64.7       TProxyStream.Check             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  395

    4.65     TReader       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  395



                                                                 21

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.65.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  395

             4.65.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  396

             4.65.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  397

             4.65.4       TReader.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  397

             4.65.5       TReader.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  397

             4.65.6       TReader.BeginReferences             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  397

             4.65.7       TReader.CheckValue             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  398

             4.65.8       TReader.DefineProperty              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  398

             4.65.9       TReader.DefineBinaryProperty                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *398

             4.65.10      TReader.EndOfList           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  398

             4.65.11      TReader.EndReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  398

             4.65.12      TReader.FixupReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  399

             4.65.13      TReader.NextValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  399

             4.65.14      TReader.Read         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  399

             4.65.15      TReader.ReadBoolean              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  399

             4.65.16      TReader.ReadChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  399

             4.65.17      TReader.ReadWideChar                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  400

             4.65.18      TReader.ReadUnicodeChar                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 400

             4.65.19      TReader.ReadCollection              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  400

             4.65.20      TReader.ReadComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  400

             4.65.21      TReader.ReadComponents                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  400

             4.65.22      TReader.ReadFloat           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  401

             4.65.23      TReader.ReadSingle             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  401

             4.65.24      TReader.ReadDate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  401

             4.65.25      TReader.ReadCurrency             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  401

             4.65.26      TReader.ReadIdent           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  401

             4.65.27      TReader.ReadInteger            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  402

             4.65.28      TReader.ReadInt64           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  402

             4.65.29      TReader.ReadSet           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  402

             4.65.30      TReader.ReadListBegin               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  402

             4.65.31      TReader.ReadListEnd              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  402

             4.65.32      TReader.ReadRootComponent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 403

             4.65.33      TReader.ReadVariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  403

             4.65.34      TReader.ReadSignature               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  403

             4.65.35      TReader.ReadString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  403

             4.65.36      TReader.ReadWideString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  403

             4.65.37      TReader.ReadUnicodeString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 404

             4.65.38      TReader.ReadValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  404

             4.65.39      TReader.CopyValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  404

             4.65.40      TReader.Driver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  404



                                                                 22

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.65.41      TReader.Owner          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  404

             4.65.42      TReader.Parent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  405

             4.65.43      TReader.OnError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  405

             4.65.44      TReader.OnPropertyNotFound                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *405

             4.65.45      TReader.OnFindMethod                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  405

             4.65.46      TReader.OnSetMethodProperty                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *406

             4.65.47      TReader.OnSetName              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  406

             4.65.48      TReader.OnReferenceName                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 406

             4.65.49      TReader.OnAncestorNotFound                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *406

             4.65.50      TReader.OnCreateComponent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 406

             4.65.51      TReader.OnFindComponentClass                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *407

             4.65.52      TReader.OnReadStringProperty                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *407

    4.66     TRecall     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  407

             4.66.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  407

             4.66.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  408

             4.66.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  408

             4.66.4       TRecall.Create       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  408

             4.66.5       TRecall.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  408

             4.66.6       TRecall.Store        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  408

             4.66.7       TRecall.Forget       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  409

             4.66.8       TRecall.Reference         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  409

    4.67     TResourceStream            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  409

             4.67.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  409

             4.67.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  409

             4.67.3       TResourceStream.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  409

             4.67.4       TResourceStream.CreateFromID                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *410

             4.67.5       TResourceStream.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  410

    4.68     TStream       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  410

             4.68.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  410

             4.68.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  411

             4.68.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  411

             4.68.4       TStream.Read         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  411

             4.68.5       TStream.Write        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  412

             4.68.6       TStream.Seek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  412

             4.68.7       TStream.ReadBuffer             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  413

             4.68.8       TStream.WriteBuffer            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  413

             4.68.9       TStream.CopyFrom            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  414

             4.68.10      TStream.ReadComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  414

             4.68.11      TStream.ReadComponentRes                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 414

             4.68.12      TStream.WriteComponent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  415



                                                                 23

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.68.13      TStream.WriteComponentRes                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 415

             4.68.14      TStream.WriteDescendent               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  415

             4.68.15      TStream.WriteDescendentRes                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 415

             4.68.16      TStream.WriteResourceHeader                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 416

             4.68.17      TStream.FixupResourceHeader                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *416

             4.68.18      TStream.ReadResHeader               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  416

             4.68.19      TStream.ReadByte            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  417

             4.68.20      TStream.ReadWord            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  417

             4.68.21      TStream.ReadDWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  417

             4.68.22      TStream.ReadQWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  417

             4.68.23      TStream.ReadAnsiString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  418

             4.68.24      TStream.WriteByte           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  418

             4.68.25      TStream.WriteWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  418

             4.68.26      TStream.WriteDWord               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  419

             4.68.27      TStream.WriteQWord               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  419

             4.68.28      TStream.WriteAnsiString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  419

             4.68.29      TStream.Position          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  420

             4.68.30      TStream.Size         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  420

    4.69     TStreamAdapter          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  420

             4.69.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  420

             4.69.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  420

             4.69.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  421

             4.69.4       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  421

             4.69.5       TStreamAdapter.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  421

             4.69.6       TStreamAdapter.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  421

             4.69.7       TStreamAdapter.Read              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  421

             4.69.8       TStreamAdapter.Write             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  422

             4.69.9       TStreamAdapter.Seek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  422

             4.69.10      TStreamAdapter.SetSize              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  422

             4.69.11      TStreamAdapter.CopyTo               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  423

             4.69.12      TStreamAdapter.Commit                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  423

             4.69.13      TStreamAdapter.Revert               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  423

             4.69.14      TStreamAdapter.LockRegion                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 423

             4.69.15      TStreamAdapter.UnlockRegion                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *424

             4.69.16      TStreamAdapter.Stat            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  424

             4.69.17      TStreamAdapter.Clone             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  424

             4.69.18      TStreamAdapter.Stream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  424

             4.69.19      TStreamAdapter.StreamOwnership                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *25

    4.70     TStringList      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  425

             4.70.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  425



                                                                 24

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.70.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  425

             4.70.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  425

             4.70.4       TStringList.Destroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  426

             4.70.5       TStringList.Add        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  426

             4.70.6       TStringList.Clear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  426

             4.70.7       TStringList.Delete        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  426

             4.70.8       TStringList.Exchange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  427

             4.70.9       TStringList.Find          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  427

             4.70.10      TStringList.IndexOf         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  427

             4.70.11      TStringList.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  427

             4.70.12      TStringList.Sort       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  428

             4.70.13      TStringList.CustomSort              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  428

             4.70.14      TStringList.Duplicates           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  428

             4.70.15      TStringList.Sorted          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  429

             4.70.16      TStringList.CaseSensitive             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  429

             4.70.17      TStringList.OnChange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  429

             4.70.18      TStringList.OnChanging              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  430

             4.70.19      TStringList.OwnsObjects             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  430

    4.71     TStrings      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  430

             4.71.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  430

             4.71.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  431

             4.71.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  432

             4.71.4       TStrings.Destroy          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  432

             4.71.5       TStrings.Add         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  432

             4.71.6       TStrings.AddObject          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  433

             4.71.7       TStrings.Append           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  433

             4.71.8       TStrings.AddStrings            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  433

             4.71.9       TStrings.AddText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  433

             4.71.10      TStrings.Assign        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  434

             4.71.11      TStrings.BeginUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  434

             4.71.12      TStrings.Clear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  434

             4.71.13      TStrings.Delete        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  435

             4.71.14      TStrings.EndUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  435

             4.71.15      TStrings.Equals        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  435

             4.71.16      TStrings.Exchange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  436

             4.71.17      TStrings.GetEnumerator              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  436

             4.71.18      TStrings.GetText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  436

             4.71.19      TStrings.IndexOf          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  436

             4.71.20      TStrings.IndexOfName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  437

             4.71.21      TStrings.IndexOfObject              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  437



                                                                 25

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.71.22      TStrings.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  437

             4.71.23      TStrings.InsertObject          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  438

             4.71.24      TStrings.LoadFromFile            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  438

             4.71.25      TStrings.LoadFromStream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  438

             4.71.26      TStrings.Move        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  438

             4.71.27      TStrings.SaveToFile         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  439

             4.71.28      TStrings.SaveToStream            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  439

             4.71.29      TStrings.SetText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  440

             4.71.30      TStrings.GetNameValue               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  440

             4.71.31      TStrings.ExtractName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  440

             4.71.32      TStrings.TextLineBreakStyle             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 440

             4.71.33      TStrings.Delimiter          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  441

             4.71.34      TStrings.DelimitedText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  441

             4.71.35      TStrings.LineBreak          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  441

             4.71.36      TStrings.StrictDelimiter            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  442

             4.71.37      TStrings.QuoteChar          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  442

             4.71.38      TStrings.NameValueSeparator                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 442

             4.71.39      TStrings.ValueFromIndex               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  442

             4.71.40      TStrings.Capacity         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  443

             4.71.41      TStrings.CommaText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  443

             4.71.42      TStrings.Count         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  444

             4.71.43      TStrings.Names         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  444

             4.71.44      TStrings.Objects          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  445

             4.71.45      TStrings.Values        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  445

             4.71.46      TStrings.Strings       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  446

             4.71.47      TStrings.Text        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  446

             4.71.48      TStrings.StringsAdapter             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  446

    4.72     TStringsEnumerator           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  447

             4.72.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  447

             4.72.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  447

             4.72.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  447

             4.72.4       TStringsEnumerator.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 447

             4.72.5       TStringsEnumerator.GetCurrent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *447

             4.72.6       TStringsEnumerator.MoveNext                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *447

             4.72.7       TStringsEnumerator.Current              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 448

    4.73     TStringStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  448

             4.73.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  448

             4.73.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  448

             4.73.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  448

             4.73.4       TStringStream.Create           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  448



                                                                 26

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.73.5       TStringStream.Read             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  449

             4.73.6       TStringStream.ReadString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  449

             4.73.7       TStringStream.Seek          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  449

             4.73.8       TStringStream.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  449

             4.73.9       TStringStream.WriteString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  450

             4.73.10      TStringStream.DataString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  450

    4.74     TTextObjectWriter            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  450

             4.74.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  450

    4.75     TThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  450

             4.75.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  450

             4.75.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  451

             4.75.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  451

             4.75.4       TThread.Execute           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  451

             4.75.5       TThread.Synchronize            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  452

             4.75.6       TThread.Queue          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  452

             4.75.7       TThread.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  452

             4.75.8       TThread.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  453

             4.75.9       TThread.CreateAnonymousThread                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *53

             4.75.10      TThread.NameThreadForDebugging                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  4*
 *53

             4.75.11      TThread.SetReturnValue              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  453

             4.75.12      TThread.CheckTerminated               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  454

             4.75.13      TThread.RemoveQueuedEvents                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *454

             4.75.14      TThread.SpinWait            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  454

             4.75.15      TThread.Sleep        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  455

             4.75.16      TThread.Yield        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  455

             4.75.17      TThread.GetSystemTimes                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  455

             4.75.18      TThread.GetTickCount             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  455

             4.75.19      TThread.GetTickCount64                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  456

             4.75.20      TThread.AfterConstruction               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 456

             4.75.21      TThread.Start        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  456

             4.75.22      TThread.Resume            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  456

             4.75.23      TThread.Suspend           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  456

             4.75.24      TThread.Terminate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  457

             4.75.25      TThread.WaitFor           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  457

             4.75.26      TThread.CurrentThread               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  457

             4.75.27      TThread.ProcessorCount              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  457

             4.75.28      TThread.IsSingleProcessor             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  458

             4.75.29      TThread.FreeOnTerminate               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  458

             4.75.30      TThread.Handle         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  458

             4.75.31      TThread.ExternalThread              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  458



                                                                 27

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.75.32      TThread.Priority          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  459

             4.75.33      TThread.Suspended           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  459

             4.75.34      TThread.Finished          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  459

             4.75.35      TThread.ThreadID            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  459

             4.75.36      TThread.OnTerminate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  459

             4.75.37      TThread.FatalException              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  460

    4.76     TThreadList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  460

             4.76.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  460

             4.76.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  460

             4.76.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  460

             4.76.4       TThreadList.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  460

             4.76.5       TThreadList.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  461

             4.76.6       TThreadList.Add           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  461

             4.76.7       TThreadList.Clear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  461

             4.76.8       TThreadList.LockList           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  461

             4.76.9       TThreadList.Remove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  462

             4.76.10      TThreadList.UnlockList              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  462

             4.76.11      TThreadList.Duplicates           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  462

    4.77     TWriter     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  462

             4.77.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  462

             4.77.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  463

             4.77.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  463

             4.77.4       TWriter.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  463

             4.77.5       TWriter.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  464

             4.77.6       TWriter.DefineProperty              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  464

             4.77.7       TWriter.DefineBinaryProperty               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 464

             4.77.8       TWriter.Write        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  464

             4.77.9       TWriter.WriteBoolean             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  464

             4.77.10      TWriter.WriteCollection             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  465

             4.77.11      TWriter.WriteComponent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  465

             4.77.12      TWriter.WriteChar           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  465

             4.77.13      TWriter.WriteWideChar               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  465

             4.77.14      TWriter.WriteDescendent               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  465

             4.77.15      TWriter.WriteFloat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  466

             4.77.16      TWriter.WriteSingle         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  466

             4.77.17      TWriter.WriteDate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  466

             4.77.18      TWriter.WriteCurrency            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  466

             4.77.19      TWriter.WriteIdent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  466

             4.77.20      TWriter.WriteInteger           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  467

             4.77.21      TWriter.WriteSet          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  467



                                                                 28

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             4.77.22      TWriter.WriteListBegin           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  467

             4.77.23      TWriter.WriteListEnd             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  467

             4.77.24      TWriter.WriteSignature           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  467

             4.77.25      TWriter.WriteRootComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 468

             4.77.26      TWriter.WriteString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  468

             4.77.27      TWriter.WriteWideString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  468

             4.77.28      TWriter.WriteUnicodeString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 468

             4.77.29      TWriter.WriteVariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  468

             4.77.30      TWriter.RootAncestor             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  469

             4.77.31      TWriter.OnFindAncestor              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  469

             4.77.32      TWriter.OnWriteMethodProperty                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *469

             4.77.33      TWriter.OnWriteStringProperty                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *469

             4.77.34      TWriter.Driver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  470

             4.77.35      TWriter.PropertyPath             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  470


5    Reference for unit 'clocale'                                                                                       471

    5.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  471


6    Reference for unit 'cmem'                                                                                          472

    6.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  472

    6.2      Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  472

             6.2.1        Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  472

    6.3      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  472

             6.3.1        CAlloc     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  472

             6.3.2        Free  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  473

             6.3.3        Malloc     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  473

             6.3.4        ReAlloc    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  473


7    Reference for unit 'collation__de'                                                                                 474

    7.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  474


8    Reference for unit 'collation__es'                                                                                 475

    8.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  475


9    Reference for unit 'collation__fr__ca'                                                                             476

    9.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  476


10   Reference for unit 'collation__ja'                                                                                 477

    10.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  477


11   Reference for unit 'collation__ko'                                                                                 478

    11.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  478



                                                                 29

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



12   Reference for unit 'collation__ru'                                                                                 479

    12.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  479


13   Reference for unit 'collation__sv'                                                                                 480

    13.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  480


14   Reference for unit 'collation__zh'                                                                                 481

    14.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  481


15   Reference for unit 'cp1250'                                                                                        482

    15.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  482


16   Reference for unit 'cp1251'                                                                                        483

    16.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  483


17   Reference for unit 'cp1252'                                                                                        484

    17.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  484


18   Reference for unit 'cp1253'                                                                                        485

    18.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  485


19   Reference for unit 'cp1254'                                                                                        486

    19.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  486


20   Reference for unit 'cp1255'                                                                                        487

    20.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  487


21   Reference for unit 'cp1256'                                                                                        488

    21.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  488


22   Reference for unit 'cp1257'                                                                                        489

    22.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  489


23   Reference for unit 'cp1258'                                                                                        490

    23.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  490


24   Reference for unit 'cp437'                                                                                         491

    24.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  491


25   Reference for unit 'cp646'                                                                                         492

    25.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  492


26   Reference for unit 'cp850'                                                                                         493

    26.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  493



                                                                 30

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



27   Reference for unit 'cp852'                                                                                         494

    27.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  494


28   Reference for unit 'cp856'                                                                                         495

    28.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  495


29   Reference for unit 'cp866'                                                                                         496

    29.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  496


30   Reference for unit 'cp874'                                                                                         497

    30.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  497


31   Reference for unit 'cp8859__1'                                                                                     498

    31.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  498


32   Reference for unit 'cp8859__2'                                                                                     499

    32.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  499


33   Reference for unit 'cp8859__5'                                                                                     500

    33.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  500


34   Reference for unit 'cp895'                                                                                         501

    34.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  501


35   Reference for unit 'cp932'                                                                                         502

    35.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  502


36   Reference for unit 'cp936'                                                                                         503

    36.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  503


37   Reference for unit 'cp949'                                                                                         504

    37.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  504


38   Reference for unit 'cp950'                                                                                         505

    38.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  505


39   Reference for unit 'cpall'                                                                                         506

    39.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  506

    39.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  506


40   Reference for unit 'Crt'                                                                                           507

    40.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  507

    40.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  507

             40.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  507

             40.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  510



                                                                 31

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             40.2.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  510

    40.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  511

             40.3.1       AssignCrt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  511

             40.3.2       ClrEol     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  512

             40.3.3       ClrScr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  512

             40.3.4       cursorbig     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  513

             40.3.5       cursoroff     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  513

             40.3.6       cursoron      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  513

             40.3.7       Delay    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  514

             40.3.8       DelLine    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  514

             40.3.9       GotoXY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  515

             40.3.10      HighVideo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  515

             40.3.11      InsLine    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  516

             40.3.12      KeyPressed        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  517

             40.3.13      LowVideo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  517

             40.3.14      NormVideo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  517

             40.3.15      NoSound       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  518

             40.3.16      ReadKey       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  518

             40.3.17      Sound      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  519

             40.3.18      TextBackground         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  519

             40.3.19      TextColor       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  520

             40.3.20      TextMode        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  520

             40.3.21      WhereX        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  521

             40.3.22      WhereY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  521

             40.3.23      Window        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  522


41   Reference for unit 'cthreads'                                                                                      523

    41.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  523

    41.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  523

             41.2.1       SetCThreadManager              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  523


42   Reference for unit 'ctypes'                                                                                        524

    42.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  524

    42.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  524

    42.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  524

             42.3.1       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  524

    42.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  529

             42.4.1       add(clongdouble,Double):Double               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *529

             42.4.2       add(Double,clongdouble):Double               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *529

             42.4.3       assign(clongdouble):Double            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  529

             42.4.4       assign(Double):clongdouble            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  530



                                                                 32

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             42.4.5       divide(clongdouble,Double):Double                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *30

             42.4.6       divide(Double,clongdouble):Double                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *30

             42.4.7       equal(clongdouble,Double):Boolean                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *30

             42.4.8       equal(Double,clongdouble):Boolean                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *30

             42.4.9       greaterthan(clongdouble,Double):Boolean                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  531

             42.4.10      greaterthan(Double,clongdouble):Boolean                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  531

             42.4.11      greaterthanorequal(clongdouble,Double):Boolean                        .  .  .  .  .  .  .  .  .  .  531

             42.4.12      greaterthanorequal(Double,clongdouble):Boolean                        .  .  .  .  .  .  .  .  .  .  531

             42.4.13      lessthan(clongdouble,Double):Boolean                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *31

             42.4.14      lessthan(Double,clongdouble):Boolean                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *32

             42.4.15      lessthanorequal(clongdouble,Double):Boolean                      .  .  .  .  .  .  .  .  .  .  .  .  532

             42.4.16      lessthanorequal(Double,clongdouble):Boolean                      .  .  .  .  .  .  .  .  .  .  .  .  532

             42.4.17      multiply(clongdouble,Double):Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *32

             42.4.18      multiply(Double,clongdouble):Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *32

             42.4.19      subtract(clongdouble,Double):Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *33

             42.4.20      subtract(Double,clongdouble):Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *33


43   Reference for unit 'cwstring'                                                                                      534

    43.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  534

    43.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  534

             43.2.1       SetCWidestringManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  534


44   Reference for unit 'dateutils'                                                                                     535

    44.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  535

    44.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  535

    44.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  535

             44.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  535

    44.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  537

             44.4.1       CompareDate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  537

             44.4.2       CompareDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  538

             44.4.3       CompareTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  539

             44.4.4       DateOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  540

             44.4.5       DateTimeToDosDateTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  541

             44.4.6       DateTimeToJulianDate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  541

             44.4.7       DateTimeToMac             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  541

             44.4.8       DateTimeToModifiedJulianDate                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *542

             44.4.9       DateTimeToUnix            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  542

             44.4.10      DayOf      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  542

             44.4.11      DayOfTheMonth             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  543

             44.4.12      DayOfTheWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  543

             44.4.13      DayOfTheYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  543



                                                                 33

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             44.4.14      DaysBetween          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  544

             44.4.15      DaysInAMonth           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  545

             44.4.16      DaysInAYear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  545

             44.4.17      DaysInMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  546

             44.4.18      DaysInYear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  546

             44.4.19      DaySpan       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  547

             44.4.20      DecodeDateDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  547

             44.4.21      DecodeDateMonthWeek                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  548

             44.4.22      DecodeDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  549

             44.4.23      DecodeDateWeek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  549

             44.4.24      DecodeDayOfWeekInMonth                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 550

             44.4.25      DosDateTimeToDateTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  550

             44.4.26      EncodeDateDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  551

             44.4.27      EncodeDateMonthWeek                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  551

             44.4.28      EncodeDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  551

             44.4.29      EncodeDateWeek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  552

             44.4.30      EncodeDayOfWeekInMonth                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 552

             44.4.31      EncodeTimeInterval          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  553

             44.4.32      EndOfADay         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  553

             44.4.33      EndOfAMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  554

             44.4.34      EndOfAWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  554

             44.4.35      EndOfAYear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  555

             44.4.36      EndOfTheDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  555

             44.4.37      EndOfTheMonth             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  556

             44.4.38      EndOfTheWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  556

             44.4.39      EndOfTheYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  557

             44.4.40      HourOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  557

             44.4.41      HourOfTheDay           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  558

             44.4.42      HourOfTheMonth            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  558

             44.4.43      HourOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  559

             44.4.44      HourOfTheYear          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  559

             44.4.45      HoursBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  559

             44.4.46      HourSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  560

             44.4.47      IncDay     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  561

             44.4.48      IncHour       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  561

             44.4.49      IncMilliSecond       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  562

             44.4.50      IncMinute       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  562

             44.4.51      IncSecond       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  563

             44.4.52      IncWeek       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  564

             44.4.53      IncYear    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  564



                                                                 34

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             44.4.54      InvalidDateDayError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  565

             44.4.55      InvalidDateMonthWeekError               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 565

             44.4.56      InvalidDateTimeError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  565

             44.4.57      InvalidDateWeekError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  566

             44.4.58      InvalidDayOfWeekInMonthError                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *566

             44.4.59      IsInLeapYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  566

             44.4.60      IsPM     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  567

             44.4.61      IsSameDay       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  567

             44.4.62      IsSameMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  568

             44.4.63      IsToday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  568

             44.4.64      IsValidDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  569

             44.4.65      IsValidDateDay         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  569

             44.4.66      IsValidDateMonthWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  570

             44.4.67      IsValidDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  571

             44.4.68      IsValidDateWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  572

             44.4.69      IsValidTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  572

             44.4.70      JulianDateToDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  573

             44.4.71      LocalTimeToUniversal             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  573

             44.4.72      MacTimeStampToUnix               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  573

             44.4.73      MacToDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  573

             44.4.74      MilliSecondOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  574

             44.4.75      MilliSecondOfTheDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  574

             44.4.76      MilliSecondOfTheHour             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  574

             44.4.77      MilliSecondOfTheMinute              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  574

             44.4.78      MilliSecondOfTheMonth               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  575

             44.4.79      MilliSecondOfTheSecond              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  575

             44.4.80      MilliSecondOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  576

             44.4.81      MilliSecondOfTheYear             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  576

             44.4.82      MilliSecondsBetween            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  576

             44.4.83      MilliSecondSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  577

             44.4.84      MinuteOf      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  578

             44.4.85      MinuteOfTheDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  578

             44.4.86      MinuteOfTheHour           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  578

             44.4.87      MinuteOfTheMonth            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  579

             44.4.88      MinuteOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  579

             44.4.89      MinuteOfTheYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  580

             44.4.90      MinutesBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  580

             44.4.91      MinuteSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  581

             44.4.92      ModifiedJulianDateToDateTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *582

             44.4.93      MonthOf       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  582



                                                                 35

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             44.4.94      MonthOfTheYear            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  582

             44.4.95      MonthsBetween          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  582

             44.4.96      MonthSpan         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  583

             44.4.97      NthDayOfWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  584

             44.4.98      PeriodBetween        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  585

             44.4.99      PreviousDayOfWeek              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  585

             44.4.100     RecodeDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  585

             44.4.101     RecodeDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  586

             44.4.102     RecodeDay       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  587

             44.4.103     RecodeHour        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  588

             44.4.104     RecodeMilliSecond           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  588

             44.4.105     RecodeMinute         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  589

             44.4.106     RecodeMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  590

             44.4.107     RecodeSecond         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  590

             44.4.108     RecodeTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  591

             44.4.109     RecodeYear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  592

             44.4.110     SameDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  592

             44.4.111     SameDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  593

             44.4.112     SameTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  594

             44.4.113     ScanDateTime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  595

             44.4.114     SecondOf      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  595

             44.4.115     SecondOfTheDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  595

             44.4.116     SecondOfTheHour           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  596

             44.4.117     SecondOfTheMinute              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  596

             44.4.118     SecondOfTheMonth            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  597

             44.4.119     SecondOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  597

             44.4.120     SecondOfTheYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  597

             44.4.121     SecondsBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  597

             44.4.122     SecondSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  598

             44.4.123     StartOfADay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  599

             44.4.124     StartOfAMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  600

             44.4.125     StartOfAWeek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  601

             44.4.126     StartOfAYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  601

             44.4.127     StartOfTheDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  602

             44.4.128     StartOfTheMonth           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  602

             44.4.129     StartOfTheWeek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  603

             44.4.130     StartOfTheYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  603

             44.4.131     TimeOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  604

             44.4.132     Today      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  604

             44.4.133     Tomorrow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  605



                                                                 36

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             44.4.134     TryEncodeDateDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  605

             44.4.135     TryEncodeDateMonthWeek                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 606

             44.4.136     TryEncodeDateTime              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  606

             44.4.137     TryEncodeDateWeek              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  607

             44.4.138     TryEncodeDayOfWeekInMonth                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *608

             44.4.139     TryEncodeTimeInterval            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  609

             44.4.140     TryJulianDateToDateTime               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  609

             44.4.141     TryModifiedJulianDateToDateTime                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  6*
 *09

             44.4.142     TryRecodeDateTime              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  610

             44.4.143     UniversalTimeToLocal             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  610

             44.4.144     UnixTimeStampToMac               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  611

             44.4.145     UnixToDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  611

             44.4.146     WeekOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  611

             44.4.147     WeekOfTheMonth            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  612

             44.4.148     WeekOfTheYear          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  612

             44.4.149     WeeksBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  613

             44.4.150     WeeksInAYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  614

             44.4.151     WeeksInYear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  614

             44.4.152     WeekSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  615

             44.4.153     WithinPastDays         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  616

             44.4.154     WithinPastHours           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  617

             44.4.155     WithinPastMilliSeconds              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  618

             44.4.156     WithinPastMinutes           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  619

             44.4.157     WithinPastMonths            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  620

             44.4.158     WithinPastSeconds           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  621

             44.4.159     WithinPastWeeks           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  622

             44.4.160     WithinPastYears           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  623

             44.4.161     YearOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  624

             44.4.162     YearsBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  624

             44.4.163     YearSpan      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  625

             44.4.164     Yesterday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  626


45   Reference for unit 'Dos'                                                                                           627

    45.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  627

    45.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  627

    45.3     System information           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  627

    45.4     Process handling        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  628

    45.5     Directory and disk handling              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  628

    45.6     File handling      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  629

    45.7     File open mode constants.              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  629



                                                                 37

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    45.8     File attributes       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  629

    45.9     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  630

             45.9.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  630

             45.9.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  631

             45.9.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  634

    45.10    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  634

             45.10.1      AddDisk       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  634

             45.10.2      DiskFree      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  635

             45.10.3      DiskSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  635

             45.10.4      DosExitCode       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  636

             45.10.5      DosVersion      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  636

             45.10.6      DTToUnixDate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  637

             45.10.7      EnvCount        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  637

             45.10.8      EnvStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  638

             45.10.9      Exec     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  638

             45.10.10     FExpand       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  639

             45.10.11     FindClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  639

             45.10.12     FindFirst     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  640

             45.10.13     FindNext      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  640

             45.10.14     FSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  641

             45.10.15     FSplit     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  641

             45.10.16     GetCBreak       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  642

             45.10.17     GetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  642

             45.10.18     GetEnv     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  643

             45.10.19     GetFAttr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  643

             45.10.20     GetFTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  644

             45.10.21     GetIntVec       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  645

             45.10.22     GetLongName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  645

             45.10.23     GetMsCount        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  646

             45.10.24     GetShortName         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  646

             45.10.25     GetTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  647

             45.10.26     GetVerify     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  647

             45.10.27     Intr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  648

             45.10.28     Keep     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  648

             45.10.29     MSDos      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  648

             45.10.30     PackTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  648

             45.10.31     SetCBreak       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  649

             45.10.32     SetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  650

             45.10.33     SetFAttr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  650

             45.10.34     SetFTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  650



                                                                 38

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             45.10.35     SetIntVec     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  651

             45.10.36     SetTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  651

             45.10.37     SetVerify     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  651

             45.10.38     SwapVectors       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  652

             45.10.39     UnixDateToDt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  652

             45.10.40     UnpackTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  652

             45.10.41     weekday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  652


46   Reference for unit 'dxeload'                                                                                       653

    46.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  653

    46.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  653

             46.2.1       dxe_load      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  653


47   Reference for unit 'dynlibs'                                                                                       654

    47.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  654

    47.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  654

             47.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  654

             47.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  654

    47.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  655

             47.3.1       FreeLibrary       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  655

             47.3.2       GetLoadErrorStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  655

             47.3.3       GetProcAddress         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  655

             47.3.4       GetProcedureAddress            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  655

             47.3.5       LoadLibrary       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  656

             47.3.6       SafeLoadLibrary        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  656

             47.3.7       UnloadLibrary        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  656


48   Reference for unit 'emu387'                                                                                        658

    48.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  658

    48.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  658

             48.2.1       npxsetup      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  658


49   Reference for unit 'errors'                                                                                        660

    49.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  660

    49.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  660

    49.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  660

             49.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  660

    49.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  660

             49.4.1       PError     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  660

             49.4.2       StrError      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  661


50   Reference for unit 'exeinfo'                                                                                       662



                                                                 39

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    50.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  662

    50.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  662

             50.2.1       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  662

    50.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  663

             50.3.1       CloseExeFile      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  663

             50.3.2       FindExeSection         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  663

             50.3.3       GetModuleByAddr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  663

             50.3.4       OpenExeFile       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  663

             50.3.5       ReadDebugLink          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  664


51   Reference for unit 'fgl'                                                                                           665

    51.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  665

    51.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  665

    51.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  665

             51.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  665

             51.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  665

    51.4     EListError       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  666

             51.4.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  666

    51.5     TFPGInterfacedObjectList               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  666

             51.5.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  666

             51.5.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  666

             51.5.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  666

             51.5.4       TFPGInterfacedObjectList.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *667

             51.5.5       TFPGInterfacedObjectList.Add                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *667

             51.5.6       TFPGInterfacedObjectList.Extract                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  6*
 *67

             51.5.7       TFPGInterfacedObjectList.GetEnumerator                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  667

             51.5.8       TFPGInterfacedObjectList.IndexOf                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  6*
 *68

             51.5.9       TFPGInterfacedObjectList.Insert                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *668

             51.5.10      TFPGInterfacedObjectList.Assign                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *668

             51.5.11      TFPGInterfacedObjectList.Remove                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  6*
 *68

             51.5.12      TFPGInterfacedObjectList.Sort                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *669

             51.5.13      TFPGInterfacedObjectList.First               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *669

             51.5.14      TFPGInterfacedObjectList.Last                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *669

             51.5.15      TFPGInterfacedObjectList.Items                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *670

             51.5.16      TFPGInterfacedObjectList.List                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *670

    51.6     TFPGList         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  670

             51.6.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  670

             51.6.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  670

             51.6.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  671

             51.6.4       TFPGList.Create           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  671



                                                                 40

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             51.6.5       TFPGList.Add           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  671

             51.6.6       TFPGList.Extract          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  671

             51.6.7       TFPGList.GetEnumerator                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  671

             51.6.8       TFPGList.IndexOf            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  672

             51.6.9       TFPGList.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  672

             51.6.10      TFPGList.Assign           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  672

             51.6.11      TFPGList.Remove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  672

             51.6.12      TFPGList.Sort          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  673

             51.6.13      TFPGList.First         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  673

             51.6.14      TFPGList.Last          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  673

             51.6.15      TFPGList.Items         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  673

             51.6.16      TFPGList.List        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  674

    51.7     TFPGListEnumerator             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  674

             51.7.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  674

             51.7.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  674

             51.7.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  674

             51.7.4       TFPGListEnumerator.Create                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 674

             51.7.5       TFPGListEnumerator.MoveNext                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *675

             51.7.6       TFPGListEnumerator.Current                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 675

    51.8     TFPGMap          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  675

             51.8.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  675

             51.8.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  675

             51.8.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  676

             51.8.4       TFPGMap.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  676

             51.8.5       TFPGMap.Add            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  676

             51.8.6       TFPGMap.Find           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  676

             51.8.7       TFPGMap.IndexOf             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  677

             51.8.8       TFPGMap.IndexOfData                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  677

             51.8.9       TFPGMap.InsertKey              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  677

             51.8.10      TFPGMap.InsertKeyData                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  677

             51.8.11      TFPGMap.Remove              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  678

             51.8.12      TFPGMap.Keys           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  678

             51.8.13      TFPGMap.Data           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  678

             51.8.14      TFPGMap.KeyData                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  679

             51.8.15      TFPGMap.OnCompare                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  679

             51.8.16      TFPGMap.OnKeyCompare                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 679

             51.8.17      TFPGMap.OnDataCompare                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 680

    51.9     TFPGMapInterfacedObjectData                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  680

             51.9.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  680

             51.9.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  680



                                                                 41

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             51.9.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  681

             51.9.4       TFPGMapInterfacedObjectData.Create                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  681

             51.9.5       TFPGMapInterfacedObjectData.Add                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  6*
 *81

             51.9.6       TFPGMapInterfacedObjectData.Find                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  6*
 *81

             51.9.7       TFPGMapInterfacedObjectData.IndexOf                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  682

             51.9.8       TFPGMapInterfacedObjectData.IndexOfData                          .  .  .  .  .  .  .  .  .  .  .  .  682

             51.9.9       TFPGMapInterfacedObjectData.InsertKey                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  682

             51.9.10      TFPGMapInterfacedObjectData.InsertKeyData                          .  .  .  .  .  .  .  .  .  .  .  682

             51.9.11      TFPGMapInterfacedObjectData.Remove                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  683

             51.9.12      TFPGMapInterfacedObjectData.Keys                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  683

             51.9.13      TFPGMapInterfacedObjectData.Data                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  683

             51.9.14      TFPGMapInterfacedObjectData.KeyData                         .  .  .  .  .  .  .  .  .  .  .  .  .  .  684

             51.9.15      TFPGMapInterfacedObjectData.OnCompare                            .  .  .  .  .  .  .  .  .  .  .  .  684

             51.9.16      TFPGMapInterfacedObjectData.OnKeyCompare                              .  .  .  .  .  .  .  .  .  .  684

             51.9.17      TFPGMapInterfacedObjectData.OnDataCompare                             .  .  .  .  .  .  .  .  .  .  685

    51.10    TFPGObjectList             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  685

             51.10.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  685

             51.10.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  685

             51.10.3      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  685

             51.10.4      TFPGObjectList.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  686

             51.10.5      TFPGObjectList.Add             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  686

             51.10.6      TFPGObjectList.Extract              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  686

             51.10.7      TFPGObjectList.GetEnumerator                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *686

             51.10.8      TFPGObjectList.IndexOf                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  687

             51.10.9      TFPGObjectList.Insert            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  687

             51.10.10     TFPGObjectList.Assign               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  687

             51.10.11     TFPGObjectList.Remove               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  687

             51.10.12     TFPGObjectList.Sort            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  688

             51.10.13     TFPGObjectList.First             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  688

             51.10.14     TFPGObjectList.Last            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  688

             51.10.15     TFPGObjectList.Items             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  688

             51.10.16     TFPGObjectList.List            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  689

             51.10.17     TFPGObjectList.FreeObjects                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 689

    51.11    TFPSList      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  689

             51.11.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  689

             51.11.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  690

             51.11.3      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  690

             51.11.4      TFPSList.Create           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  690

             51.11.5      TFPSList.Destroy          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  690

             51.11.6      TFPSList.Add         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  691



                                                                 42

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             51.11.7      TFPSList.Clear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  691

             51.11.8      TFPSList.Delete        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  691

             51.11.9      TFPSList.Error         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  691

             51.11.10     TFPSList.Exchange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  692

             51.11.11     TFPSList.Expand           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  692

             51.11.12     TFPSList.Extract          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  692

             51.11.13     TFPSList.IndexOf          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  692

             51.11.14     TFPSList.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  693

             51.11.15     TFPSList.Move          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  693

             51.11.16     TFPSList.Assign           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  693

             51.11.17     TFPSList.Remove           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  694

             51.11.18     TFPSList.Pack          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  694

             51.11.19     TFPSList.Sort        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  694

             51.11.20     TFPSList.Capacity           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  695

             51.11.21     TFPSList.Count         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  695

             51.11.22     TFPSList.Items         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  695

             51.11.23     TFPSList.ItemSize           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  696

             51.11.24     TFPSList.List        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  696

             51.11.25     TFPSList.First         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  696

             51.11.26     TFPSList.Last        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  696

    51.12    TFPSMap          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  697

             51.12.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  697

             51.12.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  697

             51.12.3      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  697

             51.12.4      TFPSMap.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  697

             51.12.5      TFPSMap.Add            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  698

             51.12.6      TFPSMap.Find           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  698

             51.12.7      TFPSMap.IndexOf             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  698

             51.12.8      TFPSMap.IndexOfData                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  699

             51.12.9      TFPSMap.Insert            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  699

             51.12.10     TFPSMap.InsertKey              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  699

             51.12.11     TFPSMap.InsertKeyData                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  699

             51.12.12     TFPSMap.Remove              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  700

             51.12.13     TFPSMap.Sort           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  700

             51.12.14     TFPSMap.Duplicates             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  700

             51.12.15     TFPSMap.KeySize             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  701

             51.12.16     TFPSMap.DataSize            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  701

             51.12.17     TFPSMap.Keys           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  701

             51.12.18     TFPSMap.Data           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  701

             51.12.19     TFPSMap.KeyData             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  702



                                                                 43

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             51.12.20     TFPSMap.Sorted            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  702

             51.12.21     TFPSMap.OnPtrCompare                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  702

             51.12.22     TFPSMap.OnKeyPtrCompare                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 702

             51.12.23     TFPSMap.OnDataPtrCompare                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *703


52   Reference for unit 'fpwidestring'                                                                                  704

    52.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  704

    52.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  704

    52.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  705

             52.3.1       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  705

    52.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  705

             52.4.1       GetActiveCollation          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  705

             52.4.2       SetActiveCollation          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  705


53   Reference for unit 'getopts'                                                                                       706

    53.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  706

    53.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  706

             53.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  706

             53.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  707

             53.2.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  707

    53.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  708

             53.3.1       GetLongOpts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  708

             53.3.2       GetOpt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  708


54   Reference for unit 'go32'                                                                                          711

    54.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  711

    54.2     Real mode callbacks          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  711

    54.3     Executing software interrupts               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  712

    54.4     Software interrupts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  714

    54.5     Hardware interrupts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  714

    54.6     Disabling interrupts         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  716

    54.7     Creating your own interrupt handlers                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 716

    54.8     Protected mode interrupts vs.  Real mode interrupts                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  716

    54.9     Handling interrupts with DPMI                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  717

    54.10    Interrupt redirection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  717

    54.11    Processor access        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  717

    54.12    I/O port access         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  717

    54.13    dos memory access            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  717

    54.14    FPC specialities        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  718

    54.15    Selectors and descriptors           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  718

    54.16    What is DPMI          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  718



                                                                 44

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    54.17    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  718

             54.17.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  718

             54.17.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  721

             54.17.3      Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  724

    54.18    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  724

             54.18.1      allocate_ldt_descriptors         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  724

             54.18.2      allocate_memory_block            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  726

             54.18.3      copyfromdos       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  727

             54.18.4      copytodos       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  727

             54.18.5      create_code_segment_alias_descriptor              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  7*
 *27

             54.18.6      disable    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  728

             54.18.7      dpmi_dosmemfillchar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  728

             54.18.8      dpmi_dosmemfillword            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  728

             54.18.9      dpmi_dosmemget            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  729

             54.18.10     dpmi_dosmemmove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  729

             54.18.11     dpmi_dosmemput            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  729

             54.18.12     enable     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  729

             54.18.13     free_ldt_descriptor       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  730

             54.18.14     free_linear_addr_mapping            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  730

             54.18.15     free_memory_block           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  730

             54.18.16     free_rm_callback       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  731

             54.18.17     get_cs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  731

             54.18.18     get_descriptor_access_right           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  731

             54.18.19     get_dpmi_version       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  732

             54.18.20     get_ds   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  732

             54.18.21     get_exception_handler          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  732

             54.18.22     get_linear_addr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  732

             54.18.23     get_meminfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  733

             54.18.24     get_next_selector_increment_value               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *734

             54.18.25     get_page_attributes         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  734

             54.18.26     get_page_size     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  734

             54.18.27     get_pm_exception_handler            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  735

             54.18.28     get_pm_interrupt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  735

             54.18.29     get_rm_callback        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  736

             54.18.30     get_rm_interrupt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  739

             54.18.31     get_run_mode         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  739

             54.18.32     get_segment_base_address            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  740

             54.18.33     get_segment_limit         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  740

             54.18.34     get_ss   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  740

             54.18.35     global_dos_alloc       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  741



                                                                 45

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             54.18.36     global_dos_free      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  742

             54.18.37     inportb    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  743

             54.18.38     inportl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  743

             54.18.39     inportw    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  743

             54.18.40     lock_code     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  744

             54.18.41     lock_data     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  744

             54.18.42     lock_linear_region        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  744

             54.18.43     map_device_in_memory_block              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 745

             54.18.44     outportb      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  745

             54.18.45     outportl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  746

             54.18.46     outportw      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  746

             54.18.47     realintr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  746

             54.18.48     request_linear_region          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  747

             54.18.49     segment_to_descriptor          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  747

             54.18.50     seg_fillchar    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  748

             54.18.51     seg_fillword    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  749

             54.18.52     seg_move      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  749

             54.18.53     set_descriptor_access_right           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  750

             54.18.54     set_exception_handler          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  750

             54.18.55     set_page_attributes         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  750

             54.18.56     set_pm_exception_handler            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  750

             54.18.57     set_pm_interrupt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  750

             54.18.58     set_rm_interrupt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  752

             54.18.59     set_segment_base_address            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  752

             54.18.60     set_segment_limit         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  752

             54.18.61     tb_offset     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  753

             54.18.62     tb_segment      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  753

             54.18.63     tb_size    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  753

             54.18.64     transfer_buffer      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  754

             54.18.65     unlock_code       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  754

             54.18.66     unlock_data       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  754

             54.18.67     unlock_linear_region        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  755


55   Reference for unit 'gpm'                                                                                           756

    55.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  756

    55.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  756

    55.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  756

             55.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  756

             55.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  758

             55.3.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  760



                                                                 46

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    55.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  761

             55.4.1       Gpm_AnyDouble             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  761

             55.4.2       Gpm_AnySingle          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  761

             55.4.3       Gpm_AnyTriple          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  761

             55.4.4       gpm_close       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  762

             55.4.5       gpm_fitvalues        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  762

             55.4.6       gpm_fitvaluesM         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  762

             55.4.7       gpm_getevent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  762

             55.4.8       gpm_getsnapshot           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  764

             55.4.9       gpm_lowerroi      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  764

             55.4.10      gpm_open        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  764

             55.4.11      gpm_poproi        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  765

             55.4.12      gpm_pushroi       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  765

             55.4.13      gpm_raiseroi      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  765

             55.4.14      gpm_repeat      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  765

             55.4.15      Gpm_StrictDouble          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  766

             55.4.16      Gpm_StrictSingle          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  766

             55.4.17      Gpm_StrictTriple          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  766


56   Reference for unit 'Graph'                                                                                         767

    56.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  767

    56.2     Categorized functions:  Text and font handling                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  7*
 *67

    56.3     Categorized functions:  Filled drawings                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 767

    56.4     Categorized functions:  Drawing primitives                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *768

    56.5     Categorized functions:  Color management                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *768

    56.6     Categorized functions:  Screen management                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *769

    56.7     Categorized functions:  Initialization             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  769

    56.8     Target specific issues:  Linux           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  770

    56.9     Target specific issues:  DOS           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  771

    56.10    A word about mode selection              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  771

    56.11    Requirements          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  775

    56.12    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  776

             56.12.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  776

             56.12.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  792

             56.12.3      Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  797

    56.13    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  800

             56.13.1      Arc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  800

             56.13.2      Bar   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  800

             56.13.3      Bar3D      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  800

             56.13.4      ClearDevice       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  801



                                                                 47

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             56.13.5      Closegraph      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  801

             56.13.6      DetectGraph       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  801

             56.13.7      DrawPoly        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  801

             56.13.8      Ellipse    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  802

             56.13.9      FillEllipse     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  802

             56.13.10     FillPoly   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  802

             56.13.11     FloodFill     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  803

             56.13.12     GetArcCoords         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  803

             56.13.13     GetAspectRatio         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  803

             56.13.14     GetColor      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  803

             56.13.15     GetDefaultPalette         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  804

             56.13.16     GetDirectVideo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  804

             56.13.17     GetDriverName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  804

             56.13.18     GetFillPattern       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  804

             56.13.19     GetFillSettings        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  805

             56.13.20     GetGraphMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  805

             56.13.21     GetLineSettings        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  805

             56.13.22     GetMaxColor          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  805

             56.13.23     GetMaxMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  806

             56.13.24     GetMaxX         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  806

             56.13.25     GetMaxY         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  806

             56.13.26     GetModeName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  806

             56.13.27     GetModeRange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  807

             56.13.28     GetPalette      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  807

             56.13.29     GetPaletteSize       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  807

             56.13.30     GetTextSettings        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  807

             56.13.31     GetViewSettings        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  808

             56.13.32     GetX     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  808

             56.13.33     GetY     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  808

             56.13.34     GraphDefaults        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  808

             56.13.35     GraphErrorMsg          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  809

             56.13.36     GraphResult       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  809

             56.13.37     InitGraph       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  809

             56.13.38     InstallUserDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  810

             56.13.39     InstallUserFont        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  810

             56.13.40     LineRel    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  810

             56.13.41     LineTo     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  811

             56.13.42     MoveRel       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  811

             56.13.43     MoveTo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  811

             56.13.44     OutText       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  812



                                                                 48

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             56.13.45     PieSlice   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  812

             56.13.46     queryadapterinfo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  812

             56.13.47     Rectangle       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  812

             56.13.48     RegisterBGIDriver           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  813

             56.13.49     RegisterBGIfont        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  813

             56.13.50     RestoreCrtMode         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  813

             56.13.51     Sector     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  813

             56.13.52     SetAspectRatio         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  814

             56.13.53     SetColor      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  814

             56.13.54     SetDirectVideo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  814

             56.13.55     SetFillPattern       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  814

             56.13.56     SetFillStyle      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  815

             56.13.57     SetGraphMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  815

             56.13.58     SetLineStyle      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  815

             56.13.59     SetPalette      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  816

             56.13.60     SetTextJustify       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  816

             56.13.61     SetTextStyle      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  817

             56.13.62     SetUserCharSize        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  817

             56.13.63     SetViewPort       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  818

             56.13.64     SetWriteMode         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  818

             56.13.65     TextHeight      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  818

             56.13.66     TextWidth       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  818


57   Reference for unit 'heaptrc'                                                                                       820

    57.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  820

    57.2     Controlling HeapTrc with environment variables                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  820

    57.3     HeapTrc Usage         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  821

    57.4     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  822

             57.4.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  822

             57.4.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  823

    57.5     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  823

             57.5.1       CheckPointer         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  823

             57.5.2       DumpHeap        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  824

             57.5.3       SetHeapExtraInfo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  824

             57.5.4       SetHeapTraceOutput             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  825


58   Reference for unit 'ipc'                                                                                           826

    58.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  826

    58.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  826

    58.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  826

             58.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  826



                                                                 49

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             58.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  828

    58.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  831

             58.4.1       ftok  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  831

             58.4.2       msgctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  832

             58.4.3       msgget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  834

             58.4.4       msgrcv     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  835

             58.4.5       msgsnd     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  835

             58.4.6       semctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  836

             58.4.7       semget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  841

             58.4.8       semop      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  841

             58.4.9       shmat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  842

             58.4.10      shmctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  842

             58.4.11      shmdt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  845

             58.4.12      shmget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  845


59   Reference for unit 'keyboard'                                                                                      846

    59.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  846

    59.2     Unix specific notes        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  846

    59.3     Writing a keyboard driver              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  847

    59.4     Keyboard scan codes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  850

    59.5     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  852

             59.5.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  852

             59.5.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  857

    59.6     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  858

             59.6.1       AddSequence          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  858

             59.6.2       AddSpecialSequence             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  858

             59.6.3       DoneKeyboard         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  859

             59.6.4       FindSequence         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  859

             59.6.5       FunctionKeyName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  859

             59.6.6       GetKeyboardDriver           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  860

             59.6.7       GetKeyEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  860

             59.6.8       GetKeyEventChar           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  861

             59.6.9       GetKeyEventCode             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  862

             59.6.10      GetKeyEventFlags            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  862

             59.6.11      GetKeyEventShiftState            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  863

             59.6.12      GetKeyEventUniCode               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  863

             59.6.13      InitKeyboard         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  864

             59.6.14      IsFunctionKey        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  864

             59.6.15      KeyEventToString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  865

             59.6.16      KeyPressed        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  865



                                                                 50

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             59.6.17      PollKeyEvent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  865

             59.6.18      PollShiftStateEvent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  866

             59.6.19      PutKeyEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  867

             59.6.20      RawReadKey           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  868

             59.6.21      RawReadString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  868

             59.6.22      RestoreStartMode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  868

             59.6.23      SetKeyboardDriver           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  868

             59.6.24      ShiftStateToString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  869

             59.6.25      TranslateKeyEvent           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  869

             59.6.26      TranslateKeyEventUniCode                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 869


60   Reference for unit 'lineinfo'                                                                                      870

    60.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  870

    60.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  870

             60.2.1       CloseStabs      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  870

             60.2.2       GetLineInfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  870

             60.2.3       StabBackTraceStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  870


61   Reference for unit 'Linux'                                                                                         872

    61.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  872

    61.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  872

    61.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  872

             61.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  872

             61.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  886

    61.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  888

             61.4.1       capget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  888

             61.4.2       capset     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  889

             61.4.3       clock_getres      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  889

             61.4.4       clock_gettime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  889

             61.4.5       clock_settime     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  889

             61.4.6       clone    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  890

             61.4.7       epoll_create      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  892

             61.4.8       epoll_ctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  892

             61.4.9       epoll_wait      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  893

             61.4.10      fdatasync     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  893

             61.4.11      futex    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  893

             61.4.12      futex_op      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  894

             61.4.13      inotify_add_watch         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  894

             61.4.14      inotify_init    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  895

             61.4.15      inotify_init1     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  895

             61.4.16      inotify_rm_watch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  896



                                                                 51

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             61.4.17      sched_yield     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  896

             61.4.18      setregid   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  896

             61.4.19      setreuid   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  896

             61.4.20      sync_file_range      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  896

             61.4.21      Sysinfo    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  897


62   Reference for unit 'lnfodwrf '                                                                                     899

    62.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  899

    62.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  899

             62.2.1       GetLineInfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  899


63   Reference for unit 'math'                                                                                          900

    63.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  900

    63.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  900

    63.3     Cash flow functions          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  900

    63.4     Geometrical functions          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  901

    63.5     Statistical functions        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  901

    63.6     Number converting            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  902

    63.7     Exponential and logarithmic functions                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 902

    63.8     Hyperbolic functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  902

    63.9     Trigoniometric functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  903

    63.10    Angle unit conversion          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  903

    63.11    Min/max determination             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  903

    63.12    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  904

             63.12.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  904

             63.12.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  905

    63.13    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  906

             63.13.1      arccos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  906

             63.13.2      arccosh    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  907

             63.13.3      arcosh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  907

             63.13.4      arcsin   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  908

             63.13.5      arcsinh    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  908

             63.13.6      arctan2    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  909

             63.13.7      arctanh    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  909

             63.13.8      arsinh   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  909

             63.13.9      artanh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  910

             63.13.10     ceil  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  910

             63.13.11     ClearExceptions        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  911

             63.13.12     CompareValue         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  911

             63.13.13     cosecant      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  912

             63.13.14     cosh  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  912



                                                                 52

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             63.13.15     cot   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  912

             63.13.16     cotan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  913

             63.13.17     csc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  913

             63.13.18     cycletorad      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  913

             63.13.19     DegNormalize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  914

             63.13.20     degtograd       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  914

             63.13.21     degtorad      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  915

             63.13.22     DivMod        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  915

             63.13.23     EnsureRange       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  915

             63.13.24     floor    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  916

             63.13.25     Frexp    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  916

             63.13.26     FutureValue       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  917

             63.13.27     GetExceptionMask            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  917

             63.13.28     GetPrecisionMode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  917

             63.13.29     GetRoundMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  918

             63.13.30     gradtodeg       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  918

             63.13.31     gradtorad       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  918

             63.13.32     hypot    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  919

             63.13.33     ifthen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  919

             63.13.34     InRange       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  920

             63.13.35     InterestRate      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  920

             63.13.36     intpower      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  920

             63.13.37     IsInfinite    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  921

             63.13.38     IsNan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  921

             63.13.39     IsZero     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  921

             63.13.40     ldexp    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  922

             63.13.41     lnxp1    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  922

             63.13.42     log10    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  923

             63.13.43     log2  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  923

             63.13.44     logn  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  924

             63.13.45     Max      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  924

             63.13.46     MaxIntValue       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  925

             63.13.47     maxvalue      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  926

             63.13.48     mean     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  927

             63.13.49     meanandstddev          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  928

             63.13.50     Min   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  928

             63.13.51     MinIntValue       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  929

             63.13.52     minvalue      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  930

             63.13.53     momentskewkurtosis             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  931

             63.13.54     norm     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  932



                                                                 53

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             63.13.55     NumberOfPeriods           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  933

             63.13.56     Payment       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  933

             63.13.57     popnstddev        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  933

             63.13.58     popnvariance      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  934

             63.13.59     power    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  935

             63.13.60     power(Float,Float):Float            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  936

             63.13.61     power(Int64,Int64):Int64            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  936

             63.13.62     PresentValue      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  936

             63.13.63     radtocycle      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  936

             63.13.64     radtodeg      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  937

             63.13.65     radtograd       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  937

             63.13.66     randg    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  938

             63.13.67     RandomFrom           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  938

             63.13.68     RandomRange          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  939

             63.13.69     RoundTo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  939

             63.13.70     SameValue       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  939

             63.13.71     sec   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  940

             63.13.72     secant     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  940

             63.13.73     SetExceptionMask          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  940

             63.13.74     SetPrecisionMode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  940

             63.13.75     SetRoundMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  940

             63.13.76     Sign  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  941

             63.13.77     SimpleRoundTo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  941

             63.13.78     sincos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  941

             63.13.79     sinh  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  942

             63.13.80     stddev     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  942

             63.13.81     sum   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  943

             63.13.82     sumInt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  944

             63.13.83     sumofsquares      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  944

             63.13.84     sumsandsquares         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  945

             63.13.85     tan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  946

             63.13.86     tanh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  947

             63.13.87     totalvariance     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  947

             63.13.88     variance      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  948

    63.14    EInvalidArgument           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  949

             63.14.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  949


64   Reference for unit 'matrix'                                                                                        950

    64.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  950

    64.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  951



                                                                 54

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.2.1       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  951

    64.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  953

             64.3.1       add(Tmatrix2_double,Double):Tmatrix2_double                        .  .  .  .  .  .  .  .  .  .  .  953

             64.3.2       add(Tmatrix2_double,Tmatrix2_double):Tmatrix2_double                            .  .  .  .  .  .  953

             64.3.3       add(Tmatrix2_extended,extended):Tmatrix2_extended                            .  .  .  .  .  .  .  954

             64.3.4       add(Tmatrix2_extended,Tmatrix2_extended):Tmatrix2_extended                               .  .  954

             64.3.5       add(Tmatrix2_single,single):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  954

             64.3.6       add(Tmatrix2_single,Tmatrix2_single):Tmatrix2_single                         .  .  .  .  .  .  .  954

             64.3.7       add(Tmatrix3_double,Double):Tmatrix3_double                        .  .  .  .  .  .  .  .  .  .  .  954

             64.3.8       add(Tmatrix3_double,Tmatrix3_double):Tmatrix3_double                            .  .  .  .  .  .  955

             64.3.9       add(Tmatrix3_extended,extended):Tmatrix3_extended                            .  .  .  .  .  .  .  955

             64.3.10      add(Tmatrix3_extended,Tmatrix3_extended):Tmatrix3_extended                               .  .  955

             64.3.11      add(Tmatrix3_single,single):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  955

             64.3.12      add(Tmatrix3_single,Tmatrix3_single):Tmatrix3_single                         .  .  .  .  .  .  .  955

             64.3.13      add(Tmatrix4_double,Double):Tmatrix4_double                        .  .  .  .  .  .  .  .  .  .  .  956

             64.3.14      add(Tmatrix4_double,Tmatrix4_double):Tmatrix4_double                            .  .  .  .  .  .  956

             64.3.15      add(Tmatrix4_extended,extended):Tmatrix4_extended                            .  .  .  .  .  .  .  956

             64.3.16      add(Tmatrix4_extended,Tmatrix4_extended):Tmatrix4_extended                               .  .  956

             64.3.17      add(Tmatrix4_single,single):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  956

             64.3.18      add(Tmatrix4_single,Tmatrix4_single):Tmatrix4_single                         .  .  .  .  .  .  .  957

             64.3.19      add(Tvector2_double,Double):Tvector2_double                      .  .  .  .  .  .  .  .  .  .  .  .  957

             64.3.20      add(Tvector2_double,Tvector2_double):Tvector2_double                         .  .  .  .  .  .  .  957

             64.3.21      add(Tvector2_extended,extended):Tvector2_extended                          .  .  .  .  .  .  .  .  957

             64.3.22      add(Tvector2_extended,Tvector2_extended):Tvector2_extended                             .  .  .  957

             64.3.23      add(Tvector2_single,single):Tvector2_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  958

             64.3.24      add(Tvector2_single,Tvector2_single):Tvector2_single                       .  .  .  .  .  .  .  .  958

             64.3.25      add(Tvector3_double,Double):Tvector3_double                      .  .  .  .  .  .  .  .  .  .  .  .  958

             64.3.26      add(Tvector3_double,Tvector3_double):Tvector3_double                         .  .  .  .  .  .  .  958

             64.3.27      add(Tvector3_extended,extended):Tvector3_extended                          .  .  .  .  .  .  .  .  958

             64.3.28      add(Tvector3_extended,Tvector3_extended):Tvector3_extended                             .  .  .  959

             64.3.29      add(Tvector3_single,single):Tvector3_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  959

             64.3.30      add(Tvector3_single,Tvector3_single):Tvector3_single                       .  .  .  .  .  .  .  .  959

             64.3.31      add(Tvector4_double,Double):Tvector4_double                      .  .  .  .  .  .  .  .  .  .  .  .  959

             64.3.32      add(Tvector4_double,Tvector4_double):Tvector4_double                         .  .  .  .  .  .  .  959

             64.3.33      add(Tvector4_extended,extended):Tvector4_extended                          .  .  .  .  .  .  .  .  960

             64.3.34      add(Tvector4_extended,Tvector4_extended):Tvector4_extended                             .  .  .  960

             64.3.35      add(Tvector4_single,single):Tvector4_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  960

             64.3.36      add(Tvector4_single,Tvector4_single):Tvector4_single                       .  .  .  .  .  .  .  .  960

             64.3.37      assign(Tmatrix2_double):Tmatrix2_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  960

             64.3.38      assign(Tmatrix2_double):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  961



                                                                 55

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.3.39      assign(Tmatrix2_double):Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  961

             64.3.40      assign(Tmatrix2_double):Tmatrix3_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  961

             64.3.41      assign(Tmatrix2_double):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  961

             64.3.42      assign(Tmatrix2_double):Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  962

             64.3.43      assign(Tmatrix2_double):Tmatrix4_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  962

             64.3.44      assign(Tmatrix2_double):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  962

             64.3.45      assign(Tmatrix2_extended):Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  962

             64.3.46      assign(Tmatrix2_extended):Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  963

             64.3.47      assign(Tmatrix2_extended):Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  963

             64.3.48      assign(Tmatrix2_extended):Tmatrix3_extended                      .  .  .  .  .  .  .  .  .  .  .  .  963

             64.3.49      assign(Tmatrix2_extended):Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  963

             64.3.50      assign(Tmatrix2_extended):Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  964

             64.3.51      assign(Tmatrix2_extended):Tmatrix4_extended                      .  .  .  .  .  .  .  .  .  .  .  .  964

             64.3.52      assign(Tmatrix2_extended):Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  964

             64.3.53      assign(Tmatrix2_single):Tmatrix2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  964

             64.3.54      assign(Tmatrix2_single):Tmatrix2_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  964

             64.3.55      assign(Tmatrix2_single):Tmatrix3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  965

             64.3.56      assign(Tmatrix2_single):Tmatrix3_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  965

             64.3.57      assign(Tmatrix2_single):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  965

             64.3.58      assign(Tmatrix2_single):Tmatrix4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  965

             64.3.59      assign(Tmatrix2_single):Tmatrix4_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  966

             64.3.60      assign(Tmatrix2_single):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  966

             64.3.61      assign(Tmatrix3_double):Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  966

             64.3.62      assign(Tmatrix3_double):Tmatrix2_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  966

             64.3.63      assign(Tmatrix3_double):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  967

             64.3.64      assign(Tmatrix3_double):Tmatrix3_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  967

             64.3.65      assign(Tmatrix3_double):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  967

             64.3.66      assign(Tmatrix3_double):Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  967

             64.3.67      assign(Tmatrix3_double):Tmatrix4_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  967

             64.3.68      assign(Tmatrix3_double):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  968

             64.3.69      assign(Tmatrix3_extended):Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  968

             64.3.70      assign(Tmatrix3_extended):Tmatrix2_extended                      .  .  .  .  .  .  .  .  .  .  .  .  968

             64.3.71      assign(Tmatrix3_extended):Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  968

             64.3.72      assign(Tmatrix3_extended):Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  969

             64.3.73      assign(Tmatrix3_extended):Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  969

             64.3.74      assign(Tmatrix3_extended):Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  969

             64.3.75      assign(Tmatrix3_extended):Tmatrix4_extended                      .  .  .  .  .  .  .  .  .  .  .  .  969

             64.3.76      assign(Tmatrix3_extended):Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  969

             64.3.77      assign(Tmatrix3_single):Tmatrix2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  970

             64.3.78      assign(Tmatrix3_single):Tmatrix2_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  970



                                                                 56

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.3.79      assign(Tmatrix3_single):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  970

             64.3.80      assign(Tmatrix3_single):Tmatrix3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  970

             64.3.81      assign(Tmatrix3_single):Tmatrix3_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  971

             64.3.82      assign(Tmatrix3_single):Tmatrix4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  971

             64.3.83      assign(Tmatrix3_single):Tmatrix4_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  971

             64.3.84      assign(Tmatrix3_single):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  971

             64.3.85      assign(Tmatrix4_double):Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  971

             64.3.86      assign(Tmatrix4_double):Tmatrix2_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  972

             64.3.87      assign(Tmatrix4_double):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  972

             64.3.88      assign(Tmatrix4_double):Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  972

             64.3.89      assign(Tmatrix4_double):Tmatrix3_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  972

             64.3.90      assign(Tmatrix4_double):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  973

             64.3.91      assign(Tmatrix4_double):Tmatrix4_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  973

             64.3.92      assign(Tmatrix4_double):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  973

             64.3.93      assign(Tmatrix4_extended):Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  973

             64.3.94      assign(Tmatrix4_extended):Tmatrix2_extended                      .  .  .  .  .  .  .  .  .  .  .  .  973

             64.3.95      assign(Tmatrix4_extended):Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  974

             64.3.96      assign(Tmatrix4_extended):Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  974

             64.3.97      assign(Tmatrix4_extended):Tmatrix3_extended                      .  .  .  .  .  .  .  .  .  .  .  .  974

             64.3.98      assign(Tmatrix4_extended):Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  974

             64.3.99      assign(Tmatrix4_extended):Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  975

             64.3.100     assign(Tmatrix4_extended):Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  .  .  975

             64.3.101     assign(Tmatrix4_single):Tmatrix2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  975

             64.3.102     assign(Tmatrix4_single):Tmatrix2_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  975

             64.3.103     assign(Tmatrix4_single):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  975

             64.3.104     assign(Tmatrix4_single):Tmatrix3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  976

             64.3.105     assign(Tmatrix4_single):Tmatrix3_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  976

             64.3.106     assign(Tmatrix4_single):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  976

             64.3.107     assign(Tmatrix4_single):Tmatrix4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  976

             64.3.108     assign(Tmatrix4_single):Tmatrix4_extended                     .  .  .  .  .  .  .  .  .  .  .  .  .  977

             64.3.109     assign(Tvector2_double):Tvector2_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  977

             64.3.110     assign(Tvector2_double):Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  977

             64.3.111     assign(Tvector2_double):Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  977

             64.3.112     assign(Tvector2_double):Tvector3_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  977

             64.3.113     assign(Tvector2_double):Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  978

             64.3.114     assign(Tvector2_double):Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  978

             64.3.115     assign(Tvector2_double):Tvector4_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  978

             64.3.116     assign(Tvector2_double):Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  978

             64.3.117     assign(Tvector2_extended):Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  979

             64.3.118     assign(Tvector2_extended):Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  979



                                                                 57

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.3.119     assign(Tvector2_extended):Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  979

             64.3.120     assign(Tvector2_extended):Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  .  .  979

             64.3.121     assign(Tvector2_extended):Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  979

             64.3.122     assign(Tvector2_extended):Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  980

             64.3.123     assign(Tvector2_extended):Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  .  .  980

             64.3.124     assign(Tvector2_extended):Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  980

             64.3.125     assign(Tvector2_single):Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  980

             64.3.126     assign(Tvector2_single):Tvector2_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  980

             64.3.127     assign(Tvector2_single):Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  981

             64.3.128     assign(Tvector2_single):Tvector3_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  981

             64.3.129     assign(Tvector2_single):Tvector3_single                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  981

             64.3.130     assign(Tvector2_single):Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  981

             64.3.131     assign(Tvector2_single):Tvector4_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  982

             64.3.132     assign(Tvector2_single):Tvector4_single                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  982

             64.3.133     assign(Tvector3_double):Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  982

             64.3.134     assign(Tvector3_double):Tvector2_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  982

             64.3.135     assign(Tvector3_double):Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  983

             64.3.136     assign(Tvector3_double):Tvector3_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  983

             64.3.137     assign(Tvector3_double):Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  983

             64.3.138     assign(Tvector3_double):Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  983

             64.3.139     assign(Tvector3_double):Tvector4_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  983

             64.3.140     assign(Tvector3_double):Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  984

             64.3.141     assign(Tvector3_extended):Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  984

             64.3.142     assign(Tvector3_extended):Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  .  .  984

             64.3.143     assign(Tvector3_extended):Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  984

             64.3.144     assign(Tvector3_extended):Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  985

             64.3.145     assign(Tvector3_extended):Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  985

             64.3.146     assign(Tvector3_extended):Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  985

             64.3.147     assign(Tvector3_extended):Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  .  .  985

             64.3.148     assign(Tvector3_extended):Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  986

             64.3.149     assign(Tvector3_single):Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  986

             64.3.150     assign(Tvector3_single):Tvector2_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  986

             64.3.151     assign(Tvector3_single):Tvector2_single                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  986

             64.3.152     assign(Tvector3_single):Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  987

             64.3.153     assign(Tvector3_single):Tvector3_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  987

             64.3.154     assign(Tvector3_single):Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  987

             64.3.155     assign(Tvector3_single):Tvector4_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  987

             64.3.156     assign(Tvector3_single):Tvector4_single                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  987

             64.3.157     assign(Tvector4_double):Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  988

             64.3.158     assign(Tvector4_double):Tvector2_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  988



                                                                 58

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.3.159     assign(Tvector4_double):Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  988

             64.3.160     assign(Tvector4_double):Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  988

             64.3.161     assign(Tvector4_double):Tvector3_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  989

             64.3.162     assign(Tvector4_double):Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  989

             64.3.163     assign(Tvector4_double):Tvector4_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  989

             64.3.164     assign(Tvector4_double):Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  989

             64.3.165     assign(Tvector4_extended):Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  989

             64.3.166     assign(Tvector4_extended):Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  .  .  990

             64.3.167     assign(Tvector4_extended):Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  990

             64.3.168     assign(Tvector4_extended):Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  990

             64.3.169     assign(Tvector4_extended):Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  .  .  990

             64.3.170     assign(Tvector4_extended):Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  991

             64.3.171     assign(Tvector4_extended):Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  991

             64.3.172     assign(Tvector4_extended):Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  991

             64.3.173     assign(Tvector4_single):Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  991

             64.3.174     assign(Tvector4_single):Tvector2_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  992

             64.3.175     assign(Tvector4_single):Tvector2_single                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  992

             64.3.176     assign(Tvector4_single):Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  992

             64.3.177     assign(Tvector4_single):Tvector3_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  992

             64.3.178     assign(Tvector4_single):Tvector3_single                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  993

             64.3.179     assign(Tvector4_single):Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  993

             64.3.180     assign(Tvector4_single):Tvector4_extended                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  993

             64.3.181     divide(Tmatrix2_double,Double):Tmatrix2_double                        .  .  .  .  .  .  .  .  .  .  993

             64.3.182     divide(Tmatrix2_extended,extended):Tmatrix2_extended                            .  .  .  .  .  .  993

             64.3.183     divide(Tmatrix2_single,single):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  994

             64.3.184     divide(Tmatrix3_double,Double):Tmatrix3_double                        .  .  .  .  .  .  .  .  .  .  994

             64.3.185     divide(Tmatrix3_extended,extended):Tmatrix3_extended                            .  .  .  .  .  .  994

             64.3.186     divide(Tmatrix3_single,single):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  994

             64.3.187     divide(Tmatrix4_double,Double):Tmatrix4_double                        .  .  .  .  .  .  .  .  .  .  994

             64.3.188     divide(Tmatrix4_extended,extended):Tmatrix4_extended                            .  .  .  .  .  .  995

             64.3.189     divide(Tmatrix4_single,single):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  995

             64.3.190     divide(Tvector2_double,Double):Tvector2_double                     .  .  .  .  .  .  .  .  .  .  .  995

             64.3.191     divide(Tvector2_extended,extended):Tvector2_extended                         .  .  .  .  .  .  .  995

             64.3.192     divide(Tvector2_single,single):Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  995

             64.3.193     divide(Tvector3_double,Double):Tvector3_double                     .  .  .  .  .  .  .  .  .  .  .  996

             64.3.194     divide(Tvector3_extended,extended):Tvector3_extended                         .  .  .  .  .  .  .  996

             64.3.195     divide(Tvector3_single,single):Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  996

             64.3.196     divide(Tvector4_double,Double):Tvector4_double                     .  .  .  .  .  .  .  .  .  .  .  996

             64.3.197     divide(Tvector4_extended,extended):Tvector4_extended                         .  .  .  .  .  .  .  996

             64.3.198     divide(Tvector4_single,single):Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  997



                                                                 59

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.3.199     multiply(Tmatrix2_double,Double):Tmatrix2_double                        .  .  .  .  .  .  .  .  .  997

             64.3.200     multiply(Tmatrix2_double,Tmatrix2_double):Tmatrix2_double                              .  .  .  997

             64.3.201     multiply(Tmatrix2_double,Tvector2_double):Tvector2_double                           .  .  .  .  997

             64.3.202     multiply(Tmatrix2_extended,extended):Tmatrix2_extended                            .  .  .  .  .  997

             64.3.203     multiply(Tmatrix2_extended,Tmatrix2_extended):Tmatrix2_extended                                998

             64.3.204     multiply(Tmatrix2_extended,Tvector2_extended):Tvector2_extended                                998

             64.3.205     multiply(Tmatrix2_single,single):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  998

             64.3.206     multiply(Tmatrix2_single,Tmatrix2_single):Tmatrix2_single                         .  .  .  .  .  998

             64.3.207     multiply(Tmatrix2_single,Tvector2_single):Tvector2_single                         .  .  .  .  .  998

             64.3.208     multiply(Tmatrix3_double,Double):Tmatrix3_double                        .  .  .  .  .  .  .  .  .  999

             64.3.209     multiply(Tmatrix3_double,Tmatrix3_double):Tmatrix3_double                              .  .  .  999

             64.3.210     multiply(Tmatrix3_double,Tvector3_double):Tvector3_double                           .  .  .  .  999

             64.3.211     multiply(Tmatrix3_extended,extended):Tmatrix3_extended                            .  .  .  .  .  999

             64.3.212     multiply(Tmatrix3_extended,Tmatrix3_extended):Tmatrix3_extended                               1000

             64.3.213     multiply(Tmatrix3_extended,Tvector3_extended):Tvector3_extended                               1000

             64.3.214     multiply(Tmatrix3_single,single):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  1000

             64.3.215     multiply(Tmatrix3_single,Tmatrix3_single):Tmatrix3_single                         .  .  .  .  .  1000

             64.3.216     multiply(Tmatrix3_single,Tvector3_single):Tvector3_single                         .  .  .  .  .  1000

             64.3.217     multiply(Tmatrix4_double,Double):Tmatrix4_double                        .  .  .  .  .  .  .  .  .  1001

             64.3.218     multiply(Tmatrix4_double,Tmatrix4_double):Tmatrix4_double                              .  .  .  1001

             64.3.219     multiply(Tmatrix4_double,Tvector4_double):Tvector4_double                           .  .  .  .  1001

             64.3.220     multiply(Tmatrix4_extended,extended):Tmatrix4_extended                            .  .  .  .  .  1001

             64.3.221     multiply(Tmatrix4_extended,Tmatrix4_extended):Tmatrix4_extended                               1002

             64.3.222     multiply(Tmatrix4_extended,Tvector4_extended):Tvector4_extended                               1002

             64.3.223     multiply(Tmatrix4_single,single):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  1002

             64.3.224     multiply(Tmatrix4_single,Tmatrix4_single):Tmatrix4_single                         .  .  .  .  .  1002

             64.3.225     multiply(Tmatrix4_single,Tvector4_single):Tvector4_single                         .  .  .  .  .  1002

             64.3.226     multiply(Tvector2_double,Double):Tvector2_double                        .  .  .  .  .  .  .  .  .  1003

             64.3.227     multiply(Tvector2_double,Tvector2_double):Tvector2_double                           .  .  .  .  1003

             64.3.228     multiply(Tvector2_extended,extended):Tvector2_extended                            .  .  .  .  .  1003

             64.3.229     multiply(Tvector2_extended,Tvector2_extended):Tvector2_extended                               1003

             64.3.230     multiply(Tvector2_single,single):Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  1004

             64.3.231     multiply(Tvector2_single,Tvector2_single):Tvector2_single                       .  .  .  .  .  .  1004

             64.3.232     multiply(Tvector3_double,Double):Tvector3_double                        .  .  .  .  .  .  .  .  .  1004

             64.3.233     multiply(Tvector3_double,Tvector3_double):Tvector3_double                           .  .  .  .  1004

             64.3.234     multiply(Tvector3_extended,extended):Tvector3_extended                            .  .  .  .  .  1004

             64.3.235     multiply(Tvector3_extended,Tvector3_extended):Tvector3_extended                               1005

             64.3.236     multiply(Tvector3_single,single):Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  1005

             64.3.237     multiply(Tvector3_single,Tvector3_single):Tvector3_single                       .  .  .  .  .  .  1005

             64.3.238     multiply(Tvector4_double,Double):Tvector4_double                        .  .  .  .  .  .  .  .  .  1005



                                                                 60

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.3.239     multiply(Tvector4_double,Tvector4_double):Tvector4_double                           .  .  .  .  1005

             64.3.240     multiply(Tvector4_extended,extended):Tvector4_extended                            .  .  .  .  .  1006

             64.3.241     multiply(Tvector4_extended,Tvector4_extended):Tvector4_extended                               1006

             64.3.242     multiply(Tvector4_single,single):Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  1006

             64.3.243     multiply(Tvector4_single,Tvector4_single):Tvector4_single                       .  .  .  .  .  .  1006

             64.3.244     negative(Tmatrix2_double):Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  1006

             64.3.245     negative(Tmatrix2_extended):Tmatrix2_extended                         .  .  .  .  .  .  .  .  .  .  1007

             64.3.246     negative(Tmatrix2_single):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  1007

             64.3.247     negative(Tmatrix3_double):Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  1007

             64.3.248     negative(Tmatrix3_extended):Tmatrix3_extended                         .  .  .  .  .  .  .  .  .  .  1007

             64.3.249     negative(Tmatrix3_single):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  1007

             64.3.250     negative(Tmatrix4_double):Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  .  .  1007

             64.3.251     negative(Tmatrix4_extended):Tmatrix4_extended                         .  .  .  .  .  .  .  .  .  .  1008

             64.3.252     negative(Tmatrix4_single):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  1008

             64.3.253     negative(Tvector2_double):Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  1008

             64.3.254     negative(Tvector2_extended):Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  .  1008

             64.3.255     negative(Tvector2_single):Tvector2_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  10*
 *08

             64.3.256     negative(Tvector3_double):Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  1009

             64.3.257     negative(Tvector3_extended):Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  .  1009

             64.3.258     negative(Tvector3_single):Tvector3_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  10*
 *09

             64.3.259     negative(Tvector4_double):Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  1009

             64.3.260     negative(Tvector4_extended):Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  .  1009

             64.3.261     negative(Tvector4_single):Tvector4_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  10*
 *10

             64.3.262     power(Tvector2_double,Tvector2_double):Double                      .  .  .  .  .  .  .  .  .  .  .  1010

             64.3.263     power(Tvector2_extended,Tvector2_extended):extended                          .  .  .  .  .  .  .  1010

             64.3.264     power(Tvector2_single,Tvector2_single):single                 .  .  .  .  .  .  .  .  .  .  .  .  .  1010

             64.3.265     power(Tvector3_double,Tvector3_double):Double                      .  .  .  .  .  .  .  .  .  .  .  1010

             64.3.266     power(Tvector3_extended,Tvector3_extended):extended                          .  .  .  .  .  .  .  1011

             64.3.267     power(Tvector3_single,Tvector3_single):single                 .  .  .  .  .  .  .  .  .  .  .  .  .  1011

             64.3.268     power(Tvector4_double,Tvector4_double):Double                      .  .  .  .  .  .  .  .  .  .  .  1011

             64.3.269     power(Tvector4_extended,Tvector4_extended):extended                          .  .  .  .  .  .  .  1011

             64.3.270     power(Tvector4_single,Tvector4_single):single                 .  .  .  .  .  .  .  .  .  .  .  .  .  1011

             64.3.271     subtract(Tmatrix2_double,Double):Tmatrix2_double                        .  .  .  .  .  .  .  .  .  1012

             64.3.272     subtract(Tmatrix2_double,Tmatrix2_double):Tmatrix2_double                              .  .  .  1012

             64.3.273     subtract(Tmatrix2_extended,extended):Tmatrix2_extended                            .  .  .  .  .  1012

             64.3.274     subtract(Tmatrix2_extended,Tmatrix2_extended):Tmatrix2_extended                               1012

             64.3.275     subtract(Tmatrix2_single,single):Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  1012

             64.3.276     subtract(Tmatrix2_single,Tmatrix2_single):Tmatrix2_single                         .  .  .  .  .  1013

             64.3.277     subtract(Tmatrix3_double,Double):Tmatrix3_double                        .  .  .  .  .  .  .  .  .  1013

             64.3.278     subtract(Tmatrix3_double,Tmatrix3_double):Tmatrix3_double                              .  .  .  1013



                                                                 61

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.3.279     subtract(Tmatrix3_extended,extended):Tmatrix3_extended                            .  .  .  .  .  1013

             64.3.280     subtract(Tmatrix3_extended,Tmatrix3_extended):Tmatrix3_extended                               1013

             64.3.281     subtract(Tmatrix3_single,single):Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  1014

             64.3.282     subtract(Tmatrix3_single,Tmatrix3_single):Tmatrix3_single                         .  .  .  .  .  1014

             64.3.283     subtract(Tmatrix4_double,Double):Tmatrix4_double                        .  .  .  .  .  .  .  .  .  1014

             64.3.284     subtract(Tmatrix4_double,Tmatrix4_double):Tmatrix4_double                              .  .  .  1014

             64.3.285     subtract(Tmatrix4_extended,extended):Tmatrix4_extended                            .  .  .  .  .  1014

             64.3.286     subtract(Tmatrix4_extended,Tmatrix4_extended):Tmatrix4_extended                               1015

             64.3.287     subtract(Tmatrix4_single,single):Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  1015

             64.3.288     subtract(Tmatrix4_single,Tmatrix4_single):Tmatrix4_single                         .  .  .  .  .  1015

             64.3.289     subtract(Tvector2_double,Double):Tvector2_double                        .  .  .  .  .  .  .  .  .  1015

             64.3.290     subtract(Tvector2_double,Tvector2_double):Tvector2_double                           .  .  .  .  1015

             64.3.291     subtract(Tvector2_extended,extended):Tvector2_extended                          .  .  .  .  .  .  1016

             64.3.292     subtract(Tvector2_extended,Tvector2_extended):Tvector2_extended                               1016

             64.3.293     subtract(Tvector2_single,single):Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  1016

             64.3.294     subtract(Tvector2_single,Tvector2_single):Tvector2_single                       .  .  .  .  .  .  1016

             64.3.295     subtract(Tvector3_double,Double):Tvector3_double                        .  .  .  .  .  .  .  .  .  1016

             64.3.296     subtract(Tvector3_double,Tvector3_double):Tvector3_double                           .  .  .  .  1017

             64.3.297     subtract(Tvector3_extended,extended):Tvector3_extended                          .  .  .  .  .  .  1017

             64.3.298     subtract(Tvector3_extended,Tvector3_extended):Tvector3_extended                               1017

             64.3.299     subtract(Tvector3_single,single):Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  1017

             64.3.300     subtract(Tvector3_single,Tvector3_single):Tvector3_single                       .  .  .  .  .  .  1017

             64.3.301     subtract(Tvector4_double,Double):Tvector4_double                        .  .  .  .  .  .  .  .  .  1018

             64.3.302     subtract(Tvector4_double,Tvector4_double):Tvector4_double                           .  .  .  .  1018

             64.3.303     subtract(Tvector4_extended,extended):Tvector4_extended                          .  .  .  .  .  .  1018

             64.3.304     subtract(Tvector4_extended,Tvector4_extended):Tvector4_extended                               1018

             64.3.305     subtract(Tvector4_single,single):Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  1018

             64.3.306     subtract(Tvector4_single,Tvector4_single):Tvector4_single                       .  .  .  .  .  .  1019

             64.3.307     symmetricaldifference(Tvector3_double,Tvector3_double):Tvector3_double                              1019

             64.3.308     symmetricaldifference(Tvector3_extended,Tvector3_extended):Tvector3_extended                             *
 *     1019

             64.3.309     symmetricaldifference(Tvector3_single,Tvector3_single):Tvector3_single                          1019

    64.4     Tmatrix2_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1020

             64.4.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1020

             64.4.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1020

             64.4.3       Tmatrix2_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1020

             64.4.4       Tmatrix2_double.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1020

             64.4.5       Tmatrix2_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1020

             64.4.6       Tmatrix2_double.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1021

             64.4.7       Tmatrix2_double.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1021

             64.4.8       Tmatrix2_double.set_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1021



                                                                 62

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.4.9       Tmatrix2_double.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1021

             64.4.10      Tmatrix2_double.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1021

             64.4.11      Tmatrix2_double.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1022

             64.4.12      Tmatrix2_double.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1022

    64.5     Tmatrix2_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1022

             64.5.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1022

             64.5.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1022

             64.5.3       Tmatrix2_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1022

             64.5.4       Tmatrix2_extended.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1023

             64.5.5       Tmatrix2_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1023

             64.5.6       Tmatrix2_extended.get_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1023

             64.5.7       Tmatrix2_extended.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1023

             64.5.8       Tmatrix2_extended.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1023

             64.5.9       Tmatrix2_extended.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1023

             64.5.10      Tmatrix2_extended.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1024

             64.5.11      Tmatrix2_extended.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1024

             64.5.12      Tmatrix2_extended.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1024

    64.6     Tmatrix2_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1024

             64.6.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1024

             64.6.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1024

             64.6.3       Tmatrix2_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1025

             64.6.4       Tmatrix2_single.init_identity           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1025

             64.6.5       Tmatrix2_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1025

             64.6.6       Tmatrix2_single.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1025

             64.6.7       Tmatrix2_single.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1025

             64.6.8       Tmatrix2_single.set_column            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1025

             64.6.9       Tmatrix2_single.set_row          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1026

             64.6.10      Tmatrix2_single.determinant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1026

             64.6.11      Tmatrix2_single.inverse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1026

             64.6.12      Tmatrix2_single.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1026

    64.7     Tmatrix3_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1026

             64.7.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1026

             64.7.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1027

             64.7.3       Tmatrix3_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1027

             64.7.4       Tmatrix3_double.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1027

             64.7.5       Tmatrix3_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1027

             64.7.6       Tmatrix3_double.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1027

             64.7.7       Tmatrix3_double.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1028

             64.7.8       Tmatrix3_double.set_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1028

             64.7.9       Tmatrix3_double.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1028



                                                                 63

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.7.10      Tmatrix3_double.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1028

             64.7.11      Tmatrix3_double.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1028

             64.7.12      Tmatrix3_double.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1028

    64.8     Tmatrix3_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1029

             64.8.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1029

             64.8.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1029

             64.8.3       Tmatrix3_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1029

             64.8.4       Tmatrix3_extended.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1029

             64.8.5       Tmatrix3_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1029

             64.8.6       Tmatrix3_extended.get_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1030

             64.8.7       Tmatrix3_extended.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1030

             64.8.8       Tmatrix3_extended.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1030

             64.8.9       Tmatrix3_extended.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1030

             64.8.10      Tmatrix3_extended.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1030

             64.8.11      Tmatrix3_extended.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1030

             64.8.12      Tmatrix3_extended.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1031

    64.9     Tmatrix3_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1031

             64.9.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1031

             64.9.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1031

             64.9.3       Tmatrix3_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1031

             64.9.4       Tmatrix3_single.init_identity           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1031

             64.9.5       Tmatrix3_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1032

             64.9.6       Tmatrix3_single.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1032

             64.9.7       Tmatrix3_single.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1032

             64.9.8       Tmatrix3_single.set_column            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1032

             64.9.9       Tmatrix3_single.set_row          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1032

             64.9.10      Tmatrix3_single.determinant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1032

             64.9.11      Tmatrix3_single.inverse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1033

             64.9.12      Tmatrix3_single.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1033

    64.10    Tmatrix4_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1033

             64.10.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1033

             64.10.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1033

             64.10.3      Tmatrix4_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1033

             64.10.4      Tmatrix4_double.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1034

             64.10.5      Tmatrix4_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1034

             64.10.6      Tmatrix4_double.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1034

             64.10.7      Tmatrix4_double.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1034

             64.10.8      Tmatrix4_double.set_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1034

             64.10.9      Tmatrix4_double.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1035

             64.10.10     Tmatrix4_double.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1035



                                                                 64

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.10.11     Tmatrix4_double.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1035

             64.10.12     Tmatrix4_double.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1035

    64.11    Tmatrix4_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1035

             64.11.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1035

             64.11.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1036

             64.11.3      Tmatrix4_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1036

             64.11.4      Tmatrix4_extended.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1036

             64.11.5      Tmatrix4_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1036

             64.11.6      Tmatrix4_extended.get_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1036

             64.11.7      Tmatrix4_extended.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1037

             64.11.8      Tmatrix4_extended.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1037

             64.11.9      Tmatrix4_extended.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1037

             64.11.10     Tmatrix4_extended.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1037

             64.11.11     Tmatrix4_extended.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1037

             64.11.12     Tmatrix4_extended.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1038

    64.12    Tmatrix4_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1038

             64.12.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1038

             64.12.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1038

             64.12.3      Tmatrix4_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1038

             64.12.4      Tmatrix4_single.init_identity           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1038

             64.12.5      Tmatrix4_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1039

             64.12.6      Tmatrix4_single.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1039

             64.12.7      Tmatrix4_single.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1039

             64.12.8      Tmatrix4_single.set_column            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1039

             64.12.9      Tmatrix4_single.set_row          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1039

             64.12.10     Tmatrix4_single.determinant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1040

             64.12.11     Tmatrix4_single.inverse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1040

             64.12.12     Tmatrix4_single.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1040

    64.13    Tvector2_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1040

             64.13.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1040

             64.13.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1040

             64.13.3      Tvector2_double.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1040

             64.13.4      Tvector2_double.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1041

             64.13.5      Tvector2_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1041

             64.13.6      Tvector2_double.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1041

             64.13.7      Tvector2_double.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1041

    64.14    Tvector2_extended          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1041

             64.14.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1041

             64.14.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1041

             64.14.3      Tvector2_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1042



                                                                 65

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.14.4      Tvector2_extended.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1042

             64.14.5      Tvector2_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1042

             64.14.6      Tvector2_extended.length            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1042

             64.14.7      Tvector2_extended.squared_length                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1042

    64.15    Tvector2_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1042

             64.15.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1042

             64.15.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1043

             64.15.3      Tvector2_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1043

             64.15.4      Tvector2_single.init_one         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1043

             64.15.5      Tvector2_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1043

             64.15.6      Tvector2_single.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1043

             64.15.7      Tvector2_single.squared_length             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1043

    64.16    Tvector3_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1044

             64.16.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1044

             64.16.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1044

             64.16.3      Tvector3_double.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1044

             64.16.4      Tvector3_double.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1044

             64.16.5      Tvector3_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1044

             64.16.6      Tvector3_double.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1044

             64.16.7      Tvector3_double.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1045

    64.17    Tvector3_extended          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1045

             64.17.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1045

             64.17.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1045

             64.17.3      Tvector3_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1045

             64.17.4      Tvector3_extended.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1045

             64.17.5      Tvector3_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1045

             64.17.6      Tvector3_extended.length            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1046

             64.17.7      Tvector3_extended.squared_length                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1046

    64.18    Tvector3_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1046

             64.18.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1046

             64.18.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1046

             64.18.3      Tvector3_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1046

             64.18.4      Tvector3_single.init_one         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1046

             64.18.5      Tvector3_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1047

             64.18.6      Tvector3_single.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1047

             64.18.7      Tvector3_single.squared_length             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1047

    64.19    Tvector4_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1047

             64.19.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1047

             64.19.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1047

             64.19.3      Tvector4_double.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1047



                                                                 66

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             64.19.4      Tvector4_double.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1048

             64.19.5      Tvector4_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1048

             64.19.6      Tvector4_double.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1048

             64.19.7      Tvector4_double.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1048

    64.20    Tvector4_extended          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1048

             64.20.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1048

             64.20.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1048

             64.20.3      Tvector4_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1049

             64.20.4      Tvector4_extended.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1049

             64.20.5      Tvector4_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1049

             64.20.6      Tvector4_extended.length            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1049

             64.20.7      Tvector4_extended.squared_length                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1049

    64.21    Tvector4_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1049

             64.21.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1049

             64.21.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1050

             64.21.3      Tvector4_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1050

             64.21.4      Tvector4_single.init_one         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1050

             64.21.5      Tvector4_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1050

             64.21.6      Tvector4_single.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1050

             64.21.7      Tvector4_single.squared_length             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1050


65   Reference for unit 'mmx'                                                                                         1051

    65.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1051

    65.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1051

             65.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1051

             65.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1052

    65.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1053

             65.3.1       emms     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1053

             65.3.2       femms      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1053


66   Reference for unit 'Mouse'                                                                                       1054

    66.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1054

    66.2     Writing a custom mouse driver               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1054

    66.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1056

             66.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1056

             66.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1057

             66.3.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1058

    66.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1058

             66.4.1       DetectMouse       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1058

             66.4.2       DoneMouse         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1059

             66.4.3       GetMouseButtons           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1060



                                                                 67

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             66.4.4       GetMouseDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1060

             66.4.5       GetMouseEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1061

             66.4.6       GetMouseX         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1061

             66.4.7       GetMouseY         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1062

             66.4.8       HideMouse       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1062

             66.4.9       InitMouse       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1063

             66.4.10      PollMouseEvent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1063

             66.4.11      PutMouseEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1063

             66.4.12      SetMouseDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1064

             66.4.13      SetMouseXY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1064

             66.4.14      ShowMouse         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1065


67   Reference for unit 'Objects'                                                                                     1066

    67.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1066

    67.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1066

             67.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1066

             67.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1068

             67.2.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1072

    67.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1072

             67.3.1       Abstract      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1072

             67.3.2       CallPointerConstructor           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1072

             67.3.3       CallPointerLocal       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1073

             67.3.4       CallPointerMethod           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1073

             67.3.5       CallPointerMethodLocal              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1073

             67.3.6       CallVoidConstructor            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1074

             67.3.7       CallVoidLocal        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1074

             67.3.8       CallVoidMethod         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1074

             67.3.9       CallVoidMethodLocal            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1075

             67.3.10      DisposeStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1075

             67.3.11      LongDiv       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1075

             67.3.12      LongMul       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1076

             67.3.13      NewStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1076

             67.3.14      RegisterObjects        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1076

             67.3.15      RegisterType         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1077

             67.3.16      SetStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1078

    67.4     TBufStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1079

             67.4.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1079

             67.4.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1079

             67.4.3       TBufStream.Init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1079

             67.4.4       TBufStream.Done           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1080



                                                                 68

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             67.4.5       TBufStream.Close          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1080

             67.4.6       TBufStream.Flush          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1080

             67.4.7       TBufStream.Truncate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1081

             67.4.8       TBufStream.Seek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1081

             67.4.9       TBufStream.Open           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1082

             67.4.10      TBufStream.Read           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1082

             67.4.11      TBufStream.Write          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1082

    67.5     TCollection      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1083

             67.5.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1083

             67.5.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1083

             67.5.3       TCollection.Init       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1083

             67.5.4       TCollection.Load          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1084

             67.5.5       TCollection.Done          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1085

             67.5.6       TCollection.At       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1085

             67.5.7       TCollection.IndexOf            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1086

             67.5.8       TCollection.GetItem            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1087

             67.5.9       TCollection.LastThat           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1087

             67.5.10      TCollection.FirstThat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1088

             67.5.11      TCollection.Pack          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1089

             67.5.12      TCollection.FreeAll         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1089

             67.5.13      TCollection.DeleteAll          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1090

             67.5.14      TCollection.Free       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1091

             67.5.15      TCollection.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1092

             67.5.16      TCollection.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1092

             67.5.17      TCollection.AtFree          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1093

             67.5.18      TCollection.FreeItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1093

             67.5.19      TCollection.AtDelete           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1094

             67.5.20      TCollection.ForEach            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1094

             67.5.21      TCollection.SetLimit           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1095

             67.5.22      TCollection.Error         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1095

             67.5.23      TCollection.AtPut         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1096

             67.5.24      TCollection.AtInsert           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1096

             67.5.25      TCollection.Store         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1097

             67.5.26      TCollection.PutItem            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1097

    67.6     TDosStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1098

             67.6.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1098

             67.6.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1098

             67.6.3       TDosStream.Init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1098

             67.6.4       TDosStream.Done           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1098

             67.6.5       TDosStream.Close          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1099



                                                                 69

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             67.6.6       TDosStream.Truncate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1099

             67.6.7       TDosStream.Seek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1100

             67.6.8       TDosStream.Open             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1101

             67.6.9       TDosStream.Read           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1101

             67.6.10      TDosStream.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1102

    67.7     TMemoryStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1102

             67.7.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1102

             67.7.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1102

             67.7.3       TMemoryStream.Init             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1102

             67.7.4       TMemoryStream.Done               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1103

             67.7.5       TMemoryStream.Truncate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1103

             67.7.6       TMemoryStream.Read               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1104

             67.7.7       TMemoryStream.Write              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1104

    67.8     TObject       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1104

             67.8.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1104

             67.8.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1105

             67.8.3       TObject.Init      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1105

             67.8.4       TObject.Free         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1105

             67.8.5       TObject.Is_Object         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1106

             67.8.6       TObject.Done         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1106

    67.9     TPoint      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  1106

             67.9.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1106

    67.10    TRect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  1106

             67.10.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1106

             67.10.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1107

             67.10.3      TRect.Empty          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1107

             67.10.4      TRect.Equals         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1108

             67.10.5      TRect.Contains         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1108

             67.10.6      TRect.Copy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1108

             67.10.7      TRect.Union       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1109

             67.10.8      TRect.Intersect        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1110

             67.10.9      TRect.Move        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1110

             67.10.10     TRect.Grow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1111

             67.10.11     TRect.Assign         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1112

    67.11    TResourceCollection            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1112

             67.11.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1112

             67.11.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1113

             67.11.3      TResourceCollection.KeyOf               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1113

             67.11.4      TResourceCollection.GetItem                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1113

             67.11.5      TResourceCollection.FreeItem               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1113



                                                                 70

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             67.11.6      TResourceCollection.PutItem                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1114

    67.12    TResourceFile         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1114

             67.12.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1114

             67.12.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1114

             67.12.3      TResourceFile.Init          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1114

             67.12.4      TResourceFile.Done          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1115

             67.12.5      TResourceFile.Count            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1115

             67.12.6      TResourceFile.KeyAt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1115

             67.12.7      TResourceFile.Get           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1115

             67.12.8      TResourceFile.SwitchTo              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1116

             67.12.9      TResourceFile.Flush            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1116

             67.12.10     TResourceFile.Delete           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1116

             67.12.11     TResourceFile.Put           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1116

    67.13    TSortedCollection          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1117

             67.13.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1117

             67.13.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1117

             67.13.3      TSortedCollection.Init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1117

             67.13.4      TSortedCollection.Load           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1118

             67.13.5      TSortedCollection.KeyOf             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1118

             67.13.6      TSortedCollection.IndexOf             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1118

             67.13.7      TSortedCollection.Compare               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1119

             67.13.8      TSortedCollection.Search            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1119

             67.13.9      TSortedCollection.Insert            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1121

             67.13.10     TSortedCollection.Store             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1122

    67.14    TStrCollection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1122

             67.14.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1122

             67.14.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1122

             67.14.3      TStrCollection.Compare              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1122

             67.14.4      TStrCollection.GetItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1123

             67.14.5      TStrCollection.FreeItem             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1123

             67.14.6      TStrCollection.PutItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1124

    67.15    TStream       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1124

             67.15.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1124

             67.15.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1125

             67.15.3      TStream.Init      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1125

             67.15.4      TStream.Get       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1125

             67.15.5      TStream.StrRead           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1126

             67.15.6      TStream.GetPos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1127

             67.15.7      TStream.GetSize           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1127

             67.15.8      TStream.ReadStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1128



                                                                 71

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             67.15.9      TStream.Open         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1128

             67.15.10     TStream.Close        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1129

             67.15.11     TStream.Reset        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1129

             67.15.12     TStream.Flush        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1129

             67.15.13     TStream.Truncate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1130

             67.15.14     TStream.Put       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1130

             67.15.15     TStream.StrWrite          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1130

             67.15.16     TStream.WriteStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1131

             67.15.17     TStream.Seek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1131

             67.15.18     TStream.Error        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1131

             67.15.19     TStream.Read         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1131

             67.15.20     TStream.Write        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1132

             67.15.21     TStream.CopyFrom            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1132

    67.16    TStringCollection          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1133

             67.16.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1133

             67.16.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1133

             67.16.3      TStringCollection.GetItem             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1134

             67.16.4      TStringCollection.Compare             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1134

             67.16.5      TStringCollection.FreeItem            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1135

             67.16.6      TStringCollection.PutItem             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1135

    67.17    TStringList      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1135

             67.17.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1135

             67.17.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1135

             67.17.3      TStringList.Load          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1136

             67.17.4      TStringList.Done          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1136

             67.17.5      TStringList.Get        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1136

    67.18    TStrListMaker         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1136

             67.18.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1136

             67.18.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1137

             67.18.3      TStrListMaker.Init          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1137

             67.18.4      TStrListMaker.Done             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1137

             67.18.5      TStrListMaker.Put           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1137

             67.18.6      TStrListMaker.Store            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1138

    67.19    TUnSortedStrCollection              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1138

             67.19.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1138

             67.19.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1138

             67.19.3      TUnSortedStrCollection.Insert              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1138


68   Reference for unit 'objpas'                                                                                      1140

    68.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1140



                                                                 72

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    68.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1140

             68.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1140

             68.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1140


69   Reference for unit 'ports'                                                                                       1142

    69.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1142

    69.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1142

             69.2.1       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1142

    69.3     tport     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  1143

             69.3.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1143

             69.3.2       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1143

             69.3.3       tport.pp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1143

    69.4     tportl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  1144

             69.4.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1144

             69.4.2       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1144

             69.4.3       tportl.pp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1144

    69.5     tportw      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  1144

             69.5.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1144

             69.5.2       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1144

             69.5.3       tportw.pp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1144


70   Reference for unit 'printer'                                                                                     1145

    70.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1145

    70.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1145

             70.2.1       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1145

    70.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1145

             70.3.1       AssignLst       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1145

             70.3.2       InitPrinter     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1146

             70.3.3       IsLstAvailable       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1146


71   Reference for unit 'sharemem'                                                                                    1147

    71.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1147


72   Reference for unit 'Sockets'                                                                                     1148

    72.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1148

    72.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1148

    72.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1148

             72.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1148

             72.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1169

    72.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1173

             72.4.1       Accept     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1173



                                                                 73

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             72.4.2       Bind     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1174

             72.4.3       CloseSocket       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1175

             72.4.4       Connect       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1175

             72.4.5       fpaccept      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1177

             72.4.6       fpbind     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1178

             72.4.7       fpconnect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1179

             72.4.8       fpgetpeername        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1180

             72.4.9       fpgetsockname        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1181

             72.4.10      fpgetsockopt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1181

             72.4.11      fplisten   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1182

             72.4.12      fprecv   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1182

             72.4.13      fprecvfrom      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1183

             72.4.14      fpsend     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1183

             72.4.15      fpsendto      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1184

             72.4.16      fpsetsockopt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1184

             72.4.17      fpshutdown        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1184

             72.4.18      fpsocket      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1185

             72.4.19      fpsocketpair      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1185

             72.4.20      HostAddrToStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1186

             72.4.21      HostAddrToStr6         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1186

             72.4.22      HostToNet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1186

             72.4.23      htonl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1186

             72.4.24      htons    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1187

             72.4.25      NetAddrToStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1187

             72.4.26      NetAddrToStr6          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1187

             72.4.27      NetToHost       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1187

             72.4.28      NToHl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1188

             72.4.29      NToHs      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1188

             72.4.30      ShortHostToNet         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1188

             72.4.31      ShortNetToHost         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1188

             72.4.32      Sock2File     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1189

             72.4.33      Sock2Text       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1189

             72.4.34      socketerror     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1189

             72.4.35      Str2UnixSockAddr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1189

             72.4.36      StrToHostAddr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1190

             72.4.37      StrToHostAddr6         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1190

             72.4.38      StrToNetAddr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1190

             72.4.39      StrToNetAddr6          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1190


73   Reference for unit 'strings'                                                                                     1191



                                                                 74

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    73.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1191

    73.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1191

             73.2.1       stralloc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1191

             73.2.2       strcat   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1191

             73.2.3       strcomp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1192

             73.2.4       strcopy    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1192

             73.2.5       strdispose      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1193

             73.2.6       strecopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1193

             73.2.7       strend     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1194

             73.2.8       stricomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1195

             73.2.9       stripos    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1195

             73.2.10      striscan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1196

             73.2.11      strlcat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1196

             73.2.12      strlcomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1197

             73.2.13      strlcopy   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1197

             73.2.14      strlen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1198

             73.2.15      strlicomp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1198

             73.2.16      strlower   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1199

             73.2.17      strmove    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1199

             73.2.18      strnew     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1200

             73.2.19      strpas   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1201

             73.2.20      strpcopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1201

             73.2.21      strpos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1202

             73.2.22      strriscan     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1202

             73.2.23      strrscan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1203

             73.2.24      strscan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1203

             73.2.25      strupper      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1203


74   Reference for unit 'strutils'                                                                                    1204

    74.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1204

    74.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1204

             74.2.1       Resource strings       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1204

             74.2.2       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1204

             74.2.3       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1205

    74.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1206

             74.3.1       AddChar       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1206

             74.3.2       AddCharR        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1206

             74.3.3       AnsiContainsStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1207

             74.3.4       AnsiContainsText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1207

             74.3.5       AnsiEndsStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1207



                                                                 75

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             74.3.6       AnsiEndsText         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1207

             74.3.7       AnsiIndexStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1208

             74.3.8       AnsiIndexText        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1208

             74.3.9       AnsiLeftStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1208

             74.3.10      AnsiMatchStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1209

             74.3.11      AnsiMatchText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1209

             74.3.12      AnsiMidStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1209

             74.3.13      AnsiProperCase         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1209

             74.3.14      AnsiReplaceStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1210

             74.3.15      AnsiReplaceText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1210

             74.3.16      AnsiResemblesText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1210

             74.3.17      AnsiReverseString         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1210

             74.3.18      AnsiRightStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1211

             74.3.19      AnsiStartsStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1211

             74.3.20      AnsiStartsText         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1211

             74.3.21      BinToHex        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1212

             74.3.22      Copy2Space        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1212

             74.3.23      Copy2SpaceDel          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1212

             74.3.24      Copy2Symb         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1213

             74.3.25      Copy2SymbDel           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1213

             74.3.26      Dec2Numb        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1213

             74.3.27      DecodeSoundexInt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1213

             74.3.28      DecodeSoundexWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1214

             74.3.29      DelChars      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1214

             74.3.30      DelSpace      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1214

             74.3.31      DelSpace1       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1215

             74.3.32      DupeString      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1215

             74.3.33      ExtractDelimited          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1215

             74.3.34      ExtractSubstr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1216

             74.3.35      ExtractWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1216

             74.3.36      ExtractWordPos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1216

             74.3.37      FindPart      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1217

             74.3.38      GetCmdLineArg          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1217

             74.3.39      Hex2Dec       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1218

             74.3.40      HexToBin        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1218

             74.3.41      IfThen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1218

             74.3.42      IntToBin      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1218

             74.3.43      IntToRoman        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1219

             74.3.44      IsEmptyStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1219

             74.3.45      IsWild     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1219



                                                                 76

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             74.3.46      IsWordPresent        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1220

             74.3.47      LeftBStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1220

             74.3.48      LeftStr    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1220

             74.3.49      MidBStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1221

             74.3.50      MidStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1221

             74.3.51      NPos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1221

             74.3.52      Numb2Dec        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1222

             74.3.53      Numb2USA          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1222

             74.3.54      PadCenter       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1222

             74.3.55      PadLeft       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1222

             74.3.56      PadRight      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1223

             74.3.57      PosEx      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1223

             74.3.58      PosSet     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1223

             74.3.59      PosSetEx      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1223

             74.3.60      RandomFrom           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1224

             74.3.61      Removeleadingchars          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1224

             74.3.62      RemovePadChars            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1224

             74.3.63      RemoveTrailingChars            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1225

             74.3.64      ReplaceStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1225

             74.3.65      ReplaceText       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1225

             74.3.66      ReverseString        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1225

             74.3.67      RightBStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1226

             74.3.68      RightStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1226

             74.3.69      RomanToInt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1226

             74.3.70      RomanToIntDef          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1227

             74.3.71      RPos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1227

             74.3.72      RPosex     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1227

             74.3.73      SearchBuf       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1227

             74.3.74      Soundex       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1228

             74.3.75      SoundexCompare            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1228

             74.3.76      SoundexInt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1229

             74.3.77      SoundexProc       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1229

             74.3.78      SoundexSimilar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1229

             74.3.79      SoundexWord          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1230

             74.3.80      StringsReplace       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1230

             74.3.81      StuffString     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1230

             74.3.82      Tab2Space       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1231

             74.3.83      TrimLeftSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1231

             74.3.84      TrimRightSet         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1231

             74.3.85      TrimSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1232



                                                                 77

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             74.3.86      TryRomanToInt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1232

             74.3.87      WordCount         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1232

             74.3.88      WordPosition         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1232

             74.3.89      XorDecode       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1233

             74.3.90      XorEncode       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1233

             74.3.91      XorString       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1233


75   Reference for unit 'System'                                                                                      1235

    75.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1235

    75.2     Unicode and codepage support                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1235

    75.3     Miscellaneous functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1236

    75.4     Operating System functions               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1237

    75.5     String handling         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1237

    75.6     Mathematical routines             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1238

    75.7     Memory management functions                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1239

    75.8     File handling functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1239

    75.9     Run-Time Error behaviour               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1240

    75.10    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1240

             75.10.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1240

             75.10.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1265

             75.10.3      Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1299

    75.11    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1303

             75.11.1      abs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1303

             75.11.2      AbstractError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1303

             75.11.3      AcquireExceptionObject              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1303

             75.11.4      add(variant,variant):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1304

             75.11.5      AddExitProc       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1304

             75.11.6      Addr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1304

             75.11.7      Align    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1305

             75.11.8      AllocMem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1305

             75.11.9      AnsiToUtf8        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1305

             75.11.10     Append     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1306

             75.11.11     arctan     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1306

             75.11.12     ArrayStringToPPchar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1307

             75.11.13     Assert     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1307

             75.11.14     Assign     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1307

             75.11.15     assign(ansistring):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1308

             75.11.16     assign(ansistring):variant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1308

             75.11.17     assign(Boolean):olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1309

             75.11.18     assign(Boolean):variant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1309



                                                                 78

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.19     assign(Byte):olevariant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1309

             75.11.20     assign(Byte):variant        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1309

             75.11.21     assign(Char):olevariant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1309

             75.11.22     assign(Char):variant        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1310

             75.11.23     assign(comp):olevariant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1310

             75.11.24     assign(comp):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1310

             75.11.25     assign(currency):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1310

             75.11.26     assign(currency):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1310

             75.11.27     assign(Double):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1310

             75.11.28     assign(Double):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1311

             75.11.29     assign(DWord):olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1311

             75.11.30     assign(DWord):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1311

             75.11.31     assign(extended):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1311

             75.11.32     assign(extended):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1311

             75.11.33     assign(Int64):olevariant         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1311

             75.11.34     assign(Int64):variant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1312

             75.11.35     assign(longbool):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1312

             75.11.36     assign(longbool):variant         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1312

             75.11.37     assign(LongInt):olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1312

             75.11.38     assign(LongInt):variant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1312

             75.11.39     assign(olevariant):ansistring           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1312

             75.11.40     assign(olevariant):Boolean            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1313

             75.11.41     assign(olevariant):Byte          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1313

             75.11.42     assign(olevariant):Char          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1313

             75.11.43     assign(olevariant):comp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1313

             75.11.44     assign(olevariant):currency           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1313

             75.11.45     assign(olevariant):Double           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1313

             75.11.46     assign(olevariant):DWord            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1314

             75.11.47     assign(olevariant):extended           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1314

             75.11.48     assign(olevariant):Int64         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1314

             75.11.49     assign(olevariant):longbool           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1314

             75.11.50     assign(olevariant):LongInt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1314

             75.11.51     assign(olevariant):QWord            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1314

             75.11.52     assign(olevariant):Real          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1315

             75.11.53     assign(olevariant):ShortInt           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1315

             75.11.54     assign(olevariant):shortstring          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1315

             75.11.55     assign(olevariant):single        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1315

             75.11.56     assign(olevariant):SmallInt           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1315

             75.11.57     assign(olevariant):TDateTime               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1315

             75.11.58     assign(olevariant):TError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1316



                                                                 79

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.59     assign(olevariant):UnicodeString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1316

             75.11.60     assign(olevariant):variant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1316

             75.11.61     assign(olevariant):WideChar             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1316

             75.11.62     assign(olevariant):widestring           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1316

             75.11.63     assign(olevariant):Word          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1316

             75.11.64     assign(olevariant):wordbool           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1317

             75.11.65     assign(QWord):olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1317

             75.11.66     assign(QWord):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1317

             75.11.67     assign(Real):olevariant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1317

             75.11.68     assign(Real):variant        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1317

             75.11.69     assign(real48):Double          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1317

             75.11.70     assign(real48):extended          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1317

             75.11.71     assign(ShortInt):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1318

             75.11.72     assign(ShortInt):variant         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1318

             75.11.73     assign(shortstring):olevariant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1318

             75.11.74     assign(shortstring):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1318

             75.11.75     assign(single):olevariant        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1318

             75.11.76     assign(single):variant         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1318

             75.11.77     assign(SmallInt):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1319

             75.11.78     assign(SmallInt):variant         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1319

             75.11.79     assign(TDateTime):olevariant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1319

             75.11.80     assign(TDateTime):variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1319

             75.11.81     assign(TError):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1319

             75.11.82     assign(TError):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1319

             75.11.83     assign(UCS4String):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1320

             75.11.84     assign(UnicodeString):olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1320

             75.11.85     assign(UnicodeString):variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1320

             75.11.86     assign(UTF8String):variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1320

             75.11.87     assign(variant):ansistring          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1320

             75.11.88     assign(variant):Boolean          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1320

             75.11.89     assign(variant):Byte        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1320

             75.11.90     assign(variant):Char        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1321

             75.11.91     assign(variant):comp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1321

             75.11.92     assign(variant):currency            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1321

             75.11.93     assign(variant):Double           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1321

             75.11.94     assign(variant):DWord            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1321

             75.11.95     assign(variant):extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1321

             75.11.96     assign(variant):Int64          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1322

             75.11.97     assign(variant):longbool         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1322

             75.11.98     assign(variant):LongInt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1322



                                                                 80

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.99     assign(variant):olevariant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1322

             75.11.100    assign(variant):QWord            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1322

             75.11.101    assign(variant):Real        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1322

             75.11.102    assign(variant):ShortInt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1323

             75.11.103    assign(variant):shortstring           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1323

             75.11.104    assign(variant):single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1323

             75.11.105    assign(variant):SmallInt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1323

             75.11.106    assign(variant):TDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1323

             75.11.107    assign(variant):TError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1323

             75.11.108    assign(variant):unicodestring           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1324

             75.11.109    assign(variant):UTF8String              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1324

             75.11.110    assign(variant):WideChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1324

             75.11.111    assign(variant):widestring            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1324

             75.11.112    assign(variant):Word           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1324

             75.11.113    assign(variant):wordbool            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1324

             75.11.114    assign(WideChar):olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1325

             75.11.115    assign(WideChar):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1325

             75.11.116    assign(widestring):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1325

             75.11.117    assign(widestring):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1325

             75.11.118    assign(Word):olevariant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1325

             75.11.119    assign(Word):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1325

             75.11.120    assign(wordbool):olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1326

             75.11.121    assign(wordbool):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1326

             75.11.122    Assigned      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1326

             75.11.123    BasicEventCreate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1327

             75.11.124    basiceventdestroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1327

             75.11.125    basiceventResetEvent           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1327

             75.11.126    basiceventSetEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1327

             75.11.127    basiceventWaitFor         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1327

             75.11.128    BeginThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1328

             75.11.129    BEtoN      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1328

             75.11.130    binStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1328

             75.11.131    BlockRead       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1329

             75.11.132    BlockWrite      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1330

             75.11.133    Break    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1330

             75.11.134    BsfByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1331

             75.11.135    BsfDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1332

             75.11.136    BsfQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1332

             75.11.137    BsfWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1332

             75.11.138    BsrByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1332



                                                                 81

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.139    BsrDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1333

             75.11.140    BsrQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1333

             75.11.141    BsrWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1333

             75.11.142    CaptureBacktrace          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1333

             75.11.143    chdir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1334

             75.11.144    chr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1334

             75.11.145    Close    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1335

             75.11.146    CloseThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1335

             75.11.147    CompareByte          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1335

             75.11.148    CompareChar          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1337

             75.11.149    CompareChar0           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1338

             75.11.150    CompareDWord           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1338

             75.11.151    CompareWord          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1339

             75.11.152    Concat     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1340

             75.11.153    Continue      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1341

             75.11.154    Copy     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1342

             75.11.155    CopyArray       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1342

             75.11.156    cos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1343

             75.11.157    Cseg     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1343

             75.11.158    Dec   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1344

             75.11.159    Default    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1345

             75.11.160    DefaultAnsi2UnicodeMove               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1345

             75.11.161    DefaultAnsi2WideMove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1345

             75.11.162    DefaultUnicode2AnsiMove               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1345

             75.11.163    Delete     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1346

             75.11.164    Dispose    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1346

             75.11.165    divide(variant,variant):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1347

             75.11.166    DoneCriticalsection         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1348

             75.11.167    DoneThread        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1348

             75.11.168    Dseg     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1348

             75.11.169    DumpExceptionBackTrace                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1349

             75.11.170    Dump_Stack        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1349

             75.11.171    DynArrayBounds            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1349

             75.11.172    DynArrayClear          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1349

             75.11.173    DynArrayDim          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1350

             75.11.174    DynArrayIndex          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1350

             75.11.175    DynArraySetLength           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1350

             75.11.176    DynArraySize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1351

             75.11.177    EmptyMethod          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1351

             75.11.178    EndThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1351



                                                                 82

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.179    EnterCriticalsection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1351

             75.11.180    EnumResourceLanguages               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1352

             75.11.181    EnumResourceNames              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1352

             75.11.182    EnumResourceTypes              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1353

             75.11.183    EOF      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1353

             75.11.184    EOLn     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1354

             75.11.185    equal(variant,variant):Boolean             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1354

             75.11.186    Erase    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1355

             75.11.187    Error    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1355

             75.11.188    Exclude       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1355

             75.11.189    Exit  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1357

             75.11.190    exp   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1358

             75.11.191    Fail  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1358

             75.11.192    FilePos    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1359

             75.11.193    FileSize   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1360

             75.11.194    FillByte      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1361

             75.11.195    FillChar      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1361

             75.11.196    FillDWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1362

             75.11.197    FillQWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1362

             75.11.198    FillWord      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1363

             75.11.199    Finalize   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1363

             75.11.200    FinalizeArray        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1364

             75.11.201    FindResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1364

             75.11.202    FindResourceEx         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1364

             75.11.203    float_raise     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1365

             75.11.204    Flush    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1365

             75.11.205    FlushThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1366

             75.11.206    FMADouble         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1366

             75.11.207    FMAExtended          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1366

             75.11.208    FMASingle       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1366

             75.11.209    fpc_dynarray_rangecheck             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1366

             75.11.210    fpc_SarInt64      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1367

             75.11.211    FPower10        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1367

             75.11.212    frac  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1367

             75.11.213    Freemem       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1367

             75.11.214    Freememory        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1368

             75.11.215    FreeResource      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1368

             75.11.216    GetCPUCount          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1368

             75.11.217    GetCurrentThreadId             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1369

             75.11.218    getdir   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1369



                                                                 83

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.219    GetFPCHeapStatus            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1370

             75.11.220    GetHeapStatus          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1370

             75.11.221    GetMem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1370

             75.11.222    GetMemory         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1370

             75.11.223    GetMemoryManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1371

             75.11.224    GetProcessID         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1371

             75.11.225    GetResourceManager             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1371

             75.11.226    GetTextCodePage           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1371

             75.11.227    GetThreadID          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1372

             75.11.228    GetThreadManager            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1372

             75.11.229    GetUnicodeStringManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1372

             75.11.230    GetVariantManager           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1372

             75.11.231    GetWideStringManager             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1373

             75.11.232    get_caller_addr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1373

             75.11.233    get_caller_frame       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1373

             75.11.234    get_caller_stackinfo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1373

             75.11.235    get_cmdline       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1374

             75.11.236    get_frame     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1374

             75.11.237    Get_pc_addr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1374

             75.11.238    greaterthan(variant,variant):Boolean                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *374

             75.11.239    greaterthanorequal(variant,variant):Boolean                   .  .  .  .  .  .  .  .  .  .  .  .  .  1375

             75.11.240    halt  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1375

             75.11.241    hexStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1375

             75.11.242    hi  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1376

             75.11.243    High     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1377

             75.11.244    HINSTANCE            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1378

             75.11.245    Inc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1378

             75.11.246    Include    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1379

             75.11.247    IndexByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1379

             75.11.248    IndexChar       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1380

             75.11.249    IndexChar0        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1381

             75.11.250    IndexDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1381

             75.11.251    IndexQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1382

             75.11.252    Indexword       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1382

             75.11.253    InitCriticalSection       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1383

             75.11.254    Initialize    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1383

             75.11.255    InitializeArray      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1385

             75.11.256    InitThread      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1386

             75.11.257    InitThreadVars         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1386

             75.11.258    Insert   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1386



                                                                 84

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.259    int   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1387

             75.11.260    intdivide(variant,variant):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1387

             75.11.261    InterlockedCompareExchange                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1387

             75.11.262    InterLockedDecrement             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1388

             75.11.263    InterLockedExchange            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1388

             75.11.264    InterLockedExchangeAdd              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1389

             75.11.265    InterLockedIncrement           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1389

             75.11.266    IOResult      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1389

             75.11.267    IsDynArrayRectangular            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1391

             75.11.268    IsMemoryManagerSet             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1391

             75.11.269    Is_IntResource       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1391

             75.11.270    KillThread      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1391

             75.11.271    LeaveCriticalsection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1392

             75.11.272    leftshift(variant,variant):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1392

             75.11.273    Length     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1392

             75.11.274    lessthan(variant,variant):Boolean               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1393

             75.11.275    lessthanorequal(variant,variant):Boolean                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  13*
 *93

             75.11.276    LEtoN      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1394

             75.11.277    ln  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1394

             75.11.278    lo  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1394

             75.11.279    LoadResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1395

             75.11.280    LockResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1395

             75.11.281    logicaland(variant,variant):variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1396

             75.11.282    logicalnot(variant):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1396

             75.11.283    logicalor(variant,variant):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1396

             75.11.284    logicalxor(variant,variant):variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1397

             75.11.285    longjmp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1397

             75.11.286    Low   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1397

             75.11.287    lowerCase       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1398

             75.11.288    MakeLangID        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1398

             75.11.289    MemSize       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1399

             75.11.290    mkdir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1399

             75.11.291    modulus(variant,variant):variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1399

             75.11.292    Move     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1399

             75.11.293    MoveChar0       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1400

             75.11.294    multiply(variant,variant):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1401

             75.11.295    negative(variant):variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1401

             75.11.296    New      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1401

             75.11.297    NtoBE      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1402

             75.11.298    NtoLE      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1402



                                                                 85

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.299    Null  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1402

             75.11.300    OctStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1402

             75.11.301    odd   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1403

             75.11.302    Ofs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1403

             75.11.303    Ord   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1404

             75.11.304    Pack     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1405

             75.11.305    Paramcount        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1405

             75.11.306    ParamStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1406

             75.11.307    pi  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1406

             75.11.308    PopCnt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1407

             75.11.309    Pos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1407

             75.11.310    Power    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1408

             75.11.311    power(variant,variant):variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1408

             75.11.312    Pred     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1409

             75.11.313    prefetch      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1409

             75.11.314    ptr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1409

             75.11.315    RaiseList     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1410

             75.11.316    Random        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1410

             75.11.317    Randomize       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1411

             75.11.318    Read     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1411

             75.11.319    ReadBarrier       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1412

             75.11.320    ReadDependencyBarrier               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1412

             75.11.321    ReadLn     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1413

             75.11.322    ReadStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1413

             75.11.323    ReadWriteBarrier          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1414

             75.11.324    Real2Double       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1414

             75.11.325    ReAllocMem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1415

             75.11.326    ReAllocMemory          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1415

             75.11.327    ReleaseExceptionObject              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1415

             75.11.328    Rename        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1415

             75.11.329    Reset    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1416

             75.11.330    ResumeThread           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1417

             75.11.331    Rewrite    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1417

             75.11.332    rightshift(variant,variant):variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1418

             75.11.333    rmdir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1418

             75.11.334    RolByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1419

             75.11.335    RolDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1419

             75.11.336    RolQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1419

             75.11.337    RolWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1420

             75.11.338    RorByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1420



                                                                 86

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.339    RorDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1420

             75.11.340    RorQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1421

             75.11.341    RorWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1421

             75.11.342    round    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1421

             75.11.343    RTLEventCreate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1422

             75.11.344    RTLeventdestroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1422

             75.11.345    RTLeventResetEvent             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1422

             75.11.346    RTLeventSetEvent            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1423

             75.11.347    RTLeventWaitFor           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1423

             75.11.348    RunError      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1423

             75.11.349    SarInt64      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1424

             75.11.350    SarLongint      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1424

             75.11.351    SarShortint       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1424

             75.11.352    SarSmallint       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1424

             75.11.353    Seek     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1425

             75.11.354    SeekEOF       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1425

             75.11.355    SeekEOLn        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1426

             75.11.356    Seg   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1427

             75.11.357    SemaphoreDestroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1427

             75.11.358    SemaphoreInit        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1428

             75.11.359    SemaphorePost          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1428

             75.11.360    SemaphoreWait          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1428

             75.11.361    SetCodePage       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1429

             75.11.362    Setjmp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1429

             75.11.363    SetLength       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1430

             75.11.364    SetMemoryManager            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1430

             75.11.365    SetMultiByteConversionCodePage                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1430

             75.11.366    SetMultiByteFileSystemCodePage                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1431

             75.11.367    SetMultiByteRTLFileSystemCodePage                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  14*
 *31

             75.11.368    SetResourceManager             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1432

             75.11.369    SetString     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1432

             75.11.370    SetTextBuf      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1432

             75.11.371    SetTextCodePage           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1433

             75.11.372    SetTextLineEnding           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1434

             75.11.373    SetThreadManager            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1434

             75.11.374    SetUnicodeStringManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1434

             75.11.375    SetVariantManager           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1435

             75.11.376    SetWideStringManager             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1435

             75.11.377    ShortCompareText            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1435

             75.11.378    sin   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1436



                                                                 87

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.379    SizeOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1436

             75.11.380    SizeofResource       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1437

             75.11.381    Slice    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1437

             75.11.382    Space    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1437

             75.11.383    Sptr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1438

             75.11.384    sqr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1438

             75.11.385    sqrt  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1439

             75.11.386    Sseg  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1439

             75.11.387    StackTop      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1439

             75.11.388    Str   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1440

             75.11.389    StringCodePage         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1440

             75.11.390    StringElementSize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1441

             75.11.391    StringOfChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1441

             75.11.392    StringRefCount         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1442

             75.11.393    StringToPPChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1442

             75.11.394    StringToUnicodeChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1442

             75.11.395    StringToWideChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1443

             75.11.396    strlen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1443

             75.11.397    strpas   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1443

             75.11.398    subtract(variant,variant):variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1443

             75.11.399    Succ     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1444

             75.11.400    SuspendThread          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1444

             75.11.401    Swap     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1444

             75.11.402    SwapEndian        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1445

             75.11.403    SysAllocMem          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1445

             75.11.404    SysAssert     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1445

             75.11.405    SysBackTraceStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1446

             75.11.406    SysFlushStdIO        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1446

             75.11.407    SysFreemem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1446

             75.11.408    SysFreememSize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1446

             75.11.409    SysGetFPCHeapStatus              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1447

             75.11.410    SysGetHeapStatus          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1447

             75.11.411    SysGetmem         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1447

             75.11.412    SysInitExceptions         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1447

             75.11.413    SysInitFPU        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1448

             75.11.414    SysInitStdIO      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1448

             75.11.415    SysMemSize        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1448

             75.11.416    SysReAllocMem          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1448

             75.11.417    SysResetFPU          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1448

             75.11.418    SysSetCtrlBreakHandler              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1449



                                                                 88

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.419    SysTryResizeMem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1449

             75.11.420    ThreadGetPriority           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1449

             75.11.421    ThreadSetPriority         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1449

             75.11.422    ThreadSwitch         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1450

             75.11.423    ToSingleByteFileSystemEncodedFileName                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  1450

             75.11.424    trunc    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1450

             75.11.425    Truncate      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1451

             75.11.426    TryEnterCriticalsection          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1451

             75.11.427    TypeInfo      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1452

             75.11.428    TypeOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1452

             75.11.429    UCS4StringToUnicodeString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1452

             75.11.430    UCS4StringToWideString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1452

             75.11.431    Unassigned      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1452

             75.11.432    UnicodeCharLenToString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1453

             75.11.433    UnicodeCharLenToStrVar                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1453

             75.11.434    UnicodeCharToString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1453

             75.11.435    UnicodeCharToStrVar              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1454

             75.11.436    UnicodeStringToUCS4String               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1454

             75.11.437    UnicodeToUtf8          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1454

             75.11.438    UniqueString      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1454

             75.11.439    UnlockResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1455

             75.11.440    UnPack     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1455

             75.11.441    upCase     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1455

             75.11.442    Utf8CodePointLen            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1456

             75.11.443    UTF8Decode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1456

             75.11.444    UTF8Encode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1457

             75.11.445    Utf8ToAnsi        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1457

             75.11.446    Utf8ToUnicode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1457

             75.11.447    Val   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1458

             75.11.448    VarArrayGet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1458

             75.11.449    VarArrayPut       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1459

             75.11.450    VarArrayRedim          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1459

             75.11.451    VarCast       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1459

             75.11.452    WaitForThreadTerminate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1460

             75.11.453    WideCharLenToString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1460

             75.11.454    WideCharLenToStrVar              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1460

             75.11.455    WideCharToString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1461

             75.11.456    WideCharToStrVar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1461

             75.11.457    WideStringToUCS4String                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1461

             75.11.458    Write    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1461



                                                                 89

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.11.459    WriteBarrier      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1462

             75.11.460    WriteLn       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1462

             75.11.461    WriteStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1463

    75.12    TDoubleRec         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1464

             75.12.1      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1464

             75.12.2      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1464

             75.12.3      TDoubleRec.Mantissa            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1465

             75.12.4      TDoubleRec.Fraction            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1465

             75.12.5      TDoubleRec.Exponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1465

             75.12.6      TDoubleRec.SpecialType              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1465

             75.12.7      TDoubleRec.Sign           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1465

             75.12.8      TDoubleRec.Exp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1466

             75.12.9      TDoubleRec.Frac           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1466

    75.13    TExtended80Rec             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1466

             75.13.1      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1467

             75.13.2      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1467

             75.13.3      TExtended80Rec.Mantissa               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1467

             75.13.4      TExtended80Rec.Fraction               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1467

             75.13.5      TExtended80Rec.Exponent               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1467

             75.13.6      TExtended80Rec.SpecialType                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1468

             75.13.7      TExtended80Rec.Sign            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1468

             75.13.8      TExtended80Rec.Exp             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1468

    75.14    TSingleRec       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1468

             75.14.1      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1469

             75.14.2      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1469

             75.14.3      TSingleRec.Mantissa            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1469

             75.14.4      TSingleRec.Fraction         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1469

             75.14.5      TSingleRec.Exponent            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1470

             75.14.6      TSingleRec.SpecialType              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1470

             75.14.7      TSingleRec.Sign        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1470

             75.14.8      TSingleRec.Exp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1470

             75.14.9      TSingleRec.Frac        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1470

    75.15    IDispatch     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1471

             75.15.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1471

             75.15.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1471

             75.15.3      IDispatch.GetTypeInfoCount              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1471

             75.15.4      IDispatch.GetTypeInfo            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1471

             75.15.5      IDispatch.GetIDsOfNames               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1471

             75.15.6      IDispatch.Invoke       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1471

    75.16    IEnumerable        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1472



                                                                 90

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.16.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1472

             75.16.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1472

             75.16.3      IEnumerable.GetEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1472

    75.17    IEnumerator        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1472

             75.17.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1472

             75.17.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1473

             75.17.3      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1473

             75.17.4      IEnumerator.GetCurrent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1473

             75.17.5      IEnumerator.MoveNext             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1473

             75.17.6      IEnumerator.Reset           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1474

             75.17.7      IEnumerator.Current            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1474

    75.18    IInvokable       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1474

             75.18.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1474

    75.19    IUnknown         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1474

             75.19.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1474

             75.19.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1474

             75.19.3      IUnknown.QueryInterface               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1475

             75.19.4      IUnknown._AddRef            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1475

             75.19.5      IUnknown._Release           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1475

    75.20    TAggregatedObject            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1475

             75.20.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1475

             75.20.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1475

             75.20.3      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1475

             75.20.4      TAggregatedObject.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1476

             75.20.5      TAggregatedObject.Controller               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1476

    75.21    TContainedObject           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1476

             75.21.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1476

             75.21.2      Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1476

    75.22    TInterfacedObject          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1476

             75.22.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1476

             75.22.2      Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1477

             75.22.3      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1477

             75.22.4      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1477

             75.22.5      TInterfacedObject.AfterConstruction                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *477

             75.22.6      TInterfacedObject.BeforeDestruction                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *477

             75.22.7      TInterfacedObject.NewInstance                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1477

             75.22.8      TInterfacedObject.RefCount              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1478

    75.23    TObject       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1478

             75.23.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1478

             75.23.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1479



                                                                 91

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             75.23.3      TObject.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1479

             75.23.4      TObject.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1480

             75.23.5      TObject.newinstance            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1480

             75.23.6      TObject.FreeInstance           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1480

             75.23.7      TObject.SafeCallException             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1480

             75.23.8      TObject.DefaultHandler              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1481

             75.23.9      TObject.Free         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1481

             75.23.10     TObject.InitInstance           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1481

             75.23.11     TObject.CleanupInstance             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1481

             75.23.12     TObject.ClassType           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1482

             75.23.13     TObject.ClassInfo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1482

             75.23.14     TObject.ClassName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1482

             75.23.15     TObject.ClassNameIs            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1482

             75.23.16     TObject.ClassParent            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1483

             75.23.17     TObject.InstanceSize           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1483

             75.23.18     TObject.InheritsFrom           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1483

             75.23.19     TObject.StringMessageTable              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1483

             75.23.20     TObject.MethodAddress               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1484

             75.23.21     TObject.MethodName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1484

             75.23.22     TObject.FieldAddress           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1484

             75.23.23     TObject.AfterConstruction             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1484

             75.23.24     TObject.BeforeDestruction             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1485

             75.23.25     TObject.DefaultHandlerStr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1485

             75.23.26     TObject.Dispatch          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1485

             75.23.27     TObject.DispatchStr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1485

             75.23.28     TObject.GetInterface           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1486

             75.23.29     TObject.GetInterfaceByStr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1486

             75.23.30     TObject.GetInterfaceWeak              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1486

             75.23.31     TObject.GetInterfaceEntry             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1487

             75.23.32     TObject.GetInterfaceEntryByStr                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1487

             75.23.33     TObject.GetInterfaceTable             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1487

             75.23.34     TObject.UnitName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1487

             75.23.35     TObject.Equals         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1488

             75.23.36     TObject.GetHashCode              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1488

             75.23.37     TObject.ToString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1488


76   Reference for unit 'sysutils'                                                                                    1489

    76.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1489

    76.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1489

    76.3     Localization support           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1489



                                                                 92

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    76.4     Unicode and codepage awareness                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1490

    76.5     Miscellaneous conversion routines                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1491

    76.6     Date/time routines           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1492

    76.7     FileName handling routines               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1492

    76.8     File input/output routines             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1493

    76.9     PChar related functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1494

    76.10    Date and time formatting characters                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1495

    76.11    Formatting strings         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1496

    76.12    String functions        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1496

    76.13    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1497

             76.13.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1497

             76.13.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1504

             76.13.3      Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1513

    76.14    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1518

             76.14.1      AbandonSignalHandler             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1518

             76.14.2      Abort    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1518

             76.14.3      AddDisk       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1519

             76.14.4      AddTerminateProc            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1519

             76.14.5      AdjustLineBreaks          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1519

             76.14.6      AnsiCompareFileName              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1520

             76.14.7      AnsiCompareStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1520

             76.14.8      AnsiCompareText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1521

             76.14.9      AnsiDequotedStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1522

             76.14.10     AnsiExtractQuotedStr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1522

             76.14.11     AnsiLastChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1523

             76.14.12     AnsiLowerCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1524

             76.14.13     AnsiLowerCaseFileName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1524

             76.14.14     AnsiPos       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1525

             76.14.15     AnsiQuotedStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1525

             76.14.16     AnsiSameStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1525

             76.14.17     AnsiSameText         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1525

             76.14.18     AnsiStrComp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1526

             76.14.19     AnsiStrIComp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1526

             76.14.20     AnsiStrLastChar           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1527

             76.14.21     AnsiStrLComp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1528

             76.14.22     AnsiStrLIComp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1529

             76.14.23     AnsiStrLower         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1530

             76.14.24     AnsiStrPos      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1530

             76.14.25     AnsiStrRScan         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1531

             76.14.26     AnsiStrScan       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1531



                                                                 93

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             76.14.27     AnsiStrUpper         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1531

             76.14.28     AnsiUpperCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1532

             76.14.29     AnsiUpperCaseFileName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1532

             76.14.30     AppendStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1533

             76.14.31     ApplicationName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1533

             76.14.32     AssignStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1534

             76.14.33     BCDToInt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1534

             76.14.34     Beep     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1535

             76.14.35     BoolToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1535

             76.14.36     BytesOf       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1535

             76.14.37     ByteToCharIndex           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1535

             76.14.38     ByteToCharLen          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1536

             76.14.39     ByteType        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1536

             76.14.40     CallTerminateProcs          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1536

             76.14.41     ChangeFileExt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1537

             76.14.42     CharInSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1537

             76.14.43     CharToByteLen          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1537

             76.14.44     CodePageNameToCodePage                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1538

             76.14.45     CodePageToCodePageName                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1538

             76.14.46     CompareMem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1538

             76.14.47     CompareMemRange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1538

             76.14.48     CompareStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1539

             76.14.49     CompareText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1540

             76.14.50     ComposeDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1540

             76.14.51     ConcatPaths       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1541

             76.14.52     CreateDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1541

             76.14.53     CreateGUID        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1542

             76.14.54     CurrentYear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1542

             76.14.55     CurrToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1543

             76.14.56     CurrToStrF        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1543

             76.14.57     Date     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1543

             76.14.58     DateTimeToFileDate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1544

             76.14.59     DateTimeToStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1544

             76.14.60     DateTimeToString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1545

             76.14.61     DateTimeToSystemTime                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1546

             76.14.62     DateTimeToTimeStamp                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1547

             76.14.63     DateToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1547

             76.14.64     DayOfWeek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1548

             76.14.65     DecodeDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1548

             76.14.66     DecodeDateFully           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1549



                                                                 94

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             76.14.67     DecodeTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1549

             76.14.68     DeleteFile      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1550

             76.14.69     DirectoryExists        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1550

             76.14.70     DiskFree      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1551

             76.14.71     DiskSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1551

             76.14.72     DisposeStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1552

             76.14.73     DoDirSeparators        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1552

             76.14.74     EncodeDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1553

             76.14.75     EncodeTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1554

             76.14.76     ExceptAddr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1554

             76.14.77     ExceptFrameCount            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1554

             76.14.78     ExceptFrames         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1555

             76.14.79     ExceptionErrorMessage            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1555

             76.14.80     ExceptObject         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1555

             76.14.81     ExcludeLeadingPathDelimiter                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1556

             76.14.82     ExcludeTrailingBackslash            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1556

             76.14.83     ExcludeTrailingPathDelimiter               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1556

             76.14.84     ExecuteProcess         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1557

             76.14.85     ExeSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1557

             76.14.86     ExpandFileName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1558

             76.14.87     ExpandFileNameCase             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1558

             76.14.88     ExpandUNCFileName                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1559

             76.14.89     ExtractFileDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1560

             76.14.90     ExtractFileDrive       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1560

             76.14.91     ExtractFileExt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1561

             76.14.92     ExtractFileName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1561

             76.14.93     ExtractFilePath        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1561

             76.14.94     ExtractRelativepath         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1562

             76.14.95     ExtractShortPathName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1562

             76.14.96     FileAge    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1563

             76.14.97     FileClose     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1563

             76.14.98     FileCreate      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1564

             76.14.99     FileDateToDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1565

             76.14.100    FileExists      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1565

             76.14.101    FileGetAttr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1566

             76.14.102    FileGetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1567

             76.14.103    FileIsReadOnly         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1568

             76.14.104    FileOpen      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1568

             76.14.105    FileRead      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1569

             76.14.106    FileSearch      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1569



                                                                 95

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             76.14.107    FileSeek      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1570

             76.14.108    FileSetAttr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1571

             76.14.109    FileSetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1571

             76.14.110    FileTruncate      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1572

             76.14.111    FileWrite     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1572

             76.14.112    FindClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1573

             76.14.113    FindCmdLineSwitch              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1573

             76.14.114    FindFirst     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1573

             76.14.115    FindNext      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1575

             76.14.116    FloattoCurr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1575

             76.14.117    FloatToDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1575

             76.14.118    FloatToDecimal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1576

             76.14.119    FloatToStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1576

             76.14.120    FloatToStrF       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1577

             76.14.121    FloatToText       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1579

             76.14.122    FloatToTextFmt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1580

             76.14.123    FmtStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1580

             76.14.124    ForceDirectories       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1581

             76.14.125    Format     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1581

             76.14.126    FormatBuf       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1588

             76.14.127    FormatCurr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1589

             76.14.128    FormatDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1589

             76.14.129    FormatFloat       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1590

             76.14.130    FreeAndNil      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1591

             76.14.131    GetAppConfigDir           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1592

             76.14.132    GetAppConfigFile          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1592

             76.14.133    GetCurrentDir        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1593

             76.14.134    GetDirs    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1593

             76.14.135    GetEnvironmentString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1594

             76.14.136    GetEnvironmentVariable              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1595

             76.14.137    GetEnvironmentVariableCount                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1595

             76.14.138    GetFileHandle        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1595

             76.14.139    GetLastOSError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1596

             76.14.140    GetLocalTime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1596

             76.14.141    GetLocalTimeOffset          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1596

             76.14.142    GetModuleName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1596

             76.14.143    GetTempDir        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1597

             76.14.144    GetTempFileName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1597

             76.14.145    GetTickCount         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1597

             76.14.146    GetTickCount64         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1598



                                                                 96

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             76.14.147    GetUserDir        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1598

             76.14.148    GuidCase      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1598

             76.14.149    GUIDToString         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1598

             76.14.150    HashName        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1599

             76.14.151    HookSignal      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1599

             76.14.152    IncAMonth       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1599

             76.14.153    IncludeLeadingPathDelimiter                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1599

             76.14.154    IncludeTrailingBackslash            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1600

             76.14.155    IncludeTrailingPathDelimiter               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1600

             76.14.156    IncMonth        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1600

             76.14.157    InquireSignal     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1601

             76.14.158    IntToHex      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1601

             76.14.159    IntToStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1602

             76.14.160    IsDelimiter     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1603

             76.14.161    IsEqualGUID          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1603

             76.14.162    IsLeapYear      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1603

             76.14.163    IsPathDelimiter        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1604

             76.14.164    IsValidIdent      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1604

             76.14.165    LastDelimiter        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1605

             76.14.166    LeftStr    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1605

             76.14.167    LoadStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1606

             76.14.168    LowerCase       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1606

             76.14.169    MSecsToTimeStamp               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1606

             76.14.170    NewStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1607

             76.14.171    Now      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1607

             76.14.172    OutOfMemoryError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1608

             76.14.173    QuotedStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1608

             76.14.174    RaiseLastOSError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1609

             76.14.175    RemoveDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1609

             76.14.176    RenameFile        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1609

             76.14.177    ReplaceDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1610

             76.14.178    ReplaceTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1610

             76.14.179    RightStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1610

             76.14.180    SafeLoadLibrary        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1611

             76.14.181    SameFileName         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1611

             76.14.182    SameText        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1611

             76.14.183    SetCurrentDir        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1612

             76.14.184    SetDirSeparators          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1612

             76.14.185    ShowException          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1612

             76.14.186    Sleep    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1613



                                                                 97

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             76.14.187    SScanf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1613

             76.14.188    StrAlloc      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1614

             76.14.189    StrBufSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1614

             76.14.190    StrByteType       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1615

             76.14.191    strcat   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1615

             76.14.192    StrCharLength        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1615

             76.14.193    strcomp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1616

             76.14.194    StrCopy       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1616

             76.14.195    StrDispose      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1617

             76.14.196    strecopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1617

             76.14.197    strend     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1617

             76.14.198    StrFmt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1618

             76.14.199    stricomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1619

             76.14.200    StringReplace        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1619

             76.14.201    StringToGUID         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1620

             76.14.202    strlcat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1620

             76.14.203    strlcomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1621

             76.14.204    StrLCopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1621

             76.14.205    StrLen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1622

             76.14.206    StrLFmt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1622

             76.14.207    strlicomp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1623

             76.14.208    strlower   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1623

             76.14.209    strmove    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1624

             76.14.210    strnew     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1625

             76.14.211    StrNextChar       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1625

             76.14.212    StrPas     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1625

             76.14.213    StrPCopy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1626

             76.14.214    StrPLCopy       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1626

             76.14.215    strpos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1626

             76.14.216    strrscan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1627

             76.14.217    strscan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1627

             76.14.218    StrToBool       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1627

             76.14.219    StrToBoolDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1628

             76.14.220    StrToCurr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1628

             76.14.221    StrToCurrDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1628

             76.14.222    StrToDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1629

             76.14.223    StrToDateDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1629

             76.14.224    StrToDateTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1630

             76.14.225    StrToDateTimeDef            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1631

             76.14.226    StrToFloat      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1631



                                                                 98

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             76.14.227    StrToFloatDef        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1632

             76.14.228    StrToInt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1633

             76.14.229    StrToInt64      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1633

             76.14.230    StrToInt64Def        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1634

             76.14.231    StrToIntDef       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1634

             76.14.232    StrToQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1635

             76.14.233    StrToQWordDef          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1635

             76.14.234    StrToTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1635

             76.14.235    StrToTimeDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1636

             76.14.236    strupper      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1636

             76.14.237    Supports      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1636

             76.14.238    SysErrorMessage           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1637

             76.14.239    SystemTimeToDateTime                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1637

             76.14.240    TextToFloat       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1638

             76.14.241    Time     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1639

             76.14.242    TimeStampToDateTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1640

             76.14.243    TimeStampToMSecs               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1640

             76.14.244    TimeToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1641

             76.14.245    Trim     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1641

             76.14.246    TrimLeft      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1642

             76.14.247    TrimRight       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1642

             76.14.248    TryEncodeDate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1643

             76.14.249    TryEncodeTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1643

             76.14.250    TryFloatToCurr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1644

             76.14.251    TryStringToGUID           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1644

             76.14.252    TryStrToBool         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1644

             76.14.253    TryStrToCurr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1645

             76.14.254    TryStrToDate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1645

             76.14.255    TryStrToDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1645

             76.14.256    TryStrToFloat        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1646

             76.14.257    TryStrToInt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1646

             76.14.258    TryStrToInt64        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1647

             76.14.259    TryStrToQWord          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1647

             76.14.260    TryStrToTime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1647

             76.14.261    UnhookSignal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1648

             76.14.262    UpperCase       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1648

             76.14.263    VendorName        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1648

             76.14.264    WideCompareStr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1649

             76.14.265    WideCompareText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1649

             76.14.266    WideFmtStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1649



                                                                 99

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             76.14.267    WideFormat        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1650

             76.14.268    WideFormatBuf          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1650

             76.14.269    WideLowerCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1650

             76.14.270    WideSameStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1651

             76.14.271    WideSameText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1651

             76.14.272    WideUpperCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1651

             76.14.273    WrapText        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1651

    76.15    EAbort      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  1652

             76.15.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1652

    76.16    EAbstractError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1652

             76.16.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1652

    76.17    EAccessViolation           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1652

             76.17.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1652

    76.18    EArgumentException             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1652

             76.18.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1652

    76.19    EArgumentOutOfRangeException                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1652

             76.19.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1652

    76.20    EAssertionFailed        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1653

             76.20.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1653

    76.21    EBusError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1653

             76.21.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1653

    76.22    EControlC        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1653

             76.22.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1653

    76.23    EConvertError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1653

             76.23.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1653

    76.24    EDivByZero         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1653

             76.24.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1653

    76.25    EExternal        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1653

             76.25.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1653

    76.26    EExternalException           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1653

             76.26.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1653

    76.27    EFormatError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1654

             76.27.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1654

    76.28    EHeapMemoryError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1654

             76.28.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1654

             76.28.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1654

             76.28.3      EHeapMemoryError.FreeInstance                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1654

    76.29    EInOutError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1654

             76.29.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1654

    76.30    EInterror     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1654



                                                                 100

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             76.30.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1654

    76.31    EIntfCastError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1655

             76.31.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1655

    76.32    EIntOverflow       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1655

             76.32.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1655

    76.33    EInvalidCast       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1655

             76.33.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1655

    76.34    EInvalidContainer          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1655

             76.34.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1655

    76.35    EInvalidInsert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1655

             76.35.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1655

    76.36    EInvalidOp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1655

             76.36.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1655

    76.37    EInvalidPointer         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1655

             76.37.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1655

    76.38    EMathError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1656

             76.38.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1656

    76.39    ENoConstructException               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1656

             76.39.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1656

    76.40    ENoThreadSupport             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1656

             76.40.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1656

    76.41    ENotImplemented            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1656

             76.41.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1656

    76.42    ENoWideStringSupport              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1656

             76.42.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1656

    76.43    EObjectCheck          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1656

             76.43.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1656

    76.44    EOSError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1657

             76.44.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1657

    76.45    EOutOfMemory            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1657

             76.45.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1657

    76.46    EOverflow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1657

             76.46.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1657

    76.47    EPackageError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1657

             76.47.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1657

    76.48    EPrivilege       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1657

             76.48.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1657

    76.49    EPropReadOnly           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1657

             76.49.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1657

    76.50    EPropWriteOnly          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1657



                                                                 101

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             76.50.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1657

    76.51    ERangeError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1658

             76.51.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1658

    76.52    ESafecallException           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1658

             76.52.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1658

    76.53    EStackOverflow          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1658

             76.53.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1658

    76.54    EUnderflow       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1658

             76.54.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1658

    76.55    EVariantError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1658

             76.55.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1658

             76.55.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1658

             76.55.3      EVariantError.CreateCode              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1658

    76.56    Exception        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1659

             76.56.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1659

             76.56.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1659

             76.56.3      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1659

             76.56.4      Exception.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1659

             76.56.5      Exception.CreateFmt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1660

             76.56.6      Exception.CreateRes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1660

             76.56.7      Exception.CreateResFmt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1660

             76.56.8      Exception.CreateHelp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1660

             76.56.9      Exception.CreateFmtHelp               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1661

             76.56.10     Exception.CreateResHelp             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1661

             76.56.11     Exception.CreateResFmtHelp                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1661

             76.56.12     Exception.ToString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1661

             76.56.13     Exception.HelpContext            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1662

             76.56.14     Exception.Message           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1662

    76.57    EZeroDivide        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1662

             76.57.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1662

    76.58    IReadWriteSync          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1662

             76.58.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1662

    76.59    TMultiReadExclusiveWriteSynchronizer                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1662

             76.59.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1662

             76.59.2      Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1663

    76.60    TSimpleRWSync           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1663

             76.60.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1663

             76.60.2      Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1663


77   Reference for unit 'Types'                                                                                       1664



                                                                 102

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    77.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1664

    77.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1664

             77.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1664

             77.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1669

    77.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1675

             77.3.1       Bounds     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1675

             77.3.2       CenterPoint       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1675

             77.3.3       EqualRect       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1676

             77.3.4       InflateRect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1676

             77.3.5       IntersectRect        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1676

             77.3.6       IsRectEmpty       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1676

             77.3.7       OffsetRect      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1677

             77.3.8       Point    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1677

             77.3.9       PtInRect      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1677

             77.3.10      Rect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1677

             77.3.11      Size  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1678

             77.3.12      UnionRect       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1678

    77.4     IClassFactory         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1678

             77.4.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1678

             77.4.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1678

             77.4.3       IClassFactory.CreateInstance            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1678

             77.4.4       IClassFactory.LockServer            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1679

    77.5     ISequentialStream          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1679

             77.5.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1679

             77.5.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1679

             77.5.3       ISequentialStream.Read              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1679

             77.5.4       ISequentialStream.Write             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1679

    77.6     IStream     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  1680

             77.6.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1680

             77.6.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1680

             77.6.3       IStream.Seek      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1680

             77.6.4       IStream.SetSize        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1680

             77.6.5       IStream.CopyTo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1680

             77.6.6       IStream.Commit         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1681

             77.6.7       IStream.Revert         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1681

             77.6.8       IStream.LockRegion          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1681

             77.6.9       IStream.UnlockRegion             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1681

             77.6.10      IStream.Stat      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1682

             77.6.11      IStream.Clone        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1682



                                                                 103

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



78   Reference for unit 'typinfo'                                                                                     1683

    78.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1683

    78.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1683

    78.3     Auxiliary functions          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1683

    78.4     Getting or setting property values               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1684

    78.5     Examining published property information                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1684

    78.6     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1685

             78.6.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1685

             78.6.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1686

    78.7     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1700

             78.7.1       FindPropInfo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1700

             78.7.2       GetEnumName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1701

             78.7.3       GetEnumNameCount               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1702

             78.7.4       GetEnumProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1702

             78.7.5       GetEnumValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1703

             78.7.6       GetFloatProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1703

             78.7.7       GetInt64Prop         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1704

             78.7.8       GetInterfaceProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1705

             78.7.9       GetMethodProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1705

             78.7.10      GetObjectProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1707

             78.7.11      GetObjectPropClass             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1708

             78.7.12      GetOrdProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1709

             78.7.13      GetPropInfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1710

             78.7.14      GetPropInfos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1710

             78.7.15      GetPropList       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1711

             78.7.16      GetPropValue         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1713

             78.7.17      GetRawInterfaceProp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1713

             78.7.18      GetSetProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1713

             78.7.19      GetStrProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1714

             78.7.20      GetTypeData          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1715

             78.7.21      GetUnicodeStrProp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1716

             78.7.22      GetVariantProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1716

             78.7.23      GetWideStrProp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1716

             78.7.24      IsPublishedProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1717

             78.7.25      IsStoredProp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1717

             78.7.26      PropIsType        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1718

             78.7.27      PropType        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1719

             78.7.28      SetEnumProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1720

             78.7.29      SetFloatProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1720

             78.7.30      SetInt64Prop      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1721



                                                                 104

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             78.7.31      SetInterfaceProp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1721

             78.7.32      SetMethodProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1722

             78.7.33      SetObjectProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1722

             78.7.34      SetOrdProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1723

             78.7.35      SetPropValue         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1723

             78.7.36      SetRawInterfaceProp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1723

             78.7.37      SetSetProp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1724

             78.7.38      SetStrProp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1724

             78.7.39      SetToString       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1725

             78.7.40      SetUnicodeStrProp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1726

             78.7.41      SetVariantProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1726

             78.7.42      SetWideStrProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1726

             78.7.43      StringToSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1727

    78.8     TProcedureSignature            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1727

             78.8.1       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1727

             78.8.2       TProcedureSignature.GetParam                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1727

    78.9     EPropertyConvertError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1728

             78.9.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1728

    78.10    EPropertyError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1728

             78.10.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1728


79   Reference for unit 'unicodedata'                                                                                 1729

    79.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1729

    79.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1730

             79.2.1       Resource strings       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1730

             79.2.2       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1730

             79.2.3       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1733

    79.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1735

             79.3.1       CanonicalOrder         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1735

             79.3.2       CompareSortKey            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1736

             79.3.3       ComputeSortKey            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1736

             79.3.4       FindCollation        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1736

             79.3.5       FreeCollation        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1737

             79.3.6       FromUCS4        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1737

             79.3.7       GetCollationCount           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1737

             79.3.8       GetProps      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1737

             79.3.9       GetPropUCA           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1738

             79.3.10      IncrementalCompareString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1738

             79.3.11      LoadCollation        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1738

             79.3.12      NormalizeNFD           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1739



                                                                 105

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             79.3.13      PrepareCollation          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1739

             79.3.14      RegisterCollation         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1739

             79.3.15      ToUCS4        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1740

             79.3.16      UnicodeIsHighSurrogate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1740

             79.3.17      UnicodeIsLowSurrogate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1740

             79.3.18      UnicodeIsSurrogatePair           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1741

             79.3.19      UnicodeToLower         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1741

             79.3.20      UnicodeToUpper            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1741

             79.3.21      UnregisterCollation         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1742

             79.3.22      UnregisterCollations           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1742

    79.4     TUCA_DataBook              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1742

             79.4.1       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1743

             79.4.2       TUCA_DataBook.IsVariable                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1743

    79.5     TUCA_PropItemContextRec                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1743

             79.5.1       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1743

             79.5.2       TUCA_PropItemContextRec.GetCodePoints                         .  .  .  .  .  .  .  .  .  .  .  .  .  1744

             79.5.3       TUCA_PropItemContextRec.GetWeights                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  17*
 *44

    79.6     TUCA_PropItemContextTreeNodeRec                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1744

             79.6.1       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1744

             79.6.2       TUCA_PropItemContextTreeNodeRec.GetLeftNode                             .  .  .  .  .  .  .  .  .  1744

             79.6.3       TUCA_PropItemContextTreeNodeRec.GetRightNode                               .  .  .  .  .  .  .  .  1744

    79.7     TUCA_PropItemContextTreeRec                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1745

             79.7.1       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1745

             79.7.2       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1745

             79.7.3       TUCA_PropItemContextTreeRec.GetData                         .  .  .  .  .  .  .  .  .  .  .  .  .  .  1745

             79.7.4       TUCA_PropItemContextTreeRec.Find                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  17*
 *45

             79.7.5       TUCA_PropItemContextTreeRec.Data                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  17*
 *45

    79.8     TUCA_PropItemRec               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1746

             79.8.1       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1746

             79.8.2       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1746

             79.8.3       TUCA_PropItemRec.HasCodePoint                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *747

             79.8.4       TUCA_PropItemRec.IsValid                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1747

             79.8.5       TUCA_PropItemRec.GetWeightArray                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *747

             79.8.6       TUCA_PropItemRec.GetSelfOnlySize                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *747

             79.8.7       TUCA_PropItemRec.GetContextual                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *747

             79.8.8       TUCA_PropItemRec.GetContext                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1747

             79.8.9       TUCA_PropItemRec.IsDeleted                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1748

             79.8.10      TUCA_PropItemRec.IsWeightCompress_1                         .  .  .  .  .  .  .  .  .  .  .  .  .  .  1748

             79.8.11      TUCA_PropItemRec.IsWeightCompress_2                         .  .  .  .  .  .  .  .  .  .  .  .  .  .  1748

             79.8.12      TUCA_PropItemRec.CodePoint                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1748



                                                                 106

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             79.8.13      TUCA_PropItemRec.Contextual                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1748

    79.9     TUC_Prop         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1748

             79.9.1       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1749

             79.9.2       TUC_Prop.Category              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1749

             79.9.3       TUC_Prop.WhiteSpace              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1749

             79.9.4       TUC_Prop.HangulSyllable               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1750

             79.9.5       TUC_Prop.NumericValue               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1750

    79.10    TUInt24Rec         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1750

             79.10.1      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1753

             79.10.2      TUInt24Rec.implicit(TUInt24Rec):Cardinal                      .  .  .  .  .  .  .  .  .  .  .  .  .  1754

             79.10.3      TUInt24Rec.implicit(TUInt24Rec):LongInt                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  1754

             79.10.4      TUInt24Rec.implicit(TUInt24Rec):Word                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  17*
 *54

             79.10.5      TUInt24Rec.implicit(TUInt24Rec):Byte                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  17*
 *54

             79.10.6      TUInt24Rec.implicit(Cardinal):TUInt24Rec                      .  .  .  .  .  .  .  .  .  .  .  .  .  1755

             79.10.7      TUInt24Rec.equal(TUInt24Rec,TUInt24Rec):Boolean                            .  .  .  .  .  .  .  .  1755

             79.10.8      TUInt24Rec.equal(TUInt24Rec,Cardinal):Boolean                         .  .  .  .  .  .  .  .  .  .  1755

             79.10.9      TUInt24Rec.equal(Cardinal,TUInt24Rec):Boolean                         .  .  .  .  .  .  .  .  .  .  1755

             79.10.10     TUInt24Rec.equal(TUInt24Rec,LongInt):Boolean                          .  .  .  .  .  .  .  .  .  .  1755

             79.10.11     TUInt24Rec.equal(LongInt,TUInt24Rec):Boolean                          .  .  .  .  .  .  .  .  .  .  1756

             79.10.12     TUInt24Rec.equal(TUInt24Rec,Word):Boolean                        .  .  .  .  .  .  .  .  .  .  .  .  1756

             79.10.13     TUInt24Rec.equal(Word,TUInt24Rec):Boolean                        .  .  .  .  .  .  .  .  .  .  .  .  1756

             79.10.14     TUInt24Rec.equal(TUInt24Rec,Byte):Boolean                        .  .  .  .  .  .  .  .  .  .  .  .  1756

             79.10.15     TUInt24Rec.equal(Byte,TUInt24Rec):Boolean                        .  .  .  .  .  .  .  .  .  .  .  .  1756

             79.10.16     TUInt24Rec.notequal(TUInt24Rec,TUInt24Rec):Boolean                              .  .  .  .  .  .  1756

             79.10.17     TUInt24Rec.notequal(TUInt24Rec,Cardinal):Boolean                           .  .  .  .  .  .  .  .  1757

             79.10.18     TUInt24Rec.notequal(Cardinal,TUInt24Rec):Boolean                           .  .  .  .  .  .  .  .  1757

             79.10.19     TUInt24Rec.greaterthan(TUInt24Rec,TUInt24Rec):Boolean                               .  .  .  .  1757

             79.10.20     TUInt24Rec.greaterthan(TUInt24Rec,Cardinal):Boolean                             .  .  .  .  .  .  1757

             79.10.21     TUInt24Rec.greaterthan(Cardinal,TUInt24Rec):Boolean                             .  .  .  .  .  .  1757

             79.10.22     TUInt24Rec.greaterthanorequal(TUInt24Rec,TUInt24Rec):Boolean                                  1758

             79.10.23     TUInt24Rec.greaterthanorequal(TUInt24Rec,Cardinal):Boolean                               .  .  1758

             79.10.24     TUInt24Rec.greaterthanorequal(Cardinal,TUInt24Rec):Boolean                               .  .  1758

             79.10.25     TUInt24Rec.lessthan(TUInt24Rec,TUInt24Rec):Boolean                              .  .  .  .  .  .  1758

             79.10.26     TUInt24Rec.lessthan(TUInt24Rec,Cardinal):Boolean                           .  .  .  .  .  .  .  .  1758

             79.10.27     TUInt24Rec.lessthan(Cardinal,TUInt24Rec):Boolean                           .  .  .  .  .  .  .  .  1759

             79.10.28     TUInt24Rec.lessthanorequal(TUInt24Rec,TUInt24Rec):Boolean                                .  .  1759

             79.10.29     TUInt24Rec.lessthanorequal(TUInt24Rec,Cardinal):Boolean                             .  .  .  .  1759

             79.10.30     TUInt24Rec.lessthanorequal(Cardinal,TUInt24Rec):Boolean                             .  .  .  .  1759


80   Reference for unit 'unicodeducet'                                                                                1760



                                                                 107

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    80.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1760


81   Reference for unit 'Unix'                                                                                        1761

    81.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1761

    81.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1761

             81.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1761

             81.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1768

             81.2.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1777

    81.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1777

             81.3.1       AssignPipe      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1777

             81.3.2       AssignStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1778

             81.3.3       FpExecL       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1779

             81.3.4       FpExecLE        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1780

             81.3.5       FpExecLP        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1781

             81.3.6       FpExecLPE         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1782

             81.3.7       FpExecV       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1782

             81.3.8       FpExecVP        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1783

             81.3.9       FpExecVPE         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1784

             81.3.10      fpFlock    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1785

             81.3.11      fpfStatFS     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1785

             81.3.12      fpfsync    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1786

             81.3.13      fpgettimeofday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1786

             81.3.14      fpStatFS      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1786

             81.3.15      fpSystem      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1787

             81.3.16      FSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1787

             81.3.17      GetDomainName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1788

             81.3.18      GetHostName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1788

             81.3.19      GetLocalTimezone            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1789

             81.3.20      GetTimezoneFile           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1789

             81.3.21      PClose     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1790

             81.3.22      POpen      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1790

             81.3.23      ReadTimezoneFile          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1791

             81.3.24      ReReadLocalTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1791

             81.3.25      SeekDir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1792

             81.3.26      SelectText      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1792

             81.3.27      SigRaise      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1792

             81.3.28      TellDir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1793

             81.3.29      WaitProcess       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1793

             81.3.30      WIFSTOPPED             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1794

             81.3.31      W_EXITCODE             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1794



                                                                 108

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             81.3.32      W_STOPCODE             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1794


82   Reference for unit 'unixcp'                                                                                      1795

    82.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1795

    82.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1795

    82.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1795

             82.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1795

             82.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1796

    82.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1796

             82.4.1       GetCodepageByName              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1796

             82.4.2       GetCodepageData           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1796

             82.4.3       GetSystemCodepage              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1796


83   Reference for unit 'unixtype'                                                                                    1798

    83.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1798

    83.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1798

             83.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1798

             83.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1800


84   Reference for unit 'unixutil'                                                                                    1813

    84.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1813

    84.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1813

             84.2.1       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1813

             84.2.2       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1813

    84.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1814

             84.3.1       ArrayStringToPPchar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1814

             84.3.2       EpochToLocal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1814

             84.3.3       GetFS      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1815

             84.3.4       GregorianToJulian           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1815

             84.3.5       JulianToGregorian           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1816

             84.3.6       LocalToEpoch         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1816

             84.3.7       StringToPPChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1817


85   Reference for unit 'video'                                                                                       1818

    85.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1818

    85.2     Examples utility unit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1819

    85.3     Writing a custom video driver               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1820

    85.4     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1823

             85.4.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1823

             85.4.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1827

             85.4.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1829



                                                                 109

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    85.5     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1830

             85.5.1       ClearScreen       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1830

             85.5.2       DefaultErrorHandler            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1831

             85.5.3       DoneVideo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1831

             85.5.4       GetCapabilities        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1832

             85.5.5       GetCursorType          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1833

             85.5.6       GetLockScreenCount             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1834

             85.5.7       GetVideoDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1834

             85.5.8       GetVideoMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1835

             85.5.9       GetVideoModeCount              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1835

             85.5.10      GetVideoModeData            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1837

             85.5.11      InitVideo     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1837

             85.5.12      LockScreenUpdate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1837

             85.5.13      SetCursorPos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1838

             85.5.14      SetCursorType          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1839

             85.5.15      SetVideoDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1839

             85.5.16      SetVideoMode         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1839

             85.5.17      UnlockScreenUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1840

             85.5.18      UpdateScreen         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1840


86   Reference for unit 'wincrt'                                                                                      1842

    86.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1842

    86.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1842

             86.2.1       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1842

    86.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1842

             86.3.1       delay    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1842

             86.3.2       keypressed      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1842

             86.3.3       nosound       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1843

             86.3.4       readkey    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1843

             86.3.5       sound    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1843

             86.3.6       textmode      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1843


87   Reference for unit 'windirs'                                                                                     1844

    87.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1844

    87.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1844

    87.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1844

             87.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1844

    87.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1847

             87.4.1       GetWindowsSpecialDir             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1847


88   Reference for unit 'x86'                                                                                         1849



                                                                 110

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    88.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1849

    88.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1849

    88.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1849

             88.3.1       fpIOperm        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1849

             88.3.2       fpIoPL     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1850

             88.3.3       ReadPort      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1850

             88.3.4       ReadPortB       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1850

             88.3.5       ReadPortL       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1851

             88.3.6       ReadPortW         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1851

             88.3.7       WritePort       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1851

             88.3.8       WritePortB        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1852

             88.3.9       WritePortl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1852

             88.3.10      WritePortW        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1852



                                                                 111

____________________________________________________________________________________________________________________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.



                                                                 112




Chapter   1



Reference   for   unit   'BaseUnix'



1.1         Used  units



                                   Table 1.1:  Used units by unit 'BaseUnix'


                                                  __Name____________Page_____
                                                    System          1235
                                                    unixtype        1798



1.2         Overview


The BaseUnix unit was implemented by Marco Van de Voort.  It contains basic unix func-
tionality.  It supersedes the Linux unit of version 1.0.X of the compiler, but only implements
a cleaned up, portable subset of that unit.

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  *  (cuLong)


Number of bits in a word.


ESysE2BIG  =  7


System error:  Argument list too long


ESysEACCES  =  13



                                                             113

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


System error:  Invalid request code


ESysEBADSLT  =  57



                                                                 114

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  Invalid slot


ESysEBFONT  =  59


System error:  Bad font file format


ESysEBUSY  =  16


System error:  Device or resource busy


ESysECANCELED  =  125


Operation canceled


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  =  ESysEDEADLK


System error:  File locking deadlock error


ESysEDESTADDRREQ  =  89


System error:  Destination address required


ESysEDOM  =  33



                                                                 115

________________________________________________________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



                                                                 116

________________________________________________________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


ESysEKEYEXPIRED  =  127


Key has expired (linux kernel module)


ESysEKEYREJECTED  =  129


Key was rejected by service (linux kernel module)


ESysEKEYREVOKED  =  128


Key has been revoked (linux kernel module)


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



                                                                 117

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


System error:  Link number out of range


ESysELOOP  =  40


System error:  Too many symbolic links encountered


ESysEMEDIUMTYPE  =  124


Wrong medium type


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



                                                                 118

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


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


ESysENOKEY  =  126


Required key not available (linux kernel module)


ESysENOLCK  =  37


System error:  No record locks available


ESysENOLINK  =  67


System error:  Link has been severed


ESysENOMEDIUM  =  123



                                                                 119

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



No medium present


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


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



                                                                 120

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  Directory not empty


ESysENOTNAM  =  118


System error:  Not a XENIX named type file


ESysENOTRECOVERABLE  =  131


State not recoverable (mutexes)


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


System error:  Operation not supported on transport endpoint


ESysEOVERFLOW  =  75


System error:  Value too large for defined data type


ESysEOWNERDEAD  =  130


Owner died (mutexes)


ESysEPERM  =  1


System error:  Operation not permitted.


ESysEPFNOSUPPORT  =  96


System error:  Protocol family not supported


ESysEPIPE  =  32


System error:  Broken pipe


ESysEPROTO  =  71



                                                                 121

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


ESysERFKILL  =  132


Operation not possible due to RF-Kill (wireless)


ESysEROFS  =  30


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



                                                                 122

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


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



                                                                 123

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  Exchange full


FD_MAXFDSET  =  1024


Maximum elements in a TFDSet (149  ) 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


Value signalling integer overflow in case of SIGFPE signal


F_GetFd  =  1


fpFCntl (164  ) command:  Get close-on-exec flag


F_GetFl  =  3


fpFCntl (164  ) command:  Get filedescriptor flags


F_GetLk  =  5


fpFCntl (164  ) command:  Get lock


F_GetOwn  =  9



                                                                 124

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



fpFCntl (164  ) command:  get owner of filedescriptor events


F_OK  =  0


fpAccess (155  ) call test:  file exists.


F_SetFd  =  2


fpFCntl (164  ) command:  Set close-on-exec flag


F_SetFl  =  4


fpFCntl (164  ) command:  Set filedescriptor flags


F_SetLk  =  6


fpFCntl (164  ) command:  Set lock


F_SetLkW  =  7


fpFCntl (164  ) command:  Test lock


F_SetOwn  =  8


fpFCntl (164  ) command:  Set owner of filedescriptor events


ln2bitmask  =  1  shl  ln2bitsinword  -  1


Last bit in word.


ln2bitsinword  =  5


Power of 2 number of bits in word.


MAP_ANON  =  MAP_ANONYMOUS


Anonymous memory mapping (data private to application)


MAP_ANONYMOUS  =  $20


FpMMap (178  ) map type:  Don't use a file


MAP_DENYWRITE  =  $800


FpMMap (178  ) option:  Ignored.


MAP_EXECUTABLE  =  $1000


FpMMap (178  ) option:  Ignored.


MAP_FAILED  =  (-1)



                                                                 125

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Memory mapping failed error code


MAP_FIXED  =  $10


FpMMap (178  ) map type:  Interpret addr exactly


MAP_GROWSDOWN  =  $100


FpMMap (178  ) option:  Memory grows downward (like a stack)


MAP_LOCKED  =  $2000


FpMMap (178  ) option:  lock the pages in memory.


MAP_NORESERVE  =  $4000


FpMMap (178  ) option:  Do not reserve swap pages for this memory.


MAP_PRIVATE  =  $2


FpMMap (178  ) map type:  Changes are private


MAP_SHARED  =  $1


FpMMap (178  ) map type:  Share changes


MAP_TYPE  =  $f


FpMMap (178  ) map type:  Bitmask for type of mapping


NAME_MAX  =  UnixType  .  NAME_MAX


Maximum filename length.


O_APPEND  =  $400


fpOpen (182  ) file open mode:  Append to file


O_CREAT  =  $40


fpOpen (182  ) file open mode:  Create if file does not yet exist.


O_DIRECT  =  $4000


fpOpen (182  ) file open mode:  Minimize caching effects


O_DIRECTORY  =  $10000


fpOpen (182  ) file open mode:  File must be directory.


O_EXCL  =  $80



                                                                 126

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



fpOpen (182  ) file open mode:  Open exclusively


O_NDELAY  =  O_NONBLOCK


fpOpen (182  ) file open mode:  Alias for O_NonBlock (127  )


O_NOCTTY  =  $100


fpOpen (182  ) file open mode:  No TTY control.


O_NOFOLLOW  =  $20000


fpOpen (182  ) file open mode:  Fail if file is symbolic link.


O_NONBLOCK  =  $800


fpOpen (182  ) file open mode:  Open in non-blocking mode


O_RDONLY  =  0


fpOpen (182  ) file open mode:  Read only


O_RDWR  =  2


fpOpen (182  ) file open mode:  Read/Write


O_SYNC  =  $1000


fpOpen (182  ) file open mode:  Write to disc at once


O_TRUNC  =  $200


fpOpen (182  ) file open mode:  Truncate file to length 0


O_WRONLY  =  1


fpOpen (182  ) file open mode:  Write only


PATH_MAX  =  UnixType  .  PATH_MAX


Maximum pathname length.


POLLERR  =  $0008


Error condition on output file descriptor


POLLHUP  =  $0010


Hang up


POLLIN  =  $0001



                                                                 127

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Data is available for reading


POLLNVAL  =  $0020


Invalid request, file descriptor not open.


POLLOUT  =  $0004


Writing data will not block the write call


POLLPRI  =  $0002


Urgent data is available for reading.


POLLRDBAND  =  $0080


Priority data ready for reading.


POLLRDNORM  =  $0040


Same as POLLIN.


POLLWRBAND  =  $0200


Priority data my be written.


POLLWRNORM  =  $0100


Equivalent to POLLOUT.


PRIO_PGRP  =  UnixType  .  PRIO_PGRP


Easy access alias for unixtype.PRIO_PGRP (1798   )


PRIO_PROCESS  =  UnixType  .  PRIO_PROCESS


Easy access alias for unixtype.PRIO_PROCESS (1798   )


PRIO_USER  =  UnixType  .  PRIO_USER


Easy access alias for unixtype.PRIO_USER (1798   )


PROT_EXEC  =  $4


FpMMap (178  ) memory access:  page can be executed


PROT_NONE  =  $0


FpMMap (178  ) memory access:  page can not be accessed


PROT_READ  =  $1



                                                                 128

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



FpMMap (178  ) memory access:  page can be read


PROT_WRITE  =  $2


FpMMap (178  ) 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


RLimit request max stack size


R_OK  =  4



                                                                 129

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



fpAccess (155  ) 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 (194  ) to indicate the signal handler must be called on
an alternate signal stack provided by sigaltstack(2) 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.


SEEK_CUR  =  1


fpLSeek (176  ) option:  Set position relative to current position.



                                                                 130

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



SEEK_END  =  2


fpLSeek (176  ) option:  Set position relative to end of file.


SEEK_SET  =  0


fpLSeek (176  ) 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)


SIGIOT  =  6


Signal:  IOT (IOT trap)



                                                                 131

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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)


SIGTTIN  =  21


Signal:  TTIN (Terminal input, background)



                                                                 132

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


SIG_IGN  =  1


Signal handler:  Ignore signal



                                                                 133

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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  (longint)  -  3


Signal information pad size.


SYS_NMLN  =  UnixType  .  SYS_NMLN


Max system name length.


S_IFBLK  =  24576


File (#rtl.baseunix.stat (149  ) record) mode:  Block device


S_IFCHR  =  8192


File (#rtl.baseunix.stat (149  ) record) mode:  Character device


S_IFDIR  =  16384


File (#rtl.baseunix.stat (149  ) record) mode:  Directory


S_IFIFO  =  4096


File (#rtl.baseunix.stat (149  ) record) mode:  FIFO


S_IFLNK  =  40960


File (#rtl.baseunix.stat (149  ) record) mode:  Link


S_IFMT  =  61440


File (#rtl.baseunix.stat (149  ) record) mode:  File type bit mask


S_IFREG  =  32768


File (#rtl.baseunix.stat (149  ) record) mode:  Regular file


S_IFSOCK  =  49152


File (#rtl.baseunix.stat (149  ) record) mode:  Socket



                                                                 134

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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_IRWXG  =  S_IRGRP  or  S_IWGRP  or  S_IXGRP


Mode flag:  Read, write, execute by groups.


S_IRWXO  =  S_IROTH  or  S_IWOTH  or  S_IXOTH


Mode flag:  Read, write, execute by others.


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 (155  ) domain name.



                                                                 135

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



UTSNAME_LENGTH  =  SYS_NMLN


Max length of utsname (155  ) system name, release, version, machine.


UTSNAME_NODENAME_LENGTH  =  UTSNAME_LENGTH


Max length of utsname (155  ) node name.


WNOHANG  =  1


#rtl.baseunix.fpWaitpid (207  ) option:  Do not wait for processes to terminate.


wordsinfdset  =  FD_MAXFDSET  div  BITSINWORD


Number of words in a TFDSet (149  ) array


wordsinsigset  =  SIG_MAXSIG  div  BITSINWORD


Number of words in a signal set.


WUNTRACED  =  2


#rtl.baseunix.fpWaitpid (207  ) option:  Also report children wich were stopped but not yet
reported


W_OK  =  2


fpAccess (155  ) call test:  write allowed


X_OK  =  1


fpAccess (155  ) call test:  execute allowed


_STAT_VER  =  _STAT_VER_LINUX


Stat version number


_STAT_VER_KERNEL  =  0


Current version of stat record


_STAT_VER_LINUX  =  1


Version of linux stat record



                                                                 136

________________________________________________________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 (1800   )


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



                                                                 137

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Clock ticks type


clong  =  UnixType.clong


C type:  long signed integer (double sized)


clonglong  =  UnixType.clonglong


C type:  64-bit (double long) signed integer.


coff_t  =  UnixType.TOff


Character offset type


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 (137  ).


csint  =  UnixType.csint


Signed integer


csize_t  =  UnixType.size_t


Character size type


cslong  =  UnixType.cslong


The size is CPU dependent.


cslonglong  =  UnixType.cslonglong


cslonglong is an alias for clonglong (138  ).


csshort  =  UnixType.csshort


Short signed integer type


cuchar  =  UnixType.cuchar


Alias for #rtl.UnixType.cuchar (1801   )


cuint  =  UnixType.cuint



                                                                 138

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


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 (1802   )


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 (183  ) and fpReadDir (187  ) calls



                                                                 139

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Dirent  =  record
   d_fileno  :  ino64_t;
   d_off  :  off_t;
   d_reclen  :  cushort;
   d_type  :  cuchar;
   d_name  :  Array[0..4095-sizeof(ino64_t)-sizeof(off_t)-sizeof(cushort)-sizeof(cuchar)]  of  Char;
end



Record used in the fpReadDir (187  ) function to return files in a directory.


FLock  =  record
   l_type  :  cshort;
   l_whence  :  cshort;
   l_start  :  kernel_off_t;
   l_len  :  kernel_off_t;
   l_pid  :  pid_t;
end



Lock description type for fpFCntl (164  ) 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 (189  ) for IO to multiple buffers to describe a buffer location.


kernel_gid_t  =  cuint


kernel_gid_t may differ from the libc type used to describe group IDs.


kernel_loff_t  =  clonglong


Long kernel offset type


kernel_mode_t  =  cuint


kernel_mode_t may differ from the libc type used to describe file modes.


kernel_off_t  =  clong



                                                                 140

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Kernel offset type


kernel_uid_t  =  cuint


kernel_uid_t may differ from the libc type used to describe user IDs.


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 (149  ) type.


PBlkSize  =  ^Blksize_t


Pointer to TBlkSize (149  ) type.


pcbool  =  UnixType.pcbool


Pointer to boolean type cbool (137  )


pcchar  =  UnixType.pcchar


Alias for #rtl.UnixType.pcchar (1803   )


pcdouble  =  UnixType.pcdouble


Pointer to cdouble (137  ) type.


pcfloat  =  UnixType.pcfloat


Pointer to cfloat (137  ) type.


pcint  =  UnixType.pcint


Pointer to cInt (137  ) type.


pcint16  =  UnixType.pcint16


Pointer to 16-bit signed integer type


pcint32  =  UnixType.pcint32



                                                                 141

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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 (149  ) type.


pclong  =  UnixType.pclong


Pointer to cLong (138  ) type.


pclonglong  =  UnixType.pclonglong


Pointer to longlong type.


pcschar  =  UnixType.pcschar


Pointer to character type cschar (138  ).


pcshort  =  UnixType.pcshort


Pointer to cShort (138  ) type.


pcsigned  =  UnixType.pcsigned


Pointer to signed integer type csigned (138  ).


pcsint  =  UnixType.pcsint


Pointer to signed integer type csint (138  )


pcsize_t  =  UnixType.psize_t


Pointer to csize_t


pcslong  =  UnixType.pcslong


Pointer ot the signed long cslong (138  )


pcslonglong  =  UnixType.pcslonglong


Pointer to Signed longlong type cslonglong (138  )


pcsshort  =  UnixType.pcsshort



                                                                 142

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Pointer to short signed integer type csshort (138  )


pcuchar  =  UnixType.pcuchar


Alias for #rtl.UnixType.pcuchar (1805   )


pcuint  =  UnixType.pcuint


Pointer to cUInt (139  ) 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 (139  ) type.


pculonglong  =  UnixType.pculonglong


Unsigned longlong type


pcunsigned  =  UnixType.pcunsigned


Alias for #rtl.unixtype.pcunsigned (1805   )


pcushort  =  UnixType.pcushort


Pointer to cuShort (139  ) type.


pDev  =  UnixType.pDev


Pointer to TDev (149  ) type.


pDir  =  ^Dir


Pointer to TDir (149  ) record


pDirent  =  ^Dirent



                                                                 143

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Pointer to TDirent (149  ) record.


pFDSet  =  ^TFDSet


Pointer to TFDSet (149  ) type.


pFilDes  =  ^TFilDes


Pointer to TFilDes (149  ) type.


pfpstate  =  ^tfpstate


Pointer to tfpstate (150  ) record.


pGid  =  UnixType.pGid


Pointer to TGid (150  ) type.


pGrpArr  =  ^TGrpArr


Pointer to TGrpArr (150  ) array.


pid_t  =  UnixType.pid_t


Process ID type.


pIno  =  UnixType.pIno


Pointer to TIno (150  ) type.


piovec  =  ^tiovec


pointer to a iovec (140  ) record


pMode  =  UnixType.pMode


Pointer to TMode (151  ) type.


pnLink  =  UnixType.pnLink


Pointer to TnLink (151  ) type.


pOff  =  UnixType.pOff


Pointer to TOff (151  ) type.


pollfd  =  record
   fd  :  cint;
   events  :  cshort;
   revents  :  cshort;
end



                                                                 144

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



pollfd is used in the fpPoll (185  ) call to describe the various actions.


pPid  =  UnixType.pPid


Pointer to TPid (151  ) type.


ppollfd  =  ^pollfd


Pointer to tpollfd.


PRLimit  =  ^TRLimit


Pointer to TRLimit (151  ) record


psigactionrec  =  ^sigactionrec


Pointer to SigActionRec (147  ) record type.


PSigContext  =  ^TSigContext


Pointer to #rtl.baseunix.TSigContext (152  ) record type.


psiginfo  =  ^tsiginfo


Pointer to #rtl.baseunix.TSigInfo (153  ) record type.


psigset  =  ^tsigset


Pointer to SigSet (147  ) type.


pSize  =  UnixType.pSize


Pointer to TSize (153  ) type.


pSize_t  =  UnixType.pSize_t


Pointer to Size_t


pSocklen  =  UnixType.pSocklen


Pointer to TSockLen (153  ) type.


psSize  =  UnixType.psSize


Pointer to TsSize (154  ) type


PStat  =  ^Stat


Pointer to TStat (154  ) type.


pstatfs  =  UnixType.PStatFs



                                                                 145

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



This is an alias for the type defined in the #rtl.unixtype (1798   ) unit.


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 (154  ) type.


ptimespec  =  UnixType.ptimespec


Pointer to timespec (150  ) type.


ptimeval  =  UnixType.ptimeval


Pointer to timeval (150  ) type.


ptimezone  =  ^timezone


Pointer to TimeZone (150  ) record.


ptime_t  =  UnixType.ptime_t


Pointer to time_t (150  ) type.


PTms  =  ^tms


Pointer to TTms (154  ) type.


Pucontext  =  ^Tucontext


Pointer to TUContext (154  ) type.


pUid  =  UnixType.pUid


Pointer to TUid (154  ) type.


pUtimBuf  =  ^UTimBuf


Pointer to TUTimBuf (154  ) type.


PUtsName  =  ^TUtsName



                                                                 146

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Pointer to TUtsName (155  ) type.


rlim_t  =  culong


rlim_t is used as the type for the various fields in the TRLimit (151  ) 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 (194  ) call.


signalhandler  =  signalhandler_t


Simple signal handler prototype


signalhandler_t  =  procedure(signal:  LongInt)


Standard signal handler prototype


sigrestorerhandler  =  sigrestorerhandler_t


Alias for sigrestorerhandler_t (147  ) type.


sigrestorerhandler_t  =  procedure


Standard signal action restorer prototype


sigset  =  sigset_t


Signal set type


sigset_t  =  Array[0..wordsinsigset-1]  of  culong


Signal set type


size_t  =  UnixType.size_t



                                                                 147

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Size specification type.


socklen_t  =  UnixType.socklen_t


Socket address length type.


ssize_t  =  UnixType.ssize_t


Small size type.


Stat  =  packed  record
case  Byte  of
0:  (
   dev  :  QWorddeprecated;
   __pad0  :  Array[0..3]  of  Bytedeprecated;
   __ino  :  Cardinaldeprecated;
   mode  :  Cardinaldeprecated;
   nlink  :  Cardinaldeprecated;
   uid  :  Cardinaldeprecated;
   gid  :  Cardinaldeprecated;
   rdev  :  QWorddeprecated;
   __pad3  :  Array[0..3]  of  Bytedeprecated;
   size  :  QWorddeprecated;
   blksize  :  Cardinaldeprecated;
   blocks  :  QWorddeprecated;
   atime  :  Cardinaldeprecated;
   atime_nsec  :  Cardinaldeprecated;
   mtime  :  Cardinaldeprecated;
   mtime_nsec  :  Cardinaldeprecated;
   ctime  :  Cardinaldeprecated;
   ctime_nsec  :  Cardinaldeprecated;
   ino  :  QWorddeprecated;
);
1:  (
   st_dev  :  QWord;
   __pad0_  :  Array[0..3]  of  Byte;
   __st_ino_  :  Cardinal;
   st_mode  :  Cardinal;
   st_nlink  :  Cardinal;
   st_uid  :  Cardinal;
   st_gid  :  Cardinal;
   st_rdev  :  QWord;
   __pad3_  :  Array[0..3]  of  Byte;
   st_size  :  QWord;
   st_blksize  :  Cardinal;
   st_blocks  :  QWord;
   st_atime  :  Cardinal;
   st_atime_nsec  :  Cardinal;
   st_mtime  :  Cardinal;
   st_mtime_nsec  :  Cardinal;
   st_ctime  :  Cardinal;
   st_ctime_nsec  :  Cardinal;
   st_ino  :  QWord;



                                                                 148

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



);
end



Record describing an inode (file) in the FPFstat (167  ) call.


TBlkCnt  =  Blkcnt_t


Alias for Blkcnt_t (137  ) type.


TBlkSize  =  Blksize_t


Alias for blksize_t (137  ) type.


TClock  =  UnixType.TClock


Alias for clock_t (138  ) type.


TDev  =  UnixType.TDev


Alias for dev_t (139  ) type.


TDir  =  Dir


Alias for Dir (139  ) type.


TDirent  =  Dirent


Alias for Dirent (140  ) type.


TFDSet  =  Array[0..(FD_MAXFDSETdivBITSINWORD)-1]  of  culong


File descriptor set for fpSelect (190  ) call.


TFilDes  =  Array[0..1]  of  cint


Array of file descriptors as used in fpPipe (184  ) call.


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;



                                                                 149

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



   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 (140  ) type.


TGrpArr  =  Array[0..0]  of  TGid


Array of gid_t (140  ) IDs


timespec  =  UnixType.timespec


Short time specification type.


timeval  =  UnixType.timeval


Time specification type.


timezone  =  record
   tz_minuteswest  :  cint;
   tz_dsttime  :  cint;
end



Record describing a timezone


time_t  =  UnixType.time_t


Time span type


TIno  =  UnixType.TIno


Alias for ino_t (140  ) type.


TIOCtlRequest  =  UnixType.TIOCtlRequest


Easy access alias for unixtype.TIOCtlRequest (1810   )


tiovec  =  iovec


Alias for the iovec (140  ) record type.


TMode  =  UnixType.TMode



                                                                 150

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Alias for mode_t (141  ) type.


tms  =  record
   tms_utime  :  clock_t;
   tms_stime  :  clock_t;
   tms_cutime  :  clock_t;
   tms_cstime  :  clock_t;
end



Record containing timings for fpTimes (204  ) call.


TnLink  =  UnixType.TnLink


Alias for nlink_t (141  ) type.


TOff  =  UnixType.TOff


Alias for off_t (141  ) type.


TPid  =  UnixType.TPid


Alias for pid_t (144  ) type.


tpollfd  =  pollfd


Alias for pollfd 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 (147  ) type.


tsigaltstack  =  record
   ss_sp  :  pointer;
   ss_flags  :  LongInt;
   ss_size  :  LongInt;
end



Provide the location of an alternate signal handler stack.



                                                                 151

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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
   case  LongInt  of
   0:  (
      _pad  :  Array[0..(SI_PAD_SIZE)-1]  of  LongInt;
   );
   1:  (
      _kill  :  record
         _pid  :  pid_t;
         _uid  :  uid_t;
      end;
   );
   2:  (
      _timer  :  record
         _timer1  :  DWord;
         _timer2  :  DWord;
      end;



                                                                 152

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



   );
   3:  (
      _rt  :  record
         _pid  :  pid_t;
         _uid  :  uid_t;
         _sigval  :  pointer;
      end;
   );
   4:  (
      _sigchld  :  record
         _pid  :  pid_t;
         _uid  :  uid_t;
         _status  :  LongInt;
         _utime  :  clock_t;
         _stime  :  clock_t;
      end;
   );
   5:  (
      _sigfault  :  record
         _addr  :  pointer;
      end;
   );
   6:  (
      _sigpoll  :  record
         _band  :  LongInt;
         _fd  :  LongInt;
      end;
   );
   end;
end



This type describes the signal that occurred.


tsignalhandler  =  signalhandler_t


Alias for signalhandler_t (147  ) type.


tsigrestorerhandler  =  sigrestorerhandler_t


Alias for sigrestorerhandler_t (147  ) type.


tsigset  =  sigset_t


Alias for SigSet (147  ) type.


TSize  =  UnixType.TSize


Alias for size_t (148  ) type


TSocklen  =  UnixType.TSocklen


Alias for socklen_t (148  ) type.



                                                                 153

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



TsSize  =  UnixType.TsSize


Alias for ssize_t (148  ) type


TStat  =  Stat


Alias for Stat (149  ) type.


tstatfs  =  UnixType.TStatFs


Record describing a file system in the unix.fpstatfs (113  ) call.


TTime  =  UnixType.TTime


Alias for TTime (154  ) type.


Ttimespec  =  UnixType.Ttimespec


Alias for TimeSpec (150  ) type.


TTimeVal  =  UnixType.TTimeVal


Alias for timeval (150  ) type.


TTimeZone  =  timezone


Alias for TimeZone (150  ) record.


TTms  =  tms


Alias for Tms (151  ) record type.


TUcontext  =  record
   uc_flags  :  Cardinal;
   uc_link  :  Pucontext;
   uc_stack  :  tsigaltstack;
   uc_mcontext  :  TSigContext;
   uc_sigmask  :  tsigset;
end



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 (155  ) type.


TUtimBuf  =  UTimBuf


Alias for UtimBuf (155  ) type.



                                                                 154

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                TUtsName  =  UtsName


                Alias for UtsName (155  ) type.


                uid_t  =  UnixType.uid_t


                User ID type


                UTimBuf  =  record
                   actime  :  time_t;
                   modtime  :  time_t;
                end



                Record used in fpUtime (206  ) to set file access and modification 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  Charplatform;
                end



                The  elements  of  this  record  are  null-terminated  C  style  strings,  you  cannot  access  them
                directly.  Note that the Domain field is a GNU extension,  and may not be available on all
                platforms.



                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
                (162  ) and friends.

       Errors:   If no more memory is available, a heap error may occur.

    See also:    fpExecv (162  ), FreeShellArgV (209  )



                1.4.2        FpAccess

    Synopsis:    Check file access



                                                                                 155

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



Declaration:     function  FpAccess(pathname:  PChar;aMode:  cint)  :  cint
                function  FpAccess(const  pathname:  RawByteString;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 (169  ).


                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 (159  ), FpChmod (157  )


                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___.____________________________________________________________________________________________________________*
 *___________



                1.4.3        FpAlarm

    Synopsis:    Schedule an alarm signal to be delivered

Declaration:     function  FpAlarm(seconds:  cuint)  :  cuint

    Visibility:   default



                                                                                 156

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (194  ), fpPause (184  )


                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(const  path:  RawByteString)  :  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 (169  ).

    See also:    fpGetCwd (168  )



                1.4.5        FpChmod

    Synopsis:    Change file permission bits



                                                                                 157

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



Declaration:     function  FpChmod(path:  PChar;Mode:  TMode)  :  cint
                function  FpChmod(const  path:  RawByteString;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 (159  ), fpAccess (155  )


                Listing:  ./bunixex/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     B a s e U n i x,U n i x;


                Var    F   :  T e x t ;


                 b e g i n



                                                                                 158

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    {   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(const  path:  RawByteString;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 (157  ), fpAccess (155  )


                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;


                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  ) ;



                                                                                 159

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    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 (182  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).

    See also:    FpOpen (182  ), FpRead (186  ), FpWrite (208  ), FpFTruncate (168  ), FpLSeek (176  )



                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 (183  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).

    See also:    FpOpenDir (183  ), FpReadDir (187  )



                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



                                                                                 160

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (161  )


                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)=-1     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

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.



                                                                                 161

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                The function returns the new file descriptor number, on error -1 is returned, and the error
                can be retrieved with fpgeterrno (169  )

       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 (160  )


                Listing:  ./bunixex/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  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(const  path:  RawByteString;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.

       Errors:   On  error,  -1  is  returned.   Extended  error  information  can  be  retrieved  with  fpGetErrNo
                (169  )


                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.



                                                                                 162

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (163  ), fpFork (166  )


                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(const  path:  RawByteString;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 (169  ), and includes the fol-
                lowing:


                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.



                                                                                 163

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (162  ), fpFork (166  )


                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 (166  ), FpExecve (163  )



                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



                                                                                 164

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



    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 (169  ) 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 (190  ), FpFD_ZERO (166  ), FpFD_IsSet (166  ), FpFD_Clr (165  ), FpFD_Set (166  )



                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 (190  ).

       Errors:   None.

    See also:    FpSelect (190  ), FpFD_ZERO (166  ), FpFD_Set (166  ), FpFD_IsSet (166  )



                                                                                 165

                ________________________________________________________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 (190  ).

       Errors:   If an invald file descriptor number is passed, -1 is returned.

    See also:    FpSelect (190  ), FpFD_ZERO (166  ), FpFD_Clr (165  ), FpFD_Set (166  )



                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 (190  ).

       Errors:   None.

    See also:    FpSelect (190  ), FpFD_ZERO (166  ), FpFD_Clr (165  ), FpFD_IsSet (166  )



                1.4.19         fpFD__ZERO

    Synopsis:    Clear all file descriptors in set

Declaration:     function  fpFD_ZERO(out  nset:  TFDSet)  :  cint

    Visibility:   default

Description:     FpFD_ZERO clears all the filedescriptors in the file descriptor set nset.

                For an example, see FpSelect (190  ).

       Errors:   None.

    See also:    FpSelect (190  ), FpFD_Clr (165  ), FpFD_Set (166  ), FpFD_IsSet (166  )



                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 (172  )).



                                                                                 166

                ________________________________________________________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 (163  ), #rtl.linux.Clone (890  )



                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 (149  ).  The function returns zero if the call was
                succesfull, a nonzero return value indicates failure.

       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).


                sys__enoent      Path does not exist.


    See also:    FpStat (199  ), FpLStat (176  )


                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 ) ;



                                                                                 167

                ________________________________________________________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 (169  ).

    See also:    FpOpen (182  ), FpClose (160  ), FpRead (186  ), FpWrite (208  ), FpLSeek (176  )



                1.4.23         FpGetcwd

    Synopsis:    Retrieve the current working directory.

Declaration:     function  FpGetcwd(path:  PChar;siz:  TSize)  :  PChar
                function  FpGetcwd  :  RawByteString

    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 (171  ), FpGetUID (173  )



                1.4.24         FpGetegid

    Synopsis:    Return effective group ID

Declaration:     function  FpGetegid  :  TGid

    Visibility:   default



                                                                                 168

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



Description:     FpGetegid returns the effective group ID of the currently running process.

       Errors:   None.

    See also:    FpGetGid (170  ),  FpGetUid (173  ),  FpGetEUid (170  ),  FpGetPid (171  ),  FpGetPPid (172  ),
                fpSetUID (194  ), FpSetGid (192  )


                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.



                                                                                 169

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



       Errors:   None.

    See also:    fpseterrno (192  )



                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 (173  ),  FpGetGid (170  ),  FpGetEGid (168  ),  FpGetPid (171  ),  FpGetPPid (172  ),
                fpSetUID (194  ), FpSetGid (192  )


                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 (168  ), FpGetUid (173  ), FpGetEUid (170  ), FpGetPid (171  ), FpGetPPid (172  ),
                fpSetUID (194  ), FpSetGid (192  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 170

                ________________________________________________________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
                (169  )

    See also:    FpGetpgrp (171  ), FpGetGID (170  ), FpGetEGID (168  )



                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 (171  ), fpGetPPID (172  ), FpGetGID (170  ), FpGetUID (173  )



                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 (172  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 171

                ________________________________________________________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 (171  )


                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 (181  ).

       Errors:   Error information is returned solely by the FpGetErrno (169  ) 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 (192  ), FpNice (181  )



                1.4.34         FpGetRLimit

    Synopsis:    Get process resource limits

Declaration:     function  FpGetRLimit(resource:  cint;rlim:  PRLimit)  :  cint

    Visibility:   default



                                                                                 172

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



Description:     FpGetRLimit  gets  the  resource  limits  for  the  current  process:  resource  determines  the
                resource of which the kernel should return the limits (one of the many RLIMIT_* constants).
                rlim should point to a TRLimit (151  ) record and on success will contain the resource limits.

                The function returns zero if the resource limits were correctly returned.

       Errors:   On error, -1 is returned and fpgeterrno (169  ) can be used to retrieve the error code.

    See also:    FpSetRLimit (193  )



                1.4.35         FpGetsid

    Synopsis:    Get current session ID

Declaration:     function  FpGetsid(pid:  TPid)  :  TPid

    Visibility:   default

Description:     FpGetsid returns the session ID of the process pid.  The return value is the session ID of
                the process.  (it equals the PID of the session leader).  The process pid must be in the same
                session as the current process.

       Errors:   On error, -1 is returned, and extended error information can be obtained with fpGetErrno.

    See also:    FpGetpgrp (171  ), FpGetpid (171  ), FpGetPpid (172  )



                1.4.36         FpGetuid

    Synopsis:    Return current user ID

Declaration:     function  FpGetuid  :  TUid

    Visibility:   default

Description:     FpGetuid returns the real user ID of the currently running process.

       Errors:   None.

    See also:    FpGetGid (170  ), FpGetEUid (170  ), FpGetEGid (168  ), FpGetPid (171  ), FpGetPPid (172  ),
                fpSetUID (194  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 173

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.37         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 (169  ).


                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___.____________________________________________________________________________________________________________*
 *___________



                1.4.38         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 (169  ):


                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 (194  ), FpSignal (197  )



                                                                                 174

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.39         FpLink

    Synopsis:    Create a hard link to a file

Declaration:     function  FpLink(existing:  PChar;newone:  PChar)  :  cint
                function  FpLink(const  existing:  RawByteString;
                                         const  newone:  RawByteString)  :  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.


    See also:    fpSymLink (200  ), fpUnLink (205  )


                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



                                                                                 175

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                        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.40         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 (182  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).

    See also:    FpOpen (182  ), FpWrite (208  ), FpClose (160  ), FpRead (186  ), FpFTruncate (168  )



                1.4.41         fpLstat

    Synopsis:    Return information about symbolic link.  Do not follow the link

Declaration:     function  fpLstat(path:  PChar;Info:  PStat)  :  cint
                function  fpLstat(const  path:  RawByteString;Info:  PStat)  :  cint
                function  fpLstat(path:  PChar;var  Info:  Stat)  :  cint
                function  fpLstat(const  Filename:  RawByteString;var  Info:  Stat)  :  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  (167  ),  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 (169  ) function.


                sys__enoent      Path does not exist.



                                                                                 176

            ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_____________________*
 *_______________



See also:    FpFStat (167  ), #rtl.unixtype.TStatFS (1811   )


            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
                    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) ;



                                                                             177

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    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.42         FpMkdir

    Synopsis:    Create a new directory

Declaration:     function  FpMkdir(path:  PChar;Mode:  TMode)  :  cint
                function  FpMkdir(const  path:  RawByteString;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 (169  ).

    See also:    fpGetCWD (168  ), fpChDir (157  )



                1.4.43         FpMkfifo

    Synopsis:    Create FIFO (named pipe) in file system

Declaration:     function  FpMkfifo(path:  PChar;Mode:  TMode)  :  cint
                function  FpMkfifo(const  path:  RawByteString;Mode:  TMode)  :  cint

    Visibility:   default

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.44         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



                                                                                 178

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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.

                offOffset 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
                (169  ) 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.

                Sys__ENOMEM            Not enough memory for this operation.


    See also:    FpMUnMap (180  )


                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    ;



                                                                                 179

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                 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.45         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 (178  ).

                The function returns True if successful, False otherwise.

                For an example, see FpMMap (178  ).

       Errors:   In case of error the function returns a nonzero value, extended error information is returned
                by the FpGetErrno (169  ) function.  See FpMMap (178  ) for possible error values.

    See also:    FpMMap (178  )



                1.4.46         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 ErrNo 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 (169  ).



                                                                                 180

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



    See also:    FpPause (184  ), FpAlarm (156  )


                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.47         fpNice

    Synopsis:    Set process priority

Declaration:     function  fpNice(N:  cint)  :  cint

    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.

                If the function is succesful, zero is returned.  On error, a nonzero value is returned.

       Errors:   Extended error information is returned by the FpGetErrno (169  ) function.


                sys__eperm      A non-superuser tried to specify a negative N, i.e.  do a priority increase.


    See also:    FpGetPriority (172  ), FpSetPriority (192  )


                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. }



                                                                                 181

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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.48         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(const  path:  RawByteString;flags:  cint)  :  cint
                function  FpOpen(const  path:  RawByteString;flags:  cint;Mode:  TMode)
                                           :  cint
                function  FpOpen(path:  ShortString;flags:  cint)  :  cint
                function  FpOpen(path:  ShortString;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.

                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.



                                                                                 182

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).

    See also:    FpClose (160  ), FpRead (186  ), FpWrite (208  ), FpFTruncate (168  ), FpLSeek (176  )


                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.49         FpOpendir

    Synopsis:    Open a directory for reading

Declaration:     function  FpOpendir(dirname:  PChar)  :  pDir
                function  FpOpendir(const  dirname:  RawByteString)  :  pDir
                function  FpOpendir(dirname:  ShortString)  :  pDir

    Visibility:   default

Description:     FpOpenDir opens the directory DirName, and returns a pdir pointer to a Dir (139  ) record,
                which can be used to read the directory structure.  If the directory cannot be opened, nil
                is returned.

       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).

    See also:    FpCloseDir (160  ), FpReadDir (187  )


                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



                                                                                 183

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    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.50         FpPause

    Synopsis:    Wait for a signal to arrive

Declaration:     function  FpPause  :  cint

    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 (156  ).



                1.4.51         FpPipe

    Synopsis:    Create a set of pipe file handlers

Declaration:     function  FpPipe(var  fildes:  TFilDes)  :  cint

    Visibility:   default



                                                                                 184

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (1790   ), fpMkFifo (178  )


                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___.____________________________________________________________________________________________________________*
 *___________



                1.4.52         FpPoll

    Synopsis:    Poll a file descriptor for events.

Declaration:     function  FpPoll(fds:  ppollfd;nfds:  cuint;timeout:  clong)  :  cint

    Visibility:   default

Description:     fpPoll waits for events on file descriptors.  fds points to an array of tpollfd records, each
                of these records describes a file descriptor on which to wait for events.  The number of file
                descriptors is given by nfds.  >timeout specifies the maximum time (in milliseconds) to wait
                for events.

                On timeout, the result value is 0.  If an event occurred on some descriptors, then the return
                value is the number of descriptors on which an event (or error) occured.  The revents field
                of the tpollfd records will contain the events for the file descriptor it described.

    See also:    tpollfd (151  )



                                                                                 185

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.53         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 (189  ), FpPWrite (186  )



                1.4.54         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 (186  ), FpWriteV (208  )



                1.4.55         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 (169  ).

    See also:    FpOpen (182  ), FpClose (160  ), FpWrite (208  ), FpFTruncate (168  ), FpLSeek (176  )


                Listing:  ./bunixex/ex20.pp



                                                                                 186

                ________________________________________________________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.56         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 (140  ) record describing the entry.  If the next entry can't be read, Nil is



                                                                                 187

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                returned.

                For an example, see FpOpenDir (183  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).

    See also:    FpCloseDir (160  ), FpOpenDir (183  )



                1.4.57         fpReadLink

    Synopsis:    Read destination of symbolic link

Declaration:     function  fpReadLink(name:  PChar;linkname:  PChar;maxlen:  size_t)  :  cint
                function  fpReadLink(const  Name:  RawByteString)  :  RawByteString

    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 (169  ) 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 process's memory space.

                SYS__ENOMEM              Not enough kernel memory was available.


    See also:    FpSymLink (200  )


                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



                                                                                 188

                ________________________________________________________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.58         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 (150  ) buffers pointed to by iov.  It works like fpRead (186  ) only on multiple buffers.

       Errors:   On error, -1 is returned.

    See also:    FpWriteV (208  ), FpPWrite (186  ), FpPRead (186  )



                1.4.59         FpRename

    Synopsis:    Rename file

Declaration:     function  FpRename(old:  PChar;newpath:  PChar)  :  cint
                function  FpRename(const  old:  RawByteString;const  newpath:  RawByteString)
                                              :  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 (169  ).


                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.



                                                                                 189

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                sys__emlink     OldPath  or  NewPath  already  have  tha  maximum  amount  of  links  pointing  to
                      them.

                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 (205  )



                1.4.60         FpRmdir

    Synopsis:    Remove a directory.

Declaration:     function  FpRmdir(path:  PChar)  :  cint
                function  FpRmdir(const  path:  RawByteString)  :  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 (169  ).



                1.4.61         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 the following I/O operation
                on the file descriptors will block.

                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 the following read operation will block.  The entries in writefds are



                                                                                 190

            ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_____________________*
 *_______________



            checked  to  see  if  the  following  write  operation  will  block,  while  entries  in  exceptfds  are
            cheked to see if an exception occorred on them.

            You can use the functions fpFD_ZERO (166  ), fpFD_Clr (165  ), fpFD_Set (166  ) or fpFD_IsSet
            (166  ) 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 (169  ).


            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 (166  ), fpFD_Clr (165  ), fpFD_Set (166  ), fpFD_IsSet (166  )


            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



                                                                             191

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                        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___.____________________________________________________________________________________________________________*
 *___________



                1.4.62         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.

    See also:    fpgeterrno (169  )



                1.4.63         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 (169  ).

    See also:    FpSetUid  (194  ),  FpGetGid  (170  ),  FpGetUid  (173  ),  FpGetEUid  (170  ),  FpGetEGid  (168  ),
                FpGetPid (171  ), FpGetPPid (172  )



                1.4.64         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 (181  ).

                The function returns zero on success, -1 on failure



                                                                                 192

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



       Errors:   Extended error information is returned by the FpGetErrno (169  ) 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 (172  ), FpNice (181  )



                1.4.65         FpSetRLimit

    Synopsis:    Set process resource limits

Declaration:     function  FpSetRLimit(Resource:  cint;rlim:  PRLimit)  :  cint

    Visibility:   default

Description:     FpGetRLimit  sets  the  resource  limits  for  the  current  process:   resource  determines  the
                resource  of  which  the  kernel  should  set  the  limits  (one  of  the  many  RLIMIT_*  constants).
                rlim should point to a TRLimit (151  ) record which contains the new limits for the resource
                indicated in resource.

                The function returns zero if the resource limits were successfully set.

       Errors:   On error, -1 is returned and fpgeterrno (169  ) can be used to retrieve the error code.

    See also:    FpGetRLimit (172  )



                1.4.66         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 (171  ).  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
                (169  )



                1.4.67         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 (1786   )



                                                                                 193

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.68         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 (169  ).

    See also:    FpGetGid (170  ), FpGetUid (173  ), FpGetEUid (170  ), FpGetEGid (168  ), FpGetPid (171  ),
                FpGetPPid (172  ), FpSetGid (192  )



                1.4.69         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  (147  )  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 (169  ).


                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 (198  ), FpSigPending (197  ), FpSigSuspend (198  ), FpKill (174  )


                Listing:  ./bunixex/ex57.pp



                                                                                 194

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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   ;


                 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.70         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 (196  ), FpSigFillSet (196  ), FpSigDelSet (195  ), FpSigIsMember (196  )



                1.4.71         FpSigDelSet

    Synopsis:    Remove a signal from a signal set.



                                                                                 195

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (196  ), FpSigFillSet (196  ), FpSigAddSet (195  ), FpSigIsMember (196  )



                1.4.72         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 (196  ), FpSigAddSet (195  ), FpSigDelSet (195  ), FpSigIsMember (196  )



                1.4.73         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 (196  ), FpSigAddSet (195  ), FpSigDelSet (195  ), FpSigIsMember (196  )



                1.4.74         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 (196  ), FpSigFillSet (196  ), FpSigAddSet (195  ), FpSigDelSet (195  )



                                                                                 196

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.75         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 (194  ) call.  The return
                value for FpSignal is the old signal handler, or nil on error.

       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).


                SIG__ERR        An error occurred.


    See also:    FpSigAction (194  ), FpKill (174  )


                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  ' .
                }


                 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.76         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.



                                                                                 197

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



       Errors:   None

    See also:    fpSigAction (194  ), fpSigProcMask (198  ), fpSigSuspend (198  ), fpSignal (197  ), fpKill (174  )



                1.4.77         FpSigProcMask

    Synopsis:    Set list of blocked signals

Declaration:     function  FpSigProcMask(how:  cint;nset:  psigset;oset:  psigset)  :  cint
                function  FpSigProcMask(how:  cint;constref  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 (194  ), fpSigPending (197  ), fpSigSuspend (198  ), fpKill (174  )



                1.4.78         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 (194  ), fpSigProcMask (198  ), fpSigPending (197  ), fpSignal (197  ), fpKill (174  )



                1.4.79         FpSigTimedWait

    Synopsis:    Wait for signal, with timeout

Declaration:     function  FpSigTimedWait(const  sigset:  tsigset;info:  psiginfo;
                                                      timeout:  ptimespec)  :  cint

    Visibility:   default



                                                                                 198

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



Description:     FpSigTimedWait will suspend the current thread and wait for one of the signals in sigset
                to  be  delivered.  information  on  the  delivered  signal  is  placed  in  the  location  provided  by
                info (or in info itself,  if the Var variant of the call is used).  If the signal is not delivered
                within the time limit set in timeout, then the call will return -1, and fpGetErrno will return
                EAGAIN.

                On success, the signal number is returned.

       Errors:   On error, -1 is returned, and extended error information can be obtained with fpGetErrno.

    See also:    FpSigSuspend (198  )



                1.4.80         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 (184  ), fpAlarm (156  ), fpNanoSleep (180  )


                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.81         FpStat

    Synopsis:    Retrieve file information about a file descriptor.

Declaration:     function  FpStat(path:  PChar;var  buf:  Stat)  :  cint
                function  FpStat(const  path:  RawByteString;var  buf:  Stat)  :  cint
                function  FpStat(path:  ShortString;var  buf:  Stat)  :  cint

    Visibility:   default



                                                                                 199

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



Description:     FpFStat gets information about the file specified in Path, and stores it in Info, which is of
                type stat (149  ).  The function returns zero if the call was succesfull, a nonzero return value
                indicates failure.

       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).


                sys__enoent     Path does not exist.


    See also:    FpStat (199  ), FpLStat (176  )


                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.82         fpSymlink

    Synopsis:    Create a symbolic link

Declaration:     function  fpSymlink(oldname:  PChar;newname:  PChar)  :  cint



                                                                                 200

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



    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 (169  ) 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 (175  ), FpUnLink (205  ), FpReadLink (188  )


                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- }
                    R e s e t ( F ) ;
                    { $ i+ }



                                                                                 201

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    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.83         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 (167  ), FpS_ISLNK (203  ), FpS_ISREG (203  ), FpS_ISDIR (202  ), FpS_ISCHR (202  ),
                FpS_ISFIFO (202  ), FpS_ISSOCK (204  )



                1.4.84         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 (167  ), FpS_ISLNK (203  ), FpS_ISREG (203  ), FpS_ISDIR (202  ), FpS_ISBLK (202  ),
                FpS_ISFIFO (202  ), FpS_ISSOCK (204  )



                1.4.85         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 (167  ), FpS_ISLNK (203  ), FpS_ISREG (203  ), FpS_ISCHR (202  ), FpS_ISBLK (202  ),
                fpS_ISFIFO (202  ), FpS_ISSOCK (204  )



                1.4.86         fpS__ISFIFO

    Synopsis:    Is file a FIFO

Declaration:     function  fpS_ISFIFO(m:  TMode)  :  Boolean

    Visibility:   default



                                                                                 202

                ________________________________________________________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 (167  ), FpS_ISLNK (203  ), FpS_ISREG (203  ), FpS_ISCHR (202  ), FpS_ISBLK (202  ),
                FpS_ISDIR (202  ), FpS_ISSOCK (204  )



                1.4.87         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 (167  ), FpS_ISFIFO (202  ), FpS_ISREG (203  ), FpS_ISCHR (202  ), FpS_ISBLK (202  ),
                FpS_ISDIR (202  ), FpS_ISSOCK (204  )


                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.88         fpS__ISREG

    Synopsis:    Is file a regular file

Declaration:     function  fpS_ISREG(m:  TMode)  :  Boolean

    Visibility:   default



                                                                                 203

                ________________________________________________________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 (167  ), FpS_ISFIFO (202  ), FpS_ISLNK (203  ), FpS_ISCHR (202  ), FpS_ISBLK (202  ),
                FpS_ISDIR (202  ), FPS_ISSOCK (204  )



                1.4.89         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 (167  ), FpS_ISFIFO (202  ), FpS_ISLNK (203  ), FpS_ISCHR (202  ), FpS_ISBLK (202  ),
                FpS_ISDIR (202  ), FpS_ISREG (203  )



                1.4.90         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
                (169  ).


                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.91         FpTimes

    Synopsis:    Return execution times for the current process

Declaration:     function  FpTimes(var  buffer:  tms)  :  TClock

    Visibility:   default



                                                                                 204

                ________________________________________________________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 (169  ).

    See also:    fpUTime (206  )



                1.4.92         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 (157  )


                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.93         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 (169  ).

    See also:    FpUTime (206  )



                1.4.94         FpUnlink

    Synopsis:    Unlink (i.e.  remove) a file.

Declaration:     function  FpUnlink(path:  PChar)  :  cint
                function  FpUnlink(const  path:  RawByteString)  :  cint

    Visibility:   default



                                                                                 205

                ________________________________________________________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 (175  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (169  ).


                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 (175  ), FpSymLink (200  )



                1.4.95         FpUtime

    Synopsis:    Set access and modification times of a file (touch).

Declaration:     function  FpUtime(path:  PChar;times:  pUtimBuf)  :  cint
                function  FpUtime(const  path:  RawByteString;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 (169  ).


                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 (204  ), FpChown (159  ), FpAccess (155  )


                Listing:  ./bunixex/ex25.pp



                                                                                 206

                ________________________________________________________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.96         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 (169  ).

    See also:    fpFork (166  ), fpExecve (163  ), fpWaitPid (207  )



                1.4.97         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.



                                                                                 207

                ________________________________________________________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
                      (890  ) 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 (166  ).

       Errors:   Extended error information can be retrieved using fpgetErrno (169  ).

    See also:    fpFork (166  ), fpExecve (163  ), fpWait (207  )



                1.4.98         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 (169  ).

    See also:    FpOpen (182  ), FpClose (160  ), FpRead (186  ), FpFTruncate (168  ), FpLSeek (176  )



                1.4.99         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 (150  ) buffers pointed to by iov.  It works like fpWrite (208  ) only from multiple
                buffers.

       Errors:   On error, -1 is returned.

    See also:    FpReadV (189  ), FpPWrite (186  ), FpPRead (186  )



                                                                                 208

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.100          FreeShellArgV

    Synopsis:    Free the result of a CreateShellArgV (155  ) 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 (155  ).

       Errors:   None.

    See also:    CreateShellArgV (155  )



                1.4.101          wexitStatus

    Synopsis:    Extract the exit status from the fpWaitPID (207  ) 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 (207  ) call.

    See also:    FpWaitPID (207  ), WTERMSIG (210  ), WSTOPSIG (210  ), WIFEXITED (209  ), WIFSIG-
                NALED (209  )



                1.4.102          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 (207  ), WTERMSIG (210  ), WSTOPSIG (210  ), WIFSIGNALED (209  ), WEX-
                ITSTATUS (209  )



                1.4.103          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 (207  ),  WTERMSIG (210  ),  WSTOPSIG (210  ),  WIFEXITED (209  ),  WEXIT-
                STATUS (209  )



                                                                                 209

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.104          wstopsig

    Synopsis:    Return the exit code from the process.

Declaration:     function  wstopsig(Status:  cint)  :  cint

    Visibility:   default

Description:     WSTOPSIG is an alias for WEXITSTATUS (209  ).

    See also:    FpWaitPID (207  ), WTERMSIG (210  ), WIFEXITED (209  ), WIFSIGNALED (209  ), WEX-
                ITSTATUS (209  )



                1.4.105          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 (207  ), WSTOPSIG (210  ), WIFEXITED (209  ), WIFSIGNALED (209  ), WEX-
                ITSTATUS (209  )



                                                                                 210




Chapter   2



Reference   for   unit   'character'



2.1         Used  units



                                   Table 2.1:  Used units by unit 'character'


                                                __Name________________Page_____
                                                  System               1235
                                                  unicodedata          1729



2.2         Overview


The character unit contains the TCharacter (218  ) class, which consists mainly of class func-
tions.  It should not be constructed, but its class methods can be used.  All class methods
also exist as regular methods.

Many routines depend on unicode collation data to be present in the binary (or distributed
on disc with the application.  This data can be loaded using the routines in the unicodedata
(1729   ) unit..  The FPC project distributes some unicode collation data in .bco files which
can be loaded using the LoadCollation (1738   ) routine from that unit.



2.3         Constants,  types  and  variables



2.3.1        Types

TCharacterOption  =  (coIgnoreInvalidSequence)



                      Table 2.2:  Enumeration values for type TCharacterOption


                 __Value________________________________Explanation__________________________________________
                   coIgnoreInvalidSequence              Ignore invalid unicodecode sequences



TCharacterOption is used in the toUpper (218  ) and toLower (218  ) functions to control the
behaviour of the function.



                                                             211

____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________________________*
 *___



TCharacterOptions  =  Set  of  TCharacterOption


TCharacterOptions  is  the  set  of  TCharacterOption,  used  in  toUpper  (218  )  and  toLower
(218  ) functions to control the behaviour of the function.


TUnicodeCategory  =  (ucUppercaseLetter,ucLowercaseLetter,
                                 ucTitlecaseLetter,ucModifierLetter,ucOtherLetter,
                                 ucNonSpacingMark,ucCombiningMark,ucEnclosingMark,
                                 ucDecimalNumber,ucLetterNumber,ucOtherNumber,
                                 ucConnectPunctuation,ucDashPunctuation,
                                 ucOpenPunctuation,ucClosePunctuation,
                                 ucInitialPunctuation,ucFinalPunctuation,
                                 ucOtherPunctuation,ucMathSymbol,ucCurrencySymbol,
                                 ucModifierSymbol,ucOtherSymbol,ucSpaceSeparator,
                                 ucLineSeparator,ucParagraphSeparator,ucControl,
                                 ucFormat,ucSurrogate,ucPrivateUse,ucUnassigned)



                      Table 2.3:  Enumeration values for type TUnicodeCategory



__Value______________________________Explanation___________________________________________________________________________________*
 *_______________
  ucClosePunctuation                 Punctuation, close (Pe)
  ucCombiningMark                    Mark, spacing combining (Mc)
  ucConnectPunctuation               Punctuation, connector (Pc)
  ucControl                          Other, control (Cc)
  ucCurrencySymbol                   Symbol, currency (Sc)
  ucDashPunctuation                  Punctuation, dash (Pd)
  ucDecimalNumber                    Number, decimal digit (Nd)
  ucEnclosingMark                    Mark, enclosing (Me)
  ucFinalPunctuation                 Punctuation, final quote (Pf, may behave like Ps or Pe depending on usage)
  ucFormat                           Other, format (Cf)
  ucInitialPunctuation               Punctuation, initial quote (Pi, may behave like Ps or Pe depending on usage)
  ucLetterNumber                     Number, letter (Nl)
  ucLineSeparator                    Separator, line (Zl)
  ucLowercaseLetter                  Letter, lowercase (Ll)
  ucMathSymbol                       Symbol, math (Sm)
  ucModifierLetter                   Letter, modifier (Lm)
  ucModifierSymbol                   Symbol, modifier (Sk)
  ucNonSpacingMark                   Mark, nonspacing (Mn)
  ucOpenPunctuation                  Punctuation, open (Ps)
  ucOtherLetter                      Letter, other (Lo)
  ucOtherNumber                      Number, other (No)
  ucOtherPunctuation                 Punctuation, other (Po)
  ucOtherSymbol                      Symbol, other (So)
  ucParagraphSeparator               Separator, paragraph (Zp)
  ucPrivateUse                       Other, private use (Co)
  ucSpaceSeparator                   Separator, space (Zs)
  ucSurrogate                        Other, surrogate (Cs)
  ucTitlecaseLetter                  Letter, titlecase (Lt)
  ucUnassigned                       Other, not assigned (including noncharacters) (Cn)
  ucUppercaseLetter                  Letter, uppercase (Lu)



                                                                 212

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                This enumeration type contains the characterization of all possible unicode characters.  It is
                used in the GetUnicodeCategory (214  ) and TCharacter.GetUnicodeCategory (221  ) functions.


                TUnicodeCategorySet  =  Set  of  TUnicodeCategory


                TUnicodeCategorySet  is  the  set  of  TUnicodeCategory  (212  ).   It  is  used  internally  in  the
                TCharacter (218  ) class.



                2.4         Procedures  and  functions



                2.4.1        ConvertFromUtf32

    Synopsis:    alias for TCharacter.ConvertFromUtf32

Declaration:     function  ConvertFromUtf32(AChar:  UCS4Char)  :  UnicodeString

    Visibility:   default

Description:     ConvertFromUtf32 is a shortcut for TCharacter.ConvertFromUtf32 (219  ).

    See also:    TCharacter.ConvertFromUtf32 (219  )



                2.4.2        ConvertToUtf32

    Synopsis:    alias for TCharacter.ConvertToUtf32

Declaration:     function  ConvertToUtf32(const  AString:  UnicodeString;AIndex:  Integer)
                                                        :  UCS4Char;    Overload
                function  ConvertToUtf32(const  AString:  UnicodeString;AIndex:  Integer;
                                                      out  ACharLength:  Integer)  :  UCS4Char;    Overload
                function  ConvertToUtf32(const  AHighSurrogate:  UnicodeChar;
                                                      const  ALowSurrogate:  UnicodeChar)  :  UCS4Char
                                                      ;    Overload

    Visibility:   default

Description:     ConvertToUtf32 is a shortcut for TCharacter.ConvertToUtf32 (220  ).

    See also:    TCharacter.ConvertToUtf32 (220  )



                2.4.3        GetNumericValue

    Synopsis:    Alias for TCharacter.GetNumericValue

Declaration:     function  GetNumericValue(AChar:  UnicodeChar)  :  Double;    Overload
                function  GetNumericValue(const  AString:  UnicodeString;AIndex:  Integer)
                                                         :  Double;    Overload

    Visibility:   default

Description:     GetNumericValue is a shortcut for TCharacter.GetNumericValue (220  ).

    See also:    TCharacter.GetNumericValue (220  )



                                                                                 213

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.4.4        GetUnicodeCategory

    Synopsis:    Alias for TCharacter.GetUnicodeCategory

Declaration:     function  GetUnicodeCategory(AChar:  UnicodeChar)  :  TUnicodeCategory
                                                             ;    Overload
                function  GetUnicodeCategory(const  AString:  UnicodeString;
                                                             AIndex:  Integer)  :  TUnicodeCategory
                                                             ;    Overload

    Visibility:   default

Description:     GetUnicodeCategory is a shortcut for TCharacter.GetUnicodeCategory (221  ).

    See also:    TCharacter.GetUnicodeCategory (221  )



                2.4.5        IsControl

    Synopsis:    Alias for TCharacter.IsControl

Declaration:     function  IsControl(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsControl(const  AString:  UnicodeString;AIndex:  Integer)
                                                :  Boolean;    Overload

    Visibility:   default

Description:     IsControl is a shortcut for TCharacter.IsControl (221  ).

    See also:    TCharacter.IsControl (221  )



                2.4.6        IsDigit

    Synopsis:    Alias for TCharacter.IsDigit

Declaration:     function  IsDigit(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsDigit(const  AString:  UnicodeString;AIndex:  Integer)  :  Boolean
                                           ;    Overload

    Visibility:   default

Description:     IsDigit is a shortcut for TCharacter.IsDigit (221  ).

    See also:    TCharacter.IsDigit (221  )



                2.4.7        IsHighSurrogate

    Synopsis:    Alias for TCharacter.IsHighSurrogate

Declaration:     function  IsHighSurrogate(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsHighSurrogate(const  AString:  UnicodeString;AIndex:  Integer)
                                                         :  Boolean;    Overload

    Visibility:   default

Description:     IsHighSurrogate is a shortcut for TCharacter.IsHighSurrogate (222  )

    See also:    TCharacter.IsHighSurrogate (222  )



                                                                                 214

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.4.8        IsLetter

    Synopsis:    Alias for TCharacter.IsLetter

Declaration:     function  IsLetter(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsLetter(const  AString:  UnicodeString;AIndex:  Integer)
                                              :  Boolean;    Overload

    Visibility:   default

Description:     IsLetter is a shortcut for TCharacter.IsLetter (223  )

    See also:    TCharacter.IsLetter (223  )



                2.4.9        IsLetterOrDigit

    Synopsis:    Alias for TCharacter.IsLetterOrDigit

Declaration:     function  IsLetterOrDigit(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsLetterOrDigit(const  AString:  UnicodeString;AIndex:  Integer)
                                                         :  Boolean;    Overload

    Visibility:   default

Description:     IsLetterOrDigit is a shortcut for TCharacter.IsLetterOrDigit (224  ).

    See also:    TCharacter.IsLetterOrDigit (224  )



                2.4.10         IsLower

    Synopsis:    Alias for TCharacter.IsLower

Declaration:     function  IsLower(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsLower(const  AString:  UnicodeString;AIndex:  Integer)  :  Boolean
                                           ;    Overload

    Visibility:   default

Description:     IsLower is a shortcut for TCharacter.IsLower (224  )

    See also:    TCharacter.IsLower (224  )



                2.4.11         IsLowSurrogate

    Synopsis:    Alias for TCharacter.IsLowSurrogate

Declaration:     function  IsLowSurrogate(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsLowSurrogate(const  AString:  UnicodeString;AIndex:  Integer)
                                                        :  Boolean;    Overload

    Visibility:   default

Description:     IsLowSurrogate is a shortcut for TCharacter.IsLowSurrogate (223  )

    See also:    TCharacter.IsLowSurrogate (223  )



                                                                                 215

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.4.12         IsNumber

    Synopsis:    Alias for TCharacter.IsNumber

Declaration:     function  IsNumber(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsNumber(const  AString:  UnicodeString;AIndex:  Integer)
                                              :  Boolean;    Overload

    Visibility:   default

Description:     IsNumber is a shortcut for TCharacter.IsNumber (225  )

    See also:    TCharacter.IsNumber (225  )



                2.4.13         IsPunctuation

    Synopsis:    Alias for TCharacter.IsPunctuation

Declaration:     function  IsPunctuation(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsPunctuation(const  AString:  UnicodeString;AIndex:  Integer)
                                                      :  Boolean;    Overload

    Visibility:   default

Description:     IsPunctuation is a shortcut for TCharacter.IsPunctuation (225  )

    See also:    TCharacter.IsPunctuation (225  )



                2.4.14         IsSeparator

    Synopsis:    Alias for TCharacter.IsSeparator

Declaration:     function  IsSeparator(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsSeparator(const  AString:  UnicodeString;AIndex:  Integer)
                                                   :  Boolean;    Overload

    Visibility:   default

Description:     IsSeparator is a shortcut for TCharacter.IsSeparator (225  )

    See also:    TCharacter.IsSeparator (225  )



                2.4.15         IsSurrogate

    Synopsis:    Alias for TCharacter.IsSurrogate

Declaration:     function  IsSurrogate(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsSurrogate(const  AString:  UnicodeString;AIndex:  Integer)
                                                   :  Boolean;    Overload

    Visibility:   default

Description:     IsSurrogate is a shortcut for TCharacter.IsSurrogate (222  ).

    See also:    TCharacter.IsSurrogate (222  )



                                                                                 216

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.4.16         IsSurrogatePair

    Synopsis:    Alias for TCharacter.IsSurrogatePair

Declaration:     function  IsSurrogatePair(const  AHighSurrogate:  UnicodeChar;
                                                        const  ALowSurrogate:  UnicodeChar)  :  Boolean
                                                        ;    Overload
                function  IsSurrogatePair(const  AString:  UnicodeString;AIndex:  Integer)
                                                         :  Boolean;    Overload

    Visibility:   default

Description:     IsSurrogatePair is a shortcut for TCharacter.IsSurrogatePair (223  )

    See also:    TCharacter.IsSurrogatePair (223  )



                2.4.17         IsSymbol

    Synopsis:    Alias for TCharacter.IsSymbol

Declaration:     function  IsSymbol(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsSymbol(const  AString:  UnicodeString;AIndex:  Integer)
                                              :  Boolean;    Overload

    Visibility:   default

Description:     IsSymbol is a shortcut for TCharacter.IsSymbol (226  )

    See also:    TCharacter.IsSymbol (226  )



                2.4.18         IsUpper

    Synopsis:    Alias for TCharacter.IsUpper

Declaration:     function  IsUpper(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsUpper(const  AString:  UnicodeString;AIndex:  Integer)  :  Boolean
                                           ;    Overload

    Visibility:   default

Description:     IsUpper is a shortcut for TCharacter.IsUpper (226  )

    See also:    TCharacter.IsUpper (226  )



                2.4.19         IsWhiteSpace

    Synopsis:    Alias for TCharacter.IsWhiteSpace

Declaration:     function  IsWhiteSpace(AChar:  UnicodeChar)  :  Boolean;    Overload
                function  IsWhiteSpace(const  AString:  UnicodeString;AIndex:  Integer)
                                                     :  Boolean;    Overload

    Visibility:   default

Description:     IsWhiteSpace is a shortcut for TCharacter.IsWhiteSpace (227  )

    See also:    TCharacter.IsWhiteSpace (227  )



                                                                                 217

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.4.20         ToLower

    Synopsis:    Alias for TCharacter.ToLower

Declaration:     function  ToLower(AChar:  UnicodeChar)  :  UnicodeChar;    Overload
                function  ToLower(const  AString:  UnicodeString)  :  UnicodeString
                                           ;    Overload

    Visibility:   default

Description:     ToLower is a shortcut for TCharacter.ToLower (227  )

    See also:    TCharacter.ToLower (227  )



                2.4.21         ToUpper

    Synopsis:    Alias for TCharacter.ToUpper

Declaration:     function  ToUpper(AChar:  UnicodeChar)  :  UnicodeChar;    Overload
                function  ToUpper(const  AString:  UnicodeString)  :  UnicodeString
                                           ;    Overload

    Visibility:   default

Description:     ToUpper is a shortcut for TCharacter.ToUpper (227  )

    See also:    TCharacter.ToUpper (227  )



                2.5         TCharacter



                2.5.1        Description

                TCharacter is provided for Delphi compatibility.  All it's class functions and methods are
                also available as regular functions.



                                                                                 218

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.5.2        Method  overview

                __Page______Method___________________________Description___________________________________________________________*
 *___________
                  219       ConvertFromUtf32                 Convert a UTF32 character to UnicodeString
                  220       ConvertToUtf32                   Convert a UTF16 character to a UTF32 character
                  219       Create                           Constructor (do not call)
                  220       GetNumericValue                  Get the numeric value of the character
                  221       GetUnicodeCategory               Get the unicode category of a character
                  221       IsControl                        Check  whether  a  unicode  character  is  a  unicode  control
                                                             character
                  221       IsDigit                          Check whether a unicode character is a digit
                  222       IsHighSurrogate                  Check  whether  a  unicode  character  is  a  surrogate  in  the
                                                             high range
                  223       IsLetter                         Check if a unicode character is a letter.
                  224       IsLetterOrDigit                  Check if a unicode character is a letter or digit
                  224       IsLower                          Check if a unicode character is a lowercase letter
                  223       IsLowSurrogate                   Check  whether  a  unicode  character  is  a  surrogate  in  the
                                                             low range
                  225       IsNumber                         Check if a unicode character is a number
                  225       IsPunctuation                    Check if a unicode character is a punctuation character
                  225       IsSeparator                      Check if a unicode character is a separator character
                  222       IsSurrogate                      Check whether a unicode character is a surrogate
                  223       IsSurrogatePair                  Check if a pair of characters is a set of high/low surrorgate
                                                             characters
                  226       IsSymbol                         Check if a unicode character is a symbol character
                  226       IsUpper                          Check whether a unicode character is an uppercase letter
                  227       IsWhiteSpace                     Check whether a unicode character is a whitespace char-
                                                             acter
                  227       ToLower                          Convert a character or string to lowercase
                __227_______ToUpper__________________________Convert_a_character_or_string_to_uppercase____________________________*
 *___________



                2.5.3        TCharacter.Create

    Synopsis:    Constructor (do not call)

Declaration:     constructor  Create

    Visibility:   public

Description:     Create is provided for completeness and Delphi compatibility, but should not be called in
                FPC code, it will raise an exception.

       Errors:   Any attempt to call Create will result in an exception being raised.



                2.5.4        TCharacter.ConvertFromUtf32

    Synopsis:    Convert a UTF32 character to UnicodeString

Declaration:     class  function  ConvertFromUtf32(AChar:  UCS4Char);    Static

    Visibility:   public

Description:     TCharacter.ConvertFromUtf32  converts  a  single  UTF32  character  AChar  to  a  UTF16
                string.  This is the opposite of TCharacter.ConvertToUtf32 (220  ).

                The  result  is  a  string,  since  multiple  UTF16  characters  can  be  needed  to  encode  a  single
                UTF32 character.



                                                                                 219

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



       Errors:   If AChar is not in the valid range of UTF32 characters, an EArgumentOutOfRangeException
                (211  ) exception is raised.

    See also:    EArgumentOutOfRangeException (211  ), TCharacter.ConvertToUtf32 (220  )



                2.5.5        TCharacter.ConvertToUtf32

    Synopsis:    Convert a UTF16 character to a UTF32 character

Declaration:     class  function  ConvertToUtf32(const  AString:  UnicodeString;
                                                                AIndex:  Integer);    Overload;    Static
                class  function  ConvertToUtf32(const  AString:  UnicodeString;
                                                                AIndex:  Integer;out  ACharLength:  Integer)
                                                                ;    Overload;    Static
                class  function  ConvertToUtf32(const  AHighSurrogate:  UnicodeChar;
                                                                const  ALowSurrogate:  UnicodeChar)
                                                                ;    Overload;    Static

    Visibility:   public

Description:     TCharacter.ConvertToUtf32 converts a UTF16-encoded unicode character to a Unicode32
                character.  This is the opposite of TCharacter.ConvertFromUtf32 (219  ).  The function exists
                in several overloaded versions, to be able to present the unicode character in one of 2 ways:


                     1.As a position AIndex (in unicodechar units) in a string AString to a Unicode32 char-
                       acter.  The source is a string, since multiple UTF16 characters can be needed to encode
                       a single UTF32 character.  In this form, Optionally, the character length (1 or 2) can
                       be returned in ACharLength.

                     2.As 2 UTF16 unicode characters, representing the high and low surrogate pairs: AHighSurrogate
                       and ALowSurrogate.


       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    TCharacter.ConvertFromUtf32 (219  ), EArgumentOutOfRangeException (211  ), EArgumentEx-
                ception (211  )



                2.5.6        TCharacter.GetNumericValue

    Synopsis:    Get the numeric value of the character

Declaration:     class  function  GetNumericValue(AChar:  UnicodeChar);    Overload;    Static
                class  function  GetNumericValue(const  AString:  UnicodeString;
                                                                  AIndex:  Integer);    Overload;    Static

    Visibility:   public

Description:     TCharacter.GetNumericValue returns the numerical value (ID) of the unicode character.
                The character can be presented in 2 ways:  AChar, a UTF16 unicode character, or a surrogate
                pair in a unicode string AString starting at position AIndex.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    TCharacter.GetUnicodeCategory (221  )



                                                                                 220

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.5.7        TCharacter.GetUnicodeCategory

    Synopsis:    Get the unicode category of a character

Declaration:     class  function  GetUnicodeCategory(AChar:  UnicodeChar);    Overload
                                                                       ;    Static
                class  function  GetUnicodeCategory(const  AString:  UnicodeString;
                                                                       AIndex:  Integer);    Overload;    Static

    Visibility:   public

Description:     TCharacter.GetUnicodeCategory returns the unicode category of a character.  The char-
                acter can be presented in 2 ways:  AChar, a UTF16 unicode character, or a surrogate pair in
                a unicode string AString starting at position AIndex.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    TUnicodeCategory (212  )



                2.5.8        TCharacter.IsControl

    Synopsis:    Check whether a unicode character is a unicode control character

Declaration:     class  function  IsControl(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsControl(const  AString:  UnicodeString;AIndex:  Integer)
                                                        ;    Overload;    Static

    Visibility:   public

Description:     IsControl returns True if a unicode character has category ucControl.  The character can
                be specified as a UTF16 character AChar or a UTF16 encoded character starting at position
                AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    GetUnicodeCategory (221  ), IsDigit (221  ), IsSurrogate (222  ), IsHighSurrogate (222  ), IsLow-
                Surrogate (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ),
                IsNumber  (225  ),  IsPunctuation  (225  ),  IsSeparator  (225  ),  IsSymbol  (226  ),  IsUpper  (226  ),
                IsWhiteSpace (227  )



                2.5.9        TCharacter.IsDigit

    Synopsis:    Check whether a unicode character is a digit

Declaration:     class  function  IsDigit(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsDigit(const  AString:  UnicodeString;AIndex:  Integer)
                                                     ;    Overload;    Static

    Visibility:   public

Description:     IsDigit returns True if a unicode character has category ucDecimalNumber.  The character
                can  be  specified  as  a  UTF16  character  AChar  or  a  UTF16  encoded  character  starting  at
                position AIndex in string AString.



                                                                                 221

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSurrogate  (222  ),  IsLowSurrogate
                (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ), IsNumber
                (225  ), IsPunctuation (225  ), IsSeparator (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace
                (227  )



                2.5.10         TCharacter.IsSurrogate

    Synopsis:    Check whether a unicode character is a surrogate

Declaration:     class  function  IsSurrogate(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsSurrogate(const  AString:  UnicodeString;AIndex:  Integer)
                                                           ;    Overload;    Static

    Visibility:   public

Description:     IsSurrogate returns True if a unicode character has category ucSurrogate.  The character
                can  be  specified  as  a  UTF16  character  AChar  or  a  UTF16  encoded  character  starting  at
                position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    EArgumentException (211  ), IsControl (221  ), IsDigit (221  ), IsHighSurrogate (222  ), IsLow-
                Surrogate (223  ),  IsLetter (223  ),  IsLetterOrDigit (224  ),  IsLower (224  ),  IsNumber (225  ),  Is-
                Punctuation (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace (227  )



                2.5.11         TCharacter.IsHighSurrogate

    Synopsis:    Check whether a unicode character is a surrogate in the high range

Declaration:     class  function  IsHighSurrogate(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsHighSurrogate(const  AString:  UnicodeString;
                                                                  AIndex:  Integer);    Overload;    Static

    Visibility:   public

Description:     IsHighSurrogate  returns  True  if  a  unicode  character  has  category  ucSurrogate  and  is
                in  the  high  range  of  the  surrogate  characters  (between  HIGH_SURROGATE_BEGIN  and
                HIGH_SURROGATE_END). The character can be specified as a UTF16 character AChar or
                a UTF16 encoded character starting at position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    EArgumentException (211  ), IsControl (221  ), IsDigit (221  ), IsSurrogate (222  ), IsLowSurro-
                gate (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ), IsNumber (225  ), IsPunctu-
                ation (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace (227  )



                                                                                 222

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.5.12         TCharacter.IsLowSurrogate

    Synopsis:    Check whether a unicode character is a surrogate in the low range

Declaration:     class  function  IsLowSurrogate(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsLowSurrogate(const  AString:  UnicodeString;
                                                                AIndex:  Integer);    Overload;    Static

    Visibility:   public

Description:     IsLowSurrogate  returns  True  if  a  unicode  character  has  category  ucSurrogate  and  is
                in  the  low  range  of  the  surrogate  characters  (between  LOW_SURROGATE_BEGIN  and
                LOW_SURROGATE_END). The character can be specified as a UTF16 character AChar or
                a UTF16 encoded character starting at position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    EArgumentException (211  ), IsControl (221  ), IsDigit (221  ), IsSurrogate (222  ), IsHighSurro-
                gate (222  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ), IsNumber (225  ), IsPunctu-
                ation (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace (227  )



                2.5.13         TCharacter.IsSurrogatePair

    Synopsis:    Check if a pair of characters is a set of high/low surrorgate characters

Declaration:     class  function  IsSurrogatePair(const  AHighSurrogate:  UnicodeChar;
                                                                  const  ALowSurrogate:  UnicodeChar)
                                                                  ;    Overload;    Static
                class  function  IsSurrogatePair(const  AString:  UnicodeString;
                                                                  AIndex:  Integer);    Overload;    Static

    Visibility:   public

Description:     IsSurrogatePair returns True if  AHighSurrogate and ALowSurrogate form a valid uni-
                code surrogate pair.  (AHighSurrogate is a high surrogate and ALowSurrogate a matching
                low surrogate) The character can be specified as a UTF16 character AChar or a pair of UTF16
                encoded characters starting at position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    EArgumentException  (211  ),  IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSur-
                rogate  (222  ),  IsLowSurrogate  (223  ),  IsLetter  (223  ),  IsLetterOrDigit  (224  ),  IsLower  (224  ),
                IsNumber (225  ), IsPunctuation (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace (227  )



                2.5.14         TCharacter.IsLetter

    Synopsis:    Check if a unicode character is a letter.

Declaration:     class  function  IsLetter(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsLetter(const  AString:  UnicodeString;AIndex:  Integer)
                                                      ;    Overload;    Static

    Visibility:   public



                                                                                 223

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



Description:     IsLetter returns True if a unicode character has category that is one of the letter categories
                (ucUppercaseLetter, ucLowercaseLetter, ucTitlecaseLetter, ucModifierLetter, ucOtherLetter).
                The character can be specified as a UTF16 character AChar or a UTF16 encoded character
                starting at position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception (211  ) exception is raised.  If the character at that position is not complete, an

    See also:    EArgumentException  (211  ),  IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSur-
                rogate (222  ),  IsLowSurrogate (223  ),  IsSurrogatePair (223  ),  IsLetter (223  ),  IsLetterOrDigit
                (224  ), IsLower (224  ), IsNumber (225  ), IsPunctuation (225  ), IsSymbol (226  ), IsUpper (226  ),
                IsWhiteSpace (227  )



                2.5.15         TCharacter.IsLetterOrDigit

    Synopsis:    Check if a unicode character is a letter or digit

Declaration:     class  function  IsLetterOrDigit(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsLetterOrDigit(const  AString:  UnicodeString;
                                                                  AIndex:  Integer);    Overload;    Static

    Visibility:   public

Description:     IsLetterOrDigit returns True if a unicode character has category that is one of the letter
                categories (ucUppercaseLetter, ucLowercaseLetter, ucTitlecaseLetter, ucModifierLetter,
                ucOtherLetter,ucDecimalNumber,ucLetterNumber).   The  character  can  be  specified  as  a
                UTF16 character AChar or a UTF16 encoded character starting at position AIndex in string
                AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSurrogate  (222  ),  IsLowSurrogate
                (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLower (224  ), IsNumber (225  ), IsPunctuation
                (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace (227  )



                2.5.16         TCharacter.IsLower

    Synopsis:    Check if a unicode character is a lowercase letter

Declaration:     class  function  IsLower(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsLower(const  AString:  UnicodeString;AIndex:  Integer)
                                                     ;    Overload;    Static

    Visibility:   public

Description:     IsLower returns True if a unicode character has category ucLowercaseLetter.  The char-
                acter can be specified as a UTF16 character AChar or a UTF16 encoded character starting
                at position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSurrogate  (222  ),  IsLowSurrogate
                (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsNumber (225  ), IsPunc-
                tuation (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace (227  )



                                                                                 224

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.5.17         TCharacter.IsNumber

    Synopsis:    Check if a unicode character is a number

Declaration:     class  function  IsNumber(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsNumber(const  AString:  UnicodeString;AIndex:  Integer)
                                                      ;    Overload;    Static

    Visibility:   public

Description:     IsNumber returns True if a unicode character has category that is one of the number cate-
                gories (ucDecimalNumber, ucLetterNumber, ucOtherNumber).  The character can be speci-
                fied as a UTF16 character AChar or a UTF16 encoded character starting at position AIndex
                in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSurrogate  (222  ),  IsLowSurrogate
                (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ), IsNumber
                (225  ), IsPunctuation (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace (227  )



                2.5.18         TCharacter.IsPunctuation

    Synopsis:    Check if a unicode character is a punctuation character

Declaration:     class  function  IsPunctuation(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsPunctuation(const  AString:  UnicodeString;
                                                              AIndex:  Integer);    Overload;    Static

    Visibility:   public

Description:     IsPunctuation returns True if a unicode character has category that is one of the punctua-
                tion categories (ucConnectPunctuation, ucDashPunctuation, ucOpenPunctuation, ucClosePunctuation,
                ucInitialPunctuation, ucFinalPunctuation, ucOtherPunctuation).  The character can
                be specified as a UTF16 character AChar or a UTF16 encoded character starting at position
                AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSurrogate  (222  ),  IsLowSurrogate
                (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ), IsNumber
                (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace (227  )



                2.5.19         TCharacter.IsSeparator

    Synopsis:    Check if a unicode character is a separator character

Declaration:     class  function  IsSeparator(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsSeparator(const  AString:  UnicodeString;AIndex:  Integer)
                                                           ;    Overload;    Static

    Visibility:   public



                                                                                 225

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



Description:     IsSeparator returns True if a unicode character has category that is one of the separator
                categories (ucSpaceSeparator, ucLineSeparator, ucParagraphSeparator).  The character
                can  be  specified  as  a  UTF16  character  AChar  or  a  UTF16  encoded  character  starting  at
                position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSurrogate  (222  ),  IsLowSurrogate
                (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ), IsNumber
                (225  ), IsPunctuation (225  ), IsSymbol (226  ), IsUpper (226  ), IsWhiteSpace (227  )



                2.5.20         TCharacter.IsSymbol

    Synopsis:    Check if a unicode character is a symbol character

Declaration:     class  function  IsSymbol(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsSymbol(const  AString:  UnicodeString;AIndex:  Integer)
                                                      ;    Overload;    Static

    Visibility:   public

Description:     IsSymbol returns True if a unicode character has category that is one of the symbol cate-
                gories (ucMathSymbol, ucCurrencySymbol, ucModifierSymbol, ucOtherSymbol).  The char-
                acter can be specified as a UTF16 character AChar or a UTF16 encoded character starting
                at position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSurrogate  (222  ),  IsLowSurrogate
                (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ), IsNumber
                (225  ), IsPunctuation (225  ), IsSeparator (225  ), IsUpper (226  ), IsWhiteSpace (227  )



                2.5.21         TCharacter.IsUpper

    Synopsis:    Check whether a unicode character is an uppercase letter

Declaration:     class  function  IsUpper(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsUpper(const  AString:  UnicodeString;AIndex:  Integer)
                                                     ;    Overload;    Static

    Visibility:   public

Description:     IsUpper returns True if a unicode character has category ucUppercaseLetter.  The char-
                acter can be specified as a UTF16 character AChar or a UTF16 encoded character starting
                at position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSurrogate  (222  ),  IsLowSurrogate
                (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ), IsNumber
                (225  ), IsPunctuation (225  ), IsSeparator (225  ), IsSymbol (226  ), IsWhiteSpace (227  )



                                                                                 226

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



                2.5.22         TCharacter.IsWhiteSpace

    Synopsis:    Check whether a unicode character is a whitespace character

Declaration:     class  function  IsWhiteSpace(AChar:  UnicodeChar);    Overload;    Static
                class  function  IsWhiteSpace(const  AString:  UnicodeString;
                                                             AIndex:  Integer);    Overload;    Static

    Visibility:   public

Description:     IsUpper returns True if a unicode character has is a whitespace character.  It checks the
                character properties.  The character can be specified as a UTF16 character AChar or a UTF16
                encoded character starting at position AIndex in string AString.

       Errors:   If AIndex is not a valid character index in the string AString, an EArgumentOutOfRange-
                Exception  (211  )  exception  is  raised.  If  the  character  at  that  position  is  not  complete,  an
                EArgumentException (211  ) exception is raised.

    See also:    IsControl  (221  ),  IsDigit  (221  ),  IsSurrogate  (222  ),  IsHighSurrogate  (222  ),  IsLowSurrogate
                (223  ), IsSurrogatePair (223  ), IsLetter (223  ), IsLetterOrDigit (224  ), IsLower (224  ), IsNumber
                (225  ), IsPunctuation (225  ), IsSeparator (225  ), IsSymbol (226  ), IsUpper (226  )



                2.5.23         TCharacter.ToLower

    Synopsis:    Convert a character or string to lowercase

Declaration:     class  function  ToLower(AChar:  UnicodeChar);    Overload;    Static
                class  function  ToLower(const  AString:  UnicodeString);    Overload;    Static
                class  function  ToLower(const  AString:  UnicodeString;
                                                     const  AOptions:  TCharacterOptions);    Overload
                                                     ;    Static

    Visibility:   public

Description:     ToLower converts the unicode character AChar or string AString to lowercase.  Options de-
                termines the behaviour of the conversion:  if  AOptions contains coIgnoreInvalidSequence
                then  no  exception  will  be  raised  when  the  string  or  character  contains  an  invalid  unicode
                sequence.  The default behaviour is to raise an EArgumentException (211  ) exception when
                this happens.

       Errors:   If  an  invalid  character  is  encountered,  an  EArgumentException  (211  )  exception  is  raised,
                unless coIgnoreInvalidSequence is specified in the options.

    See also:    TCharacter.ToUpper (227  ), TCharacter.IsLower (224  ), TCharacter.IsUpper (226  )



                2.5.24         TCharacter.ToUpper

    Synopsis:    Convert a character or string to uppercase

Declaration:     class  function  ToUpper(AChar:  UnicodeChar);    Overload;    Static
                class  function  ToUpper(const  AString:  UnicodeString);    Overload;    Static
                class  function  ToUpper(const  AString:  UnicodeString;
                                                     const  AOptions:  TCharacterOptions);    Overload
                                                     ;    Static

    Visibility:   public



                                                                                 227

                ____________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CHARACTER'____________________*
 *___________________



Description:     ToUpper converts the unicode character AChar or string AString to uppercase.  Options de-
                termines the behaviour of the conversion:  if  AOptions contains coIgnoreInvalidSequence
                then  no  exception  will  be  raised  when  the  string  or  character  contains  an  invalid  unicode
                sequence.  The default behaviour is to raise an EArgumentException (211  ) exception when
                this happens.

       Errors:   If  an  invalid  character  is  encountered,  an  EArgumentException  (211  )  exception  is  raised,
                unless coIgnoreInvalidSequence is specified in the options.

    See also:    TCharacter.ToUpper (227  ), TCharacter.IsLower (224  ), TCharacter.IsUpper (226  )



                                                                                 228




Chapter   3



Reference   for   unit   'charset'



3.1         Overview


The charset unit can be used to load single-byte character set (code page) descriptions.  It
is  used  in  the  fpwidestring  (229  )  unit  to  add  support  for  converting  single-byte  codepage
strings to unicode strings (and vice versa).

Data of a code page may be included using one of the ready-made units, or can be loaded (in
a binary form) at runtime with the loadbinaryunicodemapping (232  ) function.  The binary
files have the .bcm extension and are produced by the creumap utility distributed with Free
Pascal.

Pre-made units are available for the following codepages:  cp895 (229  ),  cp932 (229  ),  cp936
(229  ), cp949 (229  ) and cp950 (229  ).



3.2         Constants,  types  and  variables



3.2.1        Constants

BINARY_MAPPING_FILE_EXT  =  '.bcm'


BINARY_MAPPING_FILE_EXT contains the default extension of a file containing a binary-coded
map.



3.2.2        Types

preversecharmapping  =  ^treversecharmapping


Pointer to treversecharmapping


punicodecharmapping  =  ^tunicodecharmapping


Pointer to tunicodecharmapping


punicodemap  =  ^tunicodemap


Pointer to tunicodemap



                                                             229

_________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CHARSET'_________________________________*
 *___



treversecharmapping  =  packed  record
   unicode  :  tunicodechar;
   char1  :  Byte;
   char2  :  Byte;
end



treversecharmapping describes how a unicode character can be created in terms of single-
byte characters.


TSerializedMapHeader  =  packed  record
   cpName  :  string;
   cp  :  UInt16;
   mapLength  :  UInt32;
   lastChar  :  Int32;
   reverseMapLength  :  UInt32;
end



TSerializedMapHeader is a record describing the binary map data file.  The contents of this
record can be found at offset zero of a (.bcm) file containing a single-byte unicode map.


tunicodechar  =  Word


tunicodechar  is  a  type  used  to  represent  unicode  characters  in  this  file,  it  should  not  be
used for other unicode routines.


tunicodecharmapping  =  packed  record
   unicode  :  tunicodechar;
   flag  :  tunicodecharmappingflag;
   reserved  :  Byte;
end



tunicodecharmapping describes a unicode character.  An array of these mappings is built
for each character in the single-byte character set,


tunicodecharmappingflag  =  (umf_noinfo,umf_leadbyte,umf_undefined,
                                            umf_unused)



                  Table 3.1:  Enumeration values for type tunicodecharmappingflag


                  __Value__________________Explanation_______________________________________________________
                    umf_leadbyte            Unicode character uses leading byte
                    umf_noinfo              No extra information about unicode character
                    umf_undefined           Currently unused
                    umf_unused              Unused position in code page



tunicodecharmappingflag contains various Flags describing information about a unicode
character.



                                                                 230

                _________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CHARSET'_________________*
 *___________________



                tunicodemap  =  record
                   cpname  :  string;
                   cp  :  Word;
                   map  :  punicodecharmapping;
                   lastchar  :  LongInt;
                   reversemap  :  preversecharmapping;
                   reversemaplength  :  LongInt;
                   next  :  punicodemap;
                   internalmap  :  Boolean;
                end



                tunicodemap describes a complete mapping between a single-byte code page and a unicode
                character set.  It contains both a forward and backward mapping.


                tunicodestring  =  ^tunicodechar


                tunicodestring is a type used to represent unicode strings in this file, it should not be used
                for other unicode routines.



                3.3         Procedures  and  functions



                3.3.1        getascii

    Synopsis:    Convert unicode character or string to single-byte character or string.

Declaration:     function  getascii(c:  tunicodechar;p:  punicodemap)  :  string
                function  getascii(c:  tunicodechar;p:  punicodemap;ABuffer:  PAnsiChar;
                                            ABufferLen:  LongInt)  :  LongInt

    Visibility:   default

Description:     getascii converts a unicode character c to one or more single-byte characters according
                to the map in p.  The result can be a string containing up to 2 characters, or the number of
                characters copied to the buffer ABuffer with length ABufferLen.

       Errors:   If  the  character  cannot  be  translated,  ASCII  character  63  is  returned  (or  copied  to  the
                buffer).  In the case of the buffer variant of the function, -1 is then returned.  If the buffer is
                not large enough, -1 is returned.

    See also:    getunicode (232  )



                3.3.2        getmap

    Synopsis:    Find a codepage map

Declaration:     function  getmap(const  s:  string)  :  punicodemap
                function  getmap(cp:  Word)  :  punicodemap

    Visibility:   default

Description:     getmap looks in the registered codepage mappings and returns the mapping for the requested
                codepage.  The codepage can be specified using a name s or a numerical identifier cp.  The
                search is case sensitive.

       Errors:   if the requested map is not found, Nil is returned.

    See also:    registermapping (233  ), registerbinarymapping (233  ), mappingavailable (233  )



                                                                                 231

                _________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CHARSET'_________________*
 *___________________



                3.3.3        getunicode

    Synopsis:    Map single-byte character to unicode character.

Declaration:     function  getunicode(c:  Char;p:  punicodemap)  :  tunicodechar
                function  getunicode(AAnsiStr:  pansichar;AAnsiLen:  LongInt;
                                                AMap:  punicodemap;ADest:  tunicodestring)  :  LongInt

    Visibility:   default

Description:     The  first  form  of  getunicode  will  map  a  single  character  c  to  its  unicode  equivalent  for
                mapping p.  If no equivalent can be found, 0 is returned.

                The second form of getunicode will transform a string (specified using a pointer AAnsiStr to
                a buffer with length AAnsiLen) to a unicode string using single byte codepage map AMap.  It
                returns the number of unicode characters.  If ADest is Nil then just the number of characters
                is returned.  If ADest is not nil, it must point to a buffer large enough to contain the unicode
                string, and the converted string will be copied to it.

       Errors:   No checking on the validity of the buffers is done.

    See also:    getascii (231  )



                3.3.4        loadbinaryunicodemapping

    Synopsis:    Load binary single-byte codepage to unicode map from file or memory

Declaration:     function  loadbinaryunicodemapping(const  directory:  string;
                                                                       const  cpname:  string)  :  punicodemap
                                                                       ;    Overload
                function  loadbinaryunicodemapping(const  filename:  string)  :  punicodemap
                                                                       ;    Overload
                function  loadbinaryunicodemapping(const  AData:  Pointer;
                                                                       const  ADataLength:  Integer)
                                                                        :  punicodemap;    Overload

    Visibility:   default

Description:     loadbinaryunicodemapping loads a binary description of a single-byte unicode mapping.
                The  mapping  can  reside  in  a  file,  in  which  case  the  file  to  load  can  be  specified  using  a
                filename filename or using a directory directory and codepage name cpname.  In the latter
                case,  a  suffix  consisting  of  _le  or  _be  depending  on  the  endianness  of  the  current  platform
                will be appended, and the filename extension is .bcm.  Note that the file names may be case
                sensitive.

                The data can also be loaded from a memory block AData with size ADataLength.

                It  will  produce  an  in-memory  map  of  the  file.   It  returns  a  pointer  to  the  map,  or  Nil
                if  something  went  wrong.  The  resulting  mapping  can  be  registered  using  registermapping
                (233  ).

       Errors:   On error, Nil is returned.

    See also:    loadunicodemapping (233  ), registermapping (233  )



                                                                                 232

                _________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CHARSET'_________________*
 *___________________



                3.3.5        loadunicodemapping

    Synopsis:    Load textual single-byte codepage to unicode map from file

Declaration:     function  loadunicodemapping(const  cpname:  string;const  f:  string;
                                                             cp:  Word)  :  punicodemap

    Visibility:   default

Description:     loadunicodemapping  loads  a  text  description  of  a  single-byte  unicode  mapping.   It  will
                analyse  the  textual  description  in  file  f,  and  produce  an  in-memory  map  of  the  file.   It
                returns a pointer to the map, or Nil if something went wrong.  The unicode map name must
                be specified in cpName, and the numerical identifier in cp

                The resulting mapping can be registered using registermapping (233  ).

       Errors:   On error, Nil is returned.

    See also:    loadbinaryunicodemapping (232  ), registermapping (233  )



                3.3.6        mappingavailable

    Synopsis:    Check if a mapping is available for a specified code page.

Declaration:     function  mappingavailable(const  s:  string)  :  Boolean
                function  mappingavailable(cp:  Word)  :  Boolean

    Visibility:   default

Description:     mappingavailable returns True if a mapping for a specified code page (using name s or
                numerical identifier cp) is available, or False if it is not.

    See also:    registermapping (233  ), registerbinarymapping (233  ), getmap (231  )



                3.3.7        registerbinarymapping

    Synopsis:    Load and register binary single-byte codepage to unicode map from file

Declaration:     function  registerbinarymapping(const  directory:  string;
                                                                  const  cpname:  string)  :  Boolean

    Visibility:   default

Description:     registerbinarymapping calls loadbinaryunicodemapping (232  ) using directory and cpname
                and  registers  the  resulting  mapping,  if  any  was  succesfully  loaded,  using  registermapping
                (233  ).  It returns True if the operation was succesful.

       Errors:   On error, False is returned.

    See also:    loadbinaryunicodemapping (232  ), registermapping (233  )



                3.3.8        registermapping

    Synopsis:    Register mapping

Declaration:     procedure  registermapping(p:  punicodemap)

    Visibility:   default



                                                                                 233

                _________________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'CHARSET'_________________*
 *___________________



Description:     RegisterMapping registers mapping p in the registry of single-byte codepages.  No attempt
                is made to avoid double registrations.  In case of doubles, the last registered mapping will be
                used first.

    See also:    loadunicodemapping (233  ), loadbinaryunicodemapping (232  ), registerbinarymapping (233  )



                                                                                 234




Chapter   4



Reference   for   unit   'Classes'



4.1         Used  units



                                     Table 4.1:  Used units by unit 'Classes'


                                                  __Name____________Page____
                                                    rtlconsts          ??
                                                    System          1235
                                                    sysutils        1489
                                                    Types           1664
                                                    typinfo         1683



4.2         Overview


This documentation describes the FPC classes unit.  The Classes unit contains basic classes
for the Free Component Library (FCL):


     o  a TList (371  ) class for maintaining lists of pointers,

     o  TStringList (425  ) for lists of strings,

     o  TCollection (322  ) to manage collections of objects

     o  TStream (410  ) classes to support streaming.


Furthermore  it  introduces  methods  for  object  persistence,  and  classes  that  understand  an
owner-owned relationship, with automatic memory management.



4.3         Constants,  types  and  variables



4.3.1        Constants

BITSHIFT  =  5


Used to calculate the size of a bits array



                                                             235

__________________________________________________________CHAPTER_4.___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 (270  ) exception
is raised.


dupIgnore  =  Types  .  dupIgnore


Duplicate values will not 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  =  $FF00


TFileStream.Create (352  ) creates a new file if needed.


fmOpenRead  =  0


TFileStream.Create (352  ) opens a file with read-only access.


fmOpenReadWrite  =  2


TFileStream.Create (352  ) opens a file with read-write access.


fmOpenWrite  =  1


TFileStream.Create (352  ) opens a file with write-only access.


MASK  =  31


Bitmask with all bits on.


MaxBitFlags  =  $7FFFFFE0


Maximum number of bits in TBits collection.


MaxBitRec  =  MaxBitFlags  div  ((cardinal)  *  8)


Maximum number of bit records in TBits.


MaxListSize  =  Maxint  div  16


This constant sets the maximum number of elements in a TList (371  ).


scAlt  =  $8000



                                                                 236

__________________________________________________________CHAPTER_4.___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.


SGUIDObserved  =  '{663C603C-3F3C-4CC5-823C-AC8079F979E5}'


Observed interface GUID as a string


SGUIDObserver  =  '{BC7376EA-199C-4C2A-8684-F4805F0691CA}'


Observer interface GUID as a string


soFromBeginning  =  0


Seek (412  ) starts relative to the stream origin.


soFromCurrent  =  1


Seek (412  ) starts relative to the current position in the stream.


soFromEnd  =  2


Seek (412  ) starts relative to the stream end.


toEOF  =  (0)


Value returned by TParser.Token (391  ) when the end of the input stream was reached.


toFloat  =  (4)


Value returned by TParser.Token (391  ) when a floating point value was found in the input
stream.


toInteger  =  (3)


Value returned by TParser.Token (391  ) when an integer was found in the input stream.


toString  =  (2)


Value returned by TParser.Token (391  ) when a string was found in the input stream.


toSymbol  =  (1)


Value returned by TParser.Token (391  ) when a symbol was found in the input stream.


toWString  =  (5)


Value returned by TParser.Token (391  ) when a widestring was found in the input stream.



                                                                 237

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



4.3.2        Types

HMODULE  =  PtrInt


FPC doesn't support modules yet, so this is a dummy type.


HRSRC  =  TFPResourceHandle  deprecated


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 (249  ) record.


PStringItemList  =  ^TStringItemList


Pointer to a TStringItemList (249  ).


TActiveXRegType  =  (axrComponentOnly,axrIncludeDescendants)



                      Table 4.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 4.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



                                                                 238

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



This event occurs when an ancestor component cannot be found.


TBasicActionClass  =  Class  of  TBasicAction


TBasicAction (297  ) class reference.


TBasicActionLinkClass  =  Class  of  TBasicActionLink


TBasicActionLink (301  ) class reference.


TBiDiMode  =  (bdLeftToRight,bdRightToLeft,bdRightToLeftNoAlign,
                     bdRightToLeftReadingOnly)



                           Table 4.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 (328  ) property of TCollection
(322  ) to identify the descendent class of TCollectionItem (330  ) which should be created and
managed.


TCollectionNotification  =  (cnAdded,cnExtracting,cnDeleting)



                   Table 4.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 (322  ) class to send notifications about
changes to the collection.


TCollectionSortCompare  =  function(Item1:  TCollectionItem;
                                                        Item2:  TCollectionItem)  :  Integer



                                                                 239

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



TCollectionSortCompare is the prototype for a callback used in the TCollection.Sort (327  )
method.  The procedure should compare Item1 and Item2 and return an integer:


Result < 0       if  Item1 comes before Item2

Result = 0        if  Item1 is at the same level as Item2

Result > 0       if  Item1 comes after Item2


TComponentClass  =  Class  of  TComponent


The  TComponentClass  type  is  used  when  constructing  TComponent  (333  )  descendent  in-
stances and when registering components.


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)



                                    Table 4.6:  Enumeration values for type


  __Value________________________Explanation________________________________________________________________________________
    csAncestor                  The component is being streamed as part of a frame (?)
    csDesigning                 The component is being designed in an IDE.
    csDesignInstance            ??
    csDestroying                The component is being destroyed.
    csFixups                    The component's references to other components are being fixed.
    csFreeNotification          Indicates whether the component has freenotifications
    csInline                    Component is part of a frame (?).
    csLoading                   The component is being loaded from the stream.
    csReading                   Properties are being read from the stream.
    csUpdating                  The component is being updated.
    csWriting                   Properties are being written to the stream.



The following values are possible:


csLoading        The  component  (and  all  child  components)  are  being  loaded  from  a  stream.
       This  means  that  a  TReader  (395  )  instance  is  reading  properties  from  this  and  child
       components  from  a  stream  and  is  applying  the  values  found  in  the  stream  to  the
       properties.

csReading        The  properties  of  this  component  are  being  read  from  a  stream.  This  means
       that a TReader (395  ) instance is reading properties from this component from a stream
       and is applying the values.

csWriting       The  properties  of  this  component  are  being  written  to  a  stream.  This  means
       that a TWriter (462  ) instance is writing properties from this component to a stream.



                                                                 240

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



csDestroying         The component is being destroyed.

csDesigning         The component is being designed in an IDE.

csAncestor        The component has a design ancestor.  This is used to record differences be-
       tween  a  component  and  it's  design  ancestor.   For  example  a  form  TForm2  inherited
       from a form TForm1.  TForm1 and all its components are copied to TForm2.  TForm2 and
       all  its  inherited  components  have  csAncestor  set.  Only  differences  between  TForm1
       and TForm2 are stored in the stream of  TForm2.  The child components of a frame put
       onto a form have csAncestor too.

csInline     The component is a nested top level component.  For example a frame on a form.
       The children of the frame do not have csInline, unless they are other frames.

csDesignInstance            The  component  is  designed  (csDesigning)  and  is  a  root  component,
       meaning it has no owner (Owner=nil).

csFixups       The component's references to other components are being fixed.  While reading a
       component from stream, it can happen that the stream contains a component reference
       property  with  a  name  of  a  component  that  was  not  yet  created  and  read  from  the
       stream.  Such properties are saved,  and the missing references are resolved when the
       complete stream was read.  This resolving step is called fixing up references, and the
       csFixups flags is set during this step.

csFreeNotification            This flag indicates that the component has free notifications registered
       with TComponent.FreeNotification (336  )


TComponentStyle=  Set  of  (csInheritable,csCheckPropAvail,csSubComponent,
                                         csTransient)



                                    Table 4.7:  Enumeration values for type


      __Value_______________________Explanation__________________________________________________________________________
        csCheckPropAvail             ??
        csInheritable                The component can be on inherited forms.
        csSubComponent               Subcomponent - streamed as part of the owning component
        csTransient                  Transient component



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.


TDataModuleClass  =  Class  of  TDataModule


TDataModuleClass defines the class pointer for TDataModule (347  ).


TDuplicates  =  Types.TDuplicates



                                                                 241

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



Type to describe what to do with duplicate values in a TStringlist (425  ).


TExceptionClass  =  Class  of  Exception


TExceptionClass is the class pointer for the Exception (1659   ) class, defined in the SysUtils
(1489   ) unit.


TFilerFlag  =  (ffInherited,ffChildPos,ffInline)



                            Table 4.8:  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  TFilerFlag


Set of TFilerFlag (242  )


TFindAncestorEvent  =  procedure(Writer:  TWriter;Component:  TComponent;
                                                   const  Name:  string;
                                                   var  Ancestor:  TComponent;
                                                   var  RootAncestor:  TComponent)  of  object


Event that occurs w


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 (255  ) 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:  CodePointer;
                                               var  Error:  Boolean)  of  object



                                                                 242

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



If a TReader (395  ) instance needs to locate a method and it doesn't find it in the streamed
form,  then the OnFindMethod (405  ) 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.


TFPObservedOperation  =  (ooChange,ooFree,ooAddItem,ooDeleteItem,ooCustom)



                   Table 4.9:  Enumeration values for type TFPObservedOperation


        __Value_________________Explanation____________________________________________________________________________
          ooAddItem             An item is added to the observed object (generally a list).
          ooChange              The observed object has changed.
          ooCustom              Custom event.
          ooDeleteItem          An item is deleted from the observed object (generally a list).
          ooFree                The observed object is being freed.



TFPObservedOperation enumerates the possible operations that can be reported to an ob-
server.  Which of these operations is reported depends on the implementation of the observed
object.


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 (362  ) 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)



                          Table 4.10:  Enumeration values for type THelpType


                                __Value______________Explanation______________________________
                                  htContext          Help type:  Context ID help.
                                  htKeyword          Help type:  Keyword help



                                                                 243

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



Enumeration type specifying the kind of help requested.


TIdentMapEntry  =  record
   Value  :  Integer;
   Name  :  string;
end



TIdentMapEntry  is  used  internally  by  the  IdentToInt  (257  )  and  IntToIdent  (258  )  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 (263  ) call.


TInitComponentHandler  =  function(Instance:  TComponent;
                                                      RootAncestor:  TClass)  :  Boolean


TInitComponentHandler is a callback type.  It is used in the InitInheritedComponent (258  )
call  to  initialize  a  component.  Callbacks  of  this  type  are  registered  with  the  RegisterInit-
ComponentHandler (263  ) 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 (263  ) call.


TLeftRight  =  taLeftJustify..taRightJustify


TLeftRight is a subrange type based on the TAlignment (238  ) enumerated type.  It contains
only the left and right alignment constants.


TListAssignOp  =  (laCopy,laAnd,laOr,laXor,laSrcUnique,laDestUnique)



                        Table 4.11:  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



This type determines what operation TList.Assign (377  ) or TFPList.assign (358  ) performs.



                                                                 244

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



TListCallback  =  Types.TListCallback


TListCallback  is  the  method  callback  prototype  for  the  function  that  is  passed  to  the
TFPList.ForEachCall (359  ) 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 4.12:  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 (359  ) 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.


TObjectTextEncoding  =  (oteDFM,oteLFM)



                   Table 4.13:  Enumeration values for type TObjectTextEncoding


            __Value___________Explanation_________________________________________________________________________
              oteDFM         Characters are in DFM (Delphi) format:  widechar encoded.
              oteLFM         Characters are in LFM format:  UTF-8 encoded.



TObjectTextEncoding is an enumerated type which denotes the encoding of non ascii char-
acters in an object stream file.  It is needed for correct encoding when reading string values
in the text stream.


TOperation  =  (opInsert,opRemove)



                                                                 245

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



                          Table 4.14:  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.



Operation of which a component is notified.


TPersistentClass  =  Class  of  TPersistent


TPersistentClass is the class reference type for the TPersistent (391  ) class.


TPoint  =  Types.TPoint


This  record  describes  a  coordinate.   It  is  used  to  handle  the  Top  (333  )  and  Left  (333  )
properties of TComponent (333  ).

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  (405  )
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 (391  ) 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.



                                                                 246

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



TReadWriteStringPropertyEvent  =  procedure(Sender:  TObject;
                                                                     const  Instance:  TPersistent;
                                                                     PropInfo:  PPropInfo;
                                                                     var  Content:  string)  of  object


TReadWriteStringPropertyEvent is the prototype for the TReader.OnReadStringProperty
(407  )  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 4.15:  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 (412  ) 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 (406  )
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  TShiftStateEnum



                                                                 247

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



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.


TShiftStateEnum  =  (ssShift,ssAlt,ssCtrl,ssLeft,ssRight,ssMiddle,
                               ssDouble,ssMeta,ssSuper,ssHyper,ssAltGr,ssCaps,ssNum,
                               ssScroll,ssTriple,ssQuad,ssExtra1,ssExtra2)



                      Table 4.16:  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



Keyboard/Mouse shift state enumerator


TShortCut  =  (Word)..(Word)


Enumeration type to identify shortcut key combinations.


TSmallPoint  =  record
   x  :  SmallInt;
   y  :  SmallInt;
end



Same  as  TPoint  (246  ),  only  the  X  and  Y  ranges  are  limited  to  2-byte  integers  instead  of
4-byte integers.


TStreamOwnership  =  (soReference,soOwned)



                                                                 248

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



                     Table 4.17:  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 (420  ) acts, when the adapter is freed.


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 (425  ) 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 4.18:  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.



                                                                 249

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



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,vaUString,vaQWord)



                          Table 4.19:  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.
                           vaQWord                 QWord (64-bit word) value
                           vaSet                   Set data follows.
                           vaSingle                Single type follows.
                           vaString                String value.
                           vaTrue                  Boolean True value.
                           vaUString               UnicodeString 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
(469  )  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



                                                                 250

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



The TWriterProc writer procedure is a callback procedure which will be used by a TPersis-
tent (391  ) 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.



4.3.3        Variables

AddDataModule  :  procedure(DataModule:  TDataModule)  of  object


AddDataModule can be set by an IDE or a streaming mechanism to receive notification when
a new instance of a TDataModule (347  ) 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 (347  ) is created.


ApplicationShowException  :  procedure(E:  Exception)  of  object


Unused.


CreateVCLComObjectProc  :  procedure(Component:  TComponent)  =  Nil


CreateVCLComObjectProc  is  called  by  TComponent  if  it  needs  to  create  a  IVCLComObject
interface for itself (when the ComObject property is read).  It passes itself as the Component
parameter.


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 (347  ) descendent is freed.



                                                                 251

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                WakeMainThread  :  TNotifyEvent  =  Nil


                WakeMainThread is a handler, which, when set, is called by the TThread.Synchronize (452  )
                routine to signal the main thread that a synchronization routine is waiting in the queue.

                This handler is by default empty.  An actual implementation depends on the main program
                logic (usually an event loop) and must be provided by the event loop logic:  the event loop
                will  normally  call  CheckSynchronize  (253  )  at  regular  intervals.  The  WakeMainThread  can
                make sure this happens as soon as possible.

                While  this  handle  should  alert  the  main  program  thread  that  a  thread  is  waiting  for  syn-
                chronization, 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 synchroniza-
                tion.  For example, by sending a message.



                4.4         Procedures  and  functions



                4.4.1        ActivateClassGroup

    Synopsis:    Activates a class group

Declaration:     function  ActivateClassGroup(AClass:  TPersistentClass)  :  TPersistentClass

    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 (265  ), GroupDescendentsWith (257  ), ClassGroupOf (253  )



                4.4.2        BeginGlobalLoading

    Synopsis:    Not yet implemented

Declaration:     procedure  BeginGlobalLoading

    Visibility:   default

Description:     Not yet implemented



                4.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.



                                                                                 252

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



       Errors:   No length checking is done, so if an invalid size is specified, an exception may follow.

    See also:    HexToBin (257  )



                4.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 (247  ) record with the given origin (ALeft,ATop) and dimensions
                (AWidth,AHeight)  filled  in.   The  bottom-right  corner  is  calculated  by  adding  AWidth  to
                ALeft and AHeight to ATop.  As a result, a rectangle with width/height set to 0 is exactly 1
                pixel.

    See also:    Rect (261  )



                4.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 (452  ) calls that may be waiting for execution by the main thread.  If
                any such calls are waiting for execution by the main thread, they are executed at once, in
                the order that they were scheduled.

                The function returns True if any Synchronize method was executed.

                TimeOut  is  the  maximum  amount  of  time  (in  milliseconds)  that  the  CheckSynchronize
                routine will wait for synchronisation requests to appear in the queue.

                Calling this routine more often will ensure that synchronize requests are handled faster.

                This routine may not be called from any thread other than the main thread, as it will execute
                the waiting requests.

                Threads may call the WakeMainThread (252  ) to signal the main thread that the synchroni-
                sation queue contains items, and thus speed up the execution of the synchronize calls.

    See also:    TThread.Synchronize (452  ), WakeMainThread (252  )



                4.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 (265  ), ActivateClassGroup (252  ), GroupDescendentsWith (257  )



                                                                                 253

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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



                4.4.8        EndGlobalLoading

    Synopsis:    Not yet implemented.

Declaration:     procedure  EndGlobalLoading

    Visibility:   default

Description:     Not yet implemented.



                4.4.9        ExtractStrings

    Synopsis:    Split a string in different words.

Declaration:     function  ExtractStrings(Separators:  TSysCharSet;WhiteSpace:  TSysCharSet;
                                                      Content:  PChar;Strings:  TStrings;
                                                      AddEmptyStrings:  Boolean)  :  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.



                4.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 (256  ) function does not raise an exception when it does not find the class, but
                returns a Nil pointer instead.

    See also:    RegisterClass (262  ), GetClass (256  )



                                                                                 254

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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 (242  ).  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 (242  )



                4.4.12         FindIdentToInt

    Synopsis:    Return the string to integer converter for an integer type

Declaration:     function  FindIdentToInt(AIntegerType:  Pointer)  :  TIdentToInt

    Visibility:   default

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 (257  ) is called.

       Errors:   Nil is returned if no handler is registered for the given type.



                4.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 (258  ) is called.

       Errors:   Nil is returned if no handler is registered for the given type.

    See also:    IntToIdent (258  ), TIntToIdent (244  ), FindIdentToInt (255  )



                4.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 (256  )



                                                                                 255

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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 (254  ) function will raise an exception if the does not find the class.

    See also:    RegisterClass (262  ), GetClass (256  )



                4.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 (256  ), GlobalFixupReferences (256  )



                4.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 (256  ), GlobalFixupReferences (256  )



                4.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.



                                                                                 256

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    See also:    GetFixupReferenceNames (256  ), GetFixupInstanceNames (256  )



                4.4.19         GroupDescendentsWith

    Synopsis:    Add class to the group of another class.

Declaration:     procedure  GroupDescendentsWith(AClass:  TPersistentClass;
                                                                  AClassGroup:  TPersistentClass)

    Visibility:   default

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.

    See also:    StartClassGroup (265  ), ActivateClassGroup (252  ), ClassGroupOf (253  )



                4.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 (252  )



                4.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 (244  ), TIntToIdent (244  ), IntToIdent (258  ), TIdentMapEntry (244  )



                                                                                 257

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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 (260  )



                4.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 (260  ), ReadComponentResEx (261  ), ReadComponentResFile (261  )



                4.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 (244  ), TintToIdent (244  ), IdentToInt (257  ), TIdentMapEntry (244  )



                4.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 (246  ), TSmallPoint (248  ), PointsEqual (260  )



                                                                                 258

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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.



                4.4.27         NotifyGlobalLoading

    Synopsis:    Not yet implemented.

Declaration:     procedure  NotifyGlobalLoading

    Visibility:   default

Description:     Not yet implemented.



                4.4.28         ObjectBinaryToText

    Synopsis:    Converts an object stream from a binary to a text format.

Declaration:     procedure  ObjectBinaryToText(Input:  TStream;Output:  TStream;
                                                              Encoding:  TObjectTextEncoding)
                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 (259  )



                4.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 (259  )

    See also:    ObjectBinaryToText (259  ), ObjectTextToResource (260  )



                4.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.



                                                                                 259

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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 (259  ), ObjectResourceToText (259  )



                4.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 (246  ) record with the given coordinates AX and AY filled in.

    See also:    TPoint (246  ), SmallPoint (265  ), Rect (261  ), Bounds (253  )



                4.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 (246  ) or TSmallPoint (248  ))
                and returns True if the X and Y coordinates of the points are equal, or False otherwise.

    See also:    TPoint (246  ), TSmallPoint (248  ), InvalidPoint (258  )



                4.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:     ReadComponentRes will read the component's properties from the resource ResName in the
                current module (always program module).  It returns Nil if the resource was not found.  It
                returns Instance if the resource was found and successfully applied to the component.

       Errors:   The function may raise an exception if the stream contains wrong data.

    See also:    ReadComponentResEx (261  )



                                                                                 260

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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:     ReadComponentRes  will  locate  the  resource  ResName  in  instance  HInstance  (the  current
                program, normally).  It returns Nil if the resource was not found.  It returns an instantiated
                component with all properties found in the stream, applied.  This requires that the component
                is registered using registerclass.

       Errors:   The function may raise an exception if the stream contains wrong data.

    See also:    ReadComponentRes (260  )



                4.4.36         ReadComponentResFile

    Synopsis:    Read component properties from a specified resource file

Declaration:     function  ReadComponentResFile(const  FileName:  string;
                                                                Instance:  TComponent)  :  TComponent

    Visibility:   default

Description:     ReadComponentResFile starts reading properties for Instance from the file FileName.  It
                creates a filestream from FileName and then calls the TStream.ReadComponentRes (414  )
                method to read the state of the component from the stream.

    See also:    TStream.ReadComponentRes (414  ), WriteComponentResFile (266  )



                4.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 (247  ) 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 (247  ), Point (260  ), SmallPoint (265  ), Bounds (253  )



                4.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



                                                                                 261

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (264  )



                4.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 (262  ), RegisterClassAlias (262  ), RegisterComponents (263  ), UnregisterClass
                (265  )



                4.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 (262  ), RegisterClasses (262  ), RegisterComponents (263  ), UnregisterClass (265  )



                4.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 (262  ), RegisterClassAlias (262  ), RegisterComponents (263  ), UnregisterClass
                (265  )



                                                                                 262

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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 (262  ), RegisterNoIcon (264  )



                4.4.43         RegisterFindGlobalComponentProc

    Synopsis:    Register a component searching handler

Declaration:     procedure  RegisterFindGlobalComponentProc
                                                                                    (AFindGlobalComponent:  TFindGlobalComponent)

    Visibility:   default

Description:     RegisterFindGlobalComponentProc registers a global component search callback AFindGlobalComponent.
                When FindGlobalComponent (255  ) is called, then this callback will be used to search for the
                component.

       Errors:   None.

    See also:    FindGlobalComponent (255  ), UnRegisterFindGlobalComponentProc (266  )



                4.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 (258  ) call.

    See also:    InitInheritedComponent (258  ), TInitComponentHandler (244  )



                4.4.45         RegisterIntegerConsts

    Synopsis:    Registers some integer-to-identifier mappings.

Declaration:     procedure  RegisterIntegerConsts(IntegerType:  Pointer;
                                                                   IdentToIntFn:  TIdentToInt;
                                                                   IntToIdentFn:  TIntToIdent)



                                                                                 263

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    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 (257  ) and
                IntToIdent (258  ) can be used to implement these callback functions.

    See also:    TIdentToInt (244  ), TIntToIdent (244  ), IdentToInt (257  ), IntToIdent (258  )



                4.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 (263  ) except that it
                calls RegisterNoIconProc (251  ) instead of RegisterComponentsProc (251  )

    See also:    RegisterNoIconProc (251  ), RegisterComponents (263  )



                4.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



                4.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 (261  )



                                                                                 264

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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 (261  ), RemoveFixupReferences (264  )



                4.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 (248  ) record with the given coordinates AX and AY filled
                in.

    See also:    TSmallPoint (248  ), Point (260  ), Rect (261  ), Bounds (253  )



                4.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 (257  ), ActivateClassGroup (252  ), ClassGroupOf (253  )



                4.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 (266  ), UnRegisterModuleClasses (266  ), RegisterClass (262  )



                                                                                 265

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.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.



                4.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
                (255  ) is called, then this callback will be no longer be used to search for the component.

       Errors:   None.

    See also:    FindGlobalComponent (255  ), RegisterFindGlobalComponentProc (263  )



                4.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 (265  ), UnRegisterClasses (266  ), RegisterClasses (262  )



                4.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 (415  ) method
                to write the state of the component to the stream.

    See also:    TStream.WriteComponentRes (415  ), ReadComponentResFile (261  )



                                                                                 266

            __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



            4.5         EBitsError



            4.5.1        Description

            When  an  index  of  a  bit  in  a  TBits  (315  )  is  out  of  the  valid  range  (0  to  Count-1)  then  a
            EBitsError exception is raised.



            4.6         EClassNotFound



            4.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.


See also:    EFilerError (267  )



            4.7         EComponentError



            4.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.


See also:    TComponent (333  ), TComponent.Name (342  )



            4.8         EFCreateError



            4.8.1        Description

            When the operating system reports an error during creation of a new file in the Filestream
            Constructor (352  ), a EFCreateError is raised.


See also:    EStreamError (269  ), EFOpenError (268  )



            4.9         EFilerError



            4.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.


See also:    EStreamError (269  ), EReadError (269  )



                                                                             267

            __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



            4.10          EFOpenError



            4.10.1         Description

            When the operating system reports an error during the opening of a file in the Filestream
            Constructor (352  ), a EFOpenError is raised.


See also:    EStreamError (269  ), EFCreateError (267  )



            4.11          EInvalidImage



            4.11.1         Description

            This exception is not used by Free Pascal but is provided for Delphi compatibility.



            4.12          EInvalidOperation



            4.12.1         Description

            This exception is not used in Free Pascal, it is defined for Delphi compatibiliy purposes only.



            4.13          EListError



            4.13.1         Description

            If an error occurs in one of the TList (371  ) or TStrings (430  ) 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)

                6.  An attempt was made to move an item to a position outside the list's bounds.


See also:    TList (371  ), TStrings (430  )



            4.14          EMethodNotFound



            4.14.1         Description

            This  exception  is  no  longer  used  in  the  streaming  system.   This  error  is  replaced  by  a
            EReadError (269  ).


See also:    EFilerError (267  ), EReadError (269  )



                                                                             268

            __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



            4.15          EObserver



            4.15.1         Description

            EObserver is an error that is raised when an object is registered as an observer, and it does
            not implement the IFPObserver (273  ) interface.


See also:    IFPObserver (273  ), IFPObserved.FPOAttachObserver (272  )



            4.16          EOutOfResources



            4.16.1         Description

            This exception is not used in Free Pascal, it is defined for Delphi compatibiliy purposes only.



            4.17          EParserError



            4.17.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.


See also:    TParser (385  )



            4.18          EReadError



            4.18.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.


See also:    EFilerError (267  ), EWriteError (271  )



            4.19          EResNotFound



            4.19.1         Description

            This exception is not used by Free Pascal but is provided for Delphi compatibility.



            4.20          EStreamError



            4.20.1         Description

            An EStreamError is raised when an error occurs during reading from or writng to a stream:
            Possible causes are



                                                                             269

            __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



                1.  Not enough data is available in the stream.

                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.


See also:    EFCreateError (267  )



            4.21          EStringListError



            4.21.1         Description

            When an error occurs in one of the methods of TStrings (430  ) 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 (425  ) when TStringList.Duplicates
                    (428  ) is False.


See also:    TStrings (430  ), TStringList (425  )



            4.22          EThread



            4.22.1         Description

            Thread error exception.



            4.23          EThreadDestroyCalled



            4.23.1         Description

            Exception raised when a thread is destroyed illegally.



            4.24          EThreadExternalException



            4.24.1         Description

            EThreadExternalException is raised by for example TThread.CheckTerminated (454  ) and
            TThread.SetReturnValue (453  ) when the thread was not created by the Free Pascal program,
            but by an external code base (for example a DLL, or the calling application in a DLL).


See also:    TThread.CheckTerminated (454  ), TThread.SetReturnValue (453  )



                                                                             270

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.25          EWriteError



                4.25.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.


    See also:    EFilerError (267  ), EReadError (269  )



                4.26          IDesignerNotify



                4.26.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.



                4.26.2         Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                  271       Modified            Notify that the component is modified.
                __271_______Notification________Notification_of_owner_changes______________________________________________________*
 *___________



                4.26.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.



                4.26.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 (334  ) which is used
                to communicate adds to the components.

    See also:    TComponent.Notification (334  )



                                                                                 271

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.27          IFPObserved



                4.27.1         Description

                IFPObserved is an interface which can be implemented in objects that must be observable.
                Objects that wish to observe the object can register themselves with the FPOAttachObserver
                (235  ) call, and must be detached using the FPODetachObserver (235  ) call.

                This interface is not reference counted,  so care must be taken that the ooFree message is
                sent with FPONotifyObservers (235  ) when the object is freed.


    See also:    FPONotifyObservers (235  )



                4.27.2         Method  overview

                __Page______Method___________________________Description___________________________________________________________*
 *___________
                  272       FPOAttachObserver                Attach a new observer to the object
                  272       FPODetachObserver                Remove an observer from the list of observers.
                __273_______FPONotifyObservers_______________Notify_all_observers__________________________________________________*
 *___________



                4.27.3         IFPObserved.FPOAttachObserver

    Synopsis:    Attach a new observer to the object

Declaration:     procedure  FPOAttachObserver(AObserver:  TObject)

    Visibility:   default

Description:     FPOAttachObserver  must  be  called  with  an  object  instance  AObserver  that  implements
                the IFPObserver (273  ) interface.  The FPOObservedChanged (273  ) method of the interface
                will be called whenever FPONotifyObservers (235  ) is used to notify observers of a change.
                Objects implementing this interface should check that AObserver actually implements the
                IFPObserver (273  ) interface.

                Do  not  make  assumptions  on  how  the  interface  behaves  if  FPOAttachObserver  is  called
                more  than  once  with  the  same  interface.   It  may  add  the  object  to  the  list  of  observers
                unconditionally (in which case it will be notified twice) or it may check that it is not yet in
                the list.

       Errors:   If  AObserver  does  not  implement  the  IFPObserver  (273  )  interface,  an  EObserver  (269  )
                exception  must  be  raised.  No  other  errors  should  be  raised,  other  than  a  possible  out  of
                memory error.

    See also:    IFPObserver (273  ), FPOObservedChanged (273  ), FPONotifyObservers (235  )



                4.27.4         IFPObserved.FPODetachObserver

    Synopsis:    Remove an observer from the list of observers.

Declaration:     procedure  FPODetachObserver(AObserver:  TObject)

    Visibility:   default

Description:     FPODetachObserver removes the AObserver object from the list of observers.  If it was not
                in the list, then this is silently accepted.  Once removed, it will no longer receive notifications
                when FPOObservedChanged (273  ) is called.



                                                                                 272

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                If the object was added more than once using FPOAttachObserver (235  ),  then it depends
                on the implementor of the interface whether or FPODetachObserver must be called an equal
                number of times.

    See also:    IFPObserver  (273  ),  FPOObservedChanged  (273  ),  FPONotifyObservers  (235  ),  FPOAtta-
                chObserver (235  )



                4.27.5         IFPObserved.FPONotifyObservers

    Synopsis:    Notify all observers

Declaration:     procedure  FPONotifyObservers(ASender:  TObject;
                                                              AOperation:  TFPObservedOperation;
                                                              Data:  Pointer)

    Visibility:   default

Description:     FPONotifyObservers notifies all observers of the object that a change has occurred.  It calls
                FPOObservedChanged (273  ) on the IFPObserver (273  ) interface of all attached objects, and
                passes on ASender (normally this is Self), AOperation and Data.  What Data is, depends
                on the implementor of the interface.

                There is no guaranteed order in which the change notifications are delivered to the observers.
                This is an implementation-specific detail, which should not be relied upon in any way.

    See also:    IFPObserver  (273  ),  FPOObservedChanged  (273  ),  FPODetachObserver  (235  ),  FPOAtta-
                chObserver (235  )



                4.28          IFPObserver



                4.28.1         Description

                IFPObserver is the interface an object must implement if it wishes to receive change notifi-
                cations from another object.  The presence of this interface will be checked when the object
                registers itself using IFPObserver.FPOAttachObserver (273  ).  The change notifications arrive
                because the FPOObservedChanged (235  ) method is called by the observed object.


    See also:    IFPObserved (272  ), FPOAttachObserver (272  )



                4.28.2         Method  overview

                __Page______Method______________________________Description________________________________________________________*
 *___________
                __273_______FPOObservedChanged__________________Entry_point_for_change_notifications_______________________________*
 *___________



                4.28.3         IFPObserver.FPOObservedChanged

    Synopsis:    Entry point for change notifications

Declaration:     procedure  FPOObservedChanged(ASender:  TObject;
                                                              Operation:  TFPObservedOperation;
                                                              Data:  Pointer)

    Visibility:   default



                                                                                 273

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     FPOObservedChanged  is  the  method  that  is  called  by  an  observed  object  (IFPObserved
                (272  )) when it calls FPONotifyObservers (273  ) The Sender is the object under observation,
                the Operation and Data are the parameters used in the call to FPONotifyObservers.

    See also:    IFPObserved (272  ), FPONotifyObservers (273  )



                4.29          IInterfaceComponentReference



                4.29.1         Description

                IInterfaceComponentReference is an interface to return the component that implements
                a given interface.  It is implemented by TComponent (333  ).


    See also:    TComponent (333  )



                4.29.2         Method  overview

                __Page______Method___________________Description___________________________________________________________________*
 *___________
                __274_______GetComponent_____________Return_component_instance_____________________________________________________*
 *___________



                4.29.3         IInterfaceComponentReference.GetComponent

    Synopsis:    Return component instance

Declaration:     function  GetComponent  :  TComponent

    Visibility:   default

Description:     GetComponent returns the component instance.

       Errors:   None.

    See also:    TComponent (333  )



                4.30          IInterfaceList



                4.30.1         Description

                IInterfaceList is an interface for maintaining a list of interfaces, strongly resembling the
                standard  TList  (371  )  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.


    See also:    TList (371  )



                                                                                 274

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.30.2         Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  278       Add                   Add an interface to the list
                  277       Clear                 Clear the list
                  277       Delete                Remove an interface from the list
                  277       Exchange              Exchange 2 interfaces in the list
                  277       First                 Return the first non-empty interface in the list.
                  275       Get                   Retrieve an interface pointer from the list.
                  275       GetCapacity           Return the capacity of the list.
                  276       GetCount              Return the current number of elements in the list.
                  278       IndexOf               Return the index of an interface.
                  278       Insert                Insert an interface in the list.
                  278       Last                  Returns the last non-nil interface in the list.
                  279       Lock                  Lock the list
                  276       Put                   Write an item to the list
                  278       Remove                Remove an interface from the list
                  276       SetCapacity           Set the capacity of the list
                  276       SetCount              Set the number of items in the list
                __279_______Unlock________________Unlock_the_list._________________________________________________________________*
 *___________



                4.30.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  279       Capacity          rw           Capacity of the list
                  279       Count             rw           Current number of elements in the list.
                  280       Items             rw           Provides Index-based, sequential, access to the interfaces in
                ___________________________________________the_list._______________________________________________________________*
 *___________



                4.30.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 (280  ) property.

    See also:    IInterfaceList.Items (280  ), TList.Items (379  )



                4.30.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 (279  ) property.

    See also:    IInterfaceList.Capacity (279  ), TList.Capacity (378  )



                                                                                 275

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.30.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 (279  ) property.

    See also:    IInterfaceList.Count (279  ), TList.Count (379  )



                4.30.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 (280  ) property.

    See also:    IInterfaceList.Items (280  ), TList.Items (379  )



                4.30.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 (279  ) property.

    See also:    IInterfaceList.Capacity (279  ), TList.Capacity (378  )



                4.30.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 (279  )

    See also:    IInterfaceList.Count (279  ), TList.Count (379  )



                                                                                 276

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.30.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 (374  )



                4.30.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 (374  ), IInterfaceList.Add (278  ), IInterfaceList.Delete (277  ), IInterfaceList.Insert
                (278  )



                4.30.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 (375  ), IInterfaceList.Add (278  ), IInterfaceList.Delete (277  ), IInterfaceList.Insert
                (278  )



                4.30.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 (376  ), IInterfaceList.IndexOf (278  ), IInterfaceList.Last (278  )



                                                                                 277

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.30.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 (376  ), IInterfaceList.First (277  ), IInterfaceList.Last (278  )



                4.30.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 (374  ), IInterfaceList.Insert (278  ), IInterfaceList.Delete (277  )



                4.30.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 (376  ), IInterfaceList.Add (278  ), IInterfaceList.Delete (277  )



                4.30.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 (377  ), IInterfaceList.First (277  ), IInterfaceList.IndexOf (278  )



                4.30.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 (377  ), IInterfaceList.Delete (277  ), IInterfaceList.IndexOf (278  )



                                                                                 278

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.30.19          IInterfaceList.Lock

    Synopsis:    Lock the list

Declaration:     procedure  Lock

    Visibility:   default

Description:     Lock locks the list.  After a call to lock, the object list can only be accessed by the current
                thread, untill UnLock (279  ) is called.

    See also:    TInterfaceList.Lock (368  ), IInterfaceList.Unlock (279  )



                4.30.20          IInterfaceList.Unlock

    Synopsis:    Unlock the list.

Declaration:     procedure  Unlock

    Visibility:   default

Description:     Unlock unlocks a locked list.  After a call to UnLock, other threads are again able to access
                the list.

    See also:    TInterfaceList.UnLock (369  ), IInterfaceList.Lock (279  )



                4.30.21          IInterfaceList.Capacity

    Synopsis:    Capacity of the list

Declaration:     Property  Capacity  :  Integer

    Visibility:   default

      Access:    Read,Write

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 (378  ), IInterfaceList.Count (279  )



                4.30.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 (279  ), TList.Count (379  )



                                                                                 279

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.30.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 (279  ), TList.Items (379  )



                4.31          IStreamPersist



                4.31.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.


    See also:    TPersistent (391  ), TComponent (333  ), TStream (410  )



                4.31.2         Method  overview

                __Page______Method______________________Description________________________________________________________________*
 *___________
                  280       LoadFromStream              Load persistent data from stream.
                __280_______SaveToStream________________Save_persistent_data_to_stream.____________________________________________*
 *___________



                4.31.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 (391  ), TComponent (333  ), TStream (410  ), IStreamPersist.SaveToStream (280  )



                4.31.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  (391  ),  TComponent  (333  ),  TStream  (410  ),  IStreamPersist.LoadFromStream
                (280  )



                                                                                 280

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.32          IStringsAdapter



                4.32.1         Description

                Is not yet supported in Free Pascal.


    See also:    TStrings (430  )



                4.32.2         Method  overview

                __Page______Method_____________________Description_________________________________________________________________*
 *___________
                  281       ReferenceStrings           Add a reference to the indicated strings.
                __281_______ReleaseStrings_____________Release_the_reference_to_the_strings._______________________________________*
 *___________



                4.32.3         IStringsAdapter.ReferenceStrings

    Synopsis:    Add a reference to the indicated strings.

Declaration:     procedure  ReferenceStrings(S:  TStrings)

    Visibility:   default



                4.32.4         IStringsAdapter.ReleaseStrings

    Synopsis:    Release the reference to the strings.

Declaration:     procedure  ReleaseStrings

    Visibility:   default



                4.33          IVCLComOb ject



                4.33.1         Description

                IVCLComObject is used by TComponent to implement the IUnknown interface used by COM
                automation  servers.   Partially,  it  is  the  translation  to  pascal  of  the  IDispatch  interface
                definition by Microsoft.  If  TComponent needs to return an IUnknown interface, it creates a
                IVCLComObject interface instead.


    See also:    TComponent.VCLComObject (342  )



                4.33.2         Method  overview

                __Page______Method________________________Description______________________________________________________________*
 *___________
                  283       FreeOnRelease                 Is called by TComponent.FreeOnRelease
                  282       GetIDsOfNames                 The IDispatch:GetIDsOfNames call for automation servers.
                  282       GetTypeInfo                   The IDispatch:GetTypeInfo call for automation servers
                  282       GetTypeInfoCount              The   IDispatch:GetTypeInfoCount   call   for   automation
                                                          servers
                  282       Invoke                        The IDispatch:Invoke call for automation servers.
                  283       SafeCallException             This  method  can  be  invoked  if  an  exception  occurs  during
                __________________________________________Invoke___________________________________________________________________*
 *___________



                                                                                 281

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.33.3         IVCLComObject.GetTypeInfoCount

    Synopsis:    The IDispatch:GetTypeInfoCount call for automation servers

Declaration:     function  GetTypeInfoCount(out  Count:  Integer)  :  HRESULT

    Visibility:   default

Description:     GetTypeInfoCount  must  return  in  Count  either  0  or  1  to  indicate  that  it  provides  type
                information (1) or not (0).

       Errors:   On error, a nonzero (different from S_OK) return value must be returned.

    See also:    IVCLComObject.GetTypeInfo (282  )



                4.33.4         IVCLComObject.GetTypeInfo

    Synopsis:    The IDispatch:GetTypeInfo call for automation servers

Declaration:     function  GetTypeInfo(Index:  Integer;LocaleID:  Integer;out  TypeInfo)
                                                   :  HRESULT

    Visibility:   default

Description:     GetTypeInfo  must  return  the  Index-th  entry  in  the  type  information  of  the  component
                in  TypeInfo.  The  LocaleID  argument  can  be  used  to  indicate  the  locale  of  the  caller,  as
                different type information can be returned depending on the locale.

       Errors:   On error, a nonzero (different from S_OK) return value must be returned.

    See also:    IVCLComObject.GetTypeInfoCount (282  )



                4.33.5         IVCLComObject.GetIDsOfNames

    Synopsis:    The IDispatch:GetIDsOfNames call for automation servers.

Declaration:     function  GetIDsOfNames(const  IID:  TGuid;Names:  Pointer;
                                                     NameCount:  Integer;LocaleID:  Integer;
                                                     DispIDs:  Pointer)  :  HRESULT

    Visibility:   default

Description:     GetIDsOfNames must return in DispIDs the dispatch Ids for the NameCount names of the
                methods listed in Names.  The LocaleID indicates the locale of the caller.

       Errors:   On error, a nonzero (different from S_OK) return value must be returned.

    See also:    IVCLComObject.Invoke (282  )



                4.33.6         IVCLComObject.Invoke

    Synopsis:    The IDispatch:Invoke call for automation servers.

Declaration:     function  Invoke(DispID:  Integer;const  IID:  TGuid;LocaleID:  Integer;
                                         Flags:  Word;var  Params;VarResult:  Pointer;
                                         ExcepInfo:  Pointer;ArgErr:  Pointer)  :  HRESULT

    Visibility:   default



                                                                                 282

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     Invoke must invoke the method designated by DispID. IID can be ignored.  LocaleID is used
                by the caller to indicate the locale it is using.  The Flags argument describes the context in
                which Invoke is called:  a method, or property getter/setter.  The Params argument contains
                the parameters to the call.  The result should be in VarResult.  On error, ExcepInfo and
                ArgError should be filled.

                The function should return 0 (S_OK) if all went well.

    See also:    IVCLComObject.GetIDsOfNames (282  )



                4.33.7         IVCLComObject.SafeCallException

    Synopsis:    This method can be invoked if an exception occurs during Invoke

Declaration:     function  SafeCallException(ExceptObject:  TObject;
                                                           ExceptAddr:  CodePointer)  :  HRESULT

    Visibility:   default

Description:     SafeCallException  is  called  to  handle  an  exception  during  invocation  of  the  Invoke
                method.  The TObject implementation of this method returns E_UNEXPECTED.

    See also:    IVCLComObject.Invoke (282  )



                4.33.8         IVCLComObject.FreeOnRelease

    Synopsis:    Is called by TComponent.FreeOnRelease

Declaration:     procedure  FreeOnRelease

    Visibility:   default

Description:     FreeOnRelease is called by TComponent.FreeOnRelease (337  ) for the IVCLComObject in-
                terface implemented by TComponent.

    See also:    TComponent.FreeOnRelease (337  )



                4.34          TAbstractOb jectReader



                4.34.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 (303  ) 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.


    See also:    TBinaryObjectReader (303  )



                                                                                 283

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.34.2         Method  overview

                __Page______Method_____________________________Description_________________________________________________________*
 *___________
                  285       BeginComponent                     Marks the reading of a new component.
                  285       BeginProperty                      Marks the reading of a property value.
                  285       BeginRootComponent                 Starts the reading of the root component.
                  284       NextValue                          Returns the type of the next value in the stream.
                  285       Read                               Read raw data from stream
                  286       ReadBinary                         Read binary data from the stream.
                  287       ReadCurrency                       Read a currency value from the stream.
                  287       ReadDate                           Read a date value from the stream.
                  286       ReadFloat                          Read a float value from the stream.
                  287       ReadIdent                          Read an identifier from the stream.
                  288       ReadInt16                          Read a 16-bit integer from the stream.
                  288       ReadInt32                          Read a 32-bit integer from the stream.
                  289       ReadInt64                          Read a 64-bit integer from the stream.
                  288       ReadInt8                           Read an 8-bit integer from the stream.
                  289       ReadSet                            Reads a set from the stream.
                  289       ReadSignature
                  286       ReadSingle                         Read a single (real-type) value from the stream.
                  290       ReadStr                            Read a shortstring from the stream
                  290       ReadString                         Read a string of type StringType from the stream.
                  290       ReadUnicodeString                  Read a unicode string value
                  284       ReadValue                          Reads the type of the next value.
                  290       ReadWideString                     Read a widestring value from the stream.
                  291       SkipComponent                      Skip till the end of the component.
                __291_______SkipValue__________________________Skip_the_current_value._____________________________________________*
 *___________



                4.34.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
                the actual value, 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 (284  )



                4.34.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 (284  )



                                                                                 284

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.34.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  immediately  followed  by  a  call  to
                BeginComponent (285  ).

    See also:    TAbstractObjectReader.BeginComponent (285  )



                4.34.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.

                AChildPos is used to change the ordering in which components appear below their parent
                component when streaming descendent forms.

    See also:    TAbstractObjectReader.BeginRootComponent (285  ), TAbstractObjectReader.BeginProperty
                (285  )



                4.34.7         TAbstractObjectReader.BeginProperty

    Synopsis:    Marks the reading of a property value.

Declaration:     function  BeginProperty  :  string;    Virtual;    Abstract

    Visibility:   public

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 (285  )



                4.34.8         TAbstractObjectReader.Read

    Synopsis:    Read raw data from stream

Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Virtual;    Abstract

    Visibility:   public



                                                                                 285

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (306  ), TReader.Read (399  )



                4.34.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
                (284  ) returned a valuetype of vaBinary).  The data should be stored in the DestData memory
                stream by descendent classes.

    See also:    TAbstractObjectReader.ReadFloat  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt8 (288  ), TAbstractObjectReader.ReadInt16 (288  ), TAbstractObjec-
                tReader.ReadInt32 (288  ), TAbstractObjectReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet
                (289  ), TabstractObjectReader.ReadStr (290  ), TabstractObjectReader.ReadString (290  )



                4.34.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 (284  ) returned a valuetype of  vaExtended).  The return value should
                be the value of the float.

    See also:    TAbstractObjectReader.ReadFloat  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt8 (288  ), TAbstractObjectReader.ReadInt16 (288  ), TAbstractObjec-
                tReader.ReadInt32 (288  ), TAbstractObjectReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet
                (289  ), TabstractObjectReader.ReadStr (290  ), TabstractObjectReader.ReadString (290  )



                4.34.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 (284  ) returned a valuetype of vaSingle).  The return value
                should be the value of the float.

    See also:    TAbstractObjectReader.ReadFloat  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt8 (288  ), TAbstractObjectReader.ReadInt16 (288  ), TAbstractObjec-
                tReader.ReadInt32 (288  ), TAbstractObjectReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet
                (289  ), TabstractObjectReader.ReadStr (290  ), TabstractObjectReader.ReadString (290  )



                                                                                 286

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.34.12          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 (284  ) 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 (286  ), TAbstractObjectReader.ReadSingle (286  ), TAb-
                stractObjectReader.ReadIdent (287  ), TAbstractObjectReader.ReadInt8 (288  ), TAbstractO-
                bjectReader.ReadInt16  (288  ),  TAbstractObjectReader.ReadInt32  (288  ),  TAbstractObjec-
                tReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet (289  ), TabstractObjectReader.ReadStr
                (290  ), TabstractObjectReader.ReadString (290  )



                4.34.13          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 (295  )



                4.34.14          TAbstractObjectReader.ReadIdent

    Synopsis:    Read an identifier from the stream.

Declaration:     function  ReadIdent(ValueType:  TValueType)  :  string;    Virtual;    Abstract

    Visibility:   public

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 (284  ) 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.  The following table indicates which identifiers must actually be read:



                                                                       Table 4.20:

                                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.



                                                                                 287

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    See also:    TAbstractObjectReader.ReadFloat  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle  (286  ),  TAbstractObjectReader.ReadInt8  (288  ),  TAbstrac-
                tObjectReader.ReadInt16 (288  ), TAbstractObjectReader.ReadInt32 (288  ), TAbstractObjec-
                tReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet (289  ), TabstractObjectReader.ReadStr
                (290  ), TabstractObjectReader.ReadString (290  )



                4.34.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 (284  ) 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  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt16 (288  ), TAbstractObjectReader.ReadInt32 (288  ), TAbstractObjec-
                tReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet (289  ), TabstractObjectReader.ReadStr
                (290  ), TabstractObjectReader.ReadString (290  )



                4.34.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 (284  ) 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.

    See also:    TAbstractObjectReader.ReadFloat  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt8 (288  ), TAbstractObjectReader.ReadInt32 (288  ), TAbstractObjec-
                tReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet (289  ), TabstractObjectReader.ReadStr
                (290  ), TabstractObjectReader.ReadString (290  )



                4.34.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 (284  ) 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.



                                                                                 288

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    See also:    TAbstractObjectReader.ReadFloat  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt8 (288  ), TAbstractObjectReader.ReadInt16 (288  ), TAbstractObjec-
                tReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet (289  ), TabstractObjectReader.ReadStr
                (290  ), TabstractObjectReader.ReadString (290  )



                4.34.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 (284  ) 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  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt8 (288  ), TAbstractObjectReader.ReadInt16 (288  ), TAbstractObjec-
                tReader.ReadInt32 (288  ), TabstractObjectReader.ReadSet (289  ), TabstractObjectReader.ReadStr
                (290  ), TabstractObjectReader.ReadString (290  )



                4.34.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 (284  ) 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).

    See also:    TAbstractObjectReader.ReadFloat  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt8 (288  ), TAbstractObjectReader.ReadInt16 (288  ), TAbstractObjec-
                tReader.ReadInt32 (288  ), TAbstractObjectReader.ReadInt64 (289  ), TabstractObjectReader.ReadStr
                (290  ), TabstractObjectReader.ReadString (290  )



                4.34.20          TAbstractObjectReader.ReadSignature

Declaration:     procedure  ReadSignature;    Virtual;    Abstract

    Visibility:   public



                                                                                 289

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.34.21          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 string from the stream (i.e.
                after  ReadValue  (284  )  returned  a  valuetype  of  vaLString,vaWstring  or  vaString).   The
                return value is the string.

    See also:    TAbstractObjectReader.ReadFloat  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt8 (288  ), TAbstractObjectReader.ReadInt16 (288  ), TAbstractObjec-
                tReader.ReadInt32 (288  ), TAbstractObjectReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet
                (289  ), TabstractObjectReader.ReadString (290  )



                4.34.22          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  (284  )  returned  a  valuetype  of  vaLString,vaWstring  or  vaString).   The
                return value is the string.

    See also:    TAbstractObjectReader.ReadFloat  (286  ),  TAbstractObjectReader.ReadDate  (287  ),  TAb-
                stractObjectReader.ReadSingle (286  ), TAbstractObjectReader.ReadIdent (287  ), TAbstrac-
                tObjectReader.ReadInt8 (288  ), TAbstractObjectReader.ReadInt16 (288  ), TAbstractObjec-
                tReader.ReadInt32 (288  ), TAbstractObjectReader.ReadInt64 (289  ), TabstractObjectReader.ReadSet
                (289  ), TabstractObjectReader.ReadStr (290  )



                4.34.23          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 (296  )



                4.34.24          TAbstractObjectReader.ReadUnicodeString

    Synopsis:    Read a unicode string value

Declaration:     function  ReadUnicodeString  :  UnicodeString;    Virtual;    Abstract

    Visibility:   public



                                                                                 290

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     ReadUnicodeString should read a UnicodeString value from the stream.  (indicated by the
                vaUString value type).

                Descendent classes should override this method to actually read a UnicodeString value.

    See also:    TBinaryObjectWriter.WriteUnicodeString (314  ), TAbstractObjectReader.ReadWideString
                (290  )



                4.34.25          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 (285  ), TAbstractObjectReader.SkipValue (291  )



                4.34.26          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 (291  )



                4.35          TAbstractOb jectWriter



                4.35.1         Description

                Abstract driver class for writing component data.



                                                                                 291

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.35.2         Method  overview

                __Page______Method_________________________Description_____________________________________________________________*
 *___________
                  292       BeginCollection                Start writing a collection.
                  292       BeginComponent                 Start writing a component
                  293       BeginList                      Start writing a list.
                  293       BeginProperty                  Start writing a property
                  293       EndList                        Mark the end of a list.
                  293       EndProperty                    Marks the end of writing of a property.
                  293       Write                          Write raw data to stream
                  294       WriteBinary                    Writes binary data to the stream.
                  294       WriteBoolean                   Writes a boolean value to the stream.
                  295       WriteCurrency                  Write a currency value to the stream
                  294       WriteDate                      Writes a date type to the stream.
                  294       WriteFloat                     Writes a float value to the stream.
                  295       WriteIdent                     Writes an identifier to the stream.
                  295       WriteInteger                   Writes an integer value to the stream
                  296       WriteMethodName                Writes a methodname to the stream.
                  296       WriteSet                       Writes a set value to the stream.
                  292       WriteSignature
                  294       WriteSingle                    Writes a single-type real value to the stream.
                  296       WriteString                    Writes a string value to the stream.
                  295       WriteUInt64                    Write an unsigned 64-bit integer
                  296       WriteUnicodeString             Write a unicode string to the stream.
                  295       WriteVariant                   Write a variant to the stream
                __296_______WriteWideString________________Write_a_widestring_value_to_the_stream__________________________________*
 *___________



                4.35.3         TAbstractObjectWriter.BeginCollection

    Synopsis:    Start writing a collection.

Declaration:     procedure  BeginCollection;    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a collection.



                4.35.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



                4.35.5         TAbstractObjectWriter.WriteSignature

Declaration:     procedure  WriteSignature;    Virtual;    Abstract

    Visibility:   public



                                                                                 292

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.35.6         TAbstractObjectWriter.BeginList

    Synopsis:    Start writing a list.

Declaration:     procedure  BeginList;    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a list.



                4.35.7         TAbstractObjectWriter.EndList

    Synopsis:    Mark the end of a list.

Declaration:     procedure  EndList;    Virtual;    Abstract

    Visibility:   public

Description:     Mark the end of a list.



                4.35.8         TAbstractObjectWriter.BeginProperty

    Synopsis:    Start writing a property

Declaration:     procedure  BeginProperty(const  PropName:  string);    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a property



                4.35.9         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.



                4.35.10          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 (312  ), TWriter.Write (464  )



                                                                                 293

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.35.11          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.



                4.35.12          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.



                4.35.13          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.



                4.35.14          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.



                4.35.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.



                                                                                 294

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.35.16          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 (287  )



                4.35.17          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.



                4.35.18          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



                4.35.19          TAbstractObjectWriter.WriteUInt64

    Synopsis:    Write an unsigned 64-bit integer

Declaration:     procedure  WriteUInt64(Value:  QWord);    Virtual;    Abstract

    Visibility:   public

Description:     WriteUInt64  must  be  overridden  by  descendent  classes  to  write  a  64-bit  unsigned  Value
                (valuetype vaQWord) to the stream.

       Errors:   None.

    See also:    TBinaryObjectWriter.WriteUInt64 (313  )



                4.35.20          TAbstractObjectWriter.WriteVariant

    Synopsis:    Write a variant to the stream

Declaration:     procedure  WriteVariant(const  Value:  Variant);    Virtual;    Abstract

    Visibility:   public

Description:     WriteVariant must be overridden by descendent classes to write a simple variant type to
                the stream.  WriteVariant does not write arrays types or complex types.

    See also:    TBinaryObjectWriter.WriteVariant (315  )



                                                                                 295

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.35.21          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.



                4.35.22          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.



                4.35.23          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.



                4.35.24          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 (290  )



                4.35.25          TAbstractObjectWriter.WriteUnicodeString

    Synopsis:    Write a unicode string to the stream.

Declaration:     procedure  WriteUnicodeString(const  Value:  UnicodeString);    Virtual
                                                              ;    Abstract

    Visibility:   public

Description:     WriteUnicodeString  must  be  overridden  by  descendent  classes  to  write  a  unicodestring
                (valuetype vaUString) value to the stream.

    See also:    TBinaryObjectWriter.WriteUnicodeString (314  )



                                                                                 296

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.36          TBasicAction



                4.36.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.


    See also:    TBasicActionLink (301  ), TComponent (333  )



                4.36.2         Method  overview

                __Page______Method_________________________Description_____________________________________________________________*
 *___________
                  297       Create                         Creates a new instance of a TBasicAction (297  ) class.
                  297       Destroy                        Destroys the action.
                  299       Execute                        Triggers the OnExecute (300  ) event
                  298       ExecuteTarget                  Executes the action on the Target object
                  298       HandlesTarget                  Determines whether Target can be handled by this action
                  299       RegisterChanges                Registers a new client with the action.
                  299       UnRegisterChanges              Unregisters a client from the list of clients
                  299       Update                         Triggers the OnUpdate (300  ) event
                __298_______UpdateTarget___________________Notify_client_controls_when_the_action_updates_itself.__________________*
 *___________



                4.36.3         Property  overview

                __Page______Properties___________________Access_______Description__________________________________________________*
 *___________
                  300       ActionComponent              rw           Returns the component that initiated the action.
                  300       OnExecute                    rw           Event triggered when the action executes.
                __300_______OnUpdate_____________________rw___________Event_trigged_when_the_application_is_idle.__________________*
 *___________



                4.36.4         TBasicAction.Create

    Synopsis:    Creates a new instance of a TBasicAction (297  ) 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).

                Under normal circumstances it should not be necessary to create a TBasicAction descendent
                manually, actions are created in an IDE.

    See also:    Destroy (297  ), AssignClient (297  )



                4.36.5         TBasicAction.Destroy

    Synopsis:    Destroys the action.

Declaration:     destructor  Destroy;    Override

    Visibility:   public



                                                                                 297

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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.



                4.36.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:    UpdateTarget (298  ), ExecuteTarget (298  )



                4.36.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:    HandlesTarget (298  ), ExecuteTarget (298  )



                4.36.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:    HandlesTarget (298  ), UpdateTarget (298  ), Execute (299  )



                                                                                 298

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.36.9         TBasicAction.Execute

    Synopsis:    Triggers the OnExecute (300  ) 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.



                4.36.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:    UnregisterChanges (299  )



                4.36.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:    UnregisterChanges (299  ), Destroy (297  )



                4.36.12          TBasicAction.Update

    Synopsis:    Triggers the OnUpdate (300  ) 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 (300  ) event, and perform any checks
                in that handler.

    See also:    OnUpdate (300  ), Execute (299  ), UpdateTarget (298  )



                                                                                 299

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.36.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:    Execute (299  ), OnExecute (300  )



                4.36.14          TBasicAction.OnExecute

    Synopsis:    Event triggered when the action executes.

Declaration:     Property  OnExecute  :  TNotifyEvent

    Visibility:   public

      Access:    Read,Write

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 (299  ) 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:    Execute (299  ), OnUpdate (300  )



                4.36.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:    Update (299  ), OnExecute (300  )



                                                                                 300

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.37          TBasicActionLink



                4.37.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.


    See also:    TBasicAction (297  )



                4.37.2         Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  301       Create         Creates a new instance of the TBasicActionLink class
                  301       Destroy        Destroys the TBasicActionLink instance.
                  302       Execute        Calls the action's Execute method.
                __302_______Update_________Calls_the_action's_Update_method________________________________________________________*
 *___________



                4.37.3         Property  overview

                __Page______Properties_________Access_______Description____________________________________________________________*
 *___________
                  302       Action             rw           The action to which the link was assigned.
                __303_______OnChange___________rw___________Event_handler_triggered_when_the_action's_properties_change____________*
 *___________



                4.37.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:    Destroy (301  )



                4.37.5         TBasicActionLink.Destroy

    Synopsis:    Destroys the TBasicActionLink instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public



                                                                                 301

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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:    Create (301  )



                4.37.6         TBasicActionLink.Execute

    Synopsis:    Calls the action's Execute method.

Declaration:     function  Execute(AComponent:  TComponent)  :  Boolean;    Virtual

    Visibility:   public

Description:     Execute sets the ActionComponent (300  ) property of the associated Action (302  ) to AComponent
                and  then  calls  the  Action's  execute  (299  )  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:    Action (302  ), TBasicAction.ActionComponent (300  ), TBasicAction.Execute (299  ), TBasi-
                cAction.onExecute (300  )



                4.37.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 (299  ) methoda.

                Component programmers can override the Update method to provide additional processing
                when the Update method occurs.



                4.37.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 (297  ) 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 (297  )



                                                                                 302

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.37.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:    Change (301  ), TBasicAction.Change (297  )



                4.38          TBinaryOb jectReader



                4.38.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  (283  ).
                No new functionality is added by this class, it is a driver class for the streaming system.

                It  should  never  be  necessary  to  create  an  instance  of  this  class  directly.    Instead,  the
                TStream.WriteComponent (415  ) call should be used.


    See also:    TAbstractObjectReader (283  ), TBinaryObjectWriter (310  )



                                                                                 303

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.38.2         Method  overview

                __Page______Method_____________________________Description_________________________________________________________*
 *___________
                  305       BeginComponent                     Start reading a component.
                  306       BeginProperty                      Start reading a property.
                  305       BeginRootComponent                 Start reading the root component.
                  304       Create                             Creates a new binary data reader instance.
                  304       Destroy                            Destroys the binary data reader.
                  305       NextValue                          Return the type of the next value.
                  306       Read                               Read raw data from stream
                  306       ReadBinary                         Start reading a binary value.
                  307       ReadCurrency                       Read a currency value from the stream.
                  307       ReadDate                           Read a date.
                  306       ReadFloat                          Read a float value
                  307       ReadIdent                          Read an identifier
                  307       ReadInt16                          Read a 16-bits integer.
                  308       ReadInt32                          Read a 32-bits integer.
                  308       ReadInt64                          Read a 64-bits integer.
                  307       ReadInt8                           Read an 8-bits integer.
                  308       ReadSet                            Read a set
                  308       ReadSignature
                  306       ReadSingle                         Read a single-size float value
                  308       ReadStr                            Read a short string
                  309       ReadString                         Read a string
                  309       ReadUnicodeString                  Read a unicode string value
                  305       ReadValue                          Read the next value in the stream
                  309       ReadWideString                     Read a widestring value from the stream.
                  309       SkipComponent                      Skip a component's data
                __310_______SkipValue__________________________Skip_a_value's_data_________________________________________________*
 *___________



                4.38.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 (283  )



                4.38.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 (304  )



                                                                                 304

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.38.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 (283  )



                4.38.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 (283  )



                4.38.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 (283  )



                4.38.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 (283  )



                                                                                 305

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.38.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 (283  )



                4.38.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 (285  ), TReader.Read (399  )



                4.38.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 (283  )



                4.38.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 (283  )



                4.38.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 (283  )



                                                                                 306

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.38.14          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 (283  )



                4.38.15          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 (283  ).

    See also:    TAbstractObjectReader.ReadCurrency (287  ), TBinaryObjectWriter.WriteCurrency (313  )



                4.38.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 (283  )



                4.38.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 (283  )



                4.38.18          TBinaryObjectReader.ReadInt16

    Synopsis:    Read a 16-bits integer.

Declaration:     function  ReadInt16  :  SmallInt;    Override

    Visibility:   public



                                                                                 307

                __________________________________________________________CHAPTER_4.___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 (283  )



                4.38.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 (283  )



                4.38.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 (283  )



                4.38.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 (283  )



                4.38.22          TBinaryObjectReader.ReadSignature

Declaration:     procedure  ReadSignature;    Override

    Visibility:   public



                4.38.23          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 (283  )



                                                                                 308

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.38.24          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 (283  )



                4.38.25          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 (283  ).

    See also:    TAbstractObjectReader.ReadWideString (290  ), TBinaryObjectWriter.WriteWideString (314  )



                4.38.26          TBinaryObjectReader.ReadUnicodeString

    Synopsis:    Read a unicode string value

Declaration:     function  ReadUnicodeString  :  UnicodeString;    Override

    Visibility:   public

Description:     ReadUnicodeString is overridden by TBinaryObjectReaderto read a UnicodeString value
                from the binary stream.

    See also:    TAbstractObjectReader.ReadUnicodeString (290  )



                4.38.27          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 (283  ).



                                                                                 309

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.38.28          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 (283  )



                4.39          TBinaryOb jectWriter



                4.39.1         Description

                Driver class which stores component data in binary form.



                4.39.2         Method  overview

                __Page______Method_________________________Description_____________________________________________________________*
 *___________
                  311       BeginCollection                Start writing a collection.
                  311       BeginComponent                 Start writing a component
                  311       BeginList                      Start writing a list.
                  312       BeginProperty                  Start writing a property
                  310       Create                         Creates a new instance of a binary object writer.
                  311       Destroy                        Destroys an instance of the binary object writer.
                  311       EndList                        Mark the end of a list.
                  312       EndProperty                    Marks the end of writing of a property.
                  312       Write                          Write raw data to stream
                  312       WriteBinary                    Writes binary data to the stream.
                  312       WriteBoolean                   Writes a boolean value to the stream.
                  313       WriteCurrency                  Write a currency-valued type to a stream
                  313       WriteDate                      Writes a date type to the stream.
                  312       WriteFloat                     Writes a float value to the stream.
                  313       WriteIdent                     Writes an identifier to the stream.
                  313       WriteInteger                   Writes an integer value to the stream.
                  314       WriteMethodName                Writes a methodname to the stream.
                  314       WriteSet                       Writes a set value to the stream.
                  311       WriteSignature
                  313       WriteSingle                    Writes a single-type real value to the stream.
                  314       WriteStr                       Write a string to the binary stream
                  314       WriteString                    Writes a string value to the stream.
                  313       WriteUInt64                    Write an unsigned 64-bit integer
                  314       WriteUnicodeString             Write a unicode string to the stream.
                  315       WriteVariant                   Write a variant to the stream
                __314_______WriteWideString________________Write_a_widestring-valued_type_to_a_stream______________________________*
 *___________



                4.39.3         TBinaryObjectWriter.Create

    Synopsis:    Creates a new instance of a binary object writer.

Declaration:     constructor  Create(Stream:  TStream;BufSize:  Integer)



                                                                                 310

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    Visibility:  public

Description:     Creates a new instance of a binary object writer.



                4.39.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.



                4.39.5         TBinaryObjectWriter.WriteSignature

Declaration:     procedure  WriteSignature;    Override

    Visibility:   public



                4.39.6         TBinaryObjectWriter.BeginCollection

    Synopsis:    Start writing a collection.

Declaration:     procedure  BeginCollection;    Override

    Visibility:   public



                4.39.7         TBinaryObjectWriter.BeginComponent

    Synopsis:    Start writing a component

Declaration:     procedure  BeginComponent(Component:  TComponent;Flags:  TFilerFlags;
                                                        ChildPos:  Integer);    Override

    Visibility:   public



                4.39.8         TBinaryObjectWriter.BeginList

    Synopsis:    Start writing a list.

Declaration:     procedure  BeginList;    Override

    Visibility:   public



                4.39.9         TBinaryObjectWriter.EndList

    Synopsis:    Mark the end of a list.

Declaration:     procedure  EndList;    Override

    Visibility:   public



                                                                                 311

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.39.10          TBinaryObjectWriter.BeginProperty

    Synopsis:    Start writing a property

Declaration:     procedure  BeginProperty(const  PropName:  string);    Override

    Visibility:   public



                4.39.11          TBinaryObjectWriter.EndProperty

    Synopsis:    Marks the end of writing of a property.

Declaration:     procedure  EndProperty;    Override

    Visibility:   public



                4.39.12          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 (293  ), TWriter.Write (464  )



                4.39.13          TBinaryObjectWriter.WriteBinary

    Synopsis:    Writes binary data to the stream.

Declaration:     procedure  WriteBinary(const  Buffer;Count:  LongInt);    Override

    Visibility:   public



                4.39.14          TBinaryObjectWriter.WriteBoolean

    Synopsis:    Writes a boolean value to the stream.

Declaration:     procedure  WriteBoolean(Value:  Boolean);    Override

    Visibility:   public



                4.39.15          TBinaryObjectWriter.WriteFloat

    Synopsis:    Writes a float value to the stream.

Declaration:     procedure  WriteFloat(const  Value:  Extended);    Override

    Visibility:   public



                                                                                 312

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.39.16          TBinaryObjectWriter.WriteSingle

    Synopsis:    Writes a single-type real value to the stream.

Declaration:     procedure  WriteSingle(const  Value:  Single);    Override

    Visibility:   public



                4.39.17          TBinaryObjectWriter.WriteDate

    Synopsis:    Writes a date type to the stream.

Declaration:     procedure  WriteDate(const  Value:  TDateTime);    Override

    Visibility:   public



                4.39.18          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 (291  ).

    See also:    TAbstractObjectWriter.WriteCurrency (295  )



                4.39.19          TBinaryObjectWriter.WriteIdent

    Synopsis:    Writes an identifier to the stream.

Declaration:     procedure  WriteIdent(const  Ident:  string);    Override

    Visibility:   public



                4.39.20          TBinaryObjectWriter.WriteInteger

    Synopsis:    Writes an integer value to the stream.

Declaration:     procedure  WriteInteger(Value:  Int64);    Override

    Visibility:   public



                4.39.21          TBinaryObjectWriter.WriteUInt64

    Synopsis:    Write an unsigned 64-bit integer

Declaration:     procedure  WriteUInt64(Value:  QWord);    Override

    Visibility:   public

Description:     WriteUInt64  is  overridden  by  TBinaryObjectWriter  to  write  an  unsigned  64-bit  integer
                (QWord)  to  the  stream.  It  tries  to  use  the  smallest  possible  storage  for  the  value  that  is
                passed.  (largest valuetype will be vaQWord).

    See also:    TAbstractObjectWriter.WriteUInt64 (295  )



                                                                                 313

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.39.22          TBinaryObjectWriter.WriteMethodName

    Synopsis:    Writes a methodname to the stream.

Declaration:     procedure  WriteMethodName(const  Name:  string);    Override

    Visibility:   public



                4.39.23          TBinaryObjectWriter.WriteSet

    Synopsis:    Writes a set value to the stream.

Declaration:     procedure  WriteSet(Value:  LongInt;SetType:  Pointer);    Override

    Visibility:   public



                4.39.24          TBinaryObjectWriter.WriteStr

    Synopsis:    Write a string to the binary stream

Declaration:     procedure  WriteStr(const  Value:  string)

    Visibility:   public

Description:     WriteStr  writes  a  string  value  to  the  binary  stream.   It  is  exposed  so  it  can  be  used  in
                DefineProperties.



                4.39.25          TBinaryObjectWriter.WriteString

    Synopsis:    Writes a string value to the stream.

Declaration:     procedure  WriteString(const  Value:  string);    Override

    Visibility:   public



                4.39.26          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 (291  ).

    See also:    TAbstractObjectWriter.WriteWidestring (296  )



                4.39.27          TBinaryObjectWriter.WriteUnicodeString

    Synopsis:    Write a unicode string to the stream.

Declaration:     procedure  WriteUnicodeString(const  Value:  UnicodeString);    Override

    Visibility:   public



                                                                                 314

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     WriteUnicodeString is overridden TBinaryObjectWriter to write a unicodestring (value-
                type  vaUString)  value  to  the  stream.   It  simply  writes  the  character  length  and  then  all
                widecharacters.

    See also:    TAbstractObjectWriter.WriteUnicodeString (296  )



                4.39.28          TBinaryObjectWriter.WriteVariant

    Synopsis:    Write a variant to the stream

Declaration:     procedure  WriteVariant(const  VarValue:  Variant);    Override

    Visibility:   public

Description:     WriteVariant is overridden by TBinaryObjectWriter to write a simple variant type to the
                stream.   WriteVariant  does  not  write  arrays  types  or  complex  types.   Only  null,  integer
                (ordinal) float and string types are written.

       Errors:   If a non-supported type is written, then an EWriteError exception is.



                4.40          TBits



                4.40.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 store them in a conventional array.

                TBits introduces methods to store and retrieve bit values, apply masks, and search for bits.



                4.40.2         Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  317       AndBits               Performs an and operation on the bits.
                  317       Clear                 Clears a particular bit.
                  317       Clearall              Clears all bits in the array.
                  316       Create                Creates a new bits collection.
                  316       Destroy               Destroys a bit collection
                  319       Equals                Determines whether the bits of 2 arrays are equal.
                  320       FindFirstBit          Find first bit with a particular value
                  320       FindNextBit           Searches the next bit with a particular value.
                  320       FindPrevBit           Searches the previous bit with a particular value.
                  319       Get                   Retrieve the value of a particular bit
                  316       GetFSize              Returns the number of records used to store the bits.
                  319       Grow                  Expands the bits array to the requested size.
                  318       NotBits               Performs a not operation on the bits.
                  321       OpenBit               Returns the position of the first bit that is set to False.
                  318       OrBits                Performs an or operation on the bits.
                  319       SetIndex              Sets  the  start  position  for  FindNextBit  (320  )  and  FindPrevBit
                                                  (320  )
                  317       SetOn                 Turn a particular bit on.
                __318_______XorBits_______________Performs_a_xor_operation_on_the_bits.____________________________________________*
 *___________



                                                                                 315

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.40.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  321       Bits              rw           Access to all bits in the array.
                __321_______Size______________rw___________Current_size_of_the_array_of_bits.______________________________________*
 *___________



                4.40.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:    Destroy (316  )



                4.40.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:    Create (316  )



                4.40.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:    Size (321  )



                                                                                 316

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.40.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 (319  ).

       Errors:   If  bit  is  larger  than  the  maximum  allowed  bits  array  size  or  is  negative,  an  EBitsError
                (267  ) exception is raised.

    See also:    Bits (321  ), Clear (317  )



                4.40.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 (319  ).

       Errors:   If  bit  is  larger  than  the  maximum  allowed  bits  array  size  or  is  negative,  an  EBitsError
                (267  ) exception is raised.

    See also:    Bits (321  ), seton (317  )



                4.40.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:    Bits (321  ), clear (317  )



                4.40.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:    ClearAll (317  ), OrBits (318  ), XOrBits (318  ), NotBits (318  )



                                                                                 317

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.40.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:    ClearAll (317  ), andBits (317  ), XOrBits (318  ), NotBits (318  )



                4.40.12          TBits.XorBits

    Synopsis:    Performs a xor operation on the bits.

Declaration:     procedure  XorBits(BitSet:  TBits)

    Visibility:   public

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:    ClearAll (317  ), andBits (317  ), OrBits (318  ), NotBits (318  )



                4.40.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:    ClearAll (317  ), andBits (317  ), OrBits (318  ), XOrBits (318  )



                                                                                 318

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.40.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 (267  ) exception is raised.

    See also:    Bits (321  ), FindFirstBit (320  ), seton (317  )



                4.40.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 (267  )is raised.

    See also:    Size (321  )



                4.40.16          TBits.Equals

    Synopsis:    Determines whether the bits of 2 arrays are equal.

Declaration:     function  Equals(Obj:  TObject)  :  Boolean;    Override;    Overload
                function  Equals(BitSet:  TBits)  :  Boolean;    Overload

    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:    ClearAll (317  ), andBits (317  ), OrBits (318  ), XOrBits (318  )



                4.40.17          TBits.SetIndex

    Synopsis:    Sets the start position for FindNextBit (320  ) and FindPrevBit (320  )

Declaration:     procedure  SetIndex(Index:  LongInt)

    Visibility:   public

Description:     SetIndex  sets  the  search  start  position  forFindNextBit  (320  )  and  FindPrevBit  (320  )  to
                Index.  This means that these calls will start searching from position Index.

                This  mechanism  provides  an  alternative  to  FindFirstBit  (320  )  which  can  also  be  used  to
                position for the FindNextBit and FindPrevBit calls.



                                                                                 319

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



       Errors:   None.

    See also:    FindNextBit (320  ), FindPrevBit (320  ), FindFirstBit (320  ), OpenBit (321  )



                4.40.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 (320  ) and FindPrevBit (320  ) 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 (319  ) instead.

       Errors:   None.

    See also:    FindNextBit (320  ), FindPrevBit (320  ), OpenBit (321  ), SetIndex (319  )



                4.40.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 (320  ).  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 (319  ).

                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:    FindFirstBit (320  ), FindPrevBit (320  ), OpenBit (321  ), SetIndex (319  )



                4.40.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 (320  ).  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 (319  ).

                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.



                                                                                 320

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



       Errors:   None.

    See also:    FindFirstBit (320  ), FindNextBit (320  ), OpenBit (321  ), SetIndex (319  )



                4.40.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:    FindNextBit (320  ), FindPrevBit (320  ), FindFirstBit (320  ), SetIndex (319  )



                4.40.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 (267  ) exception
                is raised.

    See also:    Size (321  )



                4.40.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 (267  ) exception is raised.

    See also:    Bits (321  )



                                                                                 321

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.41          TBytesStream



                4.41.1         Description

                TBytesStream is a stream that uses an array of byte (TBytes (235  )) to keep the stream data.
                it overrides the TMemoryStream (381  ) memory allocation routine to use the array of bytes.
                The array of bytes is exposed through the Bytes (235  ) property.


    See also:    TBytes (235  ), TMemoryStream (381  ), Bytes (235  )



                4.41.2         Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  322       Create         Create  a  new  instance  of  the  stream,  initializing  it  with  an  array  of
                ___________________________bytes___________________________________________________________________________________*
 *___________



                4.41.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __322_______Bytes_____________r____________The_stream_data_as_an_array_of_bytes.___________________________________*
 *___________



                4.41.4         TBytesStream.Create

    Synopsis:    Create a new instance of the stream, initializing it with an array of bytes

Declaration:     constructor  Create(const  ABytes:  TBytes);    Overload

    Visibility:   public

Description:     Create creates a new instance and initializes the memory with the data in ABytes.

    See also:    TBytes (235  ), TMemoryStream (381  ), Bytes (235  )



                4.41.5         TBytesStream.Bytes

    Synopsis:    The stream data as an array of bytes.

Declaration:     Property  Bytes  :  TBytes

    Visibility:   public

      Access:    Read

Description:     Bytes provides byte-sized access to the array of bytes that represent the stream data.  As a
                pointer value, it equals TCustomMemoryStream.Memory (346  ), meaning that Memory points
                to the first byte in the array.

    See also:    TBytes (235  ), TMemoryStream (381  ), TCustomMemoryStream.Memory (346  )



                4.42          TCollection



                4.42.1         Description

                TCollection  implements  functionality  to  manage  a  collection  of  named  objects.  Each  of
                these objects needs to be a descendent of the TCollectionItem (330  ) class.  Exactly which
                type of object is managed can be seen from the TCollection.ItemClass (328  ) property.



                                                                                 322

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                Normally, no TCollection is created directly.  Instead, a descendents of  TCollection and
                TCollectionItem (330  ) are created as a pair.


    See also:    TCollectionItem (330  )



                4.42.2         Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  324       Add                       Creates and adds a new item to the collection.
                  324       Assign                    Assigns one collection to another.
                  324       BeginUpdate               Start an update batch.
                  325       Clear                     Removes all items from the collection.
                  323       Create                    Creates a new collection.
                  325       Delete                    Delete an item from the collection.
                  323       Destroy                   Destroys the collection and frees all the objects it manages.
                  325       EndUpdate                 Ends an update batch.
                  327       Exchange                  Exchange 2 items in the collection
                  327       FindItemID                Searches for an Item in the collection, based on its TCollection-
                                                      Item.ID (331  ) property.
                  326       GetEnumerator             Create an IEnumerator instance
                  326       GetNamePath               Overrides  TPersistent.GetNamePath  (394  )  to  return  a  proper
                                                      pathname.
                  326       Insert                    Insert an item in the collection.
                  324       Owner                     Owner of the collection.
                __327_______Sort______________________Sort_the_items_in_the_collection_____________________________________________*
 *___________



                4.42.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  327       Count             r            Number of items in the collection.
                  328       ItemClass         r            Class pointer for each item in the collection.
                __328_______Items_____________rw___________Indexed_array_of_items_in_the_collection._______________________________*
 *___________



                4.42.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 (328  ), TCollection.Destroy (323  )



                4.42.5         TCollection.Destroy

    Synopsis:    Destroys the collection and frees all the objects it manages.

Declaration:     destructor  Destroy;    Override

    Visibility:   public



                                                                                 323

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (323  )



                4.42.6         TCollection.Owner

    Synopsis:    Owner of the collection.

Declaration:     function  Owner  :  TPersistent

    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.



                4.42.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  (328  )  and  adds  it  to  the  list.
                The newly created object is returned.

    See also:    TCollection.ItemClass (328  ), TCollection.Clear (325  )



                4.42.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 (392  ), TCollectionItem (330  )



                4.42.9         TCollection.BeginUpdate

    Synopsis:    Start an update batch.

Declaration:     procedure  BeginUpdate;    Virtual

    Visibility:   public



                                                                                 324

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (322  ) 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
                      finally
                         EndUpdate;
                      end;


                This insures that the number of calls to BeginUpdate always matches the number of calls to
                TCollection.EndUpdate (325  ), even in case of an exception.

    See also:    TCollection.EndUpdate (325  ), TCollection.Changed (322  ), TCollection.Update (322  )



                4.42.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 (324  ), TCollectionItem.Destroy (331  ), TCollection.Destroy (323  )



                4.42.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  (322  )  it  should  always  be  used  in  conjunction  with  TCollec-
                tion.BeginUpdate (324  ), preferably in the Finally section of a Try  ...    Finally block.

    See also:    TCollection.BeginUpdate (324  ), TCollection.Changed (322  ), TCollection.Update (322  )



                4.42.12          TCollection.Delete

    Synopsis:    Delete an item from the collection.

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public



                                                                                 325

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 EListError exception is raised.

    See also:    TCollection.Items (328  ), TCollection.Insert (326  ), TCollection.Clear (325  )



                4.42.13          TCollection.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TCollectionEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1472   ) interface for TCollection.
                It creates a TCollectionEnumerator (328  ) instance and returns it's IEnumerator (1472   ) in-
                terface.

    See also:    TCollectionEnumerator (328  ), IEnumerator (1472   ), IEnumerable (1472   )



                4.42.14          TCollection.GetNamePath

    Synopsis:    Overrides TPersistent.GetNamePath (394  ) to return a proper pathname.

Declaration:     function  GetNamePath  :  string;    Override

    Visibility:   public

Description:     GetNamePath  returns  the  name  path  for  this  collection.   If  the  following  conditions  are
                satisfied:


                     1.There is an owner object.

                     2.The owner object returns a non-empty name path.

                     3.The TCollection.Propname (322  ) property is not empty


                collection  has  an  owner  and  the  owning  object  has  a  name,  then  the  function  returns  the
                owner name,  followed by the propname.  If one of the conditions is not satisfied,  then the
                classname is returned.

    See also:    TCollection.GetOwner (322  ), TCollection.Propname (322  )



                4.42.15          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 (324  ) adds a new item at the end.

       Errors:   None.

    See also:    TCollection.Add (324  ), TCollection.Delete (325  ), TCollection.Items (328  )



                                                                                 326

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.42.16          TCollection.FindItemID

    Synopsis:    Searches for an Item in the collection, based on its TCollectionItem.ID (331  ) 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 (331  ) 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 (328  ), TCollectionItem.ID (331  )



                4.42.17          TCollection.Exchange

    Synopsis:    Exchange 2 items in the collection

Declaration:     procedure  Exchange(const  Index1:  Integer;const  index2:  Integer)

    Visibility:   public

Description:     Exchange exchanges the items at indexes Index1 and Index2 in the collection.

       Errors:   If one of the two indexes is invalid (less than zero or larger than the number of items) an
                EListError exception is raised.

    See also:    Items (328  ), TCollectionItem.Index (332  )



                4.42.18          TCollection.Sort

    Synopsis:    Sort the items in the collection

Declaration:     procedure  Sort(const  Compare:  TCollectionSortCompare)

    Visibility:   public

Description:     Sort sorts the items in the collection, and uses the Compare procedure to compare 2 items
                in the collection.  It is more efficient do use this method than to perform the sort manually,
                because the list items are manipulated directly.

                For more information on how the Compare function should behave, see the TCollectionSort-
                Compare (240  ) type.

    See also:    TCollectionSortCompare (240  )



                4.42.19          TCollection.Count

    Synopsis:    Number of items in the collection.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read



                                                                                 327

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     Count contains the number of items in the collection.

 Remark:         The  items  in  the  collection  are  identified  by  their  TCollectionItem.Index  (332  )  property,
                which is a zero-based index, meaning that it can take values between 0 and Count-1, borders
                included.

    See also:    TCollectionItem.Index (332  ), TCollection.Items (328  )



                4.42.20          TCollection.ItemClass

    Synopsis:    Class pointer for each item in the collection.

Declaration:     Property  ItemClass  :  TCollectionItemClass

    Visibility:   public

      Access:    Read

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 (330  ), TCollection.Items (328  )



                4.42.21          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 (328  ) property.

                Adding an element to the array can be done with the TCollection.Add (324  ) method.  The
                array can be cleared with the TCollection.Clear (325  ) method.  Removing an element of the
                array should be done by freeing that element.

    See also:    TCollection.Count  (327  ),  TCollection.ItemClass  (328  ),  TCollection.Clear  (325  ),  TCollec-
                tion.Add (324  )



                4.43          TCollectionEnumerator



                4.43.1         Description

                TCollectionEnumerator implements the #rtl.system.IEnumerator (1472   ) interface for the
                TCollection (322  ) class, so the TCollection class can be used in a for  ...    in loop.  It is
                returned by the TCollection.GetEnumerator (326  ) method of  TCollection.


    See also:    TCollection (322  ), TCollection.GetEnumerator (326  ), #rtl.system.IEnumerator (1472   )



                                                                                 328

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.43.2         Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                  329       Create              Initialize a new instance of  TCollectionEnumerator
                  329       GetCurrent          Return the current pointer in the list
                  329       MoveNext            Move  the  position  of  the  enumerator  to  the  next  position  in  the
                ________________________________collection.________________________________________________________________________*
 *___________



                4.43.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __330_______Current___________r____________Current_pointer_in_the_list_____________________________________________*
 *___________



                4.43.4         TCollectionEnumerator.Create

    Synopsis:    Initialize a new instance of  TCollectionEnumerator

Declaration:     constructor  Create(ACollection:  TCollection)

    Visibility:   public

Description:     Create initializes a new instance of  TCollectionEnumerator and keeps a reference to the
                collection ACollection that will be enumerated.

    See also:    TCollection (322  )



                4.43.5         TCollectionEnumerator.GetCurrent

    Synopsis:    Return the current pointer in the list

Declaration:     function  GetCurrent  :  TCollectionItem

    Visibility:   public

Description:     GetCurrent returns the current TCollectionItem (330  ) instance in the enumerator.

       Errors:   No checking is done on the validity of the current position.

    See also:    MoveNext (329  ), TCollectionItem (330  )



                4.43.6         TCollectionEnumerator.MoveNext

    Synopsis:    Move the position of the enumerator to the next position in the collection.

Declaration:     function  MoveNext  :  Boolean

    Visibility:   public

Description:     MoveNext  puts  the  pointer  on  the  next  item  in  the  collection,  and  returns  True  if  this
                succeeded, or False if the pointer is past the last element in the list.

       Errors:   Note that if  False is returned, calling GetCurrent will result in an exception.

    See also:    GetCurrent (329  )



                                                                                 329

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.43.7         TCollectionEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  TCollectionItem

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (329  ) as a property.

    See also:    GetCurrent (329  )



                4.44          TCollectionItem



                4.44.1         Description

                TCollectionItem and TCollection (322  ) 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 (332  ), TCollection.Index (322  ) and TCollectionItem.ID (331  ).

                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 (322  ) class.
                The managing collection will create and destroy it's items by itself, it should therefore never
                be necessary to create TCollectionItem descendents manually.


    See also:    TCollection (322  )



                4.44.2         Method  overview

                __Page______Method__________________Description____________________________________________________________________*
 *___________
                  330       Create                  Creates a new instance of this collection item.
                  331       Destroy                 Destroyes this collection item.
                __331_______GetNamePath_____________Returns_the_namepath_of_this_collection_item.__________________________________*
 *___________



                4.44.3         Property  overview

                __Page______Properties____________Access_______Description_________________________________________________________*
 *___________
                  331       Collection            rw           Pointer to the collection managing this item.
                  332       DisplayName           rw           Name of the item, displayed in the object inspector.
                  331       ID                    r            Initial index of this item.
                  332       Index                 rw           Index  of  the  item  in  its  managing  collection  TCollec-
                _______________________________________________tion.Items_(328__)_property.________________________________________*
 *___________



                4.44.4         TCollectionItem.Create

    Synopsis:    Creates a new instance of this collection item.

Declaration:     constructor  Create(ACollection:  TCollection);    Virtual

    Visibility:   public



                                                                                 330

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     Create instantiates a new item in a TCollection (322  ).  It is called by the TCollection.Add
                (324  ) function and should under normal circumstances never be called directly.  called

    See also:    TCollectionItem.Destroy (331  )



                4.44.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 (330  )



                4.44.6         TCollectionItem.GetNamePath

    Synopsis:    Returns the namepath of this collection item.

Declaration:     function  GetNamePath  :  string;    Override

    Visibility:   public

Description:     GetNamePath overrides the TPersistent.GetNamePath (394  ) method to return the name of
                the managing collection and appends its TCollectionItem.Index (332  ) property.

    See also:    TCollectionItem.Collection (331  ), TPersistent.GetNamePath (394  ), TCollectionItem.Index
                (332  )



                4.44.7         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 (322  )



                4.44.8         TCollectionItem.ID

    Synopsis:    Initial index of this item.

Declaration:     Property  ID  :  Integer

    Visibility:   public



                                                                                 331

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



      Access:    Read

Description:     ID  is  the  initial  value  of  TCollectionItem.Index  (332  );  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 (332  ) 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 (328  ), TCollectionItem.Index (332  )



                4.44.9         TCollectionItem.Index

    Synopsis:    Index of the item in its managing collection TCollection.Items (328  ) 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 (328  )
                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 (331  ) property does not form a continuous series, but can
                also be used to identify an item.

    See also:    TCollectionItem.ID (331  ), TCollection.Items (328  )



                4.44.10          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 (330  ) and TCollectionItem.GetDisplayName (330  ) to add storage
                functionality.

    See also:    TCollectionItem.Index (332  ), TCollectionItem.ID (331  ), TCollectionItem.GetDisplayName
                (330  ), TCollectionItem.SetDisplayName (330  )



                                                                                 332

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



4.45          TComponent



4.45.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.



4.45.2         Interfaces  overview

__Page______Interfaces_____________________________________Description________________________________________________________
  274       IInterfaceComponentReference                   Interface for checking component references
__1474______IUnknown_______________________________________Basic_interface_for_all_COM-based_interfaces_______________________



4.45.3         Method  overview

__Page______Method_______________________________Description__________________________________________________________________
  335       BeforeDestruction                    Overrides standard BeforeDestruction.
  335       Create                               Creates a new instance of the component.
  335       Destroy                              Destroys the instance of the component.
  335       DestroyComponents                    Destroy child components.
  336       Destroying                           Called when the component is being destroyed
  336       ExecuteAction                        Standard action execution method.
  336       FindComponent                        Finds and returns the named component in the owned
                                                 components.
  336       FreeNotification                     Ask  the  component  to  notify  called  when  it  is  being
                                                 destroyed.
  337       FreeOnRelease                        Part of the IVCLComObject interface.
  337       GetEnumerator                        Create an IEnumerator instance
  337       GetNamePath                          Returns the name path of this component.
  337       GetParentComponent                   Returns the parent component.
  338       HasParent                            Does the component have a parent ?
  338       InsertComponent                      Insert the given component in the list of owned compo-
                                                 nents.
  339       IsImplementorOf                      Checks if the current component is the implementor of
                                                 the interface
  334       Notification                         Called by components that are freed and which received
                                                 a FreeNotification.
  339       ReferenceInterface                   Interface implementation of Notification
  338       RemoveComponent                      Remove  the  given  component  from  the  list  of  owned
                                                 components.
  337       RemoveFreeNotification               Remove a component from the Free Notification list.
  338       SafeCallException                    Part of the IVCLComObject Interface.
  339       SetSubComponent                      Sets the csSubComponent style.
  339       UpdateAction                         Updates the state of an action.
__334_______WriteState___________________________Writes_the_component_to_a_stream.____________________________________________



                                                                 333

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.45.4         Property  overview

                __Page______Properties___________________Access______Description___________________________________________________*
 *___________
                  340       ComObject                    r           Interface reference implemented by the component
                  340       ComponentCount               r           Count of owned components
                  340       ComponentIndex               rw          Index of component in it's owner's list.
                  340       Components                   r           Indexed list (zero-based) of all owned components.
                  341       ComponentState               r           Current component's state.
                  341       ComponentStyle               r           Current component's style.
                  341       DesignInfo                   rw          Information for IDE designer.
                  342       Name                         rws         Name of the component.
                  342       Owner                        r           Owner of this component.
                  343       Tag                          rw          Tag value of the component.
                __342_______VCLComObject_________________rw__________Not_implemented.______________________________________________*
 *___________



                4.45.5         TComponent.Notification

    Synopsis:    Called by components that are freed and which received a FreeNotification.

Declaration:     procedure  Notification(AComponent:  TComponent;Operation:  TOperation)
                                                     ;    Virtual

    Visibility:   protected

Description:     Notification is called whenever a child component is destroyed, inserted or removed from
                the list of owned component.  Components that were requested to send a notification when
                they are freed ((with FreeNotification (336  )) will also call Notification when they are freed.

                The AComponent parameter specifies which component sends the notification, and Operation
                specifies whether the component is being inserted into or removed from the child component
                list, or whether it is being destroyed.

                Descendents  of  TComponent  can  use  FreeNotification  (336  )  to  request  notification  of  the
                destruction of another object.  By overriding the Notification method, they can do special
                processing  (typically,  set  a  reference  to  this  component  to  Nil)  when  this  component  is
                destroyed.   The  Notification  method  is  called  quite  often  in  the  streaming  process,  so
                speed should be a consideration when overriding this method.

    See also:    TOperation (246  ), TComponent.FreeNotification (336  ), TComponent.RemoveFreeNotification
                (337  )



                4.45.6         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  (462  )
                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  (333  )  implementation  of  WriteState  simply  calls  TWriter.WriteData
                (462  ).  Descendent classes can, however, override WriteStateto provide additional processing
                of stream data.

    See also:    ReadState (333  ), TStream.WriteComponent (415  ), TWriter.WriteData (462  )



                                                                                 334

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.45.7         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:    Insert (333  ), Owner (342  )



                4.45.8         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 (335  ) (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:    Notification (334  ), Owner (342  ), DestroyComponents (335  ), Components (340  )



                4.45.9         TComponent.BeforeDestruction

    Synopsis:    Overrides standard BeforeDestruction.

Declaration:     procedure  BeforeDestruction;    Override

    Visibility:   public

Description:     BeforeDestruction is overridden by TComponent to set the csDestroying flag in TCom-
                ponent.ComponentState (341  )

    See also:    TComponent.ComponentState (341  )



                4.45.10          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 (340  ) 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 (335  ) destructor will not be called, which may result in an
                endless loop.

    See also:    Destroy (335  ), Components (340  )



                                                                                 335

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.45.11          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 (333  ) property, and does
                the same for all owned components.

                It is not necessary to call Destroying directly, the destructor Destroy (335  ) does this auto-
                matically.

    See also:    State (333  ), Destroy (335  )



                4.45.12          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 (297  ), TBasicAction.ExecuteAction (297  ), TBasicAction.HandlesTarget (298  ),
                TComponent.UpdateAction (339  )



                4.45.13          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:    Components (340  ), Name (342  )



                4.45.14          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 (334  ) method is called for all components in the freenotification
                list.

    See also:    Components (340  ), Notification (334  ), TComponent.RemoveFreeNotification (337  )



                                                                                 336

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.45.15          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:    TComponent.FreeNotification (336  )



                4.45.16          TComponent.FreeOnRelease

    Synopsis:    Part of the IVCLComObject interface.

Declaration:     procedure  FreeOnRelease

    Visibility:   public

Description:     Provided for Delphi compatibility, but is not yet implemented.



                4.45.17          TComponent.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TComponentEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1472   ) interface for TComponent.
                It  creates  a  TComponentEnumerator  (343  )  instance  and  returns  it's  IEnumerator  (1472   )
                interface.  The enumerator enumerates all child components of the component instance.

    See also:    TComponentEnumerator (343  ), IEnumerator (1472   ), IEnumerable (1472   )



                4.45.18          TComponent.GetNamePath

    Synopsis:    Returns the name path of this component.

Declaration:     function  GetNamePath  :  string;    Override

    Visibility:   public

Description:     GetNamePath returns the name of the component as it will be shown in the object inspector.

                TComponent overrides GetNamePath so it returns the Name (342  ) property of the component.

    See also:    Name (342  ), TPersistent.GetNamePath (394  )



                4.45.19          TComponent.GetParentComponent

    Synopsis:    Returns the parent component.

Declaration:     function  GetParentComponent  :  TComponent;    Dynamic

    Visibility:   public



                                                                                 337

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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:    HasParent (338  ), Owner (342  )



                4.45.20          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 (337  ) will return the parent component.

    See also:    HasParent (338  ), Owner (342  )



                4.45.21          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 (333  ) to see whether the component can be inserted.  It then
                checks whether there are no name conflicts by calling ValidateRename (333  ).  If neither of
                these checks have raised an exception the component is inserted, and notified of the insert.

    See also:    RemoveComponent  (338  ),  Insert  (333  ),  ValidateContainer  (333  ),  ValidateRename  (333  ),
                Notification (334  )



                4.45.22          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:    InsertComponent (338  ), Remove (333  ), ValidateRename (333  ), Notification (334  )



                4.45.23          TComponent.SafeCallException

    Synopsis:    Part of the IVCLComObject Interface.

Declaration:     function  SafeCallException(ExceptObject:  TObject;
                                                           ExceptAddr:  CodePointer)  :  HRESULT;    Override

    Visibility:   public

Description:     Provided for Delphi compatibility, but not implemented.



                                                                                 338

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.45.24          TComponent.SetSubComponent

    Synopsis:    Sets the csSubComponent style.

Declaration:     procedure  SetSubComponent(ASubComponent:  Boolean)

    Visibility:   public

Description:     SetSubComponent includes csSubComponent in the ComponentStyle (341  ) property if ASubComponent
                is True, and excludes it again if  ASubComponent is False.

    See also:    TComponent.ComponentStyle (341  )



                4.45.25          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 (297  ), TBasicAction.UpdateTarget (298  ), TBasicAction.HandlesTarget (298  ),
                TBasicAction.ExecuteAction (297  )



                4.45.26          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 (274  ) and the GetComponent
                method should return the current instance.

    See also:    IInterfaceComponentReference (274  )



                4.45.27          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 (334  ) method of  TComponent for interfaces.
                If the interface implements IInterfaceComponentReference (274  ), then the component that
                implements the interface is notified of the given operation Op.

       Errors:   None.

    See also:    TComponent.Notification (334  ), IInterfaceComponentReference (274  )



                                                                                 339

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.45.28          TComponent.ComObject

    Synopsis:    Interface reference implemented by the component

Declaration:     Property  ComObject  :  IUnknown

    Visibility:   public

      Access:    Read

Description:     ComObject  returns  the  COM  interface  represented  by  the  component.   If  the  component
                does not represent a COM interface, reading this property will raise an EComponentError
                (267  ).

    See also:    EComponentError (267  )



                4.45.29          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 (340  ).

    See also:    ComponentCount (340  ), Owner (342  )



                4.45.30          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 (340  ) array.

    See also:    Components (340  ), Owner (342  )



                4.45.31          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:    Components (340  ), ComponentCount (340  ), Owner (342  )



                                                                                 340

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.45.32          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 4.21:  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:    SetAncestor (333  ), SetDesigning (333  ), SetInline (333  ), SetDesignInstance (333  ), Updating
                (333  ), Updated (333  ), Loaded (333  )



                4.45.33          TComponent.ComponentStyle

    Synopsis:    Current component's style.

Declaration:     Property  ComponentStyle  :  TComponentStyle

    Visibility:   public

      Access:    Read

Description:     Current component's style.



                4.45.34          TComponent.DesignInfo

    Synopsis:    Information for IDE designer.

Declaration:     Property  DesignInfo  :  LongInt

    Visibility:   public

      Access:    Read,Write



                                                                                 341

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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:    Tag (343  )



                4.45.35          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 (338  ) method, or by removing the component from it's owner's
                owned component list using the RemoveComponent (338  ) method.

    See also:    Components (340  ), InsertComponent (338  ), RemoveComponent (338  )



                4.45.36          TComponent.VCLComObject

    Synopsis:    Not implemented.

Declaration:     Property  VCLComObject  :  Pointer

    Visibility:   public

      Access:    Read,Write

Description:     VCLComObject is not yet implemented in Free Pascal.



                4.45.37          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 or underscore, 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.

                By "letters", 7-bit letters are meant.

       Errors:   Attempting to set the name to an invalid value will result in an exception being raised.

    See also:    ValidateRename (333  ), Owner (342  )



                                                                                 342

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.45.38          TComponent.Tag

    Synopsis:    Tag value of the component.

Declaration:     Property  Tag  :  PtrInt

    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:    Name (342  )



                4.46          TComponentEnumerator



                4.46.1         Description

                TComponentEnumerator  implements  the  #rtl.system.IEnumerator  (1472   )  interface  for  the
                TComponent (333  ) class, so the TComponent class can be used in a for  ...    in loop over
                the TComponent.Components (340  ) child components of the component.  It is returned by
                the TComponent.GetEnumerator (337  ) method of  TComponent.


    See also:    TComponent (333  ), TComponent.GetEnumerator (337  ), #rtl.system.IEnumerator (1472   )



                4.46.2         Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                  343       Create              Initialize a new instance of  TComponentEnumerator
                  344       GetCurrent          Return the current pointer in the list
                  344       MoveNext            Move  the  position  of  the  enumerator  to  the  next  position  in  the
                ________________________________children_of_the_component._________________________________________________________*
 *___________



                4.46.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __344_______Current___________r____________Current_pointer_in_the_list_____________________________________________*
 *___________



                4.46.4         TComponentEnumerator.Create

    Synopsis:    Initialize a new instance of  TComponentEnumerator

Declaration:     constructor  Create(AComponent:  TComponent)

    Visibility:   public

Description:     Create initializes a new instance of  TComponentEnumerator and keeps a reference to the
                component AComponent that will be enumerated.

    See also:    TComponent (333  )



                                                                                 343

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.46.5         TComponentEnumerator.GetCurrent

    Synopsis:    Return the current pointer in the list

Declaration:     function  GetCurrent  :  TComponent

    Visibility:   public

Description:     GetCurrent returns the current TComponent (333  ) child component instance in the enu-
                merator.

       Errors:   No checking is done on the validity of the current position.

    See also:    MoveNext (344  ), TComponent.Components (340  )



                4.46.6         TComponentEnumerator.MoveNext

    Synopsis:    Move the position of the enumerator to the next position in the children of the component.

Declaration:     function  MoveNext  :  Boolean

    Visibility:   public

Description:     MoveNext  puts  the  pointer  on  the  next  child  in  the  components  child  components,  and
                returns True if this succeeded, or False if the pointer is past the last child in the list.

       Errors:   Note that if  False is returned, calling GetCurrent will result in an exception.

    See also:    GetCurrent (344  )



                4.46.7         TComponentEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  TComponent

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (344  ) as a property.

    See also:    GetCurrent (344  )



                4.47          TCustomMemoryStream



                4.47.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 (346  ) 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 (381  ).  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 (381  ).



                                                                                 344

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    See also:    TMemoryStream (381  ), TStream (410  )



                4.47.2         Method  overview

                __Page______Method__________________Description____________________________________________________________________*
 *___________
                  345       Read                    Reads Count bytes from the stream into buffer.
                  346       SaveToFile              Writes the contents of the stream to a file.
                  345       SaveToStream            Writes the contents of the memory stream to another stream.
                __345_______Seek____________________Sets_a_new_position_in_the_stream._____________________________________________*
 *___________



                4.47.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __346_______Memory____________r____________Pointer_to_the_data_kept_in_the_memory_stream.__________________________*
 *___________



                4.47.4         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 (411  ) method of TStream (410  ).  It will read as
                much bytes as are still available in the memory area pointer to by Memory (346  ).  After the
                bytes are read, the internal stream position is updated.

    See also:    TCustomMemoryStream.Memory (346  ), TStream.Read (411  )



                4.47.5         TCustomMemoryStream.Seek

    Synopsis:    Sets a new position in the stream.

Declaration:     function  Seek(const  Offset:  Int64;Origin:  TSeekOrigin)  :  Int64
                                      ;    Override

    Visibility:   public

Description:     Seek  overrides  the  abstract  TStream.Seek  (412  )  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 (420  ), TStream.Size (420  ), TCustomMemoryStream.Memory (346  )



                4.47.6         TCustomMemoryStream.SaveToStream

    Synopsis:    Writes the contents of the memory stream to another stream.

Declaration:     procedure  SaveToStream(Stream:  TStream)



                                                                                 345

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    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 (414  ) 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 (269  ) exception will be raised.

    See also:    TCustomMemoryStream.SaveToFile (346  ), TStream.CopyFrom (414  )



                4.47.7         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 (345  ).

 Remark:         This method will work much faster than the use of the TStream.CopyFrom (414  ) 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  (269  )  exception
                may occur.

    See also:    TCustomMemoryStream.SaveToStream (345  ), TFileStream (352  ), TStream.CopyFrom (414  )



                4.47.8         TCustomMemoryStream.Memory

    Synopsis:    Pointer to the data kept in the memory stream.

Declaration:     Property  Memory  :  Pointer

    Visibility:   public

      Access:    Read

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 (420  )



                                                                                 346

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.48          TDataModule



                4.48.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.


    See also:    TDataModule.OnCreate (349  )



                4.48.2         Method  overview

                __Page______Method_______________________Description_______________________________________________________________*
 *___________
                  348       AfterConstruction            Overrides standard TObject (1478   ) behaviour.
                  348       BeforeDestruction
                  347       Create                       Create a new instance of a TDataModule.
                  348       CreateNew
                __348_______Destroy______________________Destroys_the_TDataModule_instance.________________________________________*
 *___________



                4.48.3         Property  overview

                __Page______Properties________________Access_______Description_____________________________________________________*
 *___________
                  349       DesignOffset              rw           Position property needed for manipulation in an IDE.
                  349       DesignSize                rw           Size property needed for manipulation in an IDE.
                  350       OldCreateOrder            rw           Determines when OnCreate and OnDestroy are trig-
                                                                   gered.
                  349       OnCreate                  rw           Event handler, called when the datamodule is created.
                  349       OnDestroy                 rw           Event  handler,  called  when  the  datamodule  is  de-
                ___________________________________________________stroyed.________________________________________________________*
 *___________



                4.48.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 (348  ).
                After  that  it  reads  the  published  properties  from  a  stream  using  InitInheritedComponent
                (258  ) if a descendent class is instantiated.  If the OldCreateOrder (350  ) property is True, the
                TDataModule.OnCreate (349  ) event is called.

       Errors:   An exception can be raised during the streaming operation.

    See also:    TDataModule.CreateNew (348  )



                                                                                 347

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.48.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
                (251  ) handler is set, then it is called, with the newly created instance as an argument.

    See also:    TDataModule.Create (347  ), AddDataModule (251  ), TDataModule.OnCreate (349  )



                4.48.6         TDataModule.Destroy

    Synopsis:    Destroys the TDataModule instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy destroys the TDataModule instance.  If the OldCreateOrder (350  ) property is True
                the OnDestroy (349  ) event handler is called prior to destroying the data module.

                Before calling the inherited destroy, the RemoveDataModule (251  ) 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 (349  ), RemoveDataModule (251  )



                4.48.7         TDataModule.AfterConstruction

    Synopsis:    Overrides standard TObject (1478   ) behaviour.

Declaration:     procedure  AfterConstruction;    Override

    Visibility:   public

Description:     AfterConstruction calls the OnCreate (349  ) handler if the OldCreateOrder (350  ) property
                is False.

    See also:    TDataModule.OldCreateOrder (350  ), TDataModule.OnCreate (349  )



                4.48.8         TDataModule.BeforeDestruction

    Synopsis:

Declaration:     procedure  BeforeDestruction;    Override

    Visibility:   public

Description:     BeforeDestruction calls the OnDestroy (349  ) handler if the OldCreateOrder (350  ) prop-
                erty is False.

    See also:    TDataModule.OldCreateOrder (350  ), TDataModule.OnDestroy (349  )



                                                                                 348

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.48.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 (349  )



                4.48.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 (349  )



                4.48.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 (350  ) property.

    See also:    TDataModule.Create (347  ), TDataModule.CreateNew (348  ), TDataModule.OldCreateOrder
                (350  )



                4.48.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 (350  ) property.

    See also:    TDataModule.Destroy  (348  ),  TDataModule.OnCreate  (349  ),  TDataModule.Create  (347  ),
                TDataModule.CreateNew (348  ), TDataModule.OldCreateOrder (350  )



                                                                                 349

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.48.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 (349  ) and OnDestroy (349  ) event
                handlers are called.

                If set to True, then the OnCreate event handler is called after the data module was streamed.
                If it is set to False, then the handler is called prior to the streaming process.

                If set to True, then the OnDestroy event handler is called before the data module is removed
                from the streaming system.  If it is set to False,  then the handler is called after the data
                module was removed from the streaming process.

    See also:    TDataModule.OnDestroy (349  ), TDataModule.OnCreate (349  ), TDataModule.Destroy (348  ),
                TDataModule.Create (347  ), TDataModule.CreateNew (348  ), TDataModule.OldCreateOrder
                (350  )



                4.49          TFiler



                4.49.1         Description

                Class responsible for streaming of components.



                4.49.2         Method  overview

                __Page______Method____________________________Description__________________________________________________________*
 *___________
                  351       DefineBinaryProperty
                __350_______DefineProperty_________________________________________________________________________________________*
 *___________



                4.49.3         Property  overview

                __Page______Properties_______________Access_______Description______________________________________________________*
 *___________
                  351       Ancestor                 rw           Ancestor component from which an inherited compo-
                                                                  nent is streamed.
                  352       IgnoreChildren           rw           Determines whether children will be streamed as well.
                  351       LookupRoot               r            Component used to look up ancestor components.
                  351       Root                     rw           The root component is the initial component which is
                __________________________________________________being_streamed.__________________________________________________*
 *___________



                4.49.4         TFiler.DefineProperty

    Synopsis:

Declaration:     procedure  DefineProperty(const  Name:  string;ReadData:  TReaderProc;
                                                        WriteData:  TWriterProc;HasData:  Boolean)
                                                        ;    Virtual;    Abstract

    Visibility:   public

Description:



                                                                                 350

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.49.5         TFiler.DefineBinaryProperty

    Synopsis:

Declaration:     procedure  DefineBinaryProperty(const  Name:  string;ReadData:  TStreamProc;
                                                                  WriteData:  TStreamProc;HasData:  Boolean)
                                                                  ;    Virtual;    Abstract

    Visibility:   public

Description:



                4.49.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:    LookupRoot (351  )



                4.49.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 (351  ).

    See also:    Root (351  )



                4.49.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:    Root (351  ), LookupRoot (351  )



                                                                                 351

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.49.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.



                4.50          TFileStream



                4.50.1         Description

                TFileStream is a TStream (410  ) 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 (353  ) property to the list of public properties.


    See also:    TFileStream.Create (352  ), TStream (410  )



                4.50.2         Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  352       Create         Creates a file stream.
                __353_______Destroy________Destroys_the_file_stream._______________________________________________________________*
 *___________



                4.50.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __353_______FileName__________r____________The_filename_of_the_stream._____________________________________________*
 *___________



                4.50.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)

    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 4.22:

                      fmCreate                      TFileStream.Create (352  ) creates a new file if needed.
                      fmOpenRead                    TFileStream.Create (352  ) opens a file with read-only access.
                      fmOpenWrite                   TFileStream.Create (352  ) opens a file with write-only access.
                      fmOpenReadWrite               TFileStream.Create (352  ) opens a file with read-write access.



                                                                                 352

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                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 (268  ) exception is
                raised.

    See also:    TStream (410  ), TFileStream.FileName (353  ), THandleStream.Create (363  )



                4.50.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 (352  )



                4.50.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 (352  )



                4.51          TFPList



                4.51.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 (371  ), 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  (430  )  descendent  such  as
                TStringList (425  ).  To manage general objects, a TCollection (322  ) class exists, from which
                a descendent can be made to manage collections of various kinds.


    See also:    TStrings (430  ), TCollection (322  )



                                                                                 353

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.51.2         Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  355       Add                       Adds a new pointer to the list.
                  354       AddList                   Add all pointers from another list
                  358       Assign                    Assign performs the given operation on the list.
                  355       Clear                     Clears the pointer list.
                  355       Delete                    Removes a pointer from the list.
                  354       Destroy                   Destroys the list and releases the memory used to store the list
                                                      elements.
                  355       Error                     Raises an EListError (268  ) exception.
                  356       Exchange                  Exchanges two pointers in the list.
                  356       Expand                    Increases the capacity of the list if needed.
                  356       Extract                   Remove the first occurrence of a pointer from the list.
                  356       First                     Returns the first non-nil pointer in the list.
                  359       ForEachCall               Call a procedure or method for each pointer in the list.
                  357       GetEnumerator             Create an IEnumerator instance
                  357       IndexOf                   Returns the index of a given pointer.
                  357       IndexOfItem               Search an item in the list
                  357       Insert                    Inserts a new pointer in the list at a given position.
                  358       Last                      Returns the last non-nil pointer in the list.
                  358       Move                      Moves a pointer from one position in the list to another.
                  359       Pack                      Removes Nil pointers from the list and frees unused memory.
                  358       Remove                    Removes a value from the list.
                __359_______Sort______________________Sorts_the_pointers_in_the_list.______________________________________________*
 *___________



                4.51.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  359       Capacity          rw           Current  capacity  (i.e.    number  of  pointers  that  can  be
                                                           stored) of the list.
                  360       Count             rw           Current number of pointers in the list.
                  360       Items             rw           Provides access to the pointers in the list.
                __360_______List______________r____________Memory_array_where_pointers_are_stored._________________________________*
 *___________



                4.51.4         TFPList.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.



                4.51.5         TFPList.AddList

    Synopsis:    Add all pointers from another list

Declaration:     procedure  AddList(AList:  TFPList)

    Visibility:   public



                                                                                 354

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (358  ), TList.AddList (374  )



                4.51.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 Expand (356  ) method.

                To insert a pointer at a certain position in the list, use the Insert (357  ) method instead.

    See also:    Delete (355  ), Grow (371  ), Insert (357  )



                4.51.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:    Destroy (354  )



                4.51.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.



                4.51.9         TFPList.Error

    Synopsis:    Raises an EListError (268  ) exception.

Declaration:     class  procedure  Error(const  Msg:  string;Data:  PtrInt)

    Visibility:   public

Description:     Error raises an EListError (268  ) exception, with a message formatted with Msg and Data.



                                                                                 355

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.51.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 (268  ) exception will be raised.



                4.51.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:    Capacity (359  )



                4.51.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 (355  )



                4.51.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:    Last (358  )



                                                                                 356

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.51.14          TFPList.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TFPListEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1472   ) interface for TFPList.  It
                creates a TFPListEnumerator (361  ) instance and returns it's IEnumerator (1472   ) interface.

    See also:    TFPListEnumerator (361  ), IEnumerator (1472   ), IEnumerable (1472   )



                4.51.15          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.



                4.51.16          TFPList.IndexOfItem

    Synopsis:    Search an item in the list

Declaration:     function  IndexOfItem(Item:  Pointer;Direction:  TDirection)  :  Integer

    Visibility:   public

Description:     IndexOfItem has the same function as the IndexOf (235  ) function:  it searches for Item in
                the  list,  and  returns  the  index  of  the  first  found  matching  pointer.  If  none  is  found,  -1  is
                returned.

                In  difference  with  the  IndexOf  function,  it  accepts  a  parameter  Direction  indicating  the
                search direction:  from the beginning of the list till the end of the list, or from the end of the
                list till the beginning.  The IndexOf function starts at the beginning of the list.  The search
                direction is only important if the item can appear multiple times in the list.

    See also:    TFPList.TDirection (??  ), TFPList.IndexOf (357  )



                4.51.17          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 (268  ) exception is raised.

    See also:    Add (355  ), Delete (355  )



                                                                                 357

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.51.18          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:    First (356  )



                4.51.19          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  (268  )
                exception is raised.

    See also:    Exchange (356  )



                4.51.20          TFPList.Assign

    Synopsis:    Assign performs the given operation on the list.

Declaration:     procedure  Assign(ListA:  TFPList;AOperator:  TListAssignOp;ListB:  TFPList)

    Visibility:   public

Description:     Assign can be used to merge or assign lists It is an extended version of the usual TPersistent.Assign
                mechanism.  The arguments ListA and ListB are used as sources of pointers to add or re-
                move elements from the current list, depending on the operation AOperation.  The available
                operations are documented in the TListAssignOp (244  ) type.

    See also:    TFPList.Add (355  ), TFPList.Clear (355  )



                4.51.21          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:    Delete (355  ), IndexOf (357  ), Insert (357  )



                                                                                 358

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.51.22          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 (355  )



                4.51.23          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.



                4.51.24          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 (245  ), TListCallback (245  )



                4.51.25          TFPList.Capacity

    Synopsis:    Current capacity (i.e.  number of pointers that can be stored) of the list.

Declaration:     Property  Capacity  :  Integer

    Visibility:   public



                                                                                 359

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



      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 (355  ) or insert (357  ), 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:    SetCapacity (353  ), Count (360  )



                4.51.26          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.



                4.51.27          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.



                4.51.28          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.



                                                                                 360

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.52          TFPListEnumerator



                4.52.1         Description

                TFPListEnumerator implements the #rtl.system.IEnumerator (1472   ) interface for the TF-
                PList (353  ) class, so the TFPList class can be used in a for  ...    in loop.  It is returned
                by the TFPList.GetEnumerator (357  ) method of  TFPList.


    See also:    TFPList (353  ), TFPList.GetEnumerator (357  ), #rtl.system.IEnumerator (1472   )



                4.52.2         Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                  361       Create              Initialize a new instance of  TFPListEnumerator
                  361       GetCurrent          Return the current pointer in the list
                __361_______MoveNext____________Move_the_position_of_the_enumerator_to_the_next_position_in_the_list.______________*
 *___________



                4.52.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __362_______Current___________r____________Current_pointer_in_the_list_____________________________________________*
 *___________



                4.52.4         TFPListEnumerator.Create

    Synopsis:    Initialize a new instance of  TFPListEnumerator

Declaration:     constructor  Create(AList:  TFPList)

    Visibility:   public

Description:     Create initializes a new instance of  TFPListEnumerator and keeps a reference to the list
                AList that will be enumerated.

    See also:    TFPList (353  )



                4.52.5         TFPListEnumerator.GetCurrent

    Synopsis:    Return the current pointer in the list

Declaration:     function  GetCurrent  :  Pointer

    Visibility:   public

Description:     GetCurrent returns the current pointer in the enumerator.

       Errors:   No checking is done on the validity of the current position.

    See also:    MoveNext (361  )



                4.52.6         TFPListEnumerator.MoveNext

    Synopsis:    Move the position of the enumerator to the next position in the list.

Declaration:     function  MoveNext  :  Boolean

    Visibility:   public



                                                                                 361

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     MoveNext puts the pointer on the next item in the list, and returns True if this succeeded,
                or False if the pointer is past the last element in the list.

       Errors:   Note that if  False is returned, calling GetCurrent will result in an exception.

    See also:    GetCurrent (361  )



                4.52.7         TFPListEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  Pointer

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (361  ) as a property.

    See also:    GetCurrent (361  )



                4.53          THandleStream



                4.53.1         Description

                THandleStream  is  an  abstract  descendent  of  the  TStream  (410  )  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 (363  ) and Write (363  ) 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.


    See also:    TStream (410  ), TFileStream (352  )



                4.53.2         Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  363       Create         Create a handlestream from an OS Handle.
                  363       Read           Overrides standard read method.
                  363       Seek           Overrides the Seek method.
                __363_______Write__________Overrides_standard_write_method.________________________________________________________*
 *___________



                4.53.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __364_______Handle____________r____________The_OS_handle_of_the_stream.____________________________________________*
 *___________



                                                                                 362

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.53.4         THandleStream.Create

    Synopsis:    Create a handlestream from an OS Handle.

Declaration:     constructor  Create(AHandle:  THandle)

    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 (410  )



                4.53.5         THandleStream.Read

    Synopsis:    Overrides standard read method.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read overrides the Read (411  ) method of  TStream.  It uses the Handle (364  ) 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 (411  ), THandleStream.Write (363  ), THandleStream.Handle (364  )



                4.53.6         THandleStream.Write

    Synopsis:    Overrides standard write method.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write overrides the Write (412  ) method of  TStream.  It uses the Handle (364  ) 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 (411  ), THandleStream.Write (363  ), THandleStream.Handle (364  )



                4.53.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 (1570   ) method to position the stream on the desired position.  Note
                that handle stream descendents (notably pipes) can override the method to prevent the seek.



                                                                                 363

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.53.8         THandleStream.Handle

    Synopsis:    The OS handle of the stream.

Declaration:     Property  Handle  :  THandle

    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 (363  )

    See also:    THandleStream (362  ), THandleStream.Create (363  )



                4.54          TInterfacedPersistent



                4.54.1         Description

                TInterfacedPersistent is a direct descendent of TPersistent (391  ) which implements the
                #rtl.system.IInterface (1267   ) interface.  In particular, it implements the QueryInterface as
                a public method.


    See also:    IInterface (1267   )



                4.54.2         Interfaces  overview

                __Page______Interfaces_______Description___________________________________________________________________________*
 *___________
                __1267______IInterface_______Basic_interface_for_all_COM_based_interfaces__________________________________________*
 *___________



                4.54.3         Method  overview

                __Page______Method_______________________Description_______________________________________________________________*
 *___________
                  364       AfterConstruction            Overrides the standard AfterConstruction method.
                __364_______QueryInterface_______________Implementation_of__IInterface.QueryInterface______________________________*
 *___________



                4.54.4         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:    TObject.GetInterface (1486   )



                4.54.5         TInterfacedPersistent.AfterConstruction

    Synopsis:    Overrides the standard AfterConstruction method.

Declaration:     procedure  AfterConstruction;    Override



                                                                                 364

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    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).



                4.55          TInterfaceList



                4.55.1         Description

                TInterfaceList is a standard implementation of the IInterfaceList (274  ) interface.  It uses
                a TThreadList (460  ) instance to store the list of interfaces.


    See also:    IInterfaceList (274  ), TList (371  )



                4.55.2         Interfaces  overview

                __Page______Interfaces_____________Description_____________________________________________________________________*
 *___________
                __274_______IInterfaceList_________Interface_for_maintaining_a_list_of_interfaces._________________________________*
 *___________



                4.55.3         Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  367       Add                       Add an interface to the list
                  366       Clear                     Removes all interfaces from the list.
                  365       Create                    Create a new instance of  TInterfaceList
                  366       Delete                    Delete an interface from the list.
                  366       Destroy                   Destroys the list of interfaces
                  366       Exchange                  Exchange 2 interfaces in the list
                  369       Expand                    Expands the list
                  367       First                     Returns the first non-Nil element in the list.
                  367       GetEnumerator             Create an IEnumerator instance
                  367       IndexOf                   Returns the index of an interface.
                  368       Insert                    Insert an interface to the list
                  368       Last                      Returns the last non-Nil element in the list.
                  368       Lock                      Lock the list
                  368       Remove                    Remove an interface from the list
                __369_______Unlock____________________UnLocks_a_locked_list________________________________________________________*
 *___________



                4.55.4         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  369       Capacity          rw           The current capacity of the list.
                  369       Count             rw           The current number of elements in the list.
                __370_______Items_____________rw___________Array-based_access_to_the_list's_items._________________________________*
 *___________



                4.55.5         TInterfaceList.Create

    Synopsis:    Create a new instance of  TInterfaceList

Declaration:     constructor  Create

    Visibility:   public



                                                                                 365

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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:    Destroy (366  )



                4.55.6         TInterfaceList.Destroy

    Synopsis:    Destroys the list of interfaces

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy first calls Clear (366  ) and then frees the TInterfaceList instance from memory.

                Note that the Clear method decreases the reference count of all interfaces.

    See also:    Create (365  ), Clear (366  )



                4.55.7         TInterfaceList.Clear

    Synopsis:    Removes all interfaces from the list.

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear is the implementation of the IInterfaceList.Clear (277  ) 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  (277  ),  Add  (367  ),  Destroy  (366  ),  TList.Clear  (374  ),  TFPList.Clear
                (355  )



                4.55.8         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 (277  ) method.  It clears the slot
                first and then removes the element from the list.

    See also:    IInterfaceList.Delete (277  ), TInterfaceList.Remove (368  ), TInterfaceList.Add (367  ), TList.Delete
                (374  ), TFPList.Delete (355  )



                4.55.9         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 (277  ) method.  It exchanges
                the position of 2 interfaces in the list.

    See also:    IInterfaceList.Exchange (277  ), TInterfaceList.Delete (366  ), TInterfaceList.Add (367  ), TList.Exchange
                (375  ), TFPList.Exchange (356  )



                                                                                 366

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.55.10          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 (277  ) method.  It returns the first
                non-Nil element from the list.

    See also:    IInterfaceList.First (277  ), TList.First (376  )



                4.55.11          TInterfaceList.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TInterfaceListEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1472   ) interface for TInterfaceList.
                It  creates  a  TInterfaceListEnumerator  (370  )  instance  and  returns  it's  IEnumerator  (1472   )
                interface.  The enumerator enumerates all interfaces in the list.

    See also:    TInterfaceListEnumerator (370  ), IEnumerator (1472   ), IEnumerable (1472   )



                4.55.12          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 (278  ) 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 (278  ), TList.IndexOf (376  )



                4.55.13          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 (278  ) 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 (278  ), TInterfaceList.Delete (366  ), TInterfaceList.Insert (368  ), TList.Add
                (374  ), TFPList.Add (355  )



                                                                                 367

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.55.14          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 (278  ) 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 (278  ), TInterfaceList.Delete (366  ), TInterfaceList.Add (367  ), TList.Insert
                (376  ), TFPList.Insert (357  )



                4.55.15          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  (278  )  method.   It  returns  the  last
                non-Nil element from the list.

    See also:    IInterfaceList.Last (278  ), TInterfaceList.First (367  ), TList.Last (377  ), TFPList.Last (358  )



                4.55.16          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 (278  ) method.  It removes the
                first occurrence of the interface from the list.

    See also:    IInterfaceList.Remove (278  ), TInterfaceList.Delete (366  ), TInterfaceList.IndexOf (367  ), TList.Remove
                (377  ), TFPList.Remove (358  )



                4.55.17          TInterfaceList.Lock

    Synopsis:    Lock the list

Declaration:     procedure  Lock

    Visibility:   public

Description:     Lock  locks  the  list.  It  is  the  implementation  of  the  IInterfaceList.Lock  (279  )  method.  It
                limits access to the list to the current thread.

    See also:    IInterfaceList.Lock (279  ), TInterfaceList.UnLock (369  ), TThreadList.LockList (461  )



                                                                                 368

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.55.18          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 (279  ) method.
                After a call to unlock, the current thread releases the list for manipulation by other threads.

    See also:    IInterfaceList.UnLock (279  ), TInterfaceList.Lock (368  ), TThreadList.UnLockList (462  )



                4.55.19          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 (375  )



                4.55.20          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 (279  ), TInterfaceList.Count (369  ), TList.Capacity (378  ), TFPList.Capacity
                (359  )



                4.55.21          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 (279  ), TInterfaceList.Items (370  ), TInterfaceList.Capacity (369  ), TList.Count
                (379  ), TFPList.Count (360  )



                                                                                 369

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.55.22          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 (369  ).

    See also:    IInterfaceList.Items  (280  ),  TInterfaceList.Count  (369  ),  TList.Items  (379  ),  TFPList.Items
                (360  )



                4.56          TInterfaceListEnumerator



                4.56.1         Description

                TInterfaceListEnumerator implements the #rtl.system.IEnumerator (1472   ) interface for
                the TInterfaceList (365  ) class, so the TInterfaceList class can be used in a for  ...    in
                loop  over  the  TInterfaceList.Components  (365  )  child  components  of  the  component.  It  is
                returned by the TInterfaceList.GetEnumerator (367  ) method of  TInterfaceList.


    See also:    TInterfaceList (365  ), TInterfaceList.GetEnumerator (367  ), #rtl.system.IEnumerator (1472   )



                4.56.2         Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                  370       Create              Initialize a new instance of  TInterfaceListEnumerator
                  371       GetCurrent          Return the current pointer in the list
                  371       MoveNext            Move  the  position  of  the  enumerator  to  the  next  position  in  the
                ________________________________children_of_the_component._________________________________________________________*
 *___________



                4.56.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __371_______Current___________r____________Current_pointer_in_the_list_____________________________________________*
 *___________



                4.56.4         TInterfaceListEnumerator.Create

    Synopsis:    Initialize a new instance of  TInterfaceListEnumerator

Declaration:     constructor  Create(AList:  TInterfaceList)

    Visibility:   public

Description:     Create initializes a new instance of  TInterfaceListEnumerator and keeps a reference to
                the component AComponent that will be enumerated.

    See also:    TInterfaceList (365  )



                                                                                 370

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.56.5         TInterfaceListEnumerator.GetCurrent

    Synopsis:    Return the current pointer in the list

Declaration:     function  GetCurrent  :  IUnknown

    Visibility:   public

Description:     GetCurrent returns the current interface in the TInterfaceList (365  ) list.

       Errors:   No checking is done on the validity of the current position.

    See also:    MoveNext (371  ), TInterfaceList.Components (365  )



                4.56.6         TInterfaceListEnumerator.MoveNext

    Synopsis:    Move the position of the enumerator to the next position in the children of the component.

Declaration:     function  MoveNext  :  Boolean

    Visibility:   public

Description:     MoveNext puts the pointer on the next interface in the list, and returns True if this succeeded,
                or False if the pointer is past the last interface in the list.

       Errors:   Note that if  False is returned, calling GetCurrent will result in an exception.

    See also:    GetCurrent (371  )



                4.56.7         TInterfaceListEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  IUnknown

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (371  ) as a property.

    See also:    GetCurrent (371  )



                4.57          TList



                4.57.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 (353  ) may be used instead.

                To  manage  collections  of  strings,  it  is  better  to  use  a  TStrings  (430  )  descendent  such  as
                TStringList (425  ).  To manage general objects, a TCollection (322  ) class exists, from which
                a descendent can be made to manage collections of various kinds.


    See also:    TStrings (430  ), TCollection (322  )



                                                                                 371

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.57.2         Interfaces  overview

                __Page______Interfaces____________Description______________________________________________________________________*
 *___________
                __272_______IFPObserved___________Interface_implemented_by_an_object_that_can_be_observed._________________________*
 *___________



                4.57.3         Method  overview

                __Page______Method___________________________Description___________________________________________________________*
 *___________
                  374       Add                              Adds a new pointer to the list.
                  374       AddList                          Add all pointers from another list
                  377       Assign                           Copy the contents of other lists.
                  374       Clear                            Clears the pointer list.
                  372       Create                           Class to manage collections of pointers.
                  374       Delete                           Removes a pointer from the list.
                  373       Destroy                          Destroys  the  list  and  releases  the  memory  used  to  store
                                                             the list elements.
                  375       Error                            Raises an EListError (268  ) exception.
                  375       Exchange                         Exchanges two pointers in the list.
                  375       Expand                           Increases the capacity of the list if needed.
                  375       Extract                          Remove the first occurrence of a pointer from the list.
                  376       First                            Returns the first non-nil pointer in the list.
                  373       FPOAttachObserver                Add an observer to the list of observers
                  373       FPODetachObserver                Remove an observer from the list of observers
                  373       FPONotifyObservers               Notify observers of changes in the list
                  376       GetEnumerator                    Create an IEnumerator instance
                  376       IndexOf                          Returns the index of a given pointer.
                  376       Insert                           Inserts a new pointer in the list at a given position.
                  377       Last                             Returns the last non-nil pointer in the list.
                  377       Move                             Moves a pointer from one position in the list to another.
                  378       Pack                             Removes Nil pointers from the list and frees unused mem-
                                                             ory.
                  377       Remove                           Removes a value from the list.
                __378_______Sort_____________________________Sorts_the_pointers_in_the_list._______________________________________*
 *___________



                4.57.4         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  378       Capacity          rw           Current  capacity  (i.e.    number  of  pointers  that  can  be
                                                           stored) of the list.
                  379       Count             rw           Current number of pointers in the list.
                  379       Items             rw           Provides access to the pointers in the list.
                __379_______List______________r____________Memory_array_where_pointers_are_stored._________________________________*
 *___________



                4.57.5         TList.Create

    Synopsis:    Class to manage collections of pointers.

Declaration:     constructor  Create

    Visibility:   public

Description:     TList.Create creates a new instance of  TList.  It clears the list and prepares it for use.

    See also:    TList (371  ), TList.Destroy (373  )



                                                                                 372

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.57.6         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.



                4.57.7         TList.FPOAttachObserver

    Synopsis:    Add an observer to the list of observers

Declaration:     procedure  FPOAttachObserver(AObserver:  TObject)

    Visibility:   public

Description:     FPOAttachObserver  is  part  of  the  implementation  of  the  IFPObserved  (272  )  interface  in
                Tlist.  It adds a new observer to the list of observers.  Calling this multiple times will add
                the observed object multiple times to the list.

       Errors:   An  EObserver  exception  may  be  raised  if  AObject  does  not  implement  the  IFPObserver
                (273  ) interface.

    See also:    IFPObserver (273  ), IFPObserved.FPOAttachObserver (272  ), IFPObserved (272  )



                4.57.8         TList.FPODetachObserver

    Synopsis:    Remove an observer from the list of observers

Declaration:     procedure  FPODetachObserver(AObserver:  TObject)

    Visibility:   public

Description:     FPODetachObserver  is  part  of  the  implementation  of  the  IFPObserved  (272  )  interface  in
                Tlist.  It removes the first found instance of the observer from the list of observers.

    See also:    IFPObserved (272  ), IFPObserved.FPODetachObserver (272  ), IFPObserver (273  )



                4.57.9         TList.FPONotifyObservers

    Synopsis:    Notify observers of changes in the list

Declaration:     procedure  FPONotifyObservers(ASender:  TObject;
                                                              AOperation:  TFPObservedOperation;
                                                              Data:  Pointer)

    Visibility:   public

Description:     FPONotifyObservers  is  called  to  notify  observers  of  changes  in  the  list.   The  following
                notifications are sent:


                ooAddItem         when a pointer is added.  Data is the pointer that is added.

                ooDeleteItem          when a pointer is deleted or extracted.  Data is the pointer that is deleted or
                       extracted.



                                                                                 373

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                ooChange       called when 2 pointers are exchanged.

                ooFree    Called when the list is freed.

    See also:    FPODetachObserver (235  ), FPOAttachObserver (235  ), Add (235  ), Exchange (235  ), Delete
                (235  ), Extract (235  )



                4.57.10          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 (377  ), TFPList.AddList (354  )



                4.57.11          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 (371  ) method.

                To insert a pointer at a certain position in the list, use the Insert (376  ) method instead.

    See also:    Delete (374  ), Grow (371  ), Insert (376  )



                4.57.12          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:    Destroy (373  )



                4.57.13          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.



                                                                                 374

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.57.14          TList.Error

    Synopsis:    Raises an EListError (268  ) exception.

Declaration:     class  procedure  Error(const  Msg:  string;Data:  PtrInt);    Virtual

    Visibility:   public

Description:     Error raises an EListError (268  ) exception, with a message formatted with Msg and Data.



                4.57.15          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 (268  ) exception will be raised.



                4.57.16          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:    Capacity (378  )



                4.57.17          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 occurrence 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.

    See also:    TList.Delete (374  ), TList.IndexOf (376  ), TList.Remove (377  )



                                                                                 375

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.57.18          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:    Last (377  )



                4.57.19          TList.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TListEnumerator

    Visibility:   public

Description:     GetEnumerator  is  the  implementation  of  the  IEnumerable  (1472   )  interface  for  TList.  It
                creates a TListEnumerator (379  ) instance and returns it's IEnumerator (1472   ) interface.

    See also:    TListEnumerator (379  ), IEnumerator (1472   ), IEnumerable (1472   )



                4.57.20          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.



                4.57.21          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 (268  ) exception is raised.

    See also:    Add (374  ), Delete (374  )



                                                                                 376

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.57.22          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:    First (376  )



                4.57.23          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  (268  )
                exception is raised.

    See also:    Exchange (375  )



                4.57.24          TList.Assign

    Synopsis:    Copy the contents of other lists.

Declaration:     procedure  Assign(ListA:  TList;AOperator:  TListAssignOp;ListB:  TList)

    Visibility:   public

Description:     Assign can be used to merge or assign lists It is an extended version of the usual TPersistent.Assign
                mechanism.  The arguments ListA and ListB are used as sources of pointers to add or re-
                move elements from the current list, depending on the operation AOperation.  The available
                operations are documented in the TListAssignOp (244  ) type.

    See also:    TList.Clear (374  )



                4.57.25          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:    Delete (374  ), IndexOf (376  ), Insert (376  )



                                                                                 377

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.57.26          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 (374  )



                4.57.27          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.



                4.57.28          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 (374  ) or insert (376  ), 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:    SetCapacity (371  ), Count (379  )



                                                                                 378

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.57.29          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.



                4.57.30          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.



                4.57.31          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.



                4.58          TListEnumerator



                4.58.1         Description

                TListEnumerator  implements  the  #rtl.system.IEnumerator  (1472   )  interface  for  the  TList
                (371  )  class,  so  the  TList  class  can  be  used  in  a  for  ...    in  loop.  It  is  returned  by  the
                TList.GetEnumerator (376  ) method of  TList.


    See also:    TList (371  ), TList.GetEnumerator (376  ), #rtl.system.IEnumerator (1472   )



                4.58.2         Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                  380       Create              Initialize a new instance of  TListEnumerator
                  380       GetCurrent          Return the current pointer in the list
                __380_______MoveNext____________Move_the_position_of_the_enumerator_to_the_next_position_in_the_list.______________*
 *___________



                                                                                 379

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.58.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __380_______Current___________r____________Current_pointer_in_the_list_____________________________________________*
 *___________



                4.58.4         TListEnumerator.Create

    Synopsis:    Initialize a new instance of  TListEnumerator

Declaration:     constructor  Create(AList:  TList)

    Visibility:   public

Description:     Create  initializes  a  new  instance  of  TListEnumerator  and  keeps  a  reference  to  the  list
                AList that will be enumerated.

    See also:    TList (371  )



                4.58.5         TListEnumerator.GetCurrent

    Synopsis:    Return the current pointer in the list

Declaration:     function  GetCurrent  :  Pointer

    Visibility:   public

Description:     GetCurrent returns the current pointer in the enumerator.

       Errors:   No checking is done on the validity of the current position.

    See also:    MoveNext (380  )



                4.58.6         TListEnumerator.MoveNext

    Synopsis:    Move the position of the enumerator to the next position in the list.

Declaration:     function  MoveNext  :  Boolean

    Visibility:   public

Description:     MoveNext puts the pointer on the next item in the list, and returns True if this succeeded,
                or False if the pointer is past the last element in the list.

       Errors:   Note that if  False is returned, calling GetCurrent will result in an exception.

    See also:    GetCurrent (380  )



                4.58.7         TListEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  Pointer

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (380  ) as a property.

    See also:    GetCurrent (380  )



                                                                                 380

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.59          TMemoryStream



                4.59.1         Description

                TMemoryStream is a TStream (410  ) descendent that stores it's data in memory.  It descends
                directly from TCustomMemoryStream (344  ) and implements the necessary to allocate and
                de-allocate memory directly from the heap.  It implements the Write (383  ) 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.


    See also:    TCustomMemoryStream (344  ), TStream (410  )



                4.59.2         Method  overview

                __Page______Method______________________Description________________________________________________________________*
 *___________
                  381       Clear                       Zeroes the position, capacity and size of the stream.
                  381       Destroy                     Frees any allocated memory and destroys the memory stream.
                  382       LoadFromFile                Loads the contents of a file into memory.
                  381       LoadFromStream              Loads the contents of a stream into memory.
                  382       SetSize                     Sets the size for the memory stream.
                __383_______Write_______________________Writes_data_to_the_stream's_memory.________________________________________*
 *___________



                4.59.3         TMemoryStream.Destroy

    Synopsis:    Frees any allocated memory and destroys the memory stream.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy clears the memory stream, thus in effect freeing any memory allocated for it, and
                then frees the memory stream.



                4.59.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 (420  ), TStream.Position (420  ), TCustomMemoryStream.Memory (346  )



                4.59.5         TMemoryStream.LoadFromStream

    Synopsis:    Loads the contents of a stream into memory.



                                                                                 381

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (420  ) 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 (414  ) 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 (269  ) may occur.

    See also:    TStream.CopyFrom (414  ), TMemoryStream.LoadFromFile (382  )



                4.59.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
                (381  ) method.

    See also:    TMemoryStream.LoadFromStream (381  )



                4.59.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 (420  ), TStream.Size (420  )



                                                                                 382

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.59.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 (412  ) method.

       Errors:   If no more memory could be allocated, then an exception will be raised.

    See also:    TCustomMemoryStream.Read (345  )



                4.60          TOwnedCollection



                4.60.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.


    See also:    TCollection (322  )



                4.60.2         Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                __383_______Create_________Create_a_new_TOwnerCollection_instance._________________________________________________*
 *___________



                4.60.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  (324  )  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 (326  ) and Add (324  ) methods.

    See also:    TCollection.Create (323  ), TCollection.Owner (324  )



                4.61          TOwnerStream



                4.61.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 (385  ) property is set to True).



                                                                                 383

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    See also:    TStream (410  ), TOwnerStream.Source (384  ), TOwnerStream.SourceOwner (385  )



                4.61.2         Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  384       Create         Create a new instance of  TOwnerStream.
                __384_______Destroy________Destroys_the_TOwnerStream_instance_and_the_source_stream._______________________________*
 *___________



                4.61.3         Property  overview

                __Page______Properties____________Access_______Description_________________________________________________________*
 *___________
                  384       Source                r            Reference to the source stream.
                __385_______SourceOwner___________rw___________Indicates_whether_the_ownerstream_owns_it's_source__________________*
 *___________



                4.61.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 (384  ), TOwnerStream.Source (384  ), TOwnerStream.SourceOwner
                (385  )



                4.61.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.

    See also:    TOwnerStream.Create  (384  ),  TOwnerStream.Source  (384  ),  TOwnerStream.SourceOwner
                (385  )



                4.61.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 used by descendent streams to access the source
                stream to read from or write to.

                Do not free the Source reference directly if  SourceOwner is True.  In that case the owner
                stream instance will free the source stream itself.

    See also:    TOwnerStream.Create (384  )



                                                                                 384

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.61.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 (384  ), TOwnerStream.Destroy (384  )



                4.62          TParser



                4.62.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 (391  )
                property.  Various methods are provided to obtain the token value in the desired format.

                To advance to the next token, invoke NextToken (388  ) method.


    See also:    TParser.Token (391  ), TParser.NextToken (388  )



                4.62.2         Method  overview

                __Page______Method______________________________Description________________________________________________________*
 *___________
                  386       CheckToken                          Checks whether the token if of the given type.
                  386       CheckTokenSymbol                    Checks whether the token equals the given symbol
                  386       Create                              Creates a new parser instance.
                  386       Destroy                             Destroys the parser instance.
                  387       Error                               Raises an EParserError (269  ) exception with the given
                                                                message
                  387       ErrorFmt                            Raises an EParserError (269  ) exception and formats the
                                                                message.
                  387       ErrorStr                            Raises an EParserError (269  ) exception with the given
                                                                message
                  387       HexToBinary                         Writes hexadecimal data to a stream.
                  388       NextToken                           Reads the next token and returns its type.
                  388       SourcePos                           Returns the current position in the stream.
                  388       TokenComponentIdent                 Returns the path of a subcomponent starting from the
                                                                current token.
                  389       TokenFloat                          Returns the current token as a float.
                  389       TokenInt                            Returns the current token as an integer.
                  389       TokenString                         Returns the current token as a string.
                  390       TokenSymbolIs                       Returns True if the token equals the given symbol.
                __390_______TokenWideString_____________________Returns_the_current_token_as_a_widestring__________________________*
 *___________



                                                                                 385

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.62.3         Property  overview

                __Page______Properties_________Access_______Description____________________________________________________________*
 *___________
                  390       FloatType          r            The type of a float token.
                  391       SourceLine         r            Current source line number.
                __391_______Token______________r____________The_type_of_the_current_token._________________________________________*
 *___________



                4.62.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 (269  ) exception is raised.

    See also:    TParser.NextToken (388  ), TParser.Token (391  )



                4.62.5         TParser.Destroy

    Synopsis:    Destroys the parser instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the parser instance.

       Errors:   None.



                4.62.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 (269  ) exception is raised.

    See also:    TParser.Token (391  )



                4.62.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 (237  ), otherwise an EParserError (269  ) exception
                is raised.



                                                                                 386

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



       Errors:   If the comparison fails, or current token isn't a symbol, an EParserError (269  ) exception is
                raised.

    See also:    TParser.TokenSymbolIs (390  ), toSymbol (237  )



                4.62.8         TParser.Error

    Synopsis:    Raises an EParserError (269  ) exception with the given message

Declaration:     procedure  Error(const  Ident:  string)

    Visibility:   public

Description:     Raises an EParserError (269  ) exception with the given message



                4.62.9         TParser.ErrorFmt

    Synopsis:    Raises an EParserError (269  ) exception and formats the message.

Declaration:     procedure  ErrorFmt(const  Ident:  string;const  Args:  Array  of  const)

    Visibility:   public

Description:     Raises an EParserError (269  ) exception and formats the message.



                4.62.10          TParser.ErrorStr

    Synopsis:    Raises an EParserError (269  ) exception with the given message

Declaration:     procedure  ErrorStr(const  Message:  string)

    Visibility:   public

Description:     Raises an EParserError (269  ) exception with the given message



                4.62.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 (269  ) exception is raised.



                                                                                 387

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.62.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 (391  ) property.

                If the end of the stream is reached, toEOF (237  ) is returned.

                For details about token types, see TParser.Token (391  )

       Errors:   If an error occours while parsing the token, an EParserError (269  ) exception is raised.

    See also:    TParser.Token (391  )



                4.62.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 (391  )



                4.62.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 (237  ), 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 (389  ) or TokenWideString
                (390  ) 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 (391  ) isn't toSymbol (237  ), or no valid symbol is found after a dot, an EParserError
                (269  ) exception is raised.

    See also:    TParser.NextToken (388  ), TParser.Token (391  ), TParser.TokenString (389  ), TParser.TokenWideString
                (390  ), toSymbol (237  )



                                                                                 388

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.62.15          TParser.TokenFloat

    Synopsis:    Returns the current token as a float.

Declaration:     function  TokenFloat  :  Extended

    Visibility:   public

Description:     If current token type is toFloat (237  ), 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 (390  ) for further information.

 Remark:         In the input stream the decimal separator, if present, must be a dot (.).

       Errors:   If Token (391  ) isn't toFloat (237  ), an EParserError (269  ) exception is raised.

    See also:    TParser.FloatType (390  ), TParser.NextToken (388  ), TParser.Token (391  ), toFloat (237  )



                4.62.16          TParser.TokenInt

    Synopsis:    Returns the current token as an integer.

Declaration:     function  TokenInt  :  Int64

    Visibility:   public

Description:     If current token type is toInteger (237  ), 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 (391  ) isn't toInteger (237  ), an EConvertError (235  ) exception is raised.

    See also:    TParser.NextToken (388  ), TParser.Token (391  ), toInteger (237  )



                4.62.17          TParser.TokenString

    Synopsis:    Returns the current token as a string.

Declaration:     function  TokenString  :  string

    Visibility:   public

Description:     If current token type is toString (237  ) or toWString (237  ), 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 (391  ).

 Remark:         If Token (391  ) is toWString (237  ), TokenWideString (390  ) should be used instead.

       Errors:   None.

    See also:    TParser.NextToken (388  ), TParser.TokenWideString (390  ), TParser.Token (391  ), toString
                (237  ), toWString (237  )



                                                                                 389

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.62.18          TParser.TokenWideString

    Synopsis:    Returns the current token as a widestring

Declaration:     function  TokenWideString  :  WideString

    Visibility:   public

Description:     If  current  token  type  is  toWString  (237  ),  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
                (389  ).

       Errors:   None.

    See also:    TParser.NextToken (388  ), TokenString (389  ), TParser.Token (391  ), toWString (237  )



                4.62.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 (237  ), or comparison fails, False is returned.

       Errors:   None.

    See also:    TParser.CheckTokenSymbol (386  ), TParser.Token (391  )



                4.62.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 4.23:

                                                            s or S      Value is a single.
                                                            c or C      Value is a currency.
                                                            d or D      Value is a date.



                If Token (391  ) isn't toFloat (237  ) or one of the above characters wasn't specified, FloatType
                is the null character (zero).

    See also:    TParser.NextToken (388  ), TParser.Token (391  ), TParser.TokenFloat (389  ), toFloat (237  )



                                                                                 390

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.62.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 (388  )



                4.62.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:



                                                                       Table 4.24:



                  toEOF (237  )              Value returned by TParser.Token (391  ) when the end of the input stream was reached.
                  toSymbol (237  )           Value returned by TParser.Token (391  ) when a symbol was found in the input stream.
                  toString (237  )           Value returned by TParser.Token (391  ) when a string was found in the input stream.
                  toInteger (237  )          Value returned by TParser.Token (391  ) when an integer was found in the input stream.
                  toFloat (237  )            Value returned by TParser.Token (391  ) when a floating point value was found in the i*
 *nput stream.
                  toWString (237  )          Value returned by TParser.Token (391  ) when a widestring was found in the input strea*
 *m.



                To advance to the next token, use NextToken (388  ) method.

    See also:    TParser.CheckToken (386  ), TParser.NextToken (388  ), TParser.TokenComponentIdent (388  ),
                TParser.TokenFloat (389  ), TParser.TokenInt (389  ), TParser.TokenString (389  ), TParser.TokenWideString
                (390  )



                4.63          TPersistent



                4.63.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.



                                                                                 391

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                TPersistent  implements  the  IFPObserved  (272  )  interface  for  the  benefit  of  descendent
                classes,  but  does  not  call  IFPObserved.FPONotifyObservers  (273  ).   Descendents  such  as
                TStrings (430  ) and TCollection (322  ) and TCollectionItem (330  ) do use it.


    See also:    TComponent (333  ), IFPObserved (272  ), TStrings (430  ), TCollection (322  ), TCollectionItem
                (330  )



                4.63.2         Interfaces  overview

                __Page______Interfaces____________Description______________________________________________________________________*
 *___________
                __272_______IFPObserved___________Interface_implemented_by_an_object_that_can_be_observed._________________________*
 *___________



                4.63.3         Method  overview

                __Page______Method___________________________Description___________________________________________________________*
 *___________
                  392       Assign                           Assign the contents of one class to another.
                  392       Destroy                          Destroys the TPersistent instance.
                  393       FPOAttachObserver                Add an observer to the list of observers.
                  393       FPODetachObserver                Remove an observer from the list of observers
                  393       FPONotifyObservers               Notify observers of changes.
                  394       GetNamePath                      Returns  a  string  that  can  be  used  to  identify  the  class
                _____________________________________________instance._____________________________________________________________*
 *___________



                4.63.4         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.



                4.63.5         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  (391  )
                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


                Destination:=Source;



                                                                                 392

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                (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:    AssignTo (391  )



                4.63.6         TPersistent.FPOAttachObserver

    Synopsis:    Add an observer to the list of observers.

Declaration:     procedure  FPOAttachObserver(AObserver:  TObject)

    Visibility:   public

Description:     FPOAttachObserver  is  part  of  the  implementation  of  the  IFPObserved  (272  )  interface  in
                TPersistent.  It adds a new observer to the list of observers.  Calling this multiple times
                will add the observed object multiple times to the list.

       Errors:   An  EObserver  exception  may  be  raised  if  AObject  does  not  implement  the  IFPObserver
                (273  ) interface.

    See also:    IFPObserver (273  ), IFPObserved.FPOAttachObserver (272  ), IFPObserved (272  )



                4.63.7         TPersistent.FPODetachObserver

    Synopsis:    Remove an observer from the list of observers

Declaration:     procedure  FPODetachObserver(AObserver:  TObject)

    Visibility:   public

Description:     FPODetachObserver  is  part  of  the  implementation  of  the  IFPObserved  (272  )  interface  in
                TPersistent.  It removes the first found instance of the observer from the list of observers.

    See also:    IFPObserved (272  ), IFPObserved.FPODetachObserver (272  ), IFPObserver (273  )



                4.63.8         TPersistent.FPONotifyObservers

    Synopsis:    Notify observers of changes.

Declaration:     procedure  FPONotifyObservers(ASender:  TObject;
                                                              AOperation:  TFPObservedOperation;
                                                              Data:  Pointer)

    Visibility:   public

Description:     FPONotifyObservers can be called to notify observers of changes in the object.  This method
                simply passes on the parameters that it receives to all attached IFPObserver (273  ) interfaces.

                TPersistent does not call FPONotifyObservers.  It is implemented for the benefit of de-
                scendant classes.

    See also:    IFPObserved (272  ), IFPObserved.FPONotifyObservers (273  ), IFPObserver (273  )



                                                                                 393

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.63.9         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 (391  )



                4.64          TProxyStream



                4.64.1         Description

                TProxyStream is a proxy class for the #rtl.types.IStream (1680   ) interface.  It implements all
                stream methods by relaying them to the IStream interface.


    See also:    #rtl.types.IStream (1680   ), TStreamAdapter (420  )



                4.64.2         Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  395       Check          Check errors
                  394       Create         Create a new instance of the TProxyStream class.
                  394       Read
                  395       Seek
                __395_______Write__________________________________________________________________________________________________*
 *___________



                4.64.3         TProxyStream.Create

    Synopsis:    Create a new instance of the TProxyStream class.

Declaration:     constructor  Create(const  Stream:  IStream)

    Visibility:   public

Description:     Create initializes a new instance of the TProxyStream class.  It saves var stream for use in
                the other methods.

    See also:    #rtl.types.IStream (1680   )



                4.64.4         TProxyStream.Read

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public



                                                                                 394

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.64.5         TProxyStream.Write

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public



                4.64.6         TProxyStream.Seek

Declaration:     function  Seek(const  Offset:  Int64;Origin:  TSeekOrigin)  :  Int64
                                      ;    Override

    Visibility:   public



                4.64.7         TProxyStream.Check

    Synopsis:    Check errors

Declaration:     procedure  Check(err:  Integer);    Virtual

    Visibility:   public

Description:     Check will check the result of the IStream interface.  This method must be overridden by
                descendent classes to return interface-specific errors.

    See also:    #rtl.types.IStream (1680   )



                4.65          TReader



                4.65.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 (283  ) to do the actual reading of data.  The interface of the TReader class
                should be identical to the interface in Delphi.

                Note that the TReader design is such that it can read a single component from a stream.  It
                will read all children of this component, but it is not designed to read multiple components
                in succession from one stream.

                It  should  never  be  necessary  to  create  an  instance  of  this  class  directly.    Instead,  the
                TStream.ReadComponent (414  ) call should be used.


    See also:    TFiler (350  ), TWriter (462  ), TAbstractObjectReader (283  )



                                                                                 395

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



4.65.2         Method  overview

__Page______Method____________________________Description_____________________________________________________________________
  397       BeginReferences                   Initializes the component referencing mechanism.
  398       CheckValue                        Raises an exception if the next value in the stream is not
                                              of type Value
  404       CopyValue                         Copy a value to a writer.
  397       Create                            Creates a new reader class
  398       DefineBinaryProperty              Reads a user-defined binary property from the stream.
  398       DefineProperty                    Reads a user-defined property from the stream.
  397       Destroy                           Destroys a reader class.
  398       EndOfList                         Returns true if the stream contains an end-of-list marker.
  398       EndReferences                     Finalizes the component referencing mechanism.
  399       FixupReferences                   Tries to resolve all unresolved component references.
  399       NextValue                         Returns the type of the next value.
  399       Read                              Read raw data from stream
  399       ReadBoolean                       Reads a boolean from the stream.
  399       ReadChar                          Reads a character from the stream.
  400       ReadCollection                    Reads a collection from the stream.
  400       ReadComponent                     Starts reading a component from the stream.
  400       ReadComponents                    Starts reading child components from the stream.
  401       ReadCurrency                      Read a currency value from the stream.
  401       ReadDate                          Reads a date from the stream
  401       ReadFloat                         Reads a float from the stream.
  401       ReadIdent                         Reads an identifier from the stream.
  402       ReadInt64                         Reads a 64-bit integer from the stream.
  402       ReadInteger                       Reads an integer from the stream
  402       ReadListBegin                     Checks for the beginning of a list.
  402       ReadListEnd                       Checks for the end of a list.
  403       ReadRootComponent                 Starts reading a root component.
  402       ReadSet                           Read a set value from the stream
  403       ReadSignature
  401       ReadSingle                        Reads a single-type real from the stream.
  403       ReadString                        Reads a string from the stream.
  400       ReadUnicodeChar                   Read unicode character
  404       ReadUnicodeString                 Read a UnicodeString value from the stream
  404       ReadValue                         Reads the next value type from the stream.
  403       ReadVariant                       Read a variant from the stream
  400       ReadWideChar                      Read widechar from the stream
__403_______ReadWideString____________________Read_a_WideString_value_from_the_stream.________________________________________



                                                                 396

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.3         Property  overview

                __Page______Properties____________________________Access_______Description_________________________________________*
 *___________
                  404       Driver                                r            The driver in use for streaming the data.
                  406       OnAncestorNotFound                    rw           Handler called when the ancestor component
                                                                               cannot be found.
                  406       OnCreateComponent                     rw           Handler  called  when  a  component  needs  to
                                                                               be created.
                  405       OnError                               rw           Handler called when an error occurs.
                  407       OnFindComponentClass                  rw           Handler called when a component class refer-
                                                                               ence needs to be found.
                  405       OnFindMethod                          rw           Handler to find or change a method address.
                  405       OnPropertyNotFound                    rw           Handler for treating missing properties.
                  407       OnReadStringProperty                  rw           Handler  for  translating  strings  when  read
                                                                               from the stream.
                  406       OnReferenceName                       rw           Handler  called  when  another  component  is
                                                                               referenced.
                  406       OnSetMethodProperty                   rw           Handler for setting method properties.
                  406       OnSetName                             rw           Handler  called  when  setting  a  component
                                                                               name.
                  404       Owner                                 rw           Owner of the component being read
                __405_______Parent________________________________rw___________Parent_of_the_component_being_read._________________*
 *___________



                4.65.4         TReader.Create

    Synopsis:    Creates a new reader class

Declaration:     constructor  Create(Stream:  TStream;BufSize:  Integer)

    Visibility:   public

Description:     Creates a new reader class



                4.65.5         TReader.Destroy

    Synopsis:    Destroys a reader class.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys a reader class.



                4.65.6         TReader.BeginReferences

    Synopsis:    Initializes the component referencing mechanism.

Declaration:     procedure  BeginReferences

    Visibility:   public

Description:     When streaming components, the streaming mechanism keeps a list of existing components
                that can be referenced to.  This method initializes up that system.



                                                                                 397

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.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



                4.65.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.



                4.65.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.



                4.65.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.



                4.65.11          TReader.EndReferences

    Synopsis:    Finalizes the component referencing mechanism.

Declaration:     procedure  EndReferences

    Visibility:   public

Description:     When streaming components, the streaming mechanism keeps a list of existing components
                that can be referenced to.  This method cleans up that system.



                                                                                 398

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.12          TReader.FixupReferences

    Synopsis:    Tries to resolve all unresolved component references.

Declaration:     procedure  FixupReferences

    Visibility:   public

Description:     Tries to resolve all unresolved component references.



                4.65.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.



                4.65.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 (285  ), TBinaryObjectReader.Read (306  )



                4.65.15          TReader.ReadBoolean

    Synopsis:    Reads a boolean from the stream.

Declaration:     function  ReadBoolean  :  Boolean

    Visibility:   public

Description:     Reads a boolean from the stream.



                4.65.16          TReader.ReadChar

    Synopsis:    Reads a character from the stream.

Declaration:     function  ReadChar  :  Char

    Visibility:   public

Description:     Reads a character from the stream.



                                                                                 399

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.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 (403  ), TWriter.WriteWideChar (465  )



                4.65.18          TReader.ReadUnicodeChar

    Synopsis:    Read unicode character

Declaration:     function  ReadUnicodeChar  :  UnicodeChar

    Visibility:   public

Description:     ReadUnicodeChar reads a single unicode character from the stream.  It does this by reading
                a UnicodeString string from the stream and returning the first character.

       Errors:   If the string has a length different from 1, an EReadError exception will occur.

    See also:    TReader.ReadUnicodeString (404  )



                4.65.19          TReader.ReadCollection

    Synopsis:    Reads a collection from the stream.

Declaration:     procedure  ReadCollection(Collection:  TCollection)

    Visibility:   public

Description:     Reads a collection from the stream.



                4.65.20          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.



                4.65.21          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.



                                                                                 400

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.22          TReader.ReadFloat

    Synopsis:    Reads a float from the stream.

Declaration:     function  ReadFloat  :  Extended

    Visibility:   public

Description:     Reads a float from the stream.



                4.65.23          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.



                4.65.24          TReader.ReadDate

    Synopsis:    Reads a date from the stream

Declaration:     function  ReadDate  :  TDateTime

    Visibility:   public

Description:     Reads a date from the stream



                4.65.25          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 (466  )



                4.65.26          TReader.ReadIdent

    Synopsis:    Reads an identifier from the stream.

Declaration:     function  ReadIdent  :  string

    Visibility:   public

Description:     Reads an identifier from the stream.



                                                                                 401

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.27          TReader.ReadInteger

    Synopsis:    Reads an integer from the stream

Declaration:     function  ReadInteger  :  LongInt

    Visibility:   public

Description:     Reads an integer from the stream



                4.65.28          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.



                4.65.29          TReader.ReadSet

    Synopsis:    Read a set value from the stream

Declaration:     function  ReadSet(EnumType:  Pointer)  :  Integer

    Visibility:   public

Description:     ReadSet reads a set of elements with type EnumType and returns them as an integer where
                each element is encoded in a bit of the integer.  Thus, at most an enumerated type with 32
                elements can be read with this function.

       Errors:   No checking is performed on the validity of EnumType.  It is assumed to be a valid PTypeInfo
                pointer.

    See also:    TWriter.WriteSet (467  )



                4.65.30          TReader.ReadListBegin

    Synopsis:    Checks for the beginning of a list.

Declaration:     procedure  ReadListBegin

    Visibility:   public

Description:     Checks for the beginning of a list.



                4.65.31          TReader.ReadListEnd

    Synopsis:    Checks for the end of a list.

Declaration:     procedure  ReadListEnd

    Visibility:   public

Description:     Checks for the end of a list.



                                                                                 402

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.32          TReader.ReadRootComponent

    Synopsis:    Starts reading a root component.

Declaration:     function  ReadRootComponent(ARoot:  TComponent)  :  TComponent

    Visibility:   public

Description:     Starts reading a root component.



                4.65.33          TReader.ReadVariant

    Synopsis:    Read a variant from the stream

Declaration:     function  ReadVariant  :  Variant

    Visibility:   public

Description:     ReadVariant reads the next value from the stream and returns it as a variant.  No variant
                array can be read from the stream, only single values.

       Errors:   If no variant manager is installed, the function will raise an EReadError exception.  If the
                next value is not a simple value, again an EReadError exception is raised.  exception is

    See also:    TBinaryObjectWriter.WriteVariant (315  )



                4.65.34          TReader.ReadSignature

Declaration:     procedure  ReadSignature

    Visibility:   public



                4.65.35          TReader.ReadString

    Synopsis:    Reads a string from the stream.

Declaration:     function  ReadString  :  string

    Visibility:   public

Description:     Reads a string from the stream.



                4.65.36          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 (468  )



                                                                                 403

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.37          TReader.ReadUnicodeString

    Synopsis:    Read a UnicodeString value from the stream

Declaration:     function  ReadUnicodeString  :  UnicodeString

    Visibility:   public

Description:     ReadUnicodeString reads a UnicodeString string from the stream.  The stream can contain
                a string from any type, it will be converted to UniCodeString.

    See also:    TAbstractObjectReader.ReadUnicodeString (290  ), TWriter.WriteUnicodeString (468  )



                4.65.38          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.



                4.65.39          TReader.CopyValue

    Synopsis:    Copy a value to a writer.

Declaration:     procedure  CopyValue(Writer:  TWriter)

    Visibility:   public

Description:     CopyValue reads the next value from the reader stream, and writes it to the passed Writer.



                4.65.40          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.



                4.65.41          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



                                                                                 404

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.42          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.



                4.65.43          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.



                4.65.44          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 (246  ).

    See also:    TPropertyNotFoundEvent (246  ), TReader.OnSetMethodProperty (406  ), TReader.OnReadStringProperty
                (407  )



                4.65.45          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.



                                                                                 405

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.46          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 assigned when an object is
                being streamed in the designer.

    See also:    TReader.OnReadStringProperty (407  ), TReader.OnPropertyNotFound (405  )



                4.65.47          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.



                4.65.48          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.



                4.65.49          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.



                4.65.50          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.



                                                                                 406

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.65.51          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.



                4.65.52          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 (247  ) for a description of the various
                parameters.

    See also:    TReader.OnPropertyNotFound (405  ), TReader.OnSetMethodProperty (406  ), TReadWriteString-
                PropertyEvent (247  )



                4.66          TRecall



                4.66.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 immediately stores the properties of the reference object in the storage object.

                The  Store  (408  )  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 (409  ) can be called.


    See also:    TRecall.Create  (408  ),  TRecall.Destroy  (408  ),  TRecall.Forget  (409  ),  TRecall.Store  (408  ),
                TPersistent.Assign (392  )



                                                                                 407

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.66.2         Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  408       Create         Creates a new instance of  TRecall.
                  408       Destroy        Copies  the  stored  properties  to  the  reference  object  and  destroys  the
                                           TRecall instance.
                  409       Forget         Clear the reference property.
                __408_______Store__________Assigns_the_reference_instance_to_the_storage_instance._________________________________*
 *___________



                4.66.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __409_______Reference_________r____________The_reference_object.___________________________________________________*
 *___________



                4.66.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 (408  ) to assign the reference object properties to the storage instance.

    See also:    TRecall.Store (408  ), TRecall.Destroy (408  )



                4.66.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 (409  ) instance is still valid.  If the reference
                pointer was invalidated, call TRecall.Forget (409  ) to clear the reference instance.

    See also:    TRecall.Store (408  ), TRecall.Forget (409  )



                4.66.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  (409  )  instance  is  still  valid.  If  the  reference
                pointer was invalidated, call TRecall.Forget (409  ) to clear the reference instance.



                                                                                 408

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.66.7         TRecall.Forget

    Synopsis:    Clear the reference property.

Declaration:     procedure  Forget

    Visibility:   public

Description:     Forget sets the Reference (409  ) 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 (408  ) has no effect.

       Errors:   None.

    See also:    TRecall.Reference (409  ), TRecall.Store (408  ), TRecall.Destroy (408  )



                4.66.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 (409  ) to clear the reference and then free the reference object.

    See also:    TRecall.Forget (409  )



                4.67          TResourceStream



                4.67.1         Description

                Stream that reads its data from a resource object.



                4.67.2         Method  overview

                __Page______Method__________________Description____________________________________________________________________*
 *___________
                  409       Create                  Creates a new instance of a resource stream.
                  410       CreateFromID            Creates a new instance of a resource stream with a resource
                __410_______Destroy_________________Destroys_the_instance_of_the_resource_stream.__________________________________*
 *___________



                4.67.3         TResourceStream.Create

    Synopsis:    Creates a new instance of a resource stream.

Declaration:     constructor  Create(Instance:  TFPResourceHMODULE;const  ResName:  string;
                                              ResType:  PChar)

    Visibility:   public

Description:     Creates a new instance of a resource stream.



                                                                                 409

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.67.4         TResourceStream.CreateFromID

    Synopsis:    Creates a new instance of a resource stream with a resource

Declaration:     constructor  CreateFromID(Instance:  TFPResourceHMODULE;ResID:  Integer;
                                                        ResType:  PChar)

    Visibility:   public

Description:     The resource is loaded from the loaded module (identified by the handle Instance), identifier
                ResID and type ResType.



                4.67.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.



                4.68          TStream



                4.68.1         Description

                TStream  is  the  base  class  for  all  streaming  classes.   It  defines  methods  for  reading  (411  ),
                writing (412  ) 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 (381  ) or TFileStream (352  ) then override these
                methods to write streams to memory or file.


    See also:    TMemoryStream (381  ), TFileStream (352  ), TStringStream (448  )



                                                                                 410

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.68.2         Method  overview

                __Page______Method____________________________Description__________________________________________________________*
 *___________
                  414       CopyFrom                          Copy data from one stream to another
                  416       FixupResourceHeader               Not implemented in FPC
                  411       Read                              Reads data from the stream to a buffer and returns the
                                                              number of bytes read.
                  418       ReadAnsiString                    Read an ansistring from the stream and return its value.
                  413       ReadBuffer                        Reads data from the stream to a buffer
                  417       ReadByte                          Read a byte from the stream and return its value.
                  414       ReadComponent                     Reads component data from a stream
                  414       ReadComponentRes                  Reads component data and resource header from a stream
                  417       ReadDWord                         Read a DWord from the stream and return its value.
                  417       ReadQWord                         Read a QWord value from the stream and return its value
                  416       ReadResHeader                     Read a resource header from the stream.
                  417       ReadWord                          Read a word from the stream and return its value.
                  412       Seek                              Sets the current position in the stream
                  412       Write                             Writes data from a buffer to the stream and returns the
                                                              number of bytes written.
                  419       WriteAnsiString                   Write an ansistring to the stream.
                  413       WriteBuffer                       Writes data from a buffer to the stream
                  418       WriteByte                         Write a byte to the stream.
                  415       WriteComponent                    Write component data to the stream
                  415       WriteComponentRes                 Write resource header and component data to a stream
                  415       WriteDescendent                   Write component data to a stream, relative to an ancestor
                  415       WriteDescendentRes                Write resource header and component data to a stream,
                                                              relative to an ancestor
                  419       WriteDWord                        Write a DWord to the stream.
                  419       WriteQWord                        Write a QWord value to the stream
                  416       WriteResourceHeader               Write resource header to the stream
                __418_______WriteWord_________________________Write_a_word_to_the_stream.__________________________________________*
 *___________



                4.68.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  420       Position          rw           The current position in the stream.
                __420_______Size______________rw___________The_current_size_of_the_stream._________________________________________*
 *___________



                4.68.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 (413  ) instead.

                As implemented in TStream, Read does nothing but raises an EStreamError (269  ) exception
                to indicate that reading is not supported.  Descendent classes that allow reading must override
                this method to do the actual reading.



                                                                                 411

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                Descendent classes should (if they don't explicitly raise an exception) return a positive value
                (>=0), where zero indicates an error.

       Errors:   In case a descendent class does not allow reading from the stream, an exception is raised.

    See also:    TStream.Write (412  ), TStream.ReadBuffer (413  )



                4.68.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 (413  )
                instead.

                As implemented in TStream, Write does nothing but raises EStreamError (269  ) exception to
                indicate that writing is not supported.  Descendent classes that allow writing must override
                this method to do the actual writing.

                Descendent classes should (if they don't explicitly raise an exception) return a positive value
                (>=0), where zero indicates an error.

       Errors:   In case a descendent class does not allow writing to the stream, an exception is raised.

    See also:    TStream.Read (411  ), TStream.WriteBuffer (413  )



                4.68.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.  There is a 32-bit variant
                of this function and a 64-bit variant.  The difference can be made by choosing the correct
                Offset parameter:  the integer-typed parameter selects the 32-bit variant, the parameter of
                type TSeekOrigin (247  ) selects the 64-bit variant of the function.

                The Origin parameter for the 32-bit version can have one of the following values:



                                                                       Table 4.25:

                       Constant                   Meaning
                       soFromBeginning            Set the position relative to the start of the stream.
                       soFromCurrent              Set the position relative to the current position in the stream.
                       soFromEnd                  Set the position relative to the end of the stream.



                                                                                 412

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                These values are defined in the SysUtils (235  ) unit.

                The Origin parameter for the 64-bit version has one of the following values:



                                                                       Table 4.26:

                       Value                Meaning
                       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.



                Offset should be negative when the origin is SoFromEnd (soEnd).  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.

 Remark:        Internally, all calls are re-routed to the 64-bit version of the call.  When creating a descendent
                of  TStream, the 64-bit version of the call should be overridden.

       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 (or soBeginning).

    See also:    TStream.Position (420  )



                4.68.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
                (411  ) 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 (411  ), TStream.WriteBuffer (413  )



                4.68.8         TStream.WriteBuffer

    Synopsis:    Writes data from a buffer to the stream

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 write a fixed number of bytes, such as when writing structures
                or  the  content  of  variables.  If  the  number  of  bytes  is  not  determined,  use  TStream.Write
                (412  ) instead.  WriteBuffer uses Write internally to do the actual writing.



                                                                                 413

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



       Errors:   If the stream does not allow to write Count bytes, then an exception is raised.

    See also:    TStream.Write (412  ), TStream.ReadBuffer (413  )



                4.68.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.  If  Count is zero, then the whole contents of the Source stream is
                copied.  It is positioned on the first byte of data, and Size bytes are copied.  Note that this
                cannot be used with streams that do not allow seeking or do not allow determining the size
                of the stream.

                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 (411  ), TStream.Write (412  )



                4.68.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  (395  )  object  and  calls  its  ReadRootComponent
                (403  ) method.

       Errors:   If an error occurs during the reading of the component, an EFilerError (267  ) exception is
                raised.

    See also:    TStream.WriteComponent (415  ), TStream.ReadComponentRes (414  ), TReader.ReadRootComponent
                (403  )



                4.68.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
                (414  ) 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.



                                                                                 414

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



       Errors:   If an error occurs during the reading of the component, an EFilerError (267  ) exception is
                raised.

    See also:    TStream.ReadComponent (414  ), TStream.WriteComponentRes (415  )



                4.68.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 (414  ).  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 (415  ) with Nil ancestor.

    See also:    TStream.ReadComponent (414  ), TStream.WriteComponentRes (415  )



                4.68.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 (415  ) 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 (415  ), TStream.ReadComponentRes (414  )



                4.68.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 (462  ) object and calls its WriteDescendent (465  ) object.
                The writer is passed a binary driver object (310  ) by default.



                4.68.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



                                                                                 415

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     WriteDescendentRes  writes  a  ResName  resource  header,  and  then  calls  WriteDescendent
                (415  ) 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.



                4.68.16          TStream.WriteResourceHeader

    Synopsis:    Write resource header to the stream

Declaration:     procedure  WriteResourceHeader(const  ResName:  string;
                                                                var  FixupInfo:  LongInt)

    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
                (416  ).

                WriteResourceHeader should not be used directly.  It is called by the TStream.WriteComponentRes
                (415  ) and TStream.WriteDescendentRes (415  ) methods.

    See also:    TStream.FixupResourceHeader (416  ), TStream.WriteComponentRes (415  ), TStream.WriteDescendentRes
                (415  )



                4.68.17          TStream.FixupResourceHeader

    Synopsis:    Not implemented in FPC

Declaration:     procedure  FixupResourceHeader(FixupInfo:  LongInt)

    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 (416  ), TStream.WriteComponentRes (415  ), TStream.WriteDescendentRes
                (415  )



                4.68.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 (268  ) exception is raised.

    See also:    TStream.ReadComponentRes (414  ), EInvalidImage (268  )



                                                                                 416

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.68.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 (269  ) exception will be raised.  This is a utility
                function which symply calls the Read (411  ) function.

    See also:    TStream.Read (411  ), TStream.WriteByte (418  ), TStream.ReadWord (417  ), TStream.ReadDWord
                (417  ), TStream.ReadAnsiString (418  )



                4.68.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 (411  ) function.

       Errors:   If the word cannot be read, a EStreamError (269  ) exception will be raised.

    See also:    TStream.Read (411  ), TStream.WriteWord (418  ), TStream.ReadByte (417  ), TStream.ReadDWord
                (417  ), TStream.ReadAnsiString (418  )



                4.68.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 (411  ) function.

       Errors:   If the DWord cannot be read, a EStreamError (269  ) exception will be raised.

    See also:    TStream.Read (411  ), TStream.WriteDWord (419  ), TStream.ReadByte (417  ), TStream.ReadWord
                (417  ), TStream.ReadAnsiString (418  )



                4.68.22          TStream.ReadQWord

    Synopsis:    Read a QWord value from the stream and return its value

Declaration:     function  ReadQWord  :  QWord

    Visibility:   public

Description:     ReadQWord reads a QWord value (8 bytes) from the stream and returns it's value.

       Errors:   If not enough bytes are available on the stream, an EStreamError (269  ) exception will be
                raised.

    See also:    TStream.Read (411  ), TStream.WriteByte (418  ), TStream.ReadWord (417  ), TStream.ReadDWord
                (417  ), TStream.ReadAnsiString (418  )



                                                                                 417

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.68.23          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 (419  ) function writes an ansistring in such a format.

       Errors:   If the AnsiString cannot be read, a EStreamError (269  ) exception will be raised.

    See also:    TStream.Read (411  ), TStream.WriteAnsiString (419  ), TStream.ReadByte (417  ), TStream.ReadWord
                (417  ), TStream.ReadDWord (417  )



                4.68.24          TStream.WriteByte

    Synopsis:    Write a byte to the stream.

Declaration:     procedure  WriteByte(b:  Byte)

    Visibility:   public

Description:     WriteByte  writes  the  byte  B  to  the  stream.  This  is  a  utility  function  which  simply  calls
                the Write (412  ) function.  The byte can be read from the stream using the ReadByte (417  )
                function.

       Errors:   If an error occurs when attempting to write, an EStreamError (269  ) exception will be raised.

    See also:    TStream.Write (412  ), TStream.ReadByte (417  ), TStream.WriteWord (418  ), TStream.WriteDWord
                (419  ), TStream.WriteAnsiString (419  )



                4.68.25          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  (412  )  function.   The  word  can  be  read  from  the  stream  using  the
                ReadWord (417  ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (269  ) exception will be raised.

    See also:    TStream.Write (412  ), TStream.ReadWord (417  ), TStream.WriteByte (418  ), TStream.WriteDWord
                (419  ), TStream.WriteAnsiString (419  )



                                                                                 418

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.68.26          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 (412  ) function.  The DWord can be read from the stream using
                the ReadDWord (417  ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (269  ) exception will be raised.

    See also:    TStream.Write (412  ), TStream.ReadDWord (417  ), TStream.WriteByte (418  ), TStream.WriteWord
                (418  ), TStream.WriteAnsiString (419  )



                4.68.27          TStream.WriteQWord

    Synopsis:    Write a QWord value to the stream

Declaration:     procedure  WriteQWord(q:  QWord)

    Visibility:   public

Description:     WriteQWord writes the word W (i.e.  8 bytes) to the stream.  This is a utility function which
                simply  calls  the  Write  (412  )  function.   The  word  can  be  read  from  the  stream  using  the
                ReadQWord (417  ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (269  ) exception will be raised.

    See also:    TStream.Write (412  ), TStream.ReadByte (417  ), TStream.WriteWord (418  ), TStream.WriteDWord
                (419  ), TStream.WriteAnsiString (419  )



                4.68.28          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 (412  ) 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 (418  ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (269  ) exception will be raised.

    See also:    TStream.Write (412  ), TStream.ReadAnsiString (418  ), TStream.WriteByte (418  ), TStream.WriteWord
                (418  ), TStream.WriteDWord (419  )



                                                                                 419

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.68.29          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
                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 (269  ) exception if they do not support setting
                the stream position.

    See also:    TStream.Size (420  ), TStream.Seek (412  )



                4.68.30          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 (420  ), TStream.Seek (412  )



                4.69          TStreamAdapter



                4.69.1         Description

                Implements IStream for TStream (410  ) descendents



                4.69.2         Interfaces  overview

                __Page______Interfaces_______Description___________________________________________________________________________*
 *___________
                __1680______IStream__________COM_stream_abstraction________________________________________________________________*
 *___________



                                                                                 420

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.69.3         Method  overview

                __Page______Method_________________Description_____________________________________________________________________*
 *___________
                  424       Clone                  Clone the stream
                  423       Commit                 Commit data to the stream
                  423       CopyTo                 Copy data to destination stream
                  421       Create                 Create a new instance of  TStreamAdapter
                  421       Destroy                Free the TStreamAdapter instance
                  423       LockRegion             Lock a region of the stream
                  421       Read                   Read from the stream.
                  423       Revert                 Revert operations on the stream
                  422       Seek                   Set the stream position
                  422       SetSize                Set the stream size
                  424       Stat                   Return statistical data about the stream
                  424       UnlockRegion           Unlock a region of the stream
                __422_______Write__________________Write_to_the_stream_____________________________________________________________*
 *___________



                4.69.4         Property  overview

                __Page______Properties___________________Access_______Description__________________________________________________*
 *___________
                  424       Stream                       r            Stream on which adaptor works
                  425       StreamOwnership              rw           Determines what happens with the stream when the
                ______________________________________________________adaptor_is_freed_____________________________________________*
 *___________



                4.69.5         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
                (424  ) with Stream and initializes StreamOwnerShip (425  ) with Ownership.

                TStreamAdapter is an abstract class:  descendents must be created that implement the actual
                functionality.

    See also:    StreamOwnerShip (425  ), TStreamAdapter.Stream (424  )



                4.69.6         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.



                4.69.7         TStreamAdapter.Read

    Synopsis:    Read from the stream.

Declaration:     function  Read(pv:  Pointer;cb:  DWORD;pcbRead:  PDWord)  :  HRESULT;    Virtual



                                                                                 421

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    Visibility:  public

Description:     Read  implements  #rtl.types.ISequentialStream.Read  (1679   )  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:    #rtl.types.ISequentialStream.Read (1679   )



                4.69.8         TStreamAdapter.Write

    Synopsis:    Write to the stream

Declaration:     function  Write(pv:  Pointer;cb:  DWORD;pcbWritten:  PDWord)  :  HRESULT
                                       ;    Virtual

    Visibility:   public

Description:     Write implements #rtl.types.ISequentialStream.Write (1679   ) by writing to the stream spec-
                ified at creation.

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.ISequentialStream.Write (1679   )



                4.69.9         TStreamAdapter.Seek

    Synopsis:    Set the stream position

Declaration:     function  Seek(dlibMove:  Largeint;dwOrigin:  LongInt;
                                      out  libNewPosition:  Largeint)  :  HRESULT;    Virtual

    Visibility:   public

Description:     Seek implements #rtl.types.IStream.Seek (1680   ) by setting the position of the stream spec-
                ified at creation.

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.Seek (1680   )



                4.69.10          TStreamAdapter.SetSize

    Synopsis:    Set the stream size

Declaration:     function  SetSize(libNewSize:  Largeint)  :  HRESULT;    Virtual

    Visibility:   public

Description:     SetSize  implements  #rtl.types.IStream.Setsize  (1680   )  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:    #rtl.types.IStream.Setsize (1680   )



                                                                                 422

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.69.11          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 #rtl.types.IStream.CopyTo (1680   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.



                4.69.12          TStreamAdapter.Commit

    Synopsis:    Commit data to the stream

Declaration:     function  Commit(grfCommitFlags:  LongInt)  :  HRESULT;    Virtual

    Visibility:   public

Description:     Commit implements #rtl.types.IStream.Commit (1681   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.Commit (1681   )



                4.69.13          TStreamAdapter.Revert

    Synopsis:    Revert operations on the stream

Declaration:     function  Revert  :  HRESULT;    Virtual

    Visibility:   public

Description:     Revert implements #rtl.types.IStream.Revert (1681   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.Revert (1681   )



                4.69.14          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 #rtl.types.IStream.LockRegion (1681   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.LockRegion (1681   )



                                                                                 423

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.69.15          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 #rtl.types.IStream.UnLockRegion (1681   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.UnLockRegion (1681   )



                4.69.16          TStreamAdapter.Stat

    Synopsis:    Return statistical data about the stream

Declaration:     function  Stat(out  statstg:  TStatStg;grfStatFlag:  LongInt)  :  HRESULT
                                      ;    Virtual

    Visibility:   public

Description:     Stat implements #rtl.types.IStream.Stat (1682   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.Stat (1682   )



                4.69.17          TStreamAdapter.Clone

    Synopsis:    Clone the stream

Declaration:     function  Clone(out  stm:  IStream)  :  HRESULT;    Virtual

    Visibility:   public

Description:     Clone implements #rtl.types.IStream.Clone (1682   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.Clone (1682   )



                4.69.18          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.



                                                                                 424

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.69.19          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



                4.70          TStringList



                4.70.1         Description

                TStringList  is  a  descendent  class  of  TStrings  (430  )  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


    See also:    TStrings (430  ), TStringList.Duplicates (428  ), TStringList.Sorted (429  )



                4.70.2         Method  overview

                __Page______Method_______________Description_______________________________________________________________________*
 *___________
                  426       Add                  Implements the TStrings.Add (432  ) function.
                  426       Clear                Implements the TStrings.Clear (434  ) function.
                  428       CustomSort           Sort the stringlist using a custom sort algorithm
                  426       Delete               Implements the TStrings.Delete (435  ) function.
                  426       Destroy              Destroys the stringlist.
                  427       Exchange             Implements the TStrings.Exchange (436  ) function.
                  427       Find                 Locates the index for a given string in sorted lists.
                  427       IndexOf              Overrides the TStrings.IndexOf (436  ) property.
                  427       Insert               Overrides the TStrings.Insert (437  ) method.
                __428_______Sort_________________Sorts_the_strings_in_the_list.____________________________________________________*
 *___________



                4.70.3         Property  overview

                __Page______Properties_____________Access_______Description________________________________________________________*
 *___________
                  429       CaseSensitive          rw
                  428       Duplicates             rw           Describes the behaviour of a sorted list with respect to
                                                                duplicate strings.
                  429       OnChange               rw           Event triggered after the list was modified.
                  430       OnChanging             rw           Event triggered when the list is about to be modified.
                  430       OwnsObjects            rw           Determines  whether  the  stringlist  owns  it's  objects  or
                                                                not.
                __429_______Sorted_________________rw___________Determines_whether_the_list_is_sorted_or_not.______________________*
 *___________



                                                                                 425

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.70.4         TStringList.Destroy

    Synopsis:    Destroys the stringlist.

Declaration:     destructor  Destroy;    Override

    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.



                4.70.5         TStringList.Add

    Synopsis:    Implements the TStrings.Add (432  ) 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 (428  ) is dupError then an EStringListError (270  ) exception is
                raised.  If Duplicates is set to dupIgnore then the return value is the index of the previous
                entry.

                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
                (428  ) is dupError then an EStringListError (270  ) exception is raised.

    See also:    TStringList.Insert (427  ), TStringList.Duplicates (428  )



                4.70.6         TStringList.Clear

    Synopsis:    Implements the TStrings.Clear (434  ) function.

Declaration:     procedure  Clear;    Override

    Visibility:   public

Description:     Implements the TStrings.Clear (434  ) function.



                4.70.7         TStringList.Delete

    Synopsis:    Implements the TStrings.Delete (435  ) function.

Declaration:     procedure  Delete(Index:  Integer);    Override

    Visibility:   public

Description:     Implements the TStrings.Delete (435  ) function.



                                                                                 426

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.70.8         TStringList.Exchange

    Synopsis:    Implements the TStrings.Exchange (436  ) 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 (436  ).

 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 (429  ), TStrings.Exchange (436  )



                4.70.9         TStringList.Find

    Synopsis:    Locates the index for a given string in sorted lists.

Declaration:     function  Find(const  S:  string;out  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 (427  )
                       instead.

                     2.Find uses a binary search method to locate the string



                4.70.10          TStringList.IndexOf

    Synopsis:    Overrides the TStrings.IndexOf (436  ) property.

Declaration:     function  IndexOf(const  S:  string)  :  Integer;    Override

    Visibility:   public

Description:     IndexOf  overrides  the  ancestor  method  TStrings.indexOf  (436  ).   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 (436  ), TStringList.Find (427  )



                4.70.11          TStringList.Insert

    Synopsis:    Overrides the TStrings.Insert (437  ) 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 (270  ) exception will be raised instead.  Index is a zero-based position.



                                                                                 427

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



       Errors:   If Index contains an invalid value (less than zero or larger than Count, or the list is sorted,
                an EStringListError (270  ) exception will be raised.

    See also:    TStringList.Add (426  ), TStrings.Insert (437  ), TStrings.InsertObject (438  )



                4.70.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 (429  ) property set to True then nothing will be done.

    See also:    TStringList.Sorted (429  )



                4.70.13          TStringList.CustomSort

    Synopsis:    Sort the stringlist using a custom sort algorithm

Declaration:     procedure  CustomSort(CompareFn:  TStringListSortCompare);    Virtual

    Visibility:   public

Description:     CustomSort  sorts  the  stringlist  with  a  custom  comparison  function.  The  function  should
                compare 2 elements in the list, and return a negative number if the first item is before the
                second.  It should return 0 if the elements are equal, and a positive result indicates that the
                second elements should be before the first.

    See also:    TStringList.Sorted (429  ), TStringList.Sort (428  )



                4.70.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 4.27:



                  dupIgnore          Duplicate values will not 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 (270  ) except*
 *ion is raised.
                  dupAccept          Duplicate values can be added to the list.



                If the stringlist is not sorted, the Duplicates setting is ignored.



                                                                                 428

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.70.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  (427  )  cannot  be  used.    For  sorted  lists,
                       TStringList.Add (426  ) should be used instead.

                     2.If  Sorted is True, the TStringList.Duplicates (428  ) setting has effect.  This setting is
                       ignored when Sorted is False.

    See also:    TStringList.Sort (428  ), TStringList.Duplicates (428  ), TStringList.Add (426  ), TstringList.Insert
                (427  )



                4.70.16          TStringList.CaseSensitive

    Synopsis:

Declaration:     Property  CaseSensitive  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Indicates whether locating strings happens in a case sensitive manner.



                4.70.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 (430  ) event occurs.

    See also:    TStringList.OnChanging (430  )



                                                                                 429

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.70.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 (429  ) event occurs.

    See also:    TStringList.OnChange (429  )



                4.70.19          TStringList.OwnsObjects

    Synopsis:    Determines whether the stringlist owns it's objects or not.

Declaration:     Property  OwnsObjects  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     OwnsObjects can be set to true to let the stringlist instance own the objects in the list:  if
                an element is removed from the list, the associated object (if there is any) will be freed as
                well.  The same is true if the list is cleared or destroyed.

    See also:    TStrings.Objects (445  )



                4.71          TStrings



                4.71.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.

                An instance of TStrings is never created directly, instead a descendent class such as TStringList
                (425  ) 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 (425  ).

                TStrings  implements  the  IFPObserved  (272  )  interface:  when  the  stringlist  is  changed,  a
                ooChanged notification is sent to all observers.


    See also:    TStringList (425  ), IFPObserved (272  )



                                                                                 430

__________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



4.71.2         Method  overview

__Page______Method______________________Description___________________________________________________________________________
  432       Add                         Add a string to the list
  433       AddObject                   Add a string and associated object to the list.
  433       AddStrings                  Add contents of another stringlist to this list.
  433       AddText                     Add text to the string list.
  433       Append                      Add a string to the list.
  434       Assign                      Assign the contents of another stringlist to this one.
  434       BeginUpdate                 Mark the beginning of an update batch.
  434       Clear                       Removes all strings and associated objects from the list.
  435       Delete                      Delete a string from the list.
  432       Destroy                     Frees all strings and objects, and removes the list from mem-
                                        ory.
  435       EndUpdate                   Mark the end of an update batch.
  435       Equals                      Compares the contents of two stringlists.
  436       Exchange                    Exchanges two strings in the list.
  440       ExtractName                 Extract the name part of a string
  436       GetEnumerator               Create an IEnumerator instance
  440       GetNameValue                Return  both  name  and  value  of  a  name,value  pair  based  on
                                        it's index.
  436       GetText                     Returns the contents as a PChar
  436       IndexOf                     Find a string in the list and return its position.
  437       IndexOfName                 Finds the index of a name in the name-value pairs.
  437       IndexOfObject               Finds an object in the list and returns its index.
  437       Insert                      Insert a string in the list.
  438       InsertObject                Insert a string and associated object in the list.
  438       LoadFromFile                Load the contents of a file as a series of strings.
  438       LoadFromStream              Load the contents of a stream as a series of strings.
  438       Move                        Move a string from one place in the list to another.
  439       SaveToFile                  Save the contents of the list to a file.
  439       SaveToStream                Save the contents of the string to a stream.
__440_______SetText_____________________Set_the_contents_of_the_list_from_a_PChar.____________________________________________



                                                                 431

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.3         Property  overview

                __Page______Properties_______________________Access_______Description______________________________________________*
 *___________
                  443       Capacity                         rw           Capacity of the list, i.e.  number of strings that
                                                                          the list can currently hold before it tries to ex-
                                                                          pand.
                  443       CommaText                        rw           Contents of the list as a comma-separated string.
                  444       Count                            r            Number of strings in the list.
                  441       DelimitedText                    rw           Get  or  set  all  strings  in  the  list  in  a  delimit*
 *ed
                                                                          form.
                  441       Delimiter                        rw           Delimiter character used in DelimitedText (441  ).
                  441       LineBreak                        rw
                  444       Names                            r            Name parts of the name-value pairs in the list.
                  442       NameValueSeparator               rw           Value   of   the   character   used   to   separate
                                                                          name,value pairs
                  445       Objects                          rw           Indexed access to the objects associated with the
                                                                          strings in the list.
                  442       QuoteChar                        rw           Quote character used in DelimitedText (441  ).
                  442       StrictDelimiter                  rw           Should  only  the  delimiter  character  be  consid-
                                                                          ered a delimiter
                  446       Strings                          rw           Indexed access to the strings in the list.
                  446       StringsAdapter                   rw           Not implemented in Free Pascal.
                  446       Text                             rw           Contents of the list as one big string.
                  440       TextLineBreakStyle               rw           Determines which line breaks to use in the Text
                                                                          (446  ) property
                  442       ValueFromIndex                   rw           Return  the  value  part  of  a  string  based  on  it's
                                                                          index.
                __445_______Values___________________________rw___________Value_parts_of_the_name-value_pairs_in_the_list._________*
 *___________



                4.71.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.



                4.71.5         TStrings.Add

    Synopsis:    Add a string to the list

Declaration:     function  Add(const  S:  string)  :  Integer;    Virtual;    Overload
                function  Add(const  Fmt:  string;const  Args:  Array  of  const)  :  Integer
                                    ;    Overload

    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 (444  )

    See also:    TStrings.Objects (445  ), TStrings.AddObject (433  ), TStrings.Insert (437  ), TStrings.Delete
                (435  ), TStrings.Strings (446  ), TStrings.Count (444  )



                                                                                 432

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.6         TStrings.AddObject

    Synopsis:    Add a string and associated object to the list.

Declaration:     function  AddObject(const  S:  string;AObject:  TObject)  :  Integer;    Virtual
                                              ;    Overload
                function  AddObject(const  Fmt:  string;Args:  Array  of  const;
                                              AObject:  TObject)  :  Integer;    Overload

    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 (432  ), TStrings.Strings (446  ), TStrings.Objects (445  ), TStrings.InsertObject
                (438  )



                4.71.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  (432  ),  only  it  does  not  return  the  index  of  the
                inserted string.

    See also:    TStrings.Add (432  )



                4.71.8         TStrings.AddStrings

    Synopsis:    Add contents of another stringlist to this list.

Declaration:     procedure  AddStrings(TheStrings:  TStrings);    Virtual;    Overload
                procedure  AddStrings(const  TheStrings:  Array  of  string);    Virtual
                                                 ;    Overload

    Visibility:   public

Description:     AddStrings adds the contents of  TheStrings to the stringlist.  Any associated objects are
                added as well.

    See also:    TStrings.Add (432  ), TStrings.Assign (434  )



                4.71.9         TStrings.AddText

    Synopsis:    Add text to the string list.

Declaration:     procedure  AddText(const  S:  string);    Virtual

    Visibility:   public

Description:     AddText adds S to the strings.  It is identical in function to setting Text (235  ) but does not
                clear the list of strings first:  S is split into lines, and each line is added to the list.

    See also:    TString.Text (235  )



                                                                                 433

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.10          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 (432  ), TStrings.AddStrings (433  ), TPersistent.Assign (392  )



                4.71.11          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
                (435  ) 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 (435  ) 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 (435  )



                4.71.12          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 (444  ) is zero.

                Since  it  is  an  abstract  method,  TStrings  itself  does  not  implement  Clear.   Descendent
                classes such as TStringList (425  ) implement this method.

    See also:    TStrings.Objects (445  ), TStrings.Strings (446  ), TStrings.Delete (435  ), TStrings.Count (444  )



                                                                                 434

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.13          TStrings.Delete

    Synopsis:    Delete a string from the list.

Declaration:     procedure  Delete(Index:  Integer);    Virtual;    Abstract

    Visibility:   public

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 (425  ) implement this method.

       Errors:   If  Index is not in the allowed range, an EStringListError (270  ) is raised.

    See also:    TStrings.Insert (437  ), TStrings.Objects (445  ), TStrings.Strings (446  ), TStrings.Clear (434  )



                4.71.14          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 (434  ).

                TStrings implements the IFPObserved (272  ) interface: when EndUpdate is called, a ooChanged
                notification is sent to all observers.

    See also:    TStrings.BeginUpdate (434  ), IFPObserved (272  )



                4.71.15          TStrings.Equals

    Synopsis:    Compares the contents of two stringlists.

Declaration:     function  Equals(Obj:  TObject)  :  Boolean;    Override;    Overload
                function  Equals(TheStrings:  TStrings)  :  Boolean;    Overload

    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 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.Objects (445  ), TStrings.Strings (446  ), TStrings.Count (444  ), TStrings.Assign (434  )



                                                                                 435

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.16          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.

       Errors:   If either Index1 or Index2 is not in the range of valid indexes, an EStringListError (270  )
                exception is raised.

    See also:    TStrings.Move (438  ), TStrings.Strings (446  ), TStrings.Count (444  )



                4.71.17          TStrings.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TStringsEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1472   ) interface for TStrings.  It
                creates a TStringsEnumerator (447  ) instance and returns it's IEnumerator (1472   ) interface.

    See also:    TStringsEnumerator (447  ), IEnumerator (1472   ), IEnumerable (1472   )



                4.71.18          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.



                4.71.19          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 (437  ), TStrings.IndexOfName (437  ), TStrings.Strings (446  )



                                                                                 436

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.20          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 (436  ), TStrings.IndexOfObject (437  ), TStrings.Strings (446  )



                4.71.21          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.



                4.71.22          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 (438  ) instead.

       Errors:   If  Index is less than zero or larger than Count then an EStringListError (270  ) exception is
                raised.

    See also:    TStrings.Add (432  ), TStrings.InsertObject (438  ), TStrings.Append (433  ), TStrings.Delete
                (435  )



                                                                                 437

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.23          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 (270  ) exception is
                raised.

    See also:    TStrings.Insert (437  ), TStrings.AddObject (433  ), TStrings.Append (433  ), TStrings.Delete
                (435  )



                4.71.24          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 (352  ) with the given filename, and then executes
                TStrings.LoadfromStream (438  ); after that the file stream object is destroyed again.

    See also:    TStrings.LoadFromStream (438  ), TStrings.SaveToFile (439  ), Tstrings.SaveToStream (439  )



                4.71.25          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 (438  ), TStrings.SaveToFile (439  ), Tstrings.SaveToStream (439  )



                4.71.26          TStrings.Move

    Synopsis:    Move a string from one place in the list to another.

Declaration:     procedure  Move(CurIndex:  Integer;NewIndex:  Integer);    Virtual

    Visibility:   public



                                                                                 438

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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');
                       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 (270  ) is
                raised.

    See also:    TStrings.Exchange (436  )



                4.71.27          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 (352  ) with name FileName, calls TStrings.SaveToStream
                (439  ) and then destroys the file stream object.

       Errors:   An EStreamError (269  ) exception can be raised if the file FileName cannot be opened, or
                if it cannot be written to.

    See also:    TStrings.SaveToStream (439  ), Tstrings.LoadFromStream (438  ), TStrings.LoadFromFile (438  )



                4.71.28          TStrings.SaveToStream

    Synopsis:    Save the contents of the string to a stream.

Declaration:     procedure  SaveToStream(Stream:  TStream);    Virtual



                                                                                 439

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    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 (269  ) exception can be raised if the stream cannot be written to.

    See also:    TStrings.SaveToFile (439  ), Tstrings.LoadFromStream (438  ), TStrings.LoadFromFile (438  )



                4.71.29          TStrings.SetText

    Synopsis:    Set the contents of the list from a PChar.

Declaration:     procedure  SetText(TheText:  PChar);    Virtual

    Visibility:   public

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 (446  )



                4.71.30          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.



                4.71.31          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 (442  ) 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:    NameValueSeparator (442  )



                4.71.32          TStrings.TextLineBreakStyle

    Synopsis:    Determines which line breaks to use in the Text (446  ) property

Declaration:     Property  TextLineBreakStyle  :  TTextLineBreakStyle

    Visibility:   public

      Access:    Read,Write



                                                                                 440

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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:    Text (446  )



                4.71.33          TStrings.Delimiter

    Synopsis:    Delimiter character used in DelimitedText (441  ).

Declaration:     Property  Delimiter  :  Char

    Visibility:   public

      Access:    Read,Write

Description:     Delimiter is the delimiter character used to separate the different strings in the stringlist
                when they are read or set through the DelimitedText (441  ) property.

    See also:    TStrings.DelimitedText (441  )



                4.71.34          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:     DelimitedText  returns  all  strings,  properly  quoted  with  QuoteChar  (442  )  and  separated
                by the Delimiter (441  ) character.

                Strings are quoted if they contain a space or any character with ASCII value less than 32.

                The CommaText (443  ) property is a special case of delimited text where the delimiter char-
                acter is a comma and the quote character is a double quote.

                If StrictDelimiter (442  ) is set to True, then no quoting is done (The QuoteChar property is
                disregarded completely):  the returned text will contain the items in the stringlist, separated
                by the Delimiter character.  When writing the DelimitedText property,  the text will be
                split at all occurrences of the Delimiter character; however, when reading, the QuoteChar
                property will be taken into account.

    See also:    TStrings.Delimiter (441  ), TStrings.Text (446  ), TStrings.QuoteChar (442  ), TStrings.CommaText
                (443  )



                4.71.35          TStrings.LineBreak

Declaration:     Property  LineBreak  :  string

    Visibility:   public

      Access:    Read,Write



                                                                                 441

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.36          TStrings.StrictDelimiter

    Synopsis:    Should only the delimiter character be considered a delimiter

Declaration:     Property  StrictDelimiter  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     StrictDelimiter can be used to indicate that only the delimiter character should be con-
                sidered a delimiter when setting DelimitedText (441  ):  under normal circumstances, quotes
                and spaces are considered specially (see the TStrings.CommaText (443  ) property for more
                information).

                When  StrictDelimiter  is  set  to  True  then  only  the  Delimiter  (441  )  character  is  consid-
                ered  when  splitting  the  text  in  items:  no  quoting  whatsoever  is  performed  when  writing
                the DelimitedText property.  However, when reading the DelimitedText property, quoted
                strings are taken into account (so a quoted string can contain a delimiter that is treated as
                text instead of a delimiter).

    See also:    DelimitedText (441  ), CommaText (443  ), Delimiter (441  )



                4.71.37          TStrings.QuoteChar

    Synopsis:    Quote character used in DelimitedText (441  ).

Declaration:     Property  QuoteChar  :  Char

    Visibility:   public

      Access:    Read,Write

Description:     QuoteChar is the character used by the DelimitedText (441  ) property to quote strings that
                have a space or non-printing character in it.



                4.71.38          TStrings.NameValueSeparator

    Synopsis:    Value of the character used to separate name,value pairs

Declaration:     Property  NameValueSeparator  :  Char

    Visibility:   public

      Access:    Read,Write

Description:     NameValueSeparator is the character used to separate name,value pair.  By default, this is
                the equal sign (=), resulting in Name=Value pairs.

                It can be set to a colon for Name :  Value pairs.



                4.71.39          TStrings.ValueFromIndex

    Synopsis:    Return the value part of a string based on it's index.

Declaration:     Property  ValueFromIndex[Index:  Integer]:  string

    Visibility:   public

      Access:    Read,Write



                                                                                 442

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     ValueFromIndex  returns  the  value  part  of  a  string  based  on  the  string  index.  The  value
                part  are  all  characters  in  the  string  after  the  NameValueSeparator  (442  )  character,  or  all
                characters if the NameValueSeparator character is not present.



                4.71.40          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 (444  ) when read.  Trying to set the capacity has no effect.
                Descendent classes such as TStringlist (425  ) can override this property such that it actually
                sets the new capacity.

    See also:    TStringList (425  ), TStrings.Count (444  )



                4.71.41          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



                                                                                 443

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                Comma,String
                Quote"String
                Space
                String


                NormalString


                This is a special case of the TStrings.DelimitedText (441  ) property where the quote character
                is always the double quote, and the delimiter is always the colon.

    See also:    TStrings.Text (446  ), TStrings.SetText (440  )



                4.71.42          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 (446  ), TStrings.Objects (445  ), TStrings.Capacity (443  )



                4.71.43          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 (445  ), TStrings.IndexOfName (437  )



                                                                                 444

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.44          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

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 (270  ) exception will be
                raised.

    See also:    TStrings.Strings (446  ), TStrings.IndexOfObject (437  ), TStrings.Names (444  ), TStrings.Values
                (445  )



                4.71.45          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 (444  ), TStrings.Strings (446  ), TStrings.Objects (445  )



                                                                                 445

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.71.46          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.

                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 (445  )
                property.  The name parts of name-value pairs can be accessed with the TStrings.Names (444  )
                property, and the values can be set or read through the TStrings.Values (445  ) property.

                Searching through the list can be done using the TStrings.IndexOf (436  ) method.

       Errors:   If  Index is outside the allowed range, an EStringListError (270  ) exception is raised.

    See also:    TStrings.Count (444  ), TStrings.Objects (445  ), TStrings.Names (444  ), TStrings.Values (445  ),
                TStrings.IndexOf (436  )



                4.71.47          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 (443  ) property instead.

    See also:    TStrings.Strings (446  ), TStrings.Count (444  ), TStrings.CommaText (443  )



                4.71.48          TStrings.StringsAdapter

    Synopsis:    Not implemented in Free Pascal.

Declaration:     Property  StringsAdapter  :  IStringsAdapter

    Visibility:   public

      Access:    Read,Write

Description:     Not implemented in Free Pascal.



                                                                                 446

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.72          TStringsEnumerator



                4.72.1         Description

                TStringsEnumerator implements the #rtl.system.IEnumerator (1472   ) interface for the TStrings
                (430  ) class, so the TStrings class can be used in a for  ...    in loop.  It is returned by the
                TStrings.GetEnumerator (436  ) method of  TStrings.


    See also:    TStrings (430  ), TStrings.GetEnumerator (436  ), #rtl.system.IEnumerator (1472   )



                4.72.2         Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                  447       Create              Initialize a new instance of  TStringsEnumerator
                  447       GetCurrent          Return the current pointer in the list
                __447_______MoveNext____________Move_the_position_of_the_enumerator_to_the_next_position_in_the_list.______________*
 *___________



                4.72.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __448_______Current___________r____________Current_pointer_in_the_list_____________________________________________*
 *___________



                4.72.4         TStringsEnumerator.Create

    Synopsis:    Initialize a new instance of  TStringsEnumerator

Declaration:     constructor  Create(AStrings:  TStrings)

    Visibility:   public

Description:     Create  initializes  a  new  instance  of  TStringsEnumerator  and  keeps  a  reference  to  the
                stringlist AStrings that will be enumerated.

    See also:    TStrings (430  )



                4.72.5         TStringsEnumerator.GetCurrent

    Synopsis:    Return the current pointer in the list

Declaration:     function  GetCurrent  :  string

    Visibility:   public

Description:     GetCurrent returns the current string item in the enumerator.

       Errors:   No checking is done on the validity of the current position.

    See also:    MoveNext (447  ), TStringItem (249  )



                4.72.6         TStringsEnumerator.MoveNext

    Synopsis:    Move the position of the enumerator to the next position in the list.

Declaration:     function  MoveNext  :  Boolean

    Visibility:   public



                                                                                 447

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     MoveNext  puts  the  pointer  on  the  next  item  in  the  stringlist,  and  returns  True  if  this
                succeeded, or False if the pointer is past the last element in the list.

       Errors:   Note that if  False is returned, calling GetCurrent will result in an exception.

    See also:    GetCurrent (447  )



                4.72.7         TStringsEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  string

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (447  ) as a property.

    See also:    GetCurrent (447  )



                4.73          TStringStream



                4.73.1         Description

                TStringStream stores its data in an ansistring.  The contents of this string is available as
                the DataString (450  ) 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.


    See also:    TStream (410  ), TStringStream.DataString (450  ), TStringStream.ReadString (449  ), TStringStream.WriteString
                (450  )



                4.73.2         Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                  448       Create              Creates a new stringstream and sets its initial content.
                  449       Read                Reads from the stream.
                  449       ReadString          Reads a string of length Count
                  449       Seek                Sets the position in the stream.
                  449       Write               Write overries the TStream.Write (412  ) method.
                __450_______WriteString_________WriteString_writes_a_string_to_the_stream._________________________________________*
 *___________



                4.73.3         Property  overview

                __Page______Properties_________Access_______Description____________________________________________________________*
 *___________
                __450_______DataString_________r____________Contains_the_contents_of_the_stream_in_string_form_____________________*
 *___________



                4.73.4         TStringStream.Create

    Synopsis:    Creates a new stringstream and sets its initial content.

Declaration:     constructor  Create(const  AString:  string)



                                                                                 448

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    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 (450  )



                4.73.5         TStringStream.Read

    Synopsis:    Reads from the stream.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read overrides the Read (411  ) from TStream (410  ).  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
                (450  ), then the reading stops, i.e.  it is not possible to read beyond the end of the datastring.

    See also:    TStream.Read (411  ), TStringStream.Write (449  ), TStringStream.DataString (450  )



                4.73.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 (449  ) method.  It does not do the
                same stringas the TStream.ReadAnsiString (418  ) method, which first reads a length integer
                to determine the length of the string to be read.

    See also:    TStringStream.Read (449  ), TStream.ReadAnsiString (418  )



                4.73.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 (412  ) method.



                4.73.8         TStringStream.Write

    Synopsis:    Write overries the TStream.Write (412  ) method.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write overries the TStream.Write (412  ) method.



                                                                                 449

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.73.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.



                4.73.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



                4.74          TTextOb jectWriter



                4.74.1         Description

                Not yet implemented.



                4.75          TThread



                4.75.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 (451  ) 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.


    See also:    EThread (270  ), TThread.Execute (451  )



                                                                                 450

            __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



            4.75.2         Method  overview

            __Page______Method___________________________________Description_______________________________________________________*
 *_______
              456       AfterConstruction                        Code  to  be  executed  after  construction  but  before
                                                                 execute.
              454       CheckTerminated                          Check if the current thread has finished executing.
              452       Create                                   Creates a new thread.
              453       CreateAnonymousThread                    Execute code in an anonymous thread
              453       Destroy                                  Destroys the thread object.
              451       Execute                                  Execute  method.  Must  be  overridden  in  a  descen-
                                                                 dent thread.
              455       GetSystemTimes                           Return CPU stats
              455       GetTickCount                             Return tick count (32-bit)
              456       GetTickCount64                           Return tick count (64-bit)
              453       NameThreadForDebugging                   Set a thread name
              452       Queue                                    Queue a method for execution in the main thread
              454       RemoveQueuedEvents                       Remove   methods   scheduled   for   execution   from
                                                                 queue
              456       Resume                                   Resumes  the  thread's  execution.   Deprecated,  see
                                                                 TThread.Start
              453       SetReturnValue                           Set return value of a thread
              455       Sleep                                    Prevent thread execution
              454       SpinWait                                 Prevent thread execution in a spin-wait loop
              456       Start                                    Starts  a  thread  that  was  created  in  a  suspended
                                                                 state.
              456       Suspend                                  Suspends the thread's execution.
              452       Synchronize                              Synchronizes the thread by executing the method in
                                                                 the main thread.
              457       Terminate                                Signals the thread it should terminate.
              457       WaitFor                                  Waits  for  the  thread  to  terminate  and  returns  the
                                                                 exit status.
            __455_______Yield____________________________________Yield_execution_to_other_threads__________________________________*
 *_______



            4.75.3         Property  overview

            __Page______Properties__________________Access_______Description_______________________________________________________*
 *_______
              457       CurrentThread               r            Return current thread instance
              458       ExternalThread              r            Is the thread instance an external thread ?
              460       FatalException              r            Exception that occured during thread execution
              459       Finished                    r            Has the thread finished executing
              458       FreeOnTerminate             rw           Indicates whether the thread should free itself when
                                                                 it stops executing.
              458       Handle                      r            Returns the thread handle.
              458       IsSingleProcessor           r            Is the current system single processor or not
              459       OnTerminate                 rw           Event called when the thread terminates.
              459       Priority                    rw           Returns the thread priority.
              457       ProcessorCount              r            Return the processor count for this system
              459       Suspended                   rw           Indicates whether the thread is suspended.
            __459_______ThreadID____________________r____________Returns_the_thread_ID.____________________________________________*
 *_______



            4.75.4         TThread.Execute

Synopsis:    Execute method.  Must be overridden in a descendent thread.



                                                                             451

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Declaration:     procedure  Execute;    Virtual;    Abstract

    Visibility:  protected

Description:     Execute is a method that must be overridden in descendent classes of the thread.  It must
                contain the code that must execute in the thread.  The Execute method is responsible for
                checking Terminated (235  ) at regular intervals:  when it is set to True the execute method
                must exit.

    See also:    Terminated (235  )



                4.75.5         TThread.Synchronize

    Synopsis:    Synchronizes the thread by executing the method in the main thread.

Declaration:     procedure  Synchronize(AMethod:  TThreadMethod)
                class  procedure  Synchronize(AThread:  TThread;AMethod:  TThreadMethod)

    Visibility:   protected

Description:     Synchronizes the thread by executing the method in the main thread.



                4.75.6         TThread.Queue

    Synopsis:    Queue a method for execution in the main thread

Declaration:     procedure  Queue(aMethod:  TThreadMethod)
                class  procedure  Queue(aThread:  TThread;aMethod:  TThreadMethod);    Static

    Visibility:   protected

Description:     Queue  schedules  a  method  aMethod  for  execution  in  the  main  thread.  In  difference  with
                TThread.Synchronize (452  ), Queue just posts the method for execution in a queue, and does
                not wait for it to be executed, so this call returns at once.

                In the class procedure overloaded version of this call, the thread for which the method must
                be  posted  is  the  first  argument.  In  the  protected  version  of  this  call  (used  in  the  tthread
                instance), this argument is not there, and the thread instance is used.

                When a thread finishes it's execution, all its queued calls are removed from the queue list.

    See also:    TThread.Synchronize (452  ), TThread.RemoveQueuedEvents (454  )



                4.75.7         TThread.Create

    Synopsis:    Creates a new thread.

Declaration:     constructor  Create(CreateSuspended:  Boolean;const  StackSize:  SizeUInt)

    Visibility:   public

Description:     Creates a new thread.



                                                                                 452

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.75.8         TThread.Destroy

    Synopsis:    Destroys the thread object.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the thread object.



                4.75.9         TThread.CreateAnonymousThread

    Synopsis:    Execute code in an anonymous thread

Declaration:     class  function  CreateAnonymousThread(aProc:  TProcedure);    Static

    Visibility:   public

Description:     CreateAnonymousThread will create an instance of a TThread descendent and calls aProc
                in this procedure.  This can be used to quickly execute a method in another thread without
                having  to  expliticly  declare  a  thread  for  such  purposes.   It  returns  the  created  TThread
                instance, which can be checked for termination etc.

                Note that this method differs slightly from Delphi in that FPC does not yet support anony-
                mous methods, so the signature of  aProc differs slightly.

    See also:    TThread.CheckTerminated (454  )



                4.75.10          TThread.NameThreadForDebugging

    Synopsis:    Set a thread name

Declaration:     class  procedure  NameThreadForDebugging(aThreadName:  UnicodeString;
                                                                               aThreadID:  TThreadID);    Static
                class  procedure  NameThreadForDebugging(aThreadName:  AnsiString;
                                                                               aThreadID:  TThreadID);    Static

    Visibility:   public

Description:     NameThreadForDebugging sets the name of thread aThreadID to aThreadName.  The thread
                name can be unicode or ansistring.  This is mainly useful for debugging purposes, as thread
                names are more easily recognizable than IDs.

                Note that this requires OS support.  Currently this is not implemented for any FPC platform
                and is supported for Delphi compatibility only.



                4.75.11          TThread.SetReturnValue

    Synopsis:    Set return value of a thread

Declaration:     class  procedure  SetReturnValue(aValue:  Integer);    Static

    Visibility:   public

Description:     TThread.SetReturnValue sets the return value of an internally created thread.

       Errors:   If  the  thread  was  not  created  by  the  FPC  program,  an  EThreadExternalException  (270  )
                exception is raised.

    See also:    EThreadExternalException (270  ), TThread.CheckTerminated (454  )



                                                                                 453

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.75.12          TThread.CheckTerminated

    Synopsis:    Check if the current thread has finished executing.

Declaration:     class  function  CheckTerminated;    Static

    Visibility:   public

Description:     TThread.CheckTerminated can be used to check if the current thread has finished executing
                (i.e.  Execute has finished.  This can be called from methods in other classes where the current
                thread instance is not available.

       Errors:   If  the  thread  was  not  created  by  the  FPC  program,  an  EThreadExternalException  (270  )
                exception is raised.

    See also:    EThreadExternalException (270  ), TThread.SetReturnValue (453  )



                4.75.13          TThread.RemoveQueuedEvents

    Synopsis:    Remove methods scheduled for execution from queue

Declaration:     class  procedure  RemoveQueuedEvents(aThread:  TThread;
                                                                        aMethod:  TThreadMethod);    Static
                class  procedure  RemoveQueuedEvents(aMethod:  TThreadMethod);    Static
                class  procedure  RemoveQueuedEvents(aThread:  TThread);    Static

    Visibility:   public

Description:     RemoveQueuedEvents  removes  methods  from  the  list  of  methods  waiting  for  execution  in
                the main thread.  If only aThread is specified, all methods scheduled for execution by that
                thread are removed.  If only aMethod is specified, then all calls to that method are removed,
                regardless of the thread.  If both arguments are specified, then all calls to the given method
                by the given thread are removed.

    See also:    TThread.Synchronize (452  ), TThread.Queue (452  )



                4.75.14          TThread.SpinWait

    Synopsis:    Prevent thread execution in a spin-wait loop

Declaration:     class  procedure  SpinWait(aIterations:  LongWord);    Static

    Visibility:   public

Description:     SpinWait blocks the execution of the thread in a spin-wait loop:  it simply executes some
                simple instructions.

                This  can  be  used  to  create  short  time  delays  without  an  immediate  thread  switch  (e.g.
                SysUtils.Sleep (235  ) can cause a thread switch).  The input parameter (aIterations) specifies
                the number of spin loops.

    See also:    SysUtils.Sleep (235  ), TThread.Sleep (455  )



                                                                                 454

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.75.15          TThread.Sleep

    Synopsis:    Prevent thread execution

Declaration:     class  procedure  Sleep(aMilliseconds:  Cardinal);    Static

    Visibility:   public

Description:     Sleep  blocks  the  execution  of  the  thread  for  aMilliseconds.  This  function  simply  calls
                sysutils.sleep (235  )

                In difference with TThread.SpinWait (454  ), a thread switch may occur during the sleep.

    See also:    SysUtils.Sleep (235  ), TThread.SpinWait (454  )



                4.75.16          TThread.Yield

    Synopsis:    Yield execution to other threads

Declaration:     class  procedure  Yield;    Static

    Visibility:   public

Description:     TThread.Yield yields the processor to other threads.  It can be called from methods outside
                the thread class itself.



                4.75.17          TThread.GetSystemTimes

    Synopsis:    Return CPU stats

Declaration:     class  procedure  GetSystemTimes(out  aSystemTimes:  TSystemTimes);    Static

    Visibility:   public

Description:     GetSystemTimes is provided for Delphi compatibility only, it currently returns empty values
                only.

    See also:    TSystemTimes (235  )



                4.75.18          TThread.GetTickCount

    Synopsis:    Return tick count (32-bit)

Declaration:     class  function  GetTickCount;    Static

    Visibility:   public

Description:     GetTickCount is deprecated and should not be used.  Use TThread.GetTickCount64 (456  )
                instead.

    See also:    TThread.GetTickCount64 (456  )



                                                                                 455

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.75.19          TThread.GetTickCount64

    Synopsis:    Return tick count (64-bit)

Declaration:     class  function  GetTickCount64;    Static

    Visibility:   public

Description:     GetTickCount64 simply calls SysUtils.GetTickCount64 (235  ) and is implemented for Delphi
                compatibility only.

    See also:    SysUtils.GetTickCount64 (235  )



                4.75.20          TThread.AfterConstruction

    Synopsis:    Code to be executed after construction but before execute.

Declaration:     procedure  AfterConstruction;    Override

    Visibility:   public

Description:     AfterConstruction  is  overridden  in  TThread,  it  starts  the  thread  if  it  was  created  in  a
                suspended state.  When overriding this method, the inherited method must be called.



                4.75.21          TThread.Start

    Synopsis:    Starts a thread that was created in a suspended state.

Declaration:     procedure  Start

    Visibility:   public

Description:     The effect of this method is currently the same as calling TThread.Resume after creating a
                thread in a suspended state.  This method was added for Delphi-compatibility, where it was
                introduced after TThread.Suspend and TThread.Resume were deprecated.

    See also:    TThread.Create (452  )



                4.75.22          TThread.Resume

    Synopsis:    Resumes the thread's execution.  Deprecated, see TThread.Start

Declaration:     procedure  Resume

    Visibility:   public

Description:     Resumes the thread's execution.  Deprecated, see TThread.Start

    See also:    TThread.Start (456  ), TThread.Suspend (456  )



                4.75.23          TThread.Suspend

    Synopsis:    Suspends the thread's execution.

Declaration:     procedure  Suspend

    Visibility:   public

Description:     On non-Windows platforms, a thread can only suspend itself.  Other threads can wake up
                a suspended thread by calling TThread.Start.

    See also:    TThread.Resume (456  ), TThread.Start (456  )



                                                                                 456

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.75.24          TThread.Terminate

    Synopsis:    Signals the thread it should terminate.

Declaration:     procedure  Terminate

    Visibility:   public

Description:     Signals the thread it should terminate.



                4.75.25          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.



                4.75.26          TThread.CurrentThread

    Synopsis:    Return current thread instance

Declaration:     Property  CurrentThread  :  TThread

    Visibility:   public

      Access:    Read

Description:     TThread.CurrentThread can be used to get the current thread instance.  This is useful in
                code  that  is  not  inside  a  TThread  implementation,  but  which  needs  access  to  the  current
                thread.

                For  threads  that  were  created  outside  of  FPC  code  (DLLs  or  a  calling  program)  this  will
                return a dummy TThread instance.

    See also:    TThread.ExternalThread (458  )



                4.75.27          TThread.ProcessorCount

    Synopsis:    Return the processor count for this system

Declaration:     Property  ProcessorCount  :  LongWord

    Visibility:   public

      Access:    Read

Description:     ProcessorCount returns the processor count for this system.

                Whether this is the number of cores or the number of CPUs present in the hardware, is de-
                liberately unspecified.  The number of cores can also vary during the lifetime of the program,
                and the FPC implementation does not guarantee that this will always match, the value is
                set at program start.

                As such, the number specified should only be used as an indication of how many threads can
                be executed at once by the system.

    See also:    TThread.IsSingleProcessor (458  )



                                                                                 457

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.75.28          TThread.IsSingleProcessor

    Synopsis:    Is the current system single processor or not

Declaration:     Property  IsSingleProcessor  :  Boolean

    Visibility:   public

      Access:    Read

Description:     Thread.IsSingleProcessor returns True if TThread.ProcessorCount (457  ) is less than or
                equal to 1, False otherwise.

    See also:    TThread.ProcessorCount (457  )



                4.75.29          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.



                4.75.30          TThread.Handle

    Synopsis:    Returns the thread handle.

Declaration:     Property  Handle  :  TThreadID

    Visibility:   public

      Access:    Read

Description:     Returns the thread handle.



                4.75.31          TThread.ExternalThread

    Synopsis:    Is the thread instance an external thread ?

Declaration:     Property  ExternalThread  :  Boolean

    Visibility:   public

      Access:    Read

Description:     ExternalThread returns True if the thread is an externally created thread.  If the thread
                was created by the FPC program, this returns False.  This is useful for examining instances
                returned by TThread.CurrentThread (457  ).

    See also:    TThread.CurrentThread (457  )



                                                                                 458

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.75.32          TThread.Priority

    Synopsis:    Returns the thread priority.

Declaration:     Property  Priority  :  TThreadPriority

    Visibility:   public

      Access:    Read,Write

Description:     Returns the thread priority.



                4.75.33          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.



                4.75.34          TThread.Finished

    Synopsis:    Has the thread finished executing

Declaration:     Property  Finished  :  Boolean

    Visibility:   public

      Access:    Read

Description:     Finished is True when TThread.Execue (450  ) has finished executing, but the thread is still
                cleaning up (calling OnTerminate, etc).

    See also:    TThread.Execue (450  ), TThread.OnTerminate (459  )



                4.75.35          TThread.ThreadID

    Synopsis:    Returns the thread ID.

Declaration:     Property  ThreadID  :  TThreadID

    Visibility:   public

      Access:    Read

Description:     Returns the thread ID.



                4.75.36          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.



                                                                                 459

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.75.37          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.



                4.76          TThreadList



                4.76.1         Description

                TThreadList is a thread-safe Tlist (371  ) implementation.  Unlike TList, it can be accessed
                read-write by multiple threads:  the list implementation will take care of locking the list when
                adding or removing items from the list.


    See also:    TList (371  )



                4.76.2         Method  overview

                __Page______Method_____________Description_________________________________________________________________________*
 *___________
                  461       Add                Adds an element to the list.
                  461       Clear              Removes all emements from the list.
                  460       Create             Creates a new thread-safe list.
                  461       Destroy            Destroys the list instance.
                  461       LockList           Locks the list for exclusive access.
                  462       Remove             Removes an item from the list.
                __462_______UnlockList_________Unlocks_the_list_after_it_was_locked._______________________________________________*
 *___________



                4.76.3         Property  overview

                __Page______Properties_________Access______Description_____________________________________________________________*
 *___________
                __462_______Duplicates_________rw__________Describes_what_to_do_with_duplicates____________________________________*
 *___________



                4.76.4         TThreadList.Create

    Synopsis:    Creates a new thread-safe list.

Declaration:     constructor  Create

    Visibility:   public

Description:     Create  instantiates  a  new  TThreadList  instance.   It  initializes  a  critical  section  and  an
                internal list object.

    See also:    TThreadList.Destroy (461  )



                                                                                 460

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.76.5         TThreadList.Destroy

    Synopsis:    Destroys the list instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy finalizes the critical section, clears the internal list object and calls the inherited
                destructor.

    See also:    TThreadList.Create (460  )



                4.76.6         TThreadList.Add

    Synopsis:    Adds an element to the list.

Declaration:     procedure  Add(Item:  Pointer)

    Visibility:   public

Description:     Add attempts to lock the list and adds the pointer Item to the list.  After the pointer was
                added, the list is unlocked again.

    See also:    LockList (461  ), Clear (461  ), Remove (462  ), UnlockList (462  )



                4.76.7         TThreadList.Clear

    Synopsis:    Removes all emements from the list.

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear attempts to lock the list and then clears the list; all items are removed from the list.
                After the list is cleared, it is again unlocked.

    See also:    LockList (461  ), Add (461  ), Remove (462  ), UnlockList (462  )



                4.76.8         TThreadList.LockList

    Synopsis:    Locks the list for exclusive access.

Declaration:     function  LockList  :  TList

    Visibility:   public

Description:     LockList locks the list for exclusive access.  Locklist uses an internal critical section, so all
                rules for multiple locking of critical sections apply to locklist/unlocklist as well.

    See also:    Clear (461  ), Add (461  ), Remove (462  ), UnlockList (462  )



                                                                                 461

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.76.9         TThreadList.Remove

    Synopsis:    Removes an item from the list.

Declaration:     procedure  Remove(Item:  Pointer)

    Visibility:   public

Description:     Remove  attempts  to  lock  the  list  and  then  removes  Item  from  the  list.  After  the  item  is
                removed, the list is again unlocked.

    See also:    LockList (461  ), Add (461  ), Clear (461  ), UnlockList (462  )



                4.76.10          TThreadList.UnlockList

    Synopsis:    Unlocks the list after it was locked.

Declaration:     procedure  UnlockList

    Visibility:   public

Description:     UnLockList unlocks the list when it was locked for exclusive access.  UnLocklist and LockList
                use an internal critical section, so all rules for multiple locking/unlocking of critical sections
                apply.

    See also:    Clear (461  ), Add (461  ), Remove (462  ), lockList (461  )



                4.76.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 (428  ) property of TStringList (425  ).

    See also:    TDuplicates (242  )



                4.77          TWriter



                4.77.1         Description

                The TWriter class is a writer class that implements generic component streaming capabilities,
                independent  of  the  format  of  the  data  in  the  stream.  It  uses  a  driver  class  TAbstractOb-
                jectWriter (291  ) to do the actual reading of data.  The interface of the TWriter class should
                be identical to the interface in Delphi.

                Note that the TWriter design is such that it will write a single component to a stream.  It
                will write all children of this component, but it is not designed to write multiple components
                in succession to one stream.

                It  should  never  be  necessary  to  create  an  instance  of  this  class  directly.    Instead,  the
                TStream.WriteComponent (415  ) call should be used.


    See also:    TFiler (350  ), TWriter (462  ), TAbstractObjectReader (283  )



                                                                                 462

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.77.2         Method  overview

                __Page______Method_____________________________Description_________________________________________________________*
 *___________
                  463       Create                             Creates a new Writer with a stream and bufsize.
                  464       DefineBinaryProperty               Callback used when defining and streaming custom prop-
                                                               erties.
                  464       DefineProperty                     Callback used when defining and streaming custom prop-
                                                               erties.
                  464       Destroy                            Destroys the writer instance.
                  464       Write                              Write raw data to stream
                  464       WriteBoolean                       Write boolean value to the stream.
                  465       WriteChar                          Write a character to the stream.
                  465       WriteCollection                    Write a collection to the stream.
                  465       WriteComponent                     Stream a component to the stream.
                  466       WriteCurrency                      Write a currency value to the stream
                  466       WriteDate                          Write a date to the stream.
                  465       WriteDescendent                    Write a descendent component to the stream.
                  466       WriteFloat                         Write a float to the stream.
                  466       WriteIdent                         Write an identifier to the stream.
                  467       WriteInteger                       Write an integer to the stream.
                  467       WriteListBegin                     Write a start-of-list marker to the stream.
                  467       WriteListEnd                       Write an end-of-list marker to the stream.
                  468       WriteRootComponent                 Write a root component to the stream.
                  467       WriteSet                           Write a set value to the stream
                  467       WriteSignature
                  466       WriteSingle                        Write a single-type real to the stream.
                  468       WriteString                        Write a string to the stream.
                  468       WriteUnicodeString                 Write a unicode string to the stream.
                  468       WriteVariant                       Write a variant to the stream
                  465       WriteWideChar                      Write widechar to stream
                __468_______WriteWideString____________________Write_a_widestring_value_to_the_stream______________________________*
 *___________



                4.77.3         Property  overview

                __Page______Properties_____________________________Access_______Description________________________________________*
 *___________
                  470       Driver                                 r            Driver used when writing to the stream.
                  469       OnFindAncestor                         rw           Event  occurring  when  an  ancestor  compo-
                                                                                nent must be found.
                  469       OnWriteMethodProperty                  rw           Handler from writing method properties.
                  469       OnWriteStringProperty                  rw           Event handler for translating strings written
                                                                                to stream.
                  470       PropertyPath                           r            Path to the property that is currently being
                                                                                written
                __469_______RootAncestor___________________________rw___________Ancestor_of_root_component.________________________*
 *___________



                4.77.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.



                                                                                 463

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.77.5         TWriter.Destroy

    Synopsis:    Destroys the writer instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the writer instance.



                4.77.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.



                4.77.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.



                4.77.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 (312  ), TAbstractObjectWriter.Write (293  )



                4.77.9         TWriter.WriteBoolean

    Synopsis:    Write boolean value to the stream.

Declaration:     procedure  WriteBoolean(Value:  Boolean)

    Visibility:   public

Description:     Write boolean value to the stream.



                                                                                 464

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.77.10          TWriter.WriteCollection

    Synopsis:    Write a collection to the stream.

Declaration:     procedure  WriteCollection(Value:  TCollection)

    Visibility:   public

Description:     Write a collection to the stream.



                4.77.11          TWriter.WriteComponent

    Synopsis:    Stream a component to the stream.

Declaration:     procedure  WriteComponent(Component:  TComponent)

    Visibility:   public

Description:     Stream a component to the stream.



                4.77.12          TWriter.WriteChar

    Synopsis:    Write a character to the stream.

Declaration:     procedure  WriteChar(Value:  Char)

    Visibility:   public

Description:     Write a character to the stream.



                4.77.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 (400  ), TWriter.WriteWideString (468  )



                4.77.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.



                                                                                 465

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.77.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.



                4.77.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.



                4.77.17          TWriter.WriteDate

    Synopsis:    Write a date to the stream.

Declaration:     procedure  WriteDate(const  Value:  TDateTime)

    Visibility:   public

Description:     Write a date to the stream.



                4.77.18          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 (401  )



                4.77.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.



                                                                                 466

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.77.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.



                4.77.21          TWriter.WriteSet

    Synopsis:    Write a set value to the stream

Declaration:     procedure  WriteSet(Value:  LongInt;SetType:  Pointer)

    Visibility:   public

Description:     WriteSet writes a set Value consisting of elements with type EnumType.  The set must be
                encoded as an integer where each element is encoded in a bit of the integer.  Thus, at most
                an enumerated type with 32 elements can be written with this method.

       Errors:   No checking is performed on the validity of EnumType.  It is assumed to be a valid PTypeInfo
                pointer.

    See also:    TReader.ReadSet (402  )



                4.77.22          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.



                4.77.23          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.



                4.77.24          TWriter.WriteSignature

Declaration:     procedure  WriteSignature

    Visibility:   public



                                                                                 467

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.77.25          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.



                4.77.26          TWriter.WriteString

    Synopsis:    Write a string to the stream.

Declaration:     procedure  WriteString(const  Value:  string)

    Visibility:   public

Description:     Write a string to the stream.



                4.77.27          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 (403  )



                4.77.28          TWriter.WriteUnicodeString

    Synopsis:    Write a unicode string to the stream.

Declaration:     procedure  WriteUnicodeString(const  Value:  UnicodeString)

    Visibility:   public

Description:     WriteUnicodeString writes Value, a UnicodeString string to the stream.  It simply passes
                the string on to the WriteUnicodeString method of the writer driver class.

    See also:    TBinaryObjectWriter.WriteUnicodeString (314  ), TReader.ReadUnicodeString (404  )



                4.77.29          TWriter.WriteVariant

    Synopsis:    Write a variant to the stream

Declaration:     procedure  WriteVariant(const  VarValue:  Variant)

    Visibility:   public

Description:     WriteVariant writes Value, a simple variant, o the stream.  It simply passes the string on
                to the WriteVariant method of the writer driver class.

    See also:    TBinaryObjectWriter.WriteVariant (315  ), TReader.ReadVariant (403  )



                                                                                 468

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.77.30          TWriter.RootAncestor

    Synopsis:    Ancestor of root component.

Declaration:     Property  RootAncestor  :  TComponent

    Visibility:   public

      Access:    Read,Write

Description:     Ancestor of root component.



                4.77.31          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.



                4.77.32          TWriter.OnWriteMethodProperty

    Synopsis:    Handler from writing method properties.

Declaration:     Property  OnWriteMethodProperty  :  TWriteMethodPropertyEvent

    Visibility:   public

      Access:    Read,Write

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 (250  )
                for a description of the arguments.

    See also:    TWriteMethodPropertyEvent (250  ), TReader.OnSetMethodProperty (406  )



                4.77.33          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 (247  ) for a description of the various
                parameters.

    See also:    TReader.OnPropertyNotFound (405  ), TReader.OnSetMethodProperty (406  ), TReadWriteString-
                PropertyEvent (247  )



                                                                                 469

                __________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                4.77.34          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.



                4.77.35          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 (391  ) descendent class properties are written.



                                                                                 470




Chapter   5



Reference   for   unit   'clocale'



5.1         Overview


The clocale offers no API by itself:  it just initializes the internationalization settings of the
sysutils (1489   ) unit with the values provided by the C library found on most Unix or Linux
systems that are POSIX compliant.

The clocale should simply be included in the uses clause of the program, preferably as one
of the first units, and the initialization section of the unit will do all the work.

Note that including this unit, links your program to the C library of the system.

It makes no sense to use this unit on a non-posix system:  Windows, OS/2 or DOS - therefore
it should always be between an ifdef statement:


program  myprogram;


uses
    {$ifdef  unix}clocale{$endif},
     classes,  sysutils;



                                                             471




                Chapter   6



                Reference   for   unit   'cmem'



                6.1         Overview


                The cmem memory manager sets the system units memory manager to a C-based memory
                manager:  all  memory  management  calls  are  shunted  through  to  the  C  memory  manager,
                using Malloc (473  ), Free (473  ) and ReAlloc (473  ).  For this reason, the cmem unit should be
                the first unit of the uses clause of the program.

                The unit also offers the C memory calls directly as external declarations from the C library,
                but it is recommended to use the normal FPC routines for this.

                Obviously, including this unit links your program to the C library.



                6.2         Constants,  types  and  variables



                6.2.1        Constants

                LibName  =  'c'


                LibName is the name of the library that is actually used.  On most systems, this is simply
                "libc.so".



                6.3         Procedures  and  functions



                6.3.1        CAlloc

    Synopsis:    Allocate memory based on item size and count

Declaration:     function  CAlloc(unitSize:  ptruint;UnitCount:  ptruint)  :  pointer

    Visibility:   default

Description:     Calloc allocates memory to hold UnitCount units of size UnitSize each.  The memory is
                one block of memory.  It returns a pointer to the newly allocated memory block.

    See also:    Malloc (473  ), Free (473  ), Realloc (473  )



                                                                             472

                ______________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CMEM'_______________*
 *___________________



                6.3.2        Free

    Synopsis:    Free a previously allocated block

Declaration:     procedure  Free(P:  pointer)

    Visibility:   default

Description:     Free returns the memory block pointed to by P to the system.  After Free was called, the
                pointer P is no longer valid.

    See also:    Malloc (473  ), ReAlloc (473  )



                6.3.3        Malloc

    Synopsis:    Malloc external declaration.

Declaration:     function  Malloc(Size:  ptruint)  :  Pointer

    Visibility:   default

Description:     Malloc is the external declaration of the C librarys malloc call.  It accepts a size parameter,
                and returns a pointer to a memory block of the requested size or Nil if no more memory
                could be allocated.

    See also:    Free (473  ), ReAlloc (473  )



                6.3.4        ReAlloc

    Synopsis:    Reallocates a memory block

Declaration:     function  ReAlloc(P:  Pointer;Size:  ptruint)  :  pointer

    Visibility:   default

Description:     ReAlloc re-allocates a block of memory pointed to by p.  The new block will have size Size,
                and as much data as was available or as much data as fits is copied from the old to the new
                location.

    See also:    Malloc (473  ), Free (473  )



                                                                                 473




Chapter   7



Reference   for   unit   'collation ___de'



7.1         Overview


The collation_de unit registers the German Unicode collation (de).  This collation bases itself
on the DUCET collation, so that collation will be included as well.

This unit does not contain any routines.  It simply registers the collation in the initialization
section of the unit, so including the unit in the uses clause of the program is sufficient.



                                                             474




Chapter   8



Reference   for   unit   'collation ___es'



8.1         Overview


The collation_es unit registers the Spanish Unicode collation (de).  This collation bases itself
on the DUCET collation, so that collation will be included as well.

This unit does not contain any routines.  It simply registers the collation in the initialization
section of the unit, so including the unit in the uses clause of the program is sufficient.



                                                             475




Chapter   9



Reference   for   unit



'collation ___fr ___ca'



9.1         Overview


The collation_fr_ca unit registers the French Unicode collation (fr).  This collation bases itself
on the DUCET collation, so that collation will be included as well.

This unit does not contain any routines.  It simply registers the collation in the initialization
section of the unit, so including the unit in the uses clause of the program is sufficient.



                                                             476




Chapter   10



Reference   for   unit   'collation ___ja'



10.1          Overview


The collation_ja unit registers the Japanese Unicode collation (ja).  This collation bases itself
on the DUCET collation, so that collation will be included as well.

This unit does not contain any routines.  It simply registers the collation in the initialization
section of the unit, so including the unit in the uses clause of the program is sufficient.



                                                             477




Chapter   11



Reference   for   unit   'collation ___ko'



11.1          Overview


The collation_ko unit registers the Korean Unicode collation (ko).  This collation bases itself
on the DUCET collation, so that collation will be included as well.

This unit does not contain any routines.  It simply registers the collation in the initialization
section of the unit, so including the unit in the uses clause of the program is sufficient.



                                                             478




Chapter   12



Reference   for   unit   'collation ___ru'



12.1          Overview


The collation_ru unit registers the Russian Unicode collation (ru).  This collation bases itself
on the DUCET collation, so that collation will be included as well.

This unit does not contain any routines.  It simply registers the collation in the initialization
section of the unit, so including the unit in the uses clause of the program is sufficient.



                                                             479




Chapter   13



Reference   for   unit   'collation ___sv'



13.1          Overview


The collation_sv unit registers the Swedish Unicode collation (sv).  This collation bases itself
on the DUCET collation, so that collation will be included as well.

This unit does not contain any routines.  It simply registers the collation in the initialization
section of the unit, so including the unit in the uses clause of the program is sufficient.



                                                             480




Chapter   14



Reference   for   unit   'collation ___zh'



14.1          Overview


The collation_zh unit registers the Chinese Unicode collation (zh).  This collation bases itself
on the DUCET collation, so that collation will be included as well.

This unit does not contain any routines.  It simply registers the collation in the initialization
section of the unit, so including the unit in the uses clause of the program is sufficient.



                                                             481




Chapter   15



Reference   for   unit   'cp1250'



15.1          Overview


The cp1250 unit registers single-byte codepage 1250.  This is necessary to convert single-byte
strings using codepage 1250 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             482




Chapter   16



Reference   for   unit   'cp1251'



16.1          Overview


The cp1251 unit registers single-byte codepage 1251.  This is necessary to convert single-byte
strings using codepage 1251 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             483




Chapter   17



Reference   for   unit   'cp1252'



17.1          Overview


The cp1252 unit registers single-byte codepage 1252.  This is necessary to convert single-byte
strings using codepage 1252 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             484




Chapter   18



Reference   for   unit   'cp1253'



18.1          Overview


The cp1253 unit registers single-byte codepage 1253.  This is necessary to convert single-byte
strings using codepage 1253 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             485




Chapter   19



Reference   for   unit   'cp1254'



19.1          Overview


The cp1254 unit registers single-byte codepage 1254.  This is necessary to convert single-byte
strings using codepage 1254 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             486




Chapter   20



Reference   for   unit   'cp1255'



20.1          Overview


The cp1255 unit registers single-byte codepage 1255.  This is necessary to convert single-byte
strings using codepage 1255 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             487




Chapter   21



Reference   for   unit   'cp1256'



21.1          Overview


The cp1256 unit registers single-byte codepage 1256.  This is necessary to convert single-byte
strings using codepage 1256 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             488




Chapter   22



Reference   for   unit   'cp1257'



22.1          Overview


The cp1257 unit registers single-byte codepage 1257.  This is necessary to convert single-byte
strings using codepage 1257 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             489




Chapter   23



Reference   for   unit   'cp1258'



23.1          Overview


The cp1258 unit registers single-byte codepage 1258.  This is necessary to convert single-byte
strings using codepage 1258 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             490




Chapter   24



Reference   for   unit   'cp437'



24.1          Overview


The cp437 unit registers single-byte codepage 437.  This is necessary to convert single-byte
strings using codepage 437 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             491




Chapter   25



Reference   for   unit   'cp646'



25.1          Overview


The cp646 unit registers single-byte codepage 646.  This is necessary to convert single-byte
strings using codepage 646 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             492




Chapter   26



Reference   for   unit   'cp850'



26.1          Overview


The cp850 unit registers single-byte codepage 850.  This is necessary to convert single-byte
strings using codepage 850 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             493




Chapter   27



Reference   for   unit   'cp852'



27.1          Overview


The cp852 unit registers single-byte codepage 852.  This is necessary to convert single-byte
strings using codepage 852 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             494




Chapter   28



Reference   for   unit   'cp856'



28.1          Overview


The cp856 unit registers single-byte codepage 856.  This is necessary to convert single-byte
strings using codepage 856 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             495




Chapter   29



Reference   for   unit   'cp866'



29.1          Overview


The cp866 unit registers single-byte codepage 866.  This is necessary to convert single-byte
strings using codepage 866 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             496




Chapter   30



Reference   for   unit   'cp874'



30.1          Overview


The cp874 unit registers single-byte codepage 874.  This is necessary to convert single-byte
strings using codepage 874 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             497




Chapter   31



Reference   for   unit   'cp8859 ___1'



31.1          Overview


The cp8859_1 unit registers single-byte codepage 8859-1.  This is necessary to convert single-
byte strings using codepage 8859-1 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             498




Chapter   32



Reference   for   unit   'cp8859 ___2'



32.1          Overview


The cp8859_2 unit registers single-byte codepage 8859-2.  This is necessary to convert single-
byte strings using codepage 8859-2 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             499




Chapter   33



Reference   for   unit   'cp8859 ___5'



33.1          Overview


The cp8859_5 unit registers single-byte codepage 8859-5.  This is necessary to convert single-
byte strings using codepage 8859-5 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             500




Chapter   34



Reference   for   unit   'cp895'



34.1          Overview


The cp895 unit registers single-byte codepage 895.  This is necessary to convert single-byte
strings using codepage 895 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             501




Chapter   35



Reference   for   unit   'cp932'



35.1          Overview


The cp932 unit registers single-byte codepage 932.  This is necessary to convert single-byte
strings using codepage 932 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             502




Chapter   36



Reference   for   unit   'cp936'



36.1          Overview


The cp936 unit registers single-byte codepage 936.  This is necessary to convert single-byte
strings using codepage 936 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             503




Chapter   37



Reference   for   unit   'cp949'



37.1          Overview


The cp949 unit registers single-byte codepage 949.  This is necessary to convert single-byte
strings using codepage 949 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             504




Chapter   38



Reference   for   unit   'cp950'



38.1          Overview


The cp950 unit registers single-byte codepage 950.  This is necessary to convert single-byte
strings using codepage 950 to unicode strings.

This  unit  does  not  contain  any  routines.   It  simply  registers  the  code  page  data  in  the
initialization section of the unit, so including the unit in the uses clause of the program is
sufficient.



                                                             505




Chapter   39



Reference   for   unit   'cpall'



39.1          Used  units



                                     Table 39.1:  Used units by unit 'cpall'


                                                  __Name____________Page_____
                                                    cp1250            482
                                                    cp1251            483
                                                    cp1252            484
                                                    cp1253            485
                                                    cp1254            486
                                                    cp1255            487
                                                    cp1256            488
                                                    cp1257            489
                                                    cp1258            490
                                                    cp437             491
                                                    cp646             492
                                                    cp850             493
                                                    cp852             494
                                                    cp856             495
                                                    cp866             496
                                                    cp874             497
                                                    cp8859_1          498
                                                    cp8859_2          499
                                                    cp8859_5          500
                                                    System          1235



39.2          Overview


The cpall unit registers all known single-byte codepages:  1251 (506  ), 866 (506  ), ISO 8856-5
(506  ) (cyrillic),  8859-1 (506  ),  8859-2 (506  ),  1253 (506  ) (greek),  850 (506  ),  437 (506  ),  1252
(506  ), 646 (506  ), 874 (506  ), 856 (506  ), 1250 (506  ), 1254 (506  ), 1255 (506  ), 1256 (506  ), 1257
(506  ), 1258 (506  ), 852 (506  ).

This unit does not contain any routines.  It simply uses the other units so all corresponding
code pages are registered.



                                                             506




Chapter   40



Reference   for   unit   'Crt'



40.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  The CRT unit is not thread safe.

     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.

     o  The CRT unit stems from the TP/Dos area.  It is designed to work with single-byte
        character sets, where 1 char = 1 byte.  That means that widestrings or UTF-8 encoded
        (ansi)strings will not correctly work.



40.2          Constants,  types  and  variables



40.2.1         Constants

Black  =  0


Black color attribute


Blink  =  128


Blink attribute



                                                             507

________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________________________*
 *___



Blue  =  1


Blue color attribute


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



                                                                 508

________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________________________*
 *___



Green  =  2


Green color attribute


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



                                                                 509

________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________________________*
 *___



40.2.2         Types

PConsoleBuf  =  ^TConsoleBuf



TCharAttr  =  packed  record
    ch  :  Char;
    attr  :  Byte;
end



TConsoleBuf  =  Array[0..ConsoleMaxX*ConsoleMaxY-1]  of  TCharAttr



tcrtcoord  =  1..255


tcrtcoord is a subrange type for denoting CRT coordinates.  It supports coordinates ranging
from 1 to 255.  Using this type together with range-checking turned on can be used to debug
CRT code.



40.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 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



                                                                 510

                ________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________*
 *___________________



                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


                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



                40.3          Procedures  and  functions



                40.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 (522  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 511

                ________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________*
 *___________________



                40.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 (514  ), InsLine (516  ), ClrScr (512  )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (522  )


                Listing:  ./crtex/ex8.pp



                                                                                 512

                ________________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (513  ), CursorOff (513  )



                40.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 (513  ), CursorBig (513  )



                40.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 (513  ), CursorOff (513  )



                                                                                 513

                ________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________*
 *___________________



                40.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 (519  ), NoSound (518  )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (512  ), InsLine (516  ), ClrScr (512  )


                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  ') ;



                                                                                 514

                ________________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.3.9         GotoXY

    Synopsis:    Set cursor position on screen.

Declaration:     procedure  GotoXY(X:  tcrtcoord;Y:  tcrtcoord)

    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 (521  ), WhereY (521  ), Window (522  )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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.



                                                                                 515

                ________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________*
 *___________________



    See also:    TextColor (520  ), TextBackground (519  ), LowVideo (517  ), NormVideo (517  )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (512  ), DelLine (514  ), ClrScr (512  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 516

                ________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________*
 *___________________



                40.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 (518  )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (515  )

       Errors:   None.

    See also:    TextColor (520  ), TextBackground (519  ), HighVideo (515  ), NormVideo (517  )



                40.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 (515  )



                                                                                 517

                ________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________*
 *___________________



       Errors:   None.

    See also:    TextColor (520  ), TextBackground (519  ), LowVideo (517  ), HighVideo (515  )



                40.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 (519  )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (517  )



                                                                                 518

                ________________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (518  )



                40.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 (520  ), HighVideo (515  ), LowVideo (517  ), NormVideo (517  )


                Listing:  ./crtex/ex13.pp



                                                                                 519

                ________________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (519  ), HighVideo (515  ), LowVideo (517  ), NormVideo (517  )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.3.20          TextMode

    Synopsis:    Set screen mode.

Declaration:     procedure  TextMode(Mode:  Word)

    Visibility:   default



                                                                                 520

                ________________________________________________________________CHAPTER_40.___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 (522  )



                40.3.21          WhereX

    Synopsis:    Return X (horizontal) cursor position

Declaration:     function  WhereX  :  tcrtcoord

    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 (515  ), WhereY (521  ), Window (522  )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.3.22          WhereY

    Synopsis:    Return Y (vertical) cursor position

Declaration:     function  WhereY  :  tcrtcoord

    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 (515  ), WhereX (521  ), Window (522  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 521

                ________________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'CRT'_____________*
 *___________________



                40.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 (515  ), WhereX (521  ), WhereY (521  ), ClrScr (512  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 522




                Chapter   41



                Reference   for   unit   'cthreads'



                41.1          Overview


                The CThreads unit initializes the system unit's thread management routines with an imple-
                mentation based on the POSIX thread managing routines in the C library.  This assures that
                C libraries that are thread-aware still work if they are linked to by a FPC program.

                It  doesn't  offer  any  API  by  itself:  the  initialization  section  of  the  unit  just  initializes  the
                ThreadManager record in the System (1235   ) unit.  This is done using the SetCThreadMan-
                ager (523  ) call

                The cthreads unit simply needs to be included in the uses clause of the program, preferably
                the very first unit, and the initialization section of the unit will do all the work.

                Note that including this unit links your program to the C library of the system.

                It makes no sense to use this unit on a non-posix system:  Windows, OS/2 or DOS, therefor
                it should always between an ifdef statement:


                program  myprogram;


                uses
                    {$ifdef  unix}cthreads{$endif},
                     classes,  sysutils;


                The Lazarus IDE inserts this conditional automatically for each new started program.



                41.2          Procedures  and  functions



                41.2.1         SetCThreadManager

    Synopsis:    Sets the thread manager to the C thread manager

Declaration:     procedure  SetCThreadManager

    Visibility:   default

Description:     SetCThreadManager  actually  sets  the  thread  manager  to  the  C  thread  manager.   It  can
                be called to re-set the thread manager if the thread manager was set to some other thread
                manager during the life-time of the program.



                                                                             523




Chapter   42



Reference   for   unit   'ctypes'



42.1          Used  units



                                    Table 42.1:  Used units by unit 'ctypes'


                                                  __Name____________Page_____
                                                    System          1235
                                                    unixtype        1798



42.2          Overview


The ctypes unit contains the definitions of commonly found C types.  It can be used when
interfaces to C libraries need to be defined.  The types here are correct on all platforms, 32
or 64 bit.

The main advantage of using this file is to make sure that all C header import units use the
same definitions for basic C types.

The h2pas program can include the ctypes unit automatically in the units it generates.  The
-C command-line switch can be used for this.



42.3          Constants,  types  and  variables



42.3.1         Types

cbool  =  UnixType.cbool


C boolean (longbool)


cchar  =  UnixType.cchar


C character type (No signedness specification, 8 bit integer)


cdouble  =  UnixType.cdouble


Double precision floating point type (double)



                                                             524

__________________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'CTYPES'________________________________*
 *___



cfloat  =  UnixType.cfloat


Single precision floating point type (single)


cint  =  UnixType.cint


C integer (commonly 32 bit)


cint16  =  UnixType.cint16


16-bit signed integer.


cint32  =  UnixType.cint32


32-bit signed integer (commonly:  int)


cint64  =  UnixType.cint64


64-bit integer


cint8  =  UnixType.cint8


8-bit signed integer


clong  =  UnixType.clong


long integer (32/64 bit, depending on CPU register size)


clongdouble  =  packed  Array[0..15]  of  Byte


Long precision floating point type (extended/double, depending on CPU)


clonglong  =  UnixType.clonglong


Long (64-bit) integer


coff_t  =  UnixType.TOff


Generic type to indicate offset


cschar  =  UnixType.cschar


C signed character type (8 bit signed integer)


cshort  =  UnixType.cshort


Short integer (16 bit)


csigned  =  UnixType.csigned


Signed integer (commonly 32 bit)



                                                                 525

__________________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'CTYPES'________________________________*
 *___



csint  =  UnixType.csint


Signed integer (commonly 32 bit)


csize_t  =  UnixType.size_t


Generic type to contain a size of all kinds of structures


cslong  =  UnixType.cslong


Signed long integer (32/64 bit, depending on CPU register size)


cslonglong  =  UnixType.cslonglong


Signed long (64-bit) integer


csshort  =  UnixType.csshort


Short signed integer (16 bit)


cuchar  =  UnixType.cuchar


C unsigned character type (8 bit unsigned integer).


cuint  =  UnixType.cuint


Unsigned integer (commonly 32 bit)


cuint16  =  UnixType.cuint16


16-bit unsigned integer.


cuint32  =  UnixType.cuint32


32-bit unsigned integer


cuint64  =  UnixType.cuint64


Unsigned 64-bit integer


cuint8  =  UnixType.cuint8


8-bit unsigned integer


culong  =  UnixType.culong


Unsigned long integer (32/64 bit, depending on CPU register size)


culonglong  =  UnixType.culonglong


Unsigned long (64-bit) integer



                                                                 526

__________________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'CTYPES'________________________________*
 *___



cunsigned  =  UnixType.cunsigned


Unsigned integer (commonly 32 bit)


cushort  =  UnixType.cushort


Short unsigned integer (16 bit)


pcbool  =  UnixType.pcbool


Pointer to cbool (524  ) type.


pcchar  =  UnixType.pcchar


Pointer to cchar (524  ) type.


pcdouble  =  UnixType.pcdouble


Pointer to cdouble (524  ) type.


pcfloat  =  UnixType.pcfloat


Pointer to cfloat (525  ) type.


pcint  =  UnixType.pcint


Pointer to cint (525  ) type.


pcint16  =  UnixType.pcint16


Pointer to cint16 (525  ) type.


pcint32  =  UnixType.pcint32


Pointer to cint32 (525  ) type.


pcint64  =  UnixType.pcint64


Pointer to cint64 (525  ) type.


pcint8  =  UnixType.pcint8


Pointer to cint8 (525  ) type.


pclong  =  UnixType.pclong


Pointer to clong (525  ) type.


Pclongdouble  =  ^clongdouble


Pointer to clongdouble (525  ) type.



                                                                 527

__________________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'CTYPES'________________________________*
 *___



pclonglong  =  UnixType.pclonglong


Pointer to clonglong (525  ) type.


pcschar  =  UnixType.pcschar


Pointer to cschar (525  ) type.


pcshort  =  UnixType.pcshort


Pointer to cshort (525  ) type.


pcsigned  =  UnixType.pcsigned


Pointer to csigned (525  ) type.


pcsint  =  UnixType.pcsint


Pointer to csint (526  ) type.


pcsize_t  =  UnixType.psize_t


Pointer to generic size type


pcslong  =  UnixType.pcslong


Pointer to cslong (526  ) type.


pcslonglong  =  UnixType.pcslonglong


Pointer to cslonglong (526  ) type.


pcsshort  =  UnixType.pcsshort


Pointer to csshort (526  ) type.


pcuchar  =  UnixType.pcuchar


Pointer to cuchar (526  ) type.


pcuint  =  UnixType.pcuint


Pointer to cuint (526  ) type.


pcuint16  =  UnixType.pcuint16


Pointer to cuint16 (526  ) type.


pcuint32  =  UnixType.pcuint32


Pointer to cuint32 (526  ) type.



                                                                 528

                __________________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                pcuint64  =  UnixType.pcuint64


                Pointer to cuint64 (526  ) type.


                pcuint8  =  UnixType.pcuint8


                Pointer to cuint8 (526  ) type.


                pculong  =  UnixType.pculong


                Pointer to culong (526  ) type.


                pculonglong  =  UnixType.pculonglong


                Pointer to culonglong (526  ) type.


                pcunsigned  =  UnixType.pcunsigned


                Pointer to cunsigned (527  ) type.


                pcushort  =  UnixType.pcushort


                Pointer to cushort (527  ) type.



                42.4          Procedures  and  functions



                42.4.1         add(clongdouble,Double):Double

    Synopsis:

Declaration:     operator  +(const  c:  clongdouble;const  e:  Double)  :  Double

    Visibility:   default

Description:     This operator allows to add clongdouble and double typed values.  The result is a double
                typed value.



                42.4.2         add(Double,clongdouble):Double

    Synopsis:    Implement addition of  clongdouble and double.

Declaration:     operator  +(const  e:  Double;const  c:  clongdouble)  :  Double

    Visibility:   default

Description:     This operator allows to add double and clongdouble typed values.  The result is a double
                typed value.



                42.4.3         assign(clongdouble):Double

    Synopsis:    Implement assignment of a clongdouble to a double type.

Declaration:     operator  :=(const  v:  clongdouble)  :  Double

    Visibility:   default

Description:     This operator allows to assign a clongdouble to a Double type.



                                                                                 529

                __________________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                42.4.4         assign(Double):clongdouble

    Synopsis:    Implement assignment of a double to a clongdouble type.

Declaration:     operator  :=(const  v:  Double)  :  clongdouble

    Visibility:   default

Description:     This operator allows to assign a double to a clongdouble type.



                42.4.5         divide(clongdouble,Double):Double

    Synopsis:    Implement division of  double and clongdouble.

Declaration:     operator  /(const  c:  clongdouble;const  e:  Double)  :  Double

    Visibility:   default

Description:     This operator allows to divide a clongdouble typed value by a double typed value.  the
                result is a double typed value.



                42.4.6         divide(Double,clongdouble):Double

    Synopsis:    Implement division of  clongdouble and double.

Declaration:     operator  /(const  e:  Double;const  c:  clongdouble)  :  Double

    Visibility:   default

Description:     This operator allows to divide a double typed value by a clongdouble typed value.  the
                result is a double typed value.



                42.4.7         equal(clongdouble,Double):Boolean

    Synopsis:    Implement equality of  clongdouble and double.

Declaration:     operator  =(const  c:  clongdouble;const  e:  Double)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a double typed value and a clongdouble typed value,
                and returns True if the values are equal (only double precision is used).



                42.4.8         equal(Double,clongdouble):Boolean

    Synopsis:    Implement equality of  double and clongdouble.

Declaration:     operator  =(const  e:  Double;const  c:  clongdouble)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a clongdouble typed value and a double typed value,
                and returns True if the values are equal (only double precision is used).



                                                                                 530

                __________________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                42.4.9         greaterthan(clongdouble,Double):Boolean

    Synopsis:    Implement greater than comparison between double and clongdouble.

Declaration:     operator  >(const  c:  clongdouble;const  e:  Double)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a clongdouble typed value and a double typed value,
                and returns True if the clongdouble value is greater than the double value.



                42.4.10          greaterthan(Double,clongdouble):Boolean

    Synopsis:    Implement greater than comparison between clongdouble and double.

Declaration:     operator  >(const  e:  Double;const  c:  clongdouble)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a double typed value and a clongdouble typed value,
                and returns True if the double value is greater than the clongdouble value.



                42.4.11          greaterthanorequal(clongdouble,Double):Boolean

    Synopsis:    Implement greater than or equal comparison between double and clongdouble.

Declaration:     operator  >=(const  c:  clongdouble;const  e:  Double)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a clongdouble typed value and a double typed value,
                and returns True if the clongdouble value is greater than or equal to the double value.



                42.4.12          greaterthanorequal(Double,clongdouble):Boolean

    Synopsis:    Implement greater than or equal comparison between clongdouble and double.

Declaration:     operator  >=(const  e:  Double;const  c:  clongdouble)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a double typed value and a clongdouble typed value,
                and returns True if the double value is greater than or equal to the clongdouble value.



                42.4.13          lessthan(clongdouble,Double):Boolean

    Synopsis:    Implement less than comparison between double and clongdouble.

Declaration:     operator  <(const  c:  clongdouble;const  e:  Double)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a clongdouble typed value and a double typed value,
                and returns True if the clongdouble value is less than the double value.



                                                                                 531

                __________________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                42.4.14          lessthan(Double,clongdouble):Boolean

    Synopsis:    Implement less than comparison between clongdouble and double.

Declaration:     operator  <(const  e:  Double;const  c:  clongdouble)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a double typed value and a clongdouble typed value,
                and returns True if the double value is less than the clongdouble value.



                42.4.15          lessthanorequal(clongdouble,Double):Boolean

    Synopsis:    Implement greater than or equal comparison between double and clongdouble.

Declaration:     operator  <=(const  c:  clongdouble;const  e:  Double)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a clongdouble typed value and a double typed value,
                and returns True if the clongdouble value is less than or equal to the double value.



                42.4.16          lessthanorequal(Double,clongdouble):Boolean

    Synopsis:    Implement less than or equal comparison between clongdouble and double.

Declaration:     operator  <=(const  e:  Double;const  c:  clongdouble)  :  Boolean

    Visibility:   default

Description:     This operator compares the values of a double typed value and a clongdouble typed value,
                and returns True if the double value is less than or equal to the clongdouble value.



                42.4.17          multiply(clongdouble,Double):Double

    Synopsis:    Implement multiplication of  clongdouble and double.

Declaration:     operator  *(const  c:  clongdouble;const  e:  Double)  :  Double

    Visibility:   default

Description:     This  operator  allows  to  multiply  a  double  typed  value  with  a  clongdouble  typed  value.
                the result is a double typed value.



                42.4.18          multiply(Double,clongdouble):Double

    Synopsis:    Implement multiplication of  double and clongdouble.

Declaration:     operator  *(const  e:  Double;const  c:  clongdouble)  :  Double

    Visibility:   default

Description:     This  operator  allows  to  multiply  a  clongdouble  typed  value  with  a  double  typed  value.
                The result is a double typed value.



                                                                                 532

                __________________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                42.4.19          subtract(clongdouble,Double):Double

    Synopsis:    Implement subtraction of  double and clongdouble.

Declaration:     operator  -(const  c:  clongdouble;const  e:  Double)  :  Double

    Visibility:   default

Description:     This  operator  allows  to  subtract  a  double  typed  value  from  a  clongdouble  typed  value.
                The result is a double typed value.



                42.4.20          subtract(Double,clongdouble):Double

    Synopsis:    Implement subtraction of  clongdouble and double.

Declaration:     operator  -(const  e:  Double;const  c:  clongdouble)  :  Double

    Visibility:   default

Description:     This  operator  allows  to  subtract  a  clongdouble  typed  value  from  a  double  typed  value.
                The result is a double typed value.



                                                                                 533




                Chapter   43



                Reference   for   unit   'cwstring'



                43.1          Overview


                The cwstring unit offers no API by itself:  it just initializes the widestring manager record
                of the system (1235   ) unit with an implementation that uses collation and conversion routines
                which are provided by the C library found on most Unix or Linux systems that are POSIX
                compliant.

                The cwstring should simply be included in the uses clause of the program, preferably as one
                of the first units, and the initialization section of the unit will do all the work.

                Note that including this unit links your program to the C library of the system.

                It  makes  no  sense  to  use  this  unit  on  a  non-POSIX  system  like  Windows,  OS/2  or  DOS.
                Therefor it should always be enclosed with an ifdef statement:


                program  myprogram;


                uses
                    {$ifdef  unix}cwstring,{$endif}
                     classes,  sysutils;



                43.2          Procedures  and  functions



                43.2.1         SetCWidestringManager

    Synopsis:    Set the Widestring manager of the system unit to the C version

Declaration:     procedure  SetCWidestringManager

    Visibility:   default

Description:     SetCWidestringManager  actually  sets  the  widestring  manager  record  of  the  system  unit.
                It is called automatically by the initialization section of the unit.



                                                                             534




Chapter   44



Reference   for   unit   'dateutils'



44.1          Used  units



                                   Table 44.1:  Used units by unit 'dateutils'


                                                   __Name__________Page_____
                                                     math            900
                                                     System        1235
                                                     sysutils      1489



44.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.



44.3          Constants,  types  and  variables



44.3.1         Constants

ApproxDaysPerMonth  :  Double  =  30.4375


Average number of days in a month, measured over a year.  Used in MonthsBetween (582  ).


ApproxDaysPerYear  :  Double  =  365.25


Average number of days in a year, measured over 4 years.  Used in YearsBetween (624  ).


DayFriday  =  5


ISO day number for Friday


DayMonday  =  1



                                                             535

____________________________________________________CHAPTER_44.___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)



                                                                 536

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                RecodeLeaveFieldAsIs  =  (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



                44.4          Procedures  and  functions



                44.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 (539  ),  CompareDateTime (538  ),  SameDate (592  ),  SameTime (594  ),  Same-
                DateTime (593  )


                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        ) ;



                                                                                 537

                ____________________________________________________CHAPTER_44.___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___.____________________________________________________________________________________________________________*
 *___________



                44.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  (539  ),  CompareDate  (537  ),  SameDate  (592  ),  SameTime  (594  ),  SameDate-
                Time (593  )


                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;



                                                                                 538

                ____________________________________________________CHAPTER_44.___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___.____________________________________________________________________________________________________________*
 *___________



                44.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  (538  ),  CompareDate  (537  ),  SameDate  (592  ),  SameTime  (594  ),  Same-
                DateTime (593  )


                Listing:  ./datutex/ex100.pp



                                                                                 539

                ____________________________________________________CHAPTER_44.___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___.____________________________________________________________________________________________________________*
 *___________



                44.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 (604  ), YearOf (624  ), MonthOf (582  ), DayOf (542  ), HourOf (557  ), MinuteOf (578  ),
                SecondOf (595  ), MilliSecondOf (574  )


                Listing:  ./datutex/ex1.pp



                                                                                 540

                ____________________________________________________CHAPTER_44.___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___.____________________________________________________________________________________________________________*
 *___________



                44.4.5         DateTimeToDosDateTime

    Synopsis:    Convert TDateTime format to DOS date/time format

Declaration:     function  DateTimeToDosDateTime(const  AValue:  TDateTime)  :  LongInt

    Visibility:   default

Description:     DateTimeToDosDatetime  takes  Value,  a  TDateTime  formatted  timestamp,  and  recodes  it
                to a MS-DOS encoded date/time value.  This is a longint with the date/time encoded in the
                bits as:


                0-4  Seconds divided by 2

                5-10   Minutes

                11-15    Hours

                16-20    Day

                21-24    Month

                25-31    Years since 1980


    See also:    DosDateTimeToDateTime (550  )



                44.4.6         DateTimeToJulianDate

    Synopsis:    Converts a TDateTime value to a Julian date representation

Declaration:     function  DateTimeToJulianDate(const  AValue:  TDateTime)  :  Double

    Visibility:   default

Description:     DateTimeToJulianDate converts the AValue date/time indication to a julian (as opposed
                to Gregorian) date.

    See also:    JulianDateToDateTime  (573  ),  TryJulianDateToDateTime  (609  ),  DateTimeToModifiedJu-
                lianDate (542  ), TryModifiedJulianDateToDateTime (609  )



                44.4.7         DateTimeToMac

    Synopsis:    Convert a TDateTime timestamp to a Mac timestamp

Declaration:     function  DateTimeToMac(const  AValue:  TDateTime)  :  Int64

    Visibility:   default



                                                                                 541

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



Description:     DateTimeToMac converts the TDateTime value AValue to a valid Mac timestamp indication
                and returns the result.

       Errors:   None.

    See also:    UnixTimeStampToMac (611  ), MacToDateTime (573  ), MacTimeStampToUnix (573  )



                44.4.8         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  (541  ),  JulianDateToDateTime  (573  ),  TryJulianDateToDateTime
                (609  ), TryModifiedJulianDateToDateTime (609  )



                44.4.9         DateTimeToUnix

    Synopsis:    Convert a TDateTime value to Unix epoch time

Declaration:     function  DateTimeToUnix(const  AValue:  TDateTime)  :  Int64

    Visibility:   default

Description:     DateTimeToUnix converts a TDateTime value to a epoch time (i.e.  the number of seconds
                elapsed since 1/1/1970).

    See also:    UnixToDateTime (611  )



                44.4.10          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 (624  )

    See also:    YearOf  (624  ),  WeekOf  (611  ),  MonthOf  (582  ),  HourOf  (557  ),  MinuteOf  (578  ),  SecondOf
                (595  ), MilliSecondOf (574  )



                                                                                 542

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.11          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 (612  ) function.

    See also:    DayOfTheYear  (543  ),  WeekOfTheMonth  (612  ),  HourOfTheMonth  (558  ),  MinuteOfThe-
                Month (579  ), SecondOfTheMonth (597  ), MilliSecondOfTheMonth (575  )



                44.4.12          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 (543  ),  DayOfTheMonth (543  ),  HourOfTheWeek (559  ),  MinuteOfTheWeek
                (579  ), SecondOfTheWeek (597  ), MilliSecondOfTheWeek (576  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.13          DayOfTheYear

    Synopsis:    Extracts the day of the year from a TDateTime value

Declaration:     function  DayOfTheYear(const  AValue:  TDateTime)  :  Word



                                                                                 543

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    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 (612  ) function.

    See also:    WeekOfTheYear (612  ), HourOfTheYear (559  ), MinuteOfTheYear (580  ), SecondOfTheYear
                (597  ), MilliSecondOfTheYear (576  )



                44.4.14          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  (624  ),  MonthsBetween  (582  ),  WeeksBetween  (613  ),  HoursBetween  (559  ),
                MinutesBetween (580  ), SecondsBetween (597  ), MilliSecondsBetween (576  )


                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 }


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 544

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.15          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 (614  ),  WeeksInYear (614  ),  DaysInYear (546  ),  DaysInAYear (545  ),  DaysIn-
                Month (546  )


                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. ') ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.16          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 (614  ), WeeksInYear (614  ), DaysInYear (546  ), DaysInMonth (546  ), DaysInA-
                Month (545  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 545

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.17          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 (614  ), WeeksInYear (614  ), DaysInYear (546  ), DaysInAYear (545  ), DaysInA-
                Month (545  )


                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    ;


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.18          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 (614  ), WeeksInYear (614  ), DaysInAYear (545  ), DaysInMonth (546  ), DaysI-
                nAMonth (545  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 546

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.19          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 (625  ),  MonthSpan (583  ),  WeekSpan (615  ),  HourSpan (560  ),  MinuteSpan (581  ),
                SecondSpan (598  ), MilliSecondSpan (577  ), DaysBetween (544  )


                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 }


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.20          DecodeDateDay

    Synopsis:    Decode a DateTime value in year and year of day.

Declaration:     procedure  DecodeDateDay(const  AValue:  TDateTime;out  AYear:  Word;
                                                      out  ADayOfYear:  Word)

    Visibility:   default



                                                                                 547

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



Description:     DecodeDateDay decomposes the date indication in AValue and returns the various compo-
                nents in AYear, ADayOfYear.

    See also:    EncodeDateTime  (551  ),  EncodeDateMonthWeek  (551  ),  EncodeDateWeek  (552  ),  Encode-
                DateDay  (551  ),  DecodeDateTime  (549  ),  DecodeDateWeek  (549  ),  DecodeDateMonthWeek
                (548  )


                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       ;


                Begin
                    DecodeDateDay          (Now   ,Y , DoY  ) ;
                    TS :=  EncodeDateDay          (Y , DoY  ) ;
                    W r i t e l n(' Today     i s   :  ' ,DateToStr       (TS   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.21          DecodeDateMonthWeek

    Synopsis:    Decode a DateTime value in a month, week of month and day of week

Declaration:     procedure  DecodeDateMonthWeek(const  AValue:  TDateTime;out  AYear:  Word;
                                                                out  AMonth:  Word;out  AWeekOfMonth:  Word;
                                                                out  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  (551  ),  EncodeDateMonthWeek  (551  ),  EncodeDateWeek  (552  ),  Encode-
                DateDay (551  ), DecodeDateTime (549  ), DecodeDateWeek (549  ), DecodeDateDay (547  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 548

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.22          DecodeDateTime

    Synopsis:    Decode a datetime value in a date and time value

Declaration:     procedure  DecodeDateTime(const  AValue:  TDateTime;out  AYear:  Word;
                                                        out  AMonth:  Word;out  ADay:  Word;out  AHour:  Word;
                                                        out  AMinute:  Word;out  ASecond:  Word;
                                                        out  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

    See also:    EncodeDateTime  (551  ),  EncodeDateMonthWeek  (551  ),  EncodeDateWeek  (552  ),  Encode-
                DateDay  (551  ),  DecodeDateWeek  (549  ),  DecodeDateDay  (547  ),  DecodeDateMonthWeek
                (548  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.23          DecodeDateWeek

    Synopsis:    Decode a DateTime value in a week of year and day of week.

Declaration:     procedure  DecodeDateWeek(const  AValue:  TDateTime;out  AYear:  Word;
                                                        out  AWeekOfYear:  Word;out  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  (551  ),  EncodeDateMonthWeek  (551  ),  EncodeDateWeek  (552  ),  Encode-
                DateDay  (551  ),  DecodeDateTime  (549  ),  DecodeDateDay  (547  ),  DecodeDateMonthWeek
                (548  )


                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}



                                                                                 549

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.24          DecodeDayOfWeekInMonth

    Synopsis:    Decode a DateTime value in year, month, day of week parts

Declaration:     procedure  DecodeDayOfWeekInMonth(const  AValue:  TDateTime;
                                                                     out  AYear:  Word;out  AMonth:  Word;
                                                                     out  ANthDayOfWeek:  Word;
                                                                     out  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 (584  ), EncodeDateMonthWeek (551  ), #rtl.sysutils.DayOfWeek (1548   ), En-
                codeDayOfWeekInMonth (552  ), TryEncodeDayOfWeekInMonth (608  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.25          DosDateTimeToDateTime

    Synopsis:    Convert DOS date/time format to TDateTime format

Declaration:     function  DosDateTimeToDateTime(AValue:  LongInt)  :  TDateTime

    Visibility:   default



                                                                                 550

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



Description:     DosDateTimeToDateTime  takes  a  DOS  encoded  date/time  AValue  and  recodes  it  as  a
                TDateTime value.

                The bit encoding of the DOS date/time is explained in the DateTimeToDosDateTime (541  )
                function.

    See also:    DateTimeToDosDateTime (541  )



                44.4.26          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 (547  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    EncodeDateMonthWeek  (551  ),  DecodeDateDay  (547  ),  EncodeDateTime  (551  ),  Encode-
                DateWeek (552  ), TryEncodeDateTime (606  ), TryEncodeDateMonthWeek (606  ), TryEncode-
                DateWeek (607  )



                44.4.27          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 (548  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    DecodeDateMonthWeek  (548  ),  EncodeDateTime  (551  ),  EncodeDateWeek  (552  ),  Encode-
                DateDay  (551  ),  TryEncodeDateTime  (606  ),  TryEncodeDateWeek  (607  ),  TryEncodeDate-
                MonthWeek (606  ), TryEncodeDateDay (605  ), NthDayOfWeek (584  )



                44.4.28          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



                                                                                 551

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



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 (549  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    DecodeDateTime  (549  ),  EncodeDateMonthWeek  (551  ),  EncodeDateWeek  (552  ),  Encode-
                DateDay (551  ), TryEncodeDateTime (606  ), TryEncodeDateWeek (607  ), TryEncodeDateDay
                (605  ), TryEncodeDateMonthWeek (606  )



                44.4.29          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 (549  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    EncodeDateMonthWeek  (551  ),  DecodeDateWeek  (549  ),  EncodeDateTime  (551  ),  Encode-
                DateDay  (551  ),  TryEncodeDateTime  (606  ),  TryEncodeDateWeek  (607  ),  TryEncodeDate-
                MonthWeek (606  )



                44.4.30          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 (550  ).

       Errors:   If any of the values is not in range, then an EConvertError exception will be raised.

    See also:    NthDayOfWeek (584  ), EncodeDateMonthWeek (551  ), #rtl.sysutils.DayOfWeek (1548   ), De-
                codeDayOfWeekInMonth (550  ), TryEncodeDayOfWeekInMonth (608  )



                                                                                 552

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.31          EncodeTimeInterval

    Synopsis:    Encode an interval as a TDateTime value.

Declaration:     function  EncodeTimeInterval(Hour:  Word;Minute:  Word;Second:  Word;
                                                             MilliSecond:  Word)  :  TDateTime

    Visibility:   default

Description:     EncodeTimeInterval  encodes  a  time  interval  expressed  in  Hour,  Min,  Sec,  MSec  as  a
                TDateTime value and returns the value in Time.

       Errors:   If Min, Sec, MSec do not contain a valid time indication, then an EConvertError exception
                is raised.

    See also:    TryEncodeTimeInterval (609  )



                44.4.32          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  (602  ),  StartOfADay  (599  ),  StartOfTheWeek  (603  ),  StartOfAWeek  (601  ),
                StartOfAMonth (600  ), StartOfTheMonth (602  ), EndOfTheWeek (556  ), EndOfAWeek (554  ),
                EndOfTheYear  (557  ),  EndOfAYear  (555  ),  EndOfTheMonth  (556  ),  EndOfAMonth  (554  ),
                EndOfTheDay (555  )


                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' ;


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 553

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.33          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  (602  ),  StartOfAMonth  (600  ),  EndOfTheMonth  (556  ),  EndOfTheYear
                (557  ), EndOfAYear (555  ), StartOfAWeek (601  ), StartOfTheWeek (603  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.34          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

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 (603  ), EndOfTheWeek (556  ), EndOfAWeek (554  ), StartOfAMonth (600  ),
                EndOfTheYear (557  ), EndOfAYear (555  ), EndOfTheMonth (556  ), EndOfAMonth (554  )


                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;



                                                                                 554

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.35          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 (603  ),  EndOfTheYear (557  ),  EndOfAYear (555  ),  EndOfTheMonth (556  ),
                EndOfAMonth (554  ), StartOfAWeek (601  ), StartOfTheWeek (603  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.36          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.



                                                                                 555

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    See also:    StartOftheDay  (602  ),  StartOfADay  (599  ),  StartOfTheWeek  (603  ),  StartOfAWeek  (601  ),
                StartOfAMonth (600  ), StartOfTheMonth (602  ), EndOfTheWeek (556  ), EndOfAWeek (554  ),
                EndOfTheYear  (557  ),  EndOfAYear  (555  ),  EndOfTheMonth  (556  ),  EndOfAMonth  (554  ),
                EndOfADay (553  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.37          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 (554  ) function.

    See also:    StartOfAMonth (600  ), StartOfTheMonth (602  ), EndOfAMonth (554  ), EndOfTheYear (557  ),
                EndOfAYear (555  ), StartOfAWeek (601  ), StartOfTheWeek (603  )


                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 ';


                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,EndOfTheMonth          (Today    ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.38          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



                                                                                 556

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    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 (554  ) function.

    See also:    StartOfAWeek  (601  ),  StartOfTheWeek  (603  ),  EndOfAWeek  (554  ),  StartOfAMonth  (600  ),
                EndOfTheYear (557  ), EndOfAYear (555  ), EndOfTheMonth (556  ), EndOfAMonth (554  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.39          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 (555  ) function.

    See also:    StartOfAYear (601  ), StartOfTheYear (603  ), EndOfTheMonth (556  ), EndOfAMonth (554  ),
                StartOfAWeek (601  ), StartOfTheWeek (603  ), EndOfAYear (555  )


                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
                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.40          HourOf

    Synopsis:    Extract the hour part from a DateTime value.



                                                                                 557

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



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 (624  )

    See also:    YearOf (624  ), WeekOf (611  ), MonthOf (582  ), DayOf (542  ), MinuteOf (578  ), SecondOf (595  ),
                MilliSecondOf (574  )



                44.4.41          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 (559  ), HourOfTheMonth (558  ), HourOfTheWeek (559  ), MinuteOfTheDay
                (578  ), SecondOfTheDay (595  ), MilliSecondOfTheDay (574  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.42          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 (612  ) function.



                                                                                 558

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    See also:    WeekOfTheMonth (612  ), DayOfTheMonth (543  ), MinuteOfTheMonth (579  ), SecondOfThe-
                Month (597  ), MilliSecondOfTheMonth (575  )



                44.4.43          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 (543  ) function.

    See also:    HourOfTheYear (559  ), HourOfTheMonth (558  ), HourOfTheDay (558  ), DayOfTheWeek (543  ),
                MinuteOfTheWeek (579  ), SecondOfTheWeek (597  ), MilliSecondOfTheWeek (576  )



                44.4.44          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 (612  ) function.

    See also:    WeekOfTheYear  (612  ),  DayOfTheYear  (543  ),  MinuteOfTheYear  (580  ),  SecondOfTheYear
                (597  ), MilliSecondOfTheYear (576  )



                44.4.45          HoursBetween

    Synopsis:    Calculate the number of whole hours between two DateTime values.

Declaration:     function  HoursBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                     :  Int64

    Visibility:   default

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 (624  ), MonthsBetween (582  ), WeeksBetween (613  ), DaysBetween (544  ), Min-
                utesBetween (580  ), SecondsBetween (597  ), MilliSecondsBetween (576  )


                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;



                                                                                 559

                ____________________________________________________CHAPTER_44.___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  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___.____________________________________________________________________________________________________________*
 *___________



                44.4.46          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  (625  ),  MonthSpan  (583  ),  WeekSpan  (615  ),  DaySpan  (547  ),  MinuteSpan  (581  ),
                SecondSpan (598  ), MilliSecondSpan (577  ), HoursBetween (559  )


                Listing:  ./datutex/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 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   ;



                                                                                 560

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.47          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  (564  ),  #rtl.sysutils.IncMonth  (1600   ),  IncWeek  (564  ),  IncHour  (561  ),  IncMinute
                (562  ), IncSecond (563  ), IncMilliSecond (562  )


                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;


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.48          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



                                                                                 561

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    Visibility:  default

Description:     IncHour adds ANumberOfHours hours to AValue and returns the resulting date/time.ANumberOfHours
                can be positive or negative.

    See also:    IncYear  (564  ),  #rtl.sysutils.IncMonth  (1600   ),  IncWeek  (564  ),  IncDay  (561  ),  IncMinute
                (562  ), IncSecond (563  ), IncMilliSecond (562  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.49          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 (564  ), #rtl.sysutils.IncMonth (1600   ), IncWeek (564  ), IncDay (561  ), IncHour (561  ),
                IncSecond (563  ), IncMilliSecond (562  )


                Listing:  ./datutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                44.4.50          IncMinute

    Synopsis:    Increase a DateTime value with a number of minutes.



                                                                                 562

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



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 (564  ), #rtl.sysutils.IncMonth (1600   ), IncWeek (564  ), IncDay (561  ), IncHour (561  ),
                IncSecond (563  ), IncMilliSecond (562  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.51          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 (564  ), #rtl.sysutils.IncMonth (1600   ), IncWeek (564  ), IncDay (561  ), IncHour (561  ),
                IncSecond (563  ), IncMilliSecond (562  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 563

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.52          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  (564  ),  #rtl.sysutils.IncMonth  (1600   ),  IncDay  (561  ),  IncHour  (561  ),  IncMinute
                (562  ), IncSecond (563  ), IncMilliSecond (562  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.53          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  (1600   ),  IncWeek  (564  ),  IncDay  (561  ),  IncHour  (561  ),  IncMinute
                (562  ), IncSecond (563  ), IncMilliSecond (562  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 564

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.54          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  (1653   )  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 (566  ), InvalidDateTimeError (565  ), InvalidDateMonthWeekError (565  ),
                InvalidDayOfWeekInMonthError (566  )



                44.4.55          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  (1653   )  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 (566  ), InvalidDateTimeError (565  ), InvalidDateDayError (565  ), In-
                validDayOfWeekInMonthError (566  )



                44.4.56          InvalidDateTimeError

    Synopsis:    Raise an EConvertError about an invalid date-time specification.

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  (1653   )  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.



                                                                                 565

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    See also:    InvalidDateWeekError (566  ), InvalidDateDayError (565  ), InvalidDateMonthWeekError (565  ),
                InvalidDayOfWeekInMonthError (566  )



                44.4.57          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  (1653   )  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 (565  ), InvalidDateDayError (565  ), InvalidDateMonthWeekError (565  ),
                InvalidDayOfWeekInMonthError (566  )



                44.4.58          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  (1653   )  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.

    See also:    InvalidDateWeekError (566  ), InvalidDateTimeError (565  ), InvalidDateDayError (565  ), In-
                validDateMonthWeekError (565  )



                44.4.59          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 (624  ), IsPM (567  ), IsToday (568  ), IsSameDay (567  )


                Listing:  ./datutex/ex3.pp



                                                                                 566

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.60          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 (624  ), IsInLeapYear (566  ), IsToday (568  ), IsSameDay (567  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.61          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 (604  ), Yesterday (626  ), Tomorrow (605  ), IsToday (568  )


                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;



                                                                                 567

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.62          IsSameMonth

    Synopsis:    Check if 2 dates are in the same month.

Declaration:     function  IsSameMonth(const  Avalue:  TDateTime;const  ABasis:  TDateTime)
                                                   :  Boolean

    Visibility:   default

Description:     IsSameMonth will return True if the two dates Avalue and ABasis occur in the same year
                and month.  (i.e.  if their month and year parts match).  Otherwise, False is returned.

    See also:    IsSameDay (567  ), IsToday (568  ), SameDate (592  )



                44.4.63          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 (604  ), Yesterday (626  ), Tomorrow (605  ), IsSameDay (567  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 568

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.64          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 (572  ), IsValidDateTime (571  ), IsValidDateDay (569  ), IsValidDateWeek (572  ),
                IsValidDateMonthWeek (570  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.65          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 (569  ), IsValidTime (572  ), IsValidDateTime (571  ), IsValidDateWeek (572  ), Is-
                ValidDateMonthWeek (570  )


                Listing:  ./datutex/ex9.pp



                                                                                 569

                ____________________________________________________CHAPTER_44.___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___.____________________________________________________________________________________________________________*
 *___________



                44.4.66          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  (569  ),  IsValidTime  (572  ),  IsValidDateTime  (571  ),  IsValidDateDay  (569  ),  Is-
                ValidDateWeek (572  )


                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



                                                                                 570

                ____________________________________________________CHAPTER_44.___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___.____________________________________________________________________________________________________________*
 *___________



                44.4.67          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  (569  ),  IsValidTime  (572  ),  IsValidDateDay  (569  ),  IsValidDateWeek  (572  ),  Is-
                ValidDateMonthWeek (570  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 571

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.68          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  (569  ),  IsValidTime  (572  ),  IsValidDateTime  (571  ),  IsValidDateDay  (569  ),  Is-
                ValidDateMonthWeek (570  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.69          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.



                                                                                 572

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.70          JulianDateToDateTime

    Synopsis:    Convert a Julian date representation to a TDateTime value.

Declaration:     function  JulianDateToDateTime(const  AValue:  Double)  :  TDateTime

    Visibility:   default

Description:     JulianDateToDateTime converts the Julian AValue date/time indication to a regular TDateTime
                date/time indication.

    See also:    DateTimeToJulianDate  (541  ),  TryJulianDateToDateTime  (609  ),  DateTimeToModifiedJu-
                lianDate (542  ), TryModifiedJulianDateToDateTime (609  )



                44.4.71          LocalTimeToUniversal

    Synopsis:    Convert local time to UTC time

Declaration:     function  LocalTimeToUniversal(LT:  TDateTime)  :  TDateTime
                function  LocalTimeToUniversal(LT:  TDateTime;TZOffset:  Integer)
                                                                  :  TDateTime

    Visibility:   default

Description:     UniversalTimeToLocal converts a local time indication to a universal time indication:  it
                undoes the TZOffset timezone offset from the UT Universal time (UTC). If no TZOffset is
                specified, the local time offset as returned by GetLocalTimeOffset (535  ) is used.

    See also:    GetLocalTimeOffset (535  ), UniversalTimeToLocal (610  )



                44.4.72          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 (611  ), DateTimeToMac (541  ), MacToDateTime (573  )



                44.4.73          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 (611  ), DateTimeToMac (541  ), MacTimeStampToUnix (573  )



                                                                                 573

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.74          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 (624  )

    See also:    YearOf (624  ), WeekOf (611  ), MonthOf (582  ), DayOf (542  ), HourOf (557  ), MinuteOf (578  ),
                MilliSecondOf (574  )



                44.4.75          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 (558  ) function.

    See also:    MilliSecondOfTheYear (576  ), MilliSecondOfTheMonth (575  ), MilliSecondOfTheWeek (576  ),
                MilliSecondOfTheHour (574  ), MilliSecondOfTheMinute (574  ), MilliSecondOfTheSecond (575  ),
                HourOfTheDay (558  ), MinuteOfTheDay (578  ), SecondOfTheDay (595  )



                44.4.76          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 (578  ) function.

    See also:    MilliSecondOfTheYear (576  ), MilliSecondOfTheMonth (575  ), MilliSecondOfTheWeek (576  ),
                MilliSecondOfTheDay (574  ), MilliSecondOfTheMinute (574  ), MilliSecondOfTheSecond (575  ),
                MinuteOfTheHour (578  ), SecondOfTheHour (596  )



                44.4.77          MilliSecondOfTheMinute

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the minute

Declaration:     function  MilliSecondOfTheMinute(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default



                                                                                 574

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



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 (596  ) function.

    See also:    MilliSecondOfTheYear (576  ), MilliSecondOfTheMonth (575  ), MilliSecondOfTheWeek (576  ),
                MilliSecondOfTheDay (574  ), MilliSecondOfTheHour (574  ), MilliSecondOfTheMinute (574  ),
                MilliSecondOfTheSecond (575  ), SecondOfTheMinute (596  )



                44.4.78          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 (612  ) function.

    See also:    WeekOfTheMonth (612  ),  DayOfTheMonth (543  ),  HourOfTheMonth (558  ),  MinuteOfThe-
                Month (579  ), SecondOfTheMonth (597  ), MilliSecondOfTheMonth (575  )



                44.4.79          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 (576  ), MilliSecondOfTheMonth (575  ), MilliSecondOfTheWeek (576  ),
                MilliSecondOfTheDay (574  ), MilliSecondOfTheHour (574  ), MilliSecondOfTheMinute (574  ),
                SecondOfTheMinute (596  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 575

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.80          MilliSecondOfTheWeek

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the week

Declaration:     function  MilliSecondOfTheWeek(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

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 (543  ) function.

    See also:    MilliSecondOfTheYear (576  ), MilliSecondOfTheMonth (575  ), MilliSecondOfTheDay (574  ),
                MilliSecondOfTheHour (574  ), MilliSecondOfTheMinute (574  ), MilliSecondOfTheSecond (575  ),
                DayOfTheWeek (543  ), HourOfTheWeek (559  ), MinuteOfTheWeek (579  ), SecondOfTheWeek
                (597  )



                44.4.81          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 (612  ) function.

    See also:    WeekOfTheYear  (612  ),  DayOfTheYear  (543  ),  HourOfTheYear  (559  ),  MinuteOfTheYear
                (580  ), SecondOfTheYear (597  ), MilliSecondOfTheYear (576  )



                44.4.82          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 (624  ), MonthsBetween (582  ), WeeksBetween (613  ), DaysBetween (544  ), Hours-
                Between (559  ), MinutesBetween (580  ), SecondsBetween (597  )


                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       ) ;



                                                                                 576

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                 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   ;


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.83          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 (625  ), MonthSpan (583  ), WeekSpan (615  ), DaySpan (547  ), HourSpan (560  ), Min-
                uteSpan (581  ), SecondSpan (598  ), MilliSecondsBetween (576  )


                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       ;



                                                                                 577

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.84          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 (624  )

    See also:    YearOf (624  ), WeekOf (611  ), MonthOf (582  ), DayOf (542  ), HourOf (557  ), SecondOf (595  ),
                MilliSecondOf (574  )



                44.4.85          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 (558  ) function.

    See also:    MinuteOfTheYear (580  ), MinuteOfTheMonth (579  ), MinuteOfTheWeek (579  ), MinuteOfThe-
                Hour (578  ), HourOfTheDay (558  ), SecondOfTheDay (595  ), MilliSecondOfTheDay (574  )



                44.4.86          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.



                                                                                 578

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    See also:    MinuteOfTheYear (580  ), MinuteOfTheMonth (579  ), MinuteOfTheWeek (579  ), MinuteOfThe-
                Day (578  ), SecondOfTheHour (596  ), MilliSecondOfTheHour (574  )


                Listing:  ./datutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                44.4.87          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 (612  ) function.

    See also:    WeekOfTheMonth (612  ),  DayOfTheMonth (543  ),  HourOfTheMonth (558  ),  MinuteOfThe-
                Month (579  ), SecondOfTheMonth (597  ), MilliSecondOfTheMonth (575  )



                44.4.88          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 (543  ) function.

    See also:    MinuteOfTheYear (580  ), MinuteOfTheMonth (579  ), MinuteOfTheDay (578  ), MinuteOfThe-
                Hour  (578  ),  DayOfTheWeek  (543  ),  HourOfTheWeek  (559  ),  SecondOfTheWeek  (597  ),  Mil-
                liSecondOfTheWeek (576  )



                                                                                 579

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.89          MinuteOfTheYear

    Synopsis:    Calculate the number of minutes elapsed since the start of the year

Declaration:     function  MinuteOfTheYear(const  AValue:  TDateTime)  :  LongWord

    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 (612  ) function.

    See also:    WeekOfTheYear  (612  ),  DayOfTheYear  (543  ),  HourOfTheYear  (559  ),  MinuteOfTheYear
                (580  ), SecondOfTheYear (597  ), MilliSecondOfTheYear (576  )



                44.4.90          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 (624  ), MonthsBetween (582  ), WeeksBetween (613  ), DaysBetween (544  ), Hours-
                Between (559  ), SecondsBetween (597  ), MilliSecondsBetween (576  )


                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       ) ;



                                                                                 580

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.91          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 (625  ), MonthSpan (583  ), WeekSpan (615  ), DaySpan (547  ), HourSpan (560  ), Sec-
                ondSpan (598  ), MilliSecondSpan (577  ), MinutesBetween (580  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 581

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.92          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.

       Errors:   Currently, trying to use this function will raise an exception.

    See also:    DateTimeToJulianDate  (541  ),  JulianDateToDateTime  (573  ),  TryJulianDateToDateTime
                (609  ), DateTimeToModifiedJulianDate (542  ), TryModifiedJulianDateToDateTime (609  )



                44.4.93          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 (624  )

    See also:    YearOf (624  ), DayOf (542  ), WeekOf (611  ), HourOf (557  ), MinuteOf (578  ), SecondOf (595  ),
                MilliSecondOf (574  )



                44.4.94          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
                (582  ),  and  is  provided  for  completeness  only,  corresponding  to  the  other  PartOfTheYear
                functions.

                For an example, see the WeekOfTheYear (612  ) function.

    See also:    MonthOf (582  ), WeekOfTheYear (612  ), DayOfTheYear (543  ), HourOfTheYear (559  ), Min-
                uteOfTheYear (580  ), SecondOfTheYear (597  ), MilliSecondOfTheYear (576  )



                44.4.95          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.



                                                                                 582

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    See also:    YearsBetween (624  ), WeeksBetween (613  ), DaysBetween (544  ), HoursBetween (559  ), Min-
                utesBetween (580  ), SecondsBetween (597  ), MilliSecondsBetween (576  )


                Listing:  ./datutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                44.4.96          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  (625  ),  WeekSpan  (615  ),  DaySpan  (547  ),  HourSpan  (560  ),  MinuteSpan  (581  ),
                SecondSpan (598  ), MilliSecondSpan (577  ), MonthsBetween (582  )


                Listing:  ./datutex/ex64.pp



                                                                                 583

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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;


                 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___.____________________________________________________________________________________________________________*
 *___________



                44.4.97          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 occurrence 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 (551  ), #rtl.sysutils.DayOfWeek (1548   ), DecodeDayOfWeekInMonth
                (550  ), EncodeDayOfWeekInMonth (552  ), TryEncodeDayOfWeekInMonth (608  )


                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  ' ) ;



                                                                                 584

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    W r i t e l n(formatdateTime          ( ' dddd   ' ,Today    ) , '  o f  t h e  month    . ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.98          PeriodBetween

    Synopsis:    Return the period (in years, months, days) between two dates

Declaration:     procedure  PeriodBetween(const  ANow:  TDateTime;const  AThen:  TDateTime;
                                                      out  Years:  Word;out  months:  Word;out  days:  Word)

    Visibility:   default

Description:     PeriodBetween  returns  the  timespan  between  2  dates  (ANow  and  AThen),  expressed  as  a
                number of years, months and days in the parameters Years, months and days.  Only complete
                years, months and days are reported.

                If  ANow is before AThen, their values are reversed so the result is always positive.

    See also:    YearsBetween (624  ), MonthsBetween (582  ), WeeksBetween (613  ), DaysBetween (544  )



                44.4.99          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 (626  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.100           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



                                                                                 585

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    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 (592  ), RecodeMonth (590  ), RecodeDay (587  ), RecodeHour (588  ), RecodeMinute
                (589  ), RecodeSecond (590  ), RecodeDate (585  ), RecodeTime (591  ), RecodeDateTime (586  )


                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 ';


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.101           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  (537  ),  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 (592  ), RecodeMonth (590  ), RecodeDay (587  ), RecodeHour (588  ), RecodeMinute
                (589  ), RecodeSecond (590  ), RecodeMilliSecond (588  ), RecodeDate (585  ), RecodeTime (591  ),
                TryRecodeDateTime (610  )


                Listing:  ./datutex/ex96.pp



                                                                                 586

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.102           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 till the number of days in the month) then
                an EConvertError exception is raised.

    See also:    RecodeYear (592  ), RecodeMonth (590  ), RecodeHour (588  ), RecodeMinute (589  ), RecodeSec-
                ond  (590  ),  RecodeMilliSecond  (588  ),  RecodeDate  (585  ),  RecodeTime  (591  ),  RecodeDate-
                Time (586  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 587

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.103           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 (592  ), RecodeMonth (590  ), RecodeDay (587  ), RecodeMinute (589  ), RecodeSec-
                ond  (590  ),  RecodeMilliSecond  (588  ),  RecodeDate  (585  ),  RecodeTime  (591  ),  RecodeDate-
                Time (586  )


                Listing:  ./datutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                44.4.104           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 (592  ), RecodeMonth (590  ), RecodeDay (587  ), RecodeHour (588  ), RecodeMinute
                (589  ), RecodeSecond (590  ), RecodeDate (585  ), RecodeTime (591  ), RecodeDateTime (586  )


                Listing:  ./datutex/ex93.pp



                                                                                 588

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.105           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 (592  ), RecodeMonth (590  ), RecodeDay (587  ), RecodeHour (588  ), RecodeSec-
                ond  (590  ),  RecodeMilliSecond  (588  ),  RecodeDate  (585  ),  RecodeTime  (591  ),  RecodeDate-
                Time (586  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 589

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.106           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 (592  ), RecodeDay (587  ), RecodeHour (588  ), RecodeMinute (589  ), RecodeSec-
                ond  (590  ),  RecodeMilliSecond  (588  ),  RecodeDate  (585  ),  RecodeTime  (591  ),  RecodeDate-
                Time (586  )


                Listing:  ./datutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                44.4.107           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 (592  ), RecodeMonth (590  ), RecodeDay (587  ), RecodeHour (588  ), RecodeMinute
                (589  ),  RecodeMilliSecond  (588  ),  RecodeDate  (585  ),  RecodeTime  (591  ),  RecodeDateTime
                (586  )


                Listing:  ./datutex/ex92.pp



                                                                                 590

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.108           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 (592  ), RecodeMonth (590  ), RecodeDay (587  ), RecodeHour (588  ), RecodeMinute
                (589  ), RecodeSecond (590  ), RecodeMilliSecond (588  ), RecodeDate (585  ), RecodeDateTime
                (586  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 591

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.109           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 (590  ), RecodeDay (587  ), RecodeHour (588  ), RecodeMinute (589  ), RecodeSec-
                ond  (590  ),  RecodeMilliSecond  (588  ),  RecodeDate  (585  ),  RecodeTime  (591  ),  RecodeDate-
                Time (586  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.110           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 (537  ) returns zero.

    See also:    CompareDateTime (538  ), CompareDate (537  ), CompareTime (539  ), SameDateTime (593  ),
                SameTime (594  )


                Listing:  ./datutex/ex102.pp



                                                                                 592

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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    ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.111           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 (538  ) returns zero.

    See also:    CompareDateTime (538  ), CompareDate (537  ), CompareTime (539  ), SameDate (592  ), Same-
                Time (594  )


                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 ';



                                                                                 593

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                44.4.112           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 (539  ) returns zero.

    See also:    CompareDateTime (538  ), CompareDate (537  ), CompareTime (539  ), SameDateTime (593  ),
                SameDate (592  )


                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       ;



                                                                                 594

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.113           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

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 (1589   ) 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 (1653   ) exception is raised.

    See also:    FormatDateTime (1589   )



                44.4.114           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 (624  )

    See also:    YearOf (624  ), WeekOf (611  ), MonthOf (582  ), DayOf (542  ), HourOf (557  ), MinuteOf (578  ),
                MilliSecondOf (574  )



                44.4.115           SecondOfTheDay

    Synopsis:    Calculate the number of seconds elapsed since the start of the day

Declaration:     function  SecondOfTheDay(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default



                                                                                 595

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



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 (558  ) function.

    See also:    SecondOfTheYear (597  ), SecondOfTheMonth (597  ), SecondOfTheWeek (597  ), SecondOfThe-
                Hour (596  ), SecondOfTheMinute (596  ), HourOfTheDay (558  ), MinuteOfTheDay (578  ), Mil-
                liSecondOfTheDay (574  )



                44.4.116           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 (578  ) function.

    See also:    SecondOfTheYear (597  ), SecondOfTheMonth (597  ), SecondOfTheWeek (597  ), SecondOfThe-
                Day (595  ), SecondOfTheMinute (596  ), MinuteOfTheHour (578  ), MilliSecondOfTheHour (574  )



                44.4.117           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 (597  ), SecondOfTheMonth (597  ), SecondOfTheWeek (597  ), SecondOfThe-
                Day (595  ), SecondOfTheHour (596  ), MilliSecondOfTheMinute (574  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 596

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.118           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 (612  ) function.

    See also:    WeekOfTheMonth (612  ),  DayOfTheMonth (543  ),  HourOfTheMonth (558  ),  MinuteOfThe-
                Month (579  ), MilliSecondOfTheMonth (575  )



                44.4.119           SecondOfTheWeek

    Synopsis:    Calculate the number of seconds elapsed since the start of the week

Declaration:     function  SecondOfTheWeek(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

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 (543  ) function.

    See also:    SecondOfTheYear (597  ), SecondOfTheMonth (597  ), SecondOfTheDay (595  ), SecondOfThe-
                Hour (596  ), SecondOfTheMinute (596  ), DayOfTheWeek (543  ), HourOfTheWeek (559  ), Min-
                uteOfTheWeek (579  ), MilliSecondOfTheWeek (576  )



                44.4.120           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 (612  ) function.

    See also:    WeekOfTheYear  (612  ),  DayOfTheYear  (543  ),  HourOfTheYear  (559  ),  MinuteOfTheYear
                (580  ), SecondOfTheYear (597  ), MilliSecondOfTheYear (576  )



                44.4.121           SecondsBetween

    Synopsis:    Calculate the number of whole seconds between two DateTime values.

Declaration:     function  SecondsBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                        :  Int64

    Visibility:   default



                                                                                 597

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



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 (624  ), MonthsBetween (582  ), WeeksBetween (613  ), DaysBetween (544  ), Hours-
                Between (559  ), MinutesBetween (580  ), MilliSecondsBetween (576  )


                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
                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.122           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 (625  ), MonthSpan (583  ), WeekSpan (615  ), DaySpan (547  ), HourSpan (560  ), Min-
                uteSpan (581  ), MilliSecondSpan (577  ), SecondsBetween (597  )


                Listing:  ./datutex/ex69.pp



                                                                                 598

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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;
                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.123           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 (602  ), StartOfTheWeek (603  ), StartOfAWeek (601  ), StartOfAMonth (600  ),
                StartOfTheMonth (602  ), EndOfTheWeek (556  ), EndOfAWeek (554  ), EndOfTheYear (557  ),
                EndOfAYear  (555  ),  EndOfTheMonth  (556  ),  EndOfAMonth  (554  ),  EndOfTheDay  (555  ),
                EndOfADay (553  )


                Listing:  ./datutex/ex38.pp



                                                                                 599

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.124           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 (602  ), EndOfTheMonth (556  ), EndOfAMonth (554  ), EndOfTheYear (557  ),
                EndOfAYear (555  ), StartOfAWeek (601  ), StartOfTheWeek (603  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 600

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.125           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 (603  ), EndOfTheWeek (556  ), EndOfAWeek (554  ), StartOfAMonth (600  ),
                EndOfTheYear (557  ), EndOfAYear (555  ), EndOfTheMonth (556  ), EndOfAMonth (554  )


                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;


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.126           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 (603  ),  EndOfTheYear (557  ),  EndOfAYear (555  ),  EndOfTheMonth (556  ),
                EndOfAMonth (554  ), StartOfAWeek (601  ), StartOfTheWeek (603  )


                Listing:  ./datutex/ex26.pp



                                                                                 601

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.127           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.

    See also:    StartOfADay  (599  ),  StartOfTheWeek  (603  ),  StartOfAWeek  (601  ),  StartOfAMonth  (600  ),
                StartOfTheMonth (602  ), EndOfTheWeek (556  ), EndOfAWeek (554  ), EndOfTheYear (557  ),
                EndOfAYear (555  ), EndOfTheMonth (556  ), EndOfAMonth (554  ), EndOftheDay (555  ), End-
                OfADay (553  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.128           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  (600  )
                function.



                                                                                 602

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    See also:    StartOfAMonth  (600  ),  EndOfTheYear  (557  ),  EndOfAYear  (555  ),  EndOfTheMonth  (556  ),
                EndOfAMonth (554  ), StartOfAWeek (601  ), StartOfTheWeek (603  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.129           StartOfTheWeek

    Synopsis:    Return the first day of the week, given a date.

Declaration:     function  StartOfTheWeek(const  AValue:  TDateTime)  :  TDateTime

    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 (601  ) function.

    See also:    StartOfAWeek  (601  ),  EndOfTheWeek  (556  ),  EndOfAWeek  (554  ),  StartOfAMonth  (600  ),
                EndOfTheYear (557  ), EndOfAYear (555  ), EndOfTheMonth (556  ), EndOfAMonth (554  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.130           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 (601  ) function.



                                                                                 603

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    See also:    StartOfAYear (601  ), EndOfTheYear (557  ), EndOfAYear (555  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.131           TimeOf

    Synopsis:    Extract the time part from a DateTime indication.

Declaration:     function  TimeOf(const  AValue:  TDateTime)  :  TDateTime

    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 (540  ), YearOf (624  ), MonthOf (582  ), DayOf (542  ), HourOf (557  ), MinuteOf (578  ),
                SecondOf (595  ), MilliSecondOf (574  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.132           Today

    Synopsis:    Return the current date

Declaration:     function  Today  :  TDateTime

    Visibility:   default

Description:     Today is an alias for the Date (1543   ) function in the sysutils (1489   ) unit.

                For an example, see Yesterday (626  )

    See also:    Date (1543   ), Yesterday (626  ), Tomorrow (605  )



                                                                                 604

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.133           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 (604  ) +1.

    See also:    Today (604  ), Yesterday (626  )


                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          ( ' "Today      i s "  dd   mmmm     y y y y' ,Today    ) ) ;
                    W r i t e l n(FormatDateTime          ( ' "Tomorrow         w i l l be  "  dd  mmmm      y y y y' ,Tomorrow    *
 *   ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.134           TryEncodeDateDay

    Synopsis:    Encode a year and day of year to a TDateTime value

Declaration:     function  TryEncodeDateDay(const  AYear:  Word;const  ADayOfYear:  Word;
                                                         out  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  (551  ),  EncodeDateTime  (551  ),  EncodeDateMonthWeek  (551  ),  Encode-
                DateWeek (552  ), TryEncodeDateTime (606  ), TryEncodeDateMonthWeek (606  ), TryEncode-
                DateWeek (607  )


                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  ) ;



                                                                                 605

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.135           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;
                                                                   out  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  (548  ),  EncodeDateTime  (551  ),  EncodeDateWeek  (552  ),  Encode-
                DateDay (551  ), EncodeDateMonthWeek (551  ), TryEncodeDateTime (606  ), TryEncodeDate-
                Week (607  ), TryEncodeDateDay (605  ), NthDayOfWeek (584  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.136           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;
                                                           out  AValue:  TDateTime)  :  Boolean



                                                                                 606

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    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  (551  ),  EncodeDateMonthWeek  (551  ),  EncodeDateWeek  (552  ),  Encode-
                DateDay (551  ), TryEncodeDateDay (605  ), TryEncodeDateWeek (607  ), TryEncodeDateMon-
                thWeek (606  )


                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
                        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___.____________________________________________________________________________________________________________*
 *___________



                44.4.137           TryEncodeDateWeek

    Synopsis:    Encode a year, week and day of week triplet to a TDateTime value

Declaration:     function  TryEncodeDateWeek(const  AYear:  Word;const  AWeekOfYear:  Word;
                                                           out  AValue:  TDateTime;const  ADayOfWeek:  Word)
                                                             :  Boolean
                function  TryEncodeDateWeek(const  AYear:  Word;const  AWeekOfYear:  Word;
                                                           out  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  (551  ),  EncodeDateWeek  (552  ),  EncodeDateTime  (551  ),  Encode-
                DateDay (551  ), TryEncodeDateTime (606  ), TryEncodeDateMonthWeek (606  ), TryEncode-
                DateDay (605  )


                Listing:  ./datutex/ex82.pp



                                                                                 607

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.138           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;
                                                                        out  AValue:  TDateTime)  :  Boolean

    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 (584  ), EncodeDateMonthWeek (551  ), #rtl.sysutils.DayOfWeek (1548   ), De-
                codeDayOfWeekInMonth (550  ), EncodeDayOfWeekInMonth (552  )


                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   ') ;



                                                                                 608

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                        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___.____________________________________________________________________________________________________________*
 *___________



                44.4.139           TryEncodeTimeInterval

    Synopsis:    Try to encode an interval as a TDateTime value.

Declaration:     function  TryEncodeTimeInterval(Hour:  Word;Min:  Word;Sec:  Word;
                                                                  MSec:  Word;out  Time:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryEncodeTimeInterval  encodes  a  time  interval  expressed  in  Hour,  Min,  Sec,  MSec  as  a
                TDateTime value and returns the value in Time.  It returns True if  Min, Sec, MSec contain
                valid  time  values  (i.e.  less  than  60,  60  resp.  MSec).  The  number  of  hours  may  be  larger
                than 24.

    See also:    EncodeTimeInterval (553  )



                44.4.140           TryJulianDateToDateTime

    Synopsis:    Convert a Julian date representation to a TDateTime value.

Declaration:     function  TryJulianDateToDateTime(const  AValue:  Double;
                                                                     out  ADateTime:  TDateTime)  :  Boolean

    Visibility:   default

Description:     Try to convert a Julian date to a regular TDateTime date/time representation.

    See also:    DateTimeToJulianDate  (541  ),  JulianDateToDateTime  (573  ),  DateTimeToModifiedJulian-
                Date (542  ), TryModifiedJulianDateToDateTime (609  )



                44.4.141           TryModifiedJulianDateToDateTime

    Synopsis:    Convert a modified Julian date representation to a TDateTime value.

Declaration:     function  TryModifiedJulianDateToDateTime(const  AValue:  Double;
                                                                                  out  ADateTime:  TDateTime)
                                                                                    :  Boolean

    Visibility:   default

Description:     Not yet implemented.

       Errors:   Currently, trying to use this function will raise an exception.

    See also:    DateTimeToJulianDate  (541  ),  JulianDateToDateTime  (573  ),  TryJulianDateToDateTime
                (609  ), DateTimeToModifiedJulianDate (542  ), ModifiedJulianDateToDateTime (582  )



                                                                                 609

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.142           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;
                                                           out  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  (537  ),  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 (592  ), RecodeMonth (590  ), RecodeDay (587  ), RecodeHour (588  ), RecodeMinute
                (589  ), RecodeSecond (590  ), RecodeMilliSecond (588  ), RecodeDate (585  ), RecodeTime (591  ),
                RecodeDateTime (586  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.143           UniversalTimeToLocal

    Synopsis:    Convert UTC time to local time

Declaration:     function  UniversalTimeToLocal(UT:  TDateTime)  :  TDateTime
                function  UniversalTimeToLocal(UT:  TDateTime;TZOffset:  Integer)
                                                                  :  TDateTime



                                                                                 610

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    Visibility:  default

Description:     UniversalTimeToLocal converts a universal time indication to a local time:  it applies the
                TZOffset timezone offset to the UT Universal time (UTC). If no TZOffset is specified, the
                local time offset as returned by GetLocalTimeOffset (535  ) is used.

    See also:    GetLocalTimeOffset (535  ), LocalTimeToUniversal (573  )



                44.4.144           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 (541  ), MacToDateTime (573  ), MacTimeStampToUnix (573  )



                44.4.145           UnixToDateTime

    Synopsis:    Convert Unix epoch time to a TDateTime value

Declaration:     function  UnixToDateTime(const  AValue:  Int64)  :  TDateTime

    Visibility:   default

Description:     UnixToDateTime  converts  epoch  time  (seconds  elapsed  since  1/1/1970)  to  a  TDateTime
                value.

    See also:    DateTimeToUnix (542  )



                44.4.146           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 (624  )

    See also:    YearOf (624  ), DayOf (542  ), MonthOf (582  ), HourOf (557  ), MinuteOf (578  ), SecondOf (595  ),
                MilliSecondOf (574  )



                                                                                 611

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                44.4.147           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;out  AYear:  Word;
                                                      out  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.

    See also:    WeekOfTheYear  (612  ),  DayOfTheMonth  (543  ),  HourOfTheMonth  (558  ),  MinuteOfThe-
                Month (579  ), SecondOfTheMonth (597  ), MilliSecondOfTheMonth (575  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.148           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;out  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 (611  ).

 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.



                                                                                 612

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    See also:    WeekOf (611  ), MonthOfTheYear (582  ), DayOfTheYear (543  ), HourOfTheYear (559  ), Min-
                uteOfTheYear (580  ), SecondOfTheYear (597  ), MilliSecondOfTheYear (576  )


                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
                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.149           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 (624  ), MonthsBetween (582  ), DaysBetween (544  ), HoursBetween (559  ), Min-
                utesBetween (580  ), SecondsBetween (597  ), MilliSecondsBetween (576  )


                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   ;



                                                                                 613

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                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  ) ;
                    D2 :=  Today    -17;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.150           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 (614  ), DaysInYear (546  ), DaysInAYear (545  ), DaysInMonth (546  ), DaysInA-
                Month (545  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.151           WeeksInYear

    Synopsis:    return the number of weeks in the year, given a date

Declaration:     function  WeeksInYear(const  AValue:  TDateTime)  :  Word



                                                                                 614

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



    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  (614  ),  DaysInYear  (546  ),  DaysInAYear  (545  ),  DaysInMonth  (546  ),  DaysI-
                nAMonth (545  )


                Listing:  ./datutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                44.4.152           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  (625  ),  MonthSpan  (583  ),  DaySpan  (547  ),  HourSpan  (560  ),  MinuteSpan  (581  ),
                SecondSpan (598  ), MilliSecondSpan (577  ), WeeksBetween (613  )


                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



                                                                                 615

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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  ) ;
                    D2 :=  Today    -17;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.153           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 (544  ) 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 (623  ), WithinPastMonths (620  ), WithinPastWeeks (622  ), WithinPastHours
                (617  ), WithinPastMinutes (619  ), WithinPastSeconds (621  ), WithinPastMilliSeconds (618  )


                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  ;



                                                                                 616

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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 ) ;
                    T e s t(D1  , D2  , 2 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.154           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 (559  ) 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  (623  ),  WithinPastMonths  (620  ),  WithinPastWeeks  (622  ),  WithinPast-
                Days  (616  ),  WithinPastMinutes  (619  ),  WithinPastSeconds  (621  ),  WithinPastMilliSeconds
                (618  )


                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       ) ;



                                                                                 617

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.155           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 (576  ) 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  (623  ),  WithinPastMonths  (620  ),  WithinPastWeeks  (622  ),  WithinPast-
                Days (616  ), WithinPastHours (617  ), WithinPastMinutes (619  ), WithinPastSeconds (621  )


                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  ;



                                                                                 618

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.156           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  (580  )  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  (623  ),  WithinPastMonths  (620  ),  WithinPastWeeks  (622  ),  WithinPast-
                Days (616  ), WithinPastHours (617  ), WithinPastSeconds (621  ), WithinPastMilliSeconds (618  )


                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       ) ;



                                                                                 619

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.157           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  (582  )  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 (623  ), WithinPastWeeks (622  ), WithinPastDays (616  ), WithinPastHours
                (617  ), WithinPastMinutes (619  ), WithinPastSeconds (621  ), WithinPastMilliSeconds (618  )


                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;



                                                                                 620

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.158           WithinPastSeconds

    Synopsis:    Check whether two datetimes are only a number of seconds apart

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  (597  )  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  (623  ),  WithinPastMonths  (620  ),  WithinPastWeeks  (622  ),  WithinPast-
                Days (616  ), WithinPastHours (617  ), WithinPastMinutes (619  ), WithinPastMilliSeconds (618  )


                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 ) ;



                                                                                 621

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.159           WithinPastWeeks

    Synopsis:    Check whether two datetimes are only a number of weeks apart

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  (613  )  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 (623  ), WithinPastMonths (620  ), WithinPastDays (616  ), WithinPastHours
                (617  ), WithinPastMinutes (619  ), WithinPastSeconds (621  ), WithinPastMilliSeconds (618  )


                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 ) ;



                                                                                 622

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.160           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

    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 (624  ) 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 (620  ), WithinPastWeeks (622  ), WithinPastDays (616  ), WithinPastHours
                (617  ), WithinPastMinutes (619  ), WithinPastSeconds (621  ), WithinPastMilliSeconds (618  )


                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 ) ;



                                                                                 623

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                    T e s t(D1  , D2  , 2 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                44.4.161           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.

    See also:    MonthOf  (582  ),  DayOf  (542  ),  WeekOf  (611  ),  HourOf  (557  ),  MinuteOf  (578  ),  SecondOf
                (595  ), MilliSecondOf (574  )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.162           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 (582  ), WeeksBetween (613  ), DaysBetween (544  ), HoursBetween (559  ), Min-
                utesBetween (580  ), SecondsBetween (597  ), MilliSecondsBetween (576  ), YearSpan (625  )



                                                                                 624

                ____________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'DATEUTILS'___________________*
 *___________________



                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   ;


                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___.____________________________________________________________________________________________________________*
 *___________



                44.4.163           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  (583  ),  WeekSpan  (615  ),  DaySpan  (547  ),  HourSpan  (560  ),  MinuteSpan  (581  ),
                SecondSpan (598  ), MilliSecondSpan (577  ), YearsBetween (624  )


                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;



                                                                                 625

                ____________________________________________________CHAPTER_44.___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  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;
                    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___.____________________________________________________________________________________________________________*
 *___________



                44.4.164           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 (604  ) -1.

    See also:    Today (604  ), Tomorrow (605  )


                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          ( ' "Today      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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 626




Chapter   45



Reference   for   unit   'Dos'



45.1          Used  units



                                      Table 45.1:  Used units by unit 'Dos'


                                                  _Name_____________Page______
                                                    BaseUnix           113
                                                    System           1235



45.2          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 is the same for all operating
systems.

Because the DOS unit is a Turbo Pascal compatibility unit, it is no longer actively developed:
the  interface  is  frozen  and  it  is  maintained  only  for  the  purpose  of  porting  Turbo  Pascal
programs.  For new development, it is recommended to use the sysutils (1489   ) unit instead.



45.3          System  information


Functions for retrieving and setting general system information such as date and time.



                                                             627

________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



                                                       Table 45.2:

                  __Name__________________________Description________________________________________________
                    DosVersion (1 )               Get OS version
                    GetCBreak (642  )             Get setting of control-break handling flag
                    GetDate (642  )               Get system date
                    GetIntVec (645  )             Get interrupt vector status
                    GetTime (647  )               Get system time
                    GetVerify (647  )             Get verify flag
                    Intr (648  )                  Execute an interrupt
                    Keep (648  )                  Keep process in memory and exit
                    MSDos (648  )                 Execute MS-dos function call
                    PackTime (648  )              Pack time for file time
                    SetCBreak (649  )             Set control-break handling flag
                    SetDate (650  )               Set system date
                    SetIntVec (651  )             Set interrupt vectors
                    SetTime (651  )               Set system time
                    SetVerify (651  )             Set verify flag
                    SwapVectors (652  )           Swap interrupt vectors
                    UnPackTime (652  )            Unpack file time



45.4          Process  handling


Functions to handle process information and starting new processes.



                                                       Table 45.3:

                    __Name_______________________Description_______________________________________________
                      DosExitCode (1 )           Exit code of last executed program
                      EnvCount (637  )           Return number of environment variables
                      EnvStr (638  )             Return environment string pair
                      Exec (638  )               Execute program
                      GetEnv (643  )             Return specified environment string



45.5          Directory  and  disk  handling


Routines to handle disk information.



                                                       Table 45.4:

                        _Name____________________Description____________________________________________
                          AddDisk (634  )         Add disk to list of disks (UNIX only)
                          DiskFree (635  )        Return size of free disk space
                          DiskSize (635  )        Return total disk size



                                                                 628

________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



45.6          File  handling


Routines to handle files on disk.



                                                       Table 45.5:

         __Name_____________________________Description______________________________________________________________
           FExpand (639  )                  Expand filename to full path
           FindClose (639  )                Close finfirst/findnext session
           FindFirst (640  )                Start find of file
           FindNext (640  )                 Find next file
           FSearch (641  )                  Search for file in a path
           FSplit (641  )                   Split filename in parts
           GetFAttr (643  )                 Return file attributes
           GetFTime (644  )                 Return file time
           GetLongName (645  )              Convert short filename to long filename (DOS only)
           GetShortName (646  )             Convert long filename to short filename (DOS only)
           SetFAttr (650  )                 Set file attributes
           SetFTime (650  )                 Set file time



45.7          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:



                                      Table 45.6:  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



45.8          File  attributes


The File Attribute constants are used in FindFirst (640  ), FindNext (640  ) to determine what
type of special file to search for in addition to normal files.  These flags are also used in the
SetFAttr (650  ) and GetFAttr (643  ) routines to set and retrieve attributes of files.  For their
definitions consult fileattributes (629  ).



                                                                 629

________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



                                        Table 45.7:  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



45.9          Constants,  types  and  variables



45.9.1         Constants

anyfile  =  $3F


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


fmclosed  =  $D7B0


File is closed


fminout  =  $D7B3


File is read and write


fminput  =  $D7B1


File is read only



                                                                 630

________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



fmoutput  =  $D7B2


File is write only


foverflow  =  $0800


CPU overflow flag.  Not used.


fparity  =  $0004


CPU parity flag.  Not used.


fsign  =  $0080


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


volumeid  =  $08


Volumd ID file attribute



45.9.2         Types

ComStr  =  string


Command-line string type


DateTime  =  packed  record
    Year  :  Word;
    Month  :  Word;
    Day  :  Word;
    Hour  :  Word;
    Min  :  Word;
    Sec  :  Word;
end



                                                                 631

________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



The DateTime type is used in PackTime (648  ) and UnPackTime (652  ) for setting/reading
file times with GetFTime (644  ) and SetFTime (650  ).


DirStr  =  string


Full directory string type.


ExtStr  =  string


Filename extension string type.


NameStr  =  string


Fill filename string type.


PathStr  =  string


Full File path string type.


Registers  =  packed  record
case  i  :  Integer  of
0:  (
   ax  :  Word;
   f1  :  Word;
   bx  :  Word;
   f2  :  Word;
   cx  :  Word;
   f3  :  Word;
   dx  :  Word;
   f4  :  Word;
   bp  :  Word;
   f5  :  Word;
   si  :  Word;
   f51  :  Word;
   di  :  Word;
   f6  :  Word;
   ds  :  Word;
   f7  :  Word;
   es  :  Word;
   f8  :  Word;
   flags  :  Word;
   fs  :  Word;
   gs  :  Word;
);
1:  (
   al  :  Byte;
   ah  :  Byte;
   f9  :  Byte;
   f10  :  Byte;
   bl  :  Byte;
   bh  :  Byte;
   f11  :  Byte;



                                                                 632

________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



   f12  :  Byte;
   cl  :  Byte;
   ch  :  Byte;
   f13  :  Byte;
   f14  :  Byte;
   dl  :  Byte;
   dh  :  Byte;
);
2:  (
   eax  :  LongInt;
   ebx  :  LongInt;
   ecx  :  LongInt;
   edx  :  LongInt;
   ebp  :  LongInt;
   esi  :  LongInt;
   edi  :  LongInt;
);
end



This structure is only defined on a i386 compatible 32-bit platform, and is not used anywhere:
it is defined for Turbo Pascal backwards compatibility only.


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  (640  )  call  and  can  be  used  in  subsequent  FindNext
(640  ) calls to search for files.  The structure of this record depends on the platform.  Only
the following fields are present on all platforms:


Attr    File attributes.

Time     File modification time.

Size   File size

Name      File name (name part only, no path)

Mode      File access mode (linux only)



                                                                 633

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.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 :



                                                            Table 45.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.



                Other values are possible, but are not documented.



                45.10            Procedures  and  functions



                45.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 (635  ) and DiskSize (635  ) calls.  The DiskFree (635  ) and DiskSize (635  ) 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 (635  ), DiskSize (635  )



                                                                                 634

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.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 :


                      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 (634  ) 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 (635  ), AddDisk (634  )


                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___.____________________________________________________________________________________________________________*
 *___________



                45.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).



                                                                                 635

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                      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 (634  ) procedure.  These
                settings can be coded in dos.pp, in the initialization part.

                For an example, see DiskFree (635  ).

       Errors:   -1 when a failure occurs, or an invalid drive number is given.

    See also:    DiskFree (635  ), AddDisk (634  )



                45.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 (638  )


                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___.____________________________________________________________________________________________________________*
 *___________



                45.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.



                                                                                 636

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



       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
                    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___.____________________________________________________________________________________________________________*
 *___________



                45.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 (652  ), PackTime (648  ), UnpackTime (652  ), GetTime (647  ), SetTime (651  )



                45.10.7          EnvCount

    Synopsis:    Return the number of environment variables

Declaration:     function  EnvCount  :  LongInt

    Visibility:   default



                                                                                 637

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



Description:     EnvCount returns the number of environment variables.

       Errors:   None.

    See also:    EnvStr (638  ), GetEnv (643  )



                45.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 (637  ), GetEnv (643  )


                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___.____________________________________________________________________________________________________________*
 *___________



                45.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 (1 )

       Errors:   Errors are reported in DosError.

    See also:    DosExitCode (1 )



                                                                                 638

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.10.10           FExpand

    Synopsis:    Expand a relative path to an absolute path

Declaration:     function  FExpand(const  path:  PathStr)  :  PathStr

    Visibility:   default

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 (641  )


                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___.____________________________________________________________________________________________________________*
 *___________



                45.10.11           FindClose

    Synopsis:    Dispose resources allocated by a FindFirst (640  )/FindNext (640  ) 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 (640  ) or FindNext
                (640  ) 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 (640  ), FindNext (640  )



                                                                                 639

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.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).
                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 (639  ) 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 (640  ), FindClose (639  )


                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___.____________________________________________________________________________________________________________*
 *___________



                45.10.13           FindNext

    Synopsis:    Find next matching file after FindFirst (640  )

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 (640  ).

       Errors:   DosError is used to report errors.

    See also:    FindFirst (640  ), FindClose (639  )



                                                                                 640

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.10.14           FSearch

    Synopsis:    Search a file in searchpath

Declaration:     function  FSearch(path:  PathStr;dirlist:  string)  :  PathStr

    Visibility:   default

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 (639  )


                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___.____________________________________________________________________________________________________________*
 *___________



                45.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 (641  )


                Listing:  ./dosex/ex12.pp



                                                                                 641

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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;


                 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___.____________________________________________________________________________________________________________*
 *___________



                45.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 (649  )



                45.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 (647  ), SetDate (650  )


                Listing:  ./dosex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example2       ;
                 u s e s Dos   ;



                                                                                 642

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'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   ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                45.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 (637  ), EnvStr (638  )


                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___.____________________________________________________________________________________________________________*
 *___________



                45.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



                                                                                 643

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                      oSysFile

                      oVolumeId

                      oDirectory

                      oArchive


                Under linux, supported attributes are:


                      oDirectory

                      oReadOnly if the current process doesn't have access to the file.

                      oHidden for files whose name starts with a dot ('.').


       Errors:   Errors are reported in DosError

    See also:    SetFAttr (650  )


                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___.____________________________________________________________________________________________________________*
 *___________



                45.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 (650  ), PackTime (648  ), UnPackTime (652  )


                Listing:  ./dosex/ex9.pp



                                                                                 644

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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 ;
                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___.____________________________________________________________________________________________________________*
 *___________



                45.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 (651  )



                45.10.22           GetLongName

    Synopsis:    Get the long filename of a DOS 8.3 filename.

Declaration:     function  GetLongName(var  p:  string)  :  Boolean



                                                                                 645

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



    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 (646  )



                45.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 (647  )



                45.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 (645  )



                                                                                 646

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.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 (642  ), SetTime (651  )


                Listing:__./dosex/ex3.pp___________________________________________________________________________________________*
 *___________

                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___.____________________________________________________________________________________________________________*
 *___________



                45.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 (651  )



                                                                                 647

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.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 (648  )



                45.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.



                45.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 (648  )



                45.10.30           PackTime

    Synopsis:    Pack DateTime value to a packed-time format.

Declaration:     procedure  PackTime(var  t:  DateTime;var  p:  LongInt)

    Visibility:   default



                                                                                 648

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



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 (650  ), FindFirst (640  ), FindNext (640  ), UnPackTime (652  )


                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
                      b e g i n
                         Y e a r: = 2 0 0 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___.____________________________________________________________________________________________________________*
 *___________



                45.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 (642  )



                                                                                 649

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.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 (642  ), SetTime (651  )



                45.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 (643  )



                45.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 (644  ), PackTime (648  ), UnPackTime (652  )



                                                                                 650

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.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 (645  )



                45.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 (647  ), SetDate (650  )



                45.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 (651  )



                                                                                 651

                ________________________________________________________________CHAPTER_45.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                45.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 (638  ), SetIntVec (651  )



                45.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 (637  ), PackTime (648  ), UnpackTime (652  ), GetTime (647  ), SetTime (651  )



                45.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 (648  ).

       Errors:   None.

    See also:    GetFTime (644  ), FindFirst (640  ), FindNext (640  ), PackTime (648  )



                45.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 (648  ), UnpackTime (652  ), GetTime (647  ), SetTime (651  )



                                                                                 652




                Chapter   46



                Reference   for   unit   'dxeload'



                46.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.



                46.2          Procedures  and  functions



                46.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 (658  ) unit in the RTL.

       Errors:   If an error occurs during the load or relocations, Nil is returned.



                                                                             653




Chapter   47



Reference   for   unit   'dynlibs'



47.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.



47.2          Constants,  types  and  variables



47.2.1         Constants

NilHandle  =  (0)


Correctly typed Nil handle - returned on error by LoadLibrary (656  )


SharedSuffix  =  'so'


SharedSuffix contains the extension of a shared library (dynamically loadable library) on
the current platform.  It does not contain the .  (dot) character.  This can be used to determine
the name of a shared library in a platform independent way.



47.2.2         Types

HModule  =  TLibHandle


Alias for TLibHandle (654  ) 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.



                                                             654

                _________________________________________________________CHAPTER_47.___REFERENCE_FOR_UNIT_'DYNLIBS'________________*
 *___________________



                TOrdinalEntry  =  SizeUInt


                TOrdinalEntry  is  mainly  used  on  Windows  and  OS/2  operating  systems  to  retrieve  the
                address  of  a  procedure  using  the  index  (ordinal)  of  the  procedure.   On  these  operating
                systems, entry points can be loaded using name or ordinal value.



                47.3          Procedures  and  functions



                47.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 (656  ), and is provided for
                compatibility with Delphi.

    See also:    UnloadLibrary (656  )



                47.3.2         GetLoadErrorStr

    Synopsis:    Return a textual description of the last load error

Declaration:     function  GetLoadErrorStr  :  string

    Visibility:   default

Description:     GetLoadErrorStr returns a textual description of the last library loading or unloading error.
                No other system calls may be made between the load call and the call of  GetLoadErrorStr

    See also:    LoadLibrary (656  )



                47.3.3         GetProcAddress

    Synopsis:    For compatibility with Delphi/Windows:  Get the address of a procedure

Declaration:     function  GetProcAddress(Lib:  TLibHandle;const  ProcName:  AnsiString)
                                                        :  Pointer

    Visibility:   default

Description:     GetProcAddress  provides  the  same  functionality  as  GetProcedureAddress  (655  ),  and  is
                provided for compatibility with Delphi.

    See also:    GetProcedureAddress (655  )



                47.3.4         GetProcedureAddress

    Synopsis:    Get the address of a procedure or symbol in a dynamic library.

Declaration:     function  GetProcedureAddress(Lib:  TLibHandle;const  ProcName:  AnsiString)
                                                                :  Pointer
                function  GetProcedureAddress(Lib:  TLibHandle;Ordinal:  TOrdinalEntry)
                                                                :  Pointer



                                                                                 655

                _________________________________________________________CHAPTER_47.___REFERENCE_FOR_UNIT_'DYNLIBS'________________*
 *___________________



    Visibility:  default

Description:     GetProcedureAddress returns a pointer to the location in memory of the symbol ProcName
                or ordinal value Ordinal 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.

                Only windows and OS/2 support getting the address of a function using an ordinal value.

       Errors:   If the symbol cannot be found, Nil is returned.

    See also:    LoadLibrary (656  ), UnLoadLibrary (656  )



                47.3.5         LoadLibrary

    Synopsis:    Load a dynamic library and return a handle to it.

Declaration:     function  LoadLibrary(const  Name:  RawByteString)  :  TLibHandle
                function  LoadLibrary(const  Name:  UnicodeString)  :  TLibHandle

    Visibility:   default

Description:     LoadLibrary loads a dynamic library in file Name and returns a handle to it.  If the library
                cannot be loaded, NilHandle (654  ) 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 (654  ) is returned.

    See also:    UnloadLibrary (656  ), GetProcedureAddress (655  )



                47.3.6         SafeLoadLibrary

    Synopsis:    Saves the control word and loads a library

Declaration:     function  SafeLoadLibrary(const  Name:  RawByteString)  :  TLibHandle
                function  SafeLoadLibrary(const  Name:  UnicodeString)  :  TLibHandle

    Visibility:   default

Description:     SafeLoadLibary  saves  the  FPU  control  word,  and  calls  LoadLibrary  (656  )  with  library
                name Name.  After that function has returned, the FPU control word is saved again.  (only
                on Intel i386 CPUS).

    See also:    LoadLibrary (656  )



                47.3.7         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.



                                                                                 656

            _________________________________________________________CHAPTER_47.___REFERENCE_FOR_UNIT_'DYNLIBS'____________________*
 *_______________



   Errors:   On error, False is returned.

See also:    LoadLibrary (656  ), GetProcedureAddress (655  )



                                                                             657




                Chapter   48



                Reference   for   unit   'emu387'



                48.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.



                48.2          Procedures  and  functions



                48.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.



                                                                             658

         ___________________________________________________________CHAPTER_48.___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.



                                                                          659




            Chapter   49



            Reference   for   unit   'errors'



            49.1          Used  units



                                                 Table 49.1:  Used units by unit 'errors'


                                                              __Name____________Page_____
                                                                System          1235
                                                                unixtype        1798



            49.2          Overview


            The errors unit contains routines to convert a unix system call error code to an error message:
            StrError (661  ).  It is only available on unix platforms.



            49.3          Constants,  types  and  variables



            49.3.1         Constants

            sys_errlist  :  Array[0..sys_errn-1]  of  PChar  =  ('Success',  'Operation  not  permitted',  'No  such  file  or  dir*
 *ectory',  'No  such  process',  'Interrupted  system  call',  'I/O  error',  'No  such  device  or  address',  'Arg  list  too  l*
 *ong',  'Exec  format  error',  'Bad  file  number',  'No  child  processes',  'Try  again',  'Out@


            sys_errn is an array with then error codes for the current operating system.  It should not
            be used directly, instead use StrError (661  ).


            sys_errn  =  125


            sys_errn is the number of error codes for the current operating system.  It should not be
            used directly, instead use StrError (661  ).



            49.4          Procedures  and  functions



            49.4.1         PError

Synopsis:    Print error on standard error routput



                                                                         660

                __________________________________________________________CHAPTER_49.___REFERENCE_FOR_UNIT_'ERRORS'________________*
 *___________________



Declaration:     procedure  PError(const  s:  string;Errno:  cint)

    Visibility:  default

Description:     PError will print the error message S followed by the errNo and the result for StrError(errNo)
                for ErrNo on standard output.

       Errors:   None.

    See also:    StrError (661  )



                49.4.2         StrError

    Synopsis:    Convert an error code to a string

Declaration:     function  StrError(err:  cint)  :  string

    Visibility:   default

Description:     StrError will convert the error code err to a string.

       Errors:   If  the  error  code  is  unknown  or  out  of  bounds,  an  'Unknown  error  (err)'  string  will  be
                returned.

    See also:    PError (660  )



                                                                                 661




Chapter   50



Reference   for   unit   'exeinfo'



50.1          Overview


The  exeinfo  unit  implements  some  cross-platform  routines  to  examine  the  contents  of  an
executable:  information about sections, mapping addresses to loaded modules etc.

It  is  mainly  used  by  the  lineinfo  (870  )  and  lnfodwrf  (899  )  unit  to  examine  the  binary  for
debug info.



50.2          Constants,  types  and  variables



50.2.1         Types

TExeFile  =  record
    f  :  File;
    size  :  Int64;
    isopen  :  Boolean;
    nsects  :  LongInt;
    sechdrofs  :  ptruint;
    secstrofs  :  ptruint;
    processaddress  :  ptruint;
    FunctionRelative  :  Boolean;
    ImgOffset  :  ptruint;
    filename  :  string;
    buf  :  Array[0..4095]  of  Byte;
    bufsize  :  LongInt;
    bufcnt  :  LongInt;
end



TExeFile is a record used in the various calls of this unit.  It contains a file descriptor, and
various fields that describe the executable.

The  structure  of  TExeFile  is  opaque,  that  is,  one  shouldn't  rely  on  the  exactness  of  this
structure, it may change any time in the future.



                                                             662

                ________________________________________________________CHAPTER_50.___REFERENCE_FOR_UNIT_'EXEINFO'_________________*
 *___________________



                50.3          Procedures  and  functions



                50.3.1         CloseExeFile

    Synopsis:    Close a previously opened file.

Declaration:     function  CloseExeFile(var  e:  TExeFile)  :  Boolean

    Visibility:   default

Description:     CloseExeFile closes an executable file image previously opened with OpenExeFile (663  ),
                and represented by e.

                The function returns True if the file was closed succesfully, or False if something went wrong.

       Errors:   In case of an error, False is returned.

    See also:    OpenExeFile (663  )



                50.3.2         FindExeSection

    Synopsis:    Find a section in the binary image.

Declaration:     function  FindExeSection(var  e:  TExeFile;const  secname:  string;
                                                      var  secofs:  LongInt;var  seclen:  LongInt)
                                                        :  Boolean

    Visibility:   default

Description:     FindExeSection examines the binary that was opened with OpenExeFile (663  ) (represented
                by e) and searches for the section named secname.  If found, the section offset is returned in
                secofs and the section length (in bytes) is returned in seclen.

                The function returns True if the section was found, False if not.

    See also:    OpenExeFile (663  )



                50.3.3         GetModuleByAddr

    Synopsis:    Return the module name by address

Declaration:     procedure  GetModuleByAddr(addr:  pointer;var  baseaddr:  pointer;
                                                         var  filename:  string)

    Visibility:   default

Description:     GetModuleByAddr returns the name of the module that contains address addr.  If succesful,
                it  returns  True  and  returns  the  filename  in  FileName  and  the  base  address  at  which  it  is
                loaded in BaseAddr.



                50.3.4         OpenExeFile

    Synopsis:    Open an executable file

Declaration:     function  OpenExeFile(var  e:  TExeFile;const  fn:  string)  :  Boolean

    Visibility:   default



                                                                                 663

                ________________________________________________________CHAPTER_50.___REFERENCE_FOR_UNIT_'EXEINFO'_________________*
 *___________________



Description:     OpenExeFile opens the executable file fn and initializes the structure e for subsequent calls
                to routines in the exeinfo unit.

                The function returns True if the file was opened succesfully, false otherwise.

    See also:    FindExeSection (663  ), CloseExeFile (663  ), ReadDebugLink (664  )



                50.3.5         ReadDebugLink

    Synopsis:    Read the location of a debug info filename

Declaration:     function  ReadDebugLink(var  e:  TExeFile;var  dbgfn:  string)  :  Boolean

    Visibility:   default

Description:     ReadDebugLink  examines  the  .gnu_debuglink  section  to  see  if  the  debug  information  is
                stored  in  an  external  file.   If  so,  then  the  name  of  the  file  with  the  debug  information  is
                returned in the dbgfn parameter.

                The function returns false if there is no external debug information file, or if the file with
                debug  information  does  not  exist.  It  is  searched  next  to  the  binary  file  or  in  the  current
                directory.

    See also:    OpenExeFile (663  ), CloseExeFile (663  )



                                                                                 664




Chapter   51



Reference   for   unit   'fgl'



51.1          Used  units



                                       Table 51.1:  Used units by unit 'fgl'


                                                   __Name__________Page_____
                                                     System        1235
                                                     sysutils      1489
                                                     Types         1664



51.2          Overview


The fgl unit contains some basic list-related generic classes.



51.3          Constants,  types  and  variables



51.3.1         Constants

MaxGListSize  =  MaxInt  div  1024


MaxGListSize is the maximum number of elements in the TFPGList (670  ) list.


MaxListSize  =  Maxint  div  16


MaxListSize is the maximum number of elements a list can contain before the memory runs
out.



51.3.2         Types

TFPSListCompareFunc  =  function(Key1:  Pointer;Key2:  Pointer)  :  Integer
                                                     of  object


TFPSListCompareFunc is used in the TFPSList.Sort (694  ) method to compare 2 elements.
The list passes 2 pointers to the actual items to the compare function.  The result of this
function determines how the pointers will be sorted:



                                                             665

            ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_________________*
 *_______________



                 o If  the  result  of  this  function  is  negative,  the  first  key  (key1)  is  assumed  to  be  'less'
                   than the second key (key2) and will be moved before the second in the list.

                 o If the function result is positive, the first key (key1) pointer is assumed to be 'greater
                   than' the second key (key2)and will be moved after the second in the list.

                 o if the function result is zero,  the keys are assumed to be 'equal' and no moving will
                   take place.



            51.4          EListError



            51.4.1         Description

            EListError is the exception used in the TFPSList (689  ) class to indicate errors such as a
            list index out of bounds, wrong capacity etc.


See also:    TFPSList.Capacity (695  ), TFPSList.Exchange (692  ), TFPSList.Items (695  )



            51.5          TFPGInterfacedOb jectList



            51.5.1         Description

            TFPGList can be used to specialize a list for any class type T that requires reference counting
            (all objects that implement IInterface or IUnknown)).  It will specialize to a list with the
            same methods as TFPSList (689  ) or classes.TFPList (665  ) or TFPObjectList

            Classes  that  implement  IInterface  or  IUnknown  require  special  care  to  maintain  the  ref-
            erence count.  The TFPGInterfacedObjectList list provides the necessary functionality to
            deal with this.


See also:    TFPSList (689  ), classes.TFPList (665  )



            51.5.2         Method  overview

            __Page______Method____________________Description______________________________________________________________________*
 *_______
              667       Add                       Add new object of class T to the list.
              668       Assign                    Copy objects from Source list
              667       Create                    Instantiate a new interfaced object list.
              667       Extract                   Extract an item from the list
              667       GetEnumerator             Return a list enumerator for T
              668       IndexOf                   Index of object
              668       Insert                    Insert a new object in the list
              668       Remove                    Remove an object from the list.
            __669_______Sort______________________Sort_the_objects_in_the_list_____________________________________________________*
 *_______



            51.5.3         Property  overview

            __Page______Properties________Access_______Description_________________________________________________________________*
 *_______
              669       First             rw           First non-nil object
              670       Items             rw           Indexed access to objects in the list.
              669       Last              rw           Last non-Nil object
            __670_______List______________r____________Internal_list_pointer_______________________________________________________*
 *_______



                                                                             666

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.5.4         TFPGInterfacedObjectList.Create

    Synopsis:    Instantiate a new interfaced object list.

Declaration:     constructor  Create

    Visibility:   public

Description:     Create instantiates a new object list.  It will simply call the inherited constructor with the
                correct item size.

    See also:    TFPSList.Destroy (690  )



                51.5.5         TFPGInterfacedObjectList.Add

    Synopsis:    Add new object of class T to the list.

Declaration:     function  Add(const  Item:  T)  :  Integer

    Visibility:   public

Description:     Add adds a new item Item of class type T to the list and returns the position at which the
                item was added.  Add will increase the reference count of the object.

       Errors:   If the item could not be added, an EListError (666  ) exception is raised.

    See also:    TFPGInterfacedObjectList.Extract (667  ), TFPGInterfacedObjectList.Items (670  ), TFPGIn-
                terfacedObjectList.IndexOf (668  )



                51.5.6         TFPGInterfacedObjectList.Extract

    Synopsis:    Extract an item from the list

Declaration:     function  Extract(const  Item:  T)  :  T

    Visibility:   public

Description:     Extract  removes  Item  from  the  list  and  returns  the  removed  item,  or  Nil  if  it  was  not
                found.

                The extracted object will not be destroyed.

       Errors:   None.

    See also:    TFPSList.Delete (691  )



                51.5.7         TFPGInterfacedObjectList.GetEnumerator

    Synopsis:    Return a list enumerator for T

Declaration:     function  GetEnumerator  :  TFPGListEnumeratorSpec

    Visibility:   public

Description:     GetEnumerator returns an enumerator for the elements in the list.  It is a specialized version
                of TFPGListEnumerator (674  ).

    See also:    TFPGListEnumerator (674  )



                                                                                 667

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.5.8         TFPGInterfacedObjectList.IndexOf

    Synopsis:    Index of object

Declaration:     function  IndexOf(const  Item:  T)  :  Integer

    Visibility:   public

Description:     IndexOf returns the index of Item in the list, or -1 if the object does not appear in the list.

       Errors:   None.

    See also:    TFPGInterfacedObjectList.Items (670  ), TFPGInterfacedObjectList.Insert (668  ), TFPGIn-
                terfacedObjectList.Add (667  )



                51.5.9         TFPGInterfacedObjectList.Insert

    Synopsis:    Insert a new object in the list

Declaration:     procedure  Insert(Index:  Integer;const  Item:  T)

    Visibility:   public

Description:     Insert inserts a new object (Item) in the list at position Index.  The index is zero based
                and must be less than Count (695  ).

       Errors:   If an invalid index is specified, an EListError (666  ) exception is raised.

    See also:    TFPGInterfacedObjectList.Items (670  ), TFPGInterfacedObjectList.Add (667  )



                51.5.10          TFPGInterfacedObjectList.Assign

    Synopsis:    Copy objects from Source list

Declaration:     procedure  Assign(Source:  TFPGInterfacedObjectList)

    Visibility:   public

Description:     Assign clears the list and copies all items in Source to the list.  The source list must be of
                the same type as the destination list.

    See also:    TFPSList.Clear (691  ), TFPGObjectList.Add (686  )



                51.5.11          TFPGInterfacedObjectList.Remove

    Synopsis:    Remove an object from the list.

Declaration:     function  Remove(const  Item:  T)  :  Integer

    Visibility:   public

Description:     Remove removes the object Item from the list, and returns the index of the removed item.
                If no item was removed, -1 is returned.  Only the first object is removed.

                Removing an object from the list may cause the object to be freed.

       Errors:   None.

    See also:    TFPGInterfacedObjectList.IndexOf (668  ), TFPSList.Delete (691  ), TFPGInterfacedObjectList.FreeObjects
                (666  )



                                                                                 668

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.5.12          TFPGInterfacedObjectList.Sort

    Synopsis:    Sort the objects in the list

Declaration:     procedure  Sort(Compare:  TCompareFunc)

    Visibility:   public

Description:     Sort sorts the elements in the list using the provided Compare function.  The list passes 2
                items to the compare function.  The result of this function determines how the items will be
                sorted:


                      oIf the result of this function is negative, the first object (Item1) is assumed to be 'less'
                       than the second object (Item2) and will be moved before the second in the list.

                      oIf the function result is positive, the first object (Item1) is assumed to be 'greater than'
                       the second object (Item2)and will be moved after the second in the list.

                      oif the function result is zero, the objects are assumed to be 'equal' and no moving will
                       take place.


       Errors:   None.

    See also:    TFPSList.Sorted (689  )



                51.5.13          TFPGInterfacedObjectList.First

    Synopsis:    First non-nil object

Declaration:     Property  First  :  T

    Visibility:   public

      Access:    Read,Write

Description:     First returns the first non-nil object.  If no such element is present, Nil is returned.

    See also:    TFPSList.First (696  ), TFPGInterfacedObjectList.Last (669  ), TFPSList.Pack (694  )



                51.5.14          TFPGInterfacedObjectList.Last

    Synopsis:    Last non-Nil object

Declaration:     Property  Last  :  T

    Visibility:   public

      Access:    Read,Write

Description:     Last returns the last non-Nil object.  If no such element is present, Nil is returned.

    See also:    TFPGInterfacedObjectList.First (669  ), TFPSList.Last (696  )



                                                                                 669

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.5.15          TFPGInterfacedObjectList.Items

    Synopsis:    Indexed access to objects in the list.

Declaration:     Property  Items[Index:  Integer]:  T;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items provides indexed access to the objects in the list.  The objects can be get or set.

                The index Index is zero based, and has a maximum value of Count-1 (695  ).

                The previous object at position Index may be freed when setting the property, depending
                on its reference count.

       Errors:   If an invalid index is used, an EListError (666  ) exception is raised.

    See also:    TFPSList.Count (695  )



                51.5.16          TFPGInterfacedObjectList.List

    Synopsis:    Internal list pointer

Declaration:     Property  List  :  PTypeList

    Visibility:   public

      Access:    Read

Description:     List is the internal list of objects.  It should not be used directly.

    See also:    TFPGInterfacedObjectList.Items (670  )



                51.6          TFPGList



                51.6.1         Description

                TFPGList  can  be  used  to  specialize  a  list  for  any  type  T  that  does  not  require  reference
                counting (such as interfaced objects).  It will specialize to a list with the same methods as
                TFPSList (689  ) or classes.TFPList (665  )


    See also:    TFPSList (689  ), classes.TFPList (665  )



                51.6.2         Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  671       Add                       Add new item of type T to the list.
                  672       Assign                    Copy elements from Source list
                  671       Create                    Instantiate a new list
                  671       Extract                   Extract an item from the list
                  671       GetEnumerator             Return a list enumerator for T.
                  672       IndexOf                   Index of item
                  672       Insert                    Insert a new item in the list
                  672       Remove                    Remove an item from the list.
                __673_______Sort______________________Sort_the_list________________________________________________________________*
 *___________



                                                                                 670

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.6.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  673       First             rw           First non-empty item
                  673       Items             rw           Indexed access to items in the list
                  673       Last              rw           Last non-empty item
                __674_______List______________r____________Internal_list_object____________________________________________________*
 *___________



                51.6.4         TFPGList.Create

    Synopsis:    Instantiate a new list

Declaration:     constructor  Create

    Visibility:   public

Description:     Create instantiates a new list.  It will simply call the inherited constructor with the correct
                item size:  sizeof(T).



                51.6.5         TFPGList.Add

    Synopsis:    Add new item of type T to the list.

Declaration:     function  Add(const  Item:  T)  :  Integer

    Visibility:   public

Description:     Add adds a new item Item of generic type T to the list and returns the position at which
                the item was added.

       Errors:   If the item could not be added, an EListError (666  ) exception is raised.

    See also:    TFPGList.Extract (671  ), TFPGList.Items (673  ), TFPGList.IndexOf (672  )



                51.6.6         TFPGList.Extract

    Synopsis:    Extract an item from the list

Declaration:     function  Extract(const  Item:  T)  :  T

    Visibility:   public

Description:     Extract removes Item from the list and returns the removed item, or an expression equiv-
                alent to T(0) if it was not found.

       Errors:   None.

    See also:    TFPSList.Delete (691  )



                51.6.7         TFPGList.GetEnumerator

    Synopsis:    Return a list enumerator for T.

Declaration:     function  GetEnumerator  :  TFPGListEnumeratorSpec

    Visibility:   public

Description:     GetEnumerator returns an enumerator for the elements in the list.  It is a specialized version
                of TFPGListEnumerator (674  ).

    See also:    TFPGListEnumerator (674  )



                                                                                 671

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.6.8         TFPGList.IndexOf

    Synopsis:    Index of item

Declaration:     function  IndexOf(const  Item:  T)  :  Integer

    Visibility:   public

Description:     IndexOf returns the index of  Item in the list, or -1 if the item does not appear in the list.

       Errors:   None.

    See also:    TFPGList.Items (673  ), TFPGList.Insert (672  ), TFPSList.Add (691  )



                51.6.9         TFPGList.Insert

    Synopsis:    Insert a new item in the list

Declaration:     procedure  Insert(Index:  Integer;const  Item:  T)

    Visibility:   public

Description:     Insert inserts a new item in the list at position Index.  The index is zero based and must
                be less than Count (695  ).

       Errors:   If an invalid index is specified, an EListError (666  ) exception is raised.

    See also:    TFPGList.Items (673  ), TFPGList.Insert (672  ), TFPSList.Add (691  )



                51.6.10          TFPGList.Assign

    Synopsis:    Copy elements from Source list

Declaration:     procedure  Assign(Source:  TFPGList)

    Visibility:   public

Description:     Assign clears the list and copies all items in Source to the list.  The source list must be of
                the same type as the destination list.

    See also:    TFPSList.Clear (691  ), TFPGList.Add (671  )



                51.6.11          TFPGList.Remove

    Synopsis:    Remove an item from the list.

Declaration:     function  Remove(const  Item:  T)  :  Integer

    Visibility:   public

Description:     Remove removes the item Item from the list, and returns the index of the removed item.  If
                no item was removed, -1 is returned.  Only the first item is removed.

       Errors:   None.

    See also:    TFPGList.IndexOf (672  )



                                                                                 672

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.6.12          TFPGList.Sort

    Synopsis:    Sort the list

Declaration:     procedure  Sort(Compare:  TCompareFunc)

    Visibility:   public

Description:     Sort sorts the elements in the list using the provided Compare function.  The list passes 2
                items to the compare function.  The result of this function determines how the items will be
                sorted:


                      oIf the result of this function is negative, the first item (Item1) is assumed to be 'less'
                       than the second item (Item2) and will be moved before the second in the list.

                      oIf the function result is positive, the first item (Item1) is assumed to be 'greater than'
                       the second item (Item2)and will be moved after the second in the list.

                      oif the function result is zero,  the items are assumed to be 'equal' and no moving will
                       take place.



                51.6.13          TFPGList.First

    Synopsis:    First non-empty item

Declaration:     Property  First  :  T

    Visibility:   public

      Access:    Read,Write

Description:     First returns the first non-empty item, which means the first item not equal to T(0).  If
                no such element is present, T(0).  is returned.

    See also:    TFPSList.First (696  ), TFPGList.Last (673  )



                51.6.14          TFPGList.Last

    Synopsis:    Last non-empty item

Declaration:     Property  Last  :  T

    Visibility:   public

      Access:    Read,Write

Description:     Last returns the last non-empty item, which means the last item not equal to T(0).  If no
                such element is present, T(0).  is returned.

    See also:    TFPGList.First (673  ), TFPSList.Last (696  )



                51.6.15          TFPGList.Items

    Synopsis:    Indexed access to items in the list

Declaration:     Property  Items[Index:  Integer]:  T;  default

    Visibility:   public

      Access:    Read,Write



                                                                                 673

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



Description:     Items provides indexed access to the items in the list.  The items can be get or set.

                The index Index is zero based, and has a maximum value of Count-1 (695  ).

       Errors:   If an invalid index is used, an EListError (666  ) exception is raised.

    See also:    TFPSList.Count (695  )



                51.6.16          TFPGList.List

    Synopsis:    Internal list object

Declaration:     Property  List  :  PTypeList

    Visibility:   public

      Access:    Read

Description:     List is the internal list of items.  It should not be used directly.

    See also:    TFPGList.Items (673  )



                51.7          TFPGListEnumerator



                51.7.1         Description

                TFPGListEnumerator is a generic list enumerator.  It is used in the TFPGList (670  ) class to
                implement the enumerator for the list.

                Normally there should be no need to instantiate or use this class directly.


    See also:    TFPGList (670  )



                51.7.2         Method  overview

                __Page______Method____________Description__________________________________________________________________________*
 *___________
                  674       Create            Create a new list enumerator
                __675_______MoveNext__________Move_to_next_element_in_the_list_____________________________________________________*
 *___________



                51.7.3         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __675_______Current___________r____________Current_enumerated_element______________________________________________*
 *___________



                51.7.4         TFPGListEnumerator.Create

    Synopsis:    Create a new list enumerator

Declaration:     constructor  Create(AList:  TFPSList)

    Visibility:   public

Description:     Create is called by the list AList to initialize a new enumerator.  There should be no need
                to call this directly.

    See also:    TFPGList (670  )



                                                                                 674

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.7.5         TFPGListEnumerator.MoveNext

    Synopsis:    Move to next element in the list

Declaration:     function  MoveNext  :  Boolean

    Visibility:   public

Description:     MoveNext moves to the next element in the list.

    See also:    TFPGListEnumerator.Current (675  )



                51.7.6         TFPGListEnumerator.Current

    Synopsis:    Current enumerated element

Declaration:     Property  Current  :  T

    Visibility:   public

      Access:    Read

Description:     Current  returns  the  currently  enumerated  element.  It  is  only  valid  after  TFPGListEnu-
                merator.MoveNext (675  ) was called and returned True.

    See also:    TFPGListEnumerator.MoveNext (675  )



                51.8          TFPGMap



                51.8.1         Description

                TFPGMap is a generic map class.  It can be used to specialize a map for any key type and data
                type that do not require manual reference counting:  For reference counted interface objects,
                TFPGMapInterfacedObjectData (680  ) must be used.


    See also:    TFPGMapInterfacedObjectData (680  )



                51.8.2         Method  overview

                __Page______Method__________________Description____________________________________________________________________*
 *___________
                  676       Add                     Add a key and value to the map
                  676       Create                  Create a new instance of the map
                  676       Find                    Find item based on key
                  677       IndexOf                 Find index of a key in the list.
                  677       IndexOfData             Find index of data value in the list.
                  677       InsertKey               Insert a new key in the list
                  677       InsertKeyData           Insert a new key with associated data in the list
                __678_______Remove__________________Remove_a_key_from_the_list_____________________________________________________*
 *___________



                                                                                 675

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.8.3         Property  overview

                __Page______Properties__________________Access______Description____________________________________________________*
 *___________
                  678       Data                        rw          Indexed access to the data in the list
                  679       KeyData                     rw          Access to data based on key
                  678       Keys                        rw          Indexed access to the keys in the list.
                  679       OnCompare                   rw          Alias for OnKeyCompare
                  680       OnDataCompare               rw          Compare function for data values.
                __679_______OnKeyCompare________________rw__________Compare_function_for_key_values._______________________________*
 *___________



                51.8.4         TFPGMap.Create

    Synopsis:    Create a new instance of the map

Declaration:     constructor  Create

    Visibility:   public

Description:     Create instantiates a new map.  It mainly initializes the TFPSMap (697  ) parent with the
                sized of the key and data.

    See also:    TFPSMap.Create (697  )



                51.8.5         TFPGMap.Add

    Synopsis:    Add a key and value to the map

Declaration:     function  Add(const  AKey:  TKey;const  AData:  TData)  :  Integer
                function  Add(const  AKey:  TKey)  :  Integer

    Visibility:   public

Description:     Add adds a new key AKey of generic type TKey with data value AData to the list and returns
                the position at which the key was added.

       Errors:   If the item could not be added, an EListError (666  ) exception is raised.  If Duplicates (700  )
                is set to dupError and a duplicate key is added, an EListError (666  ) exception is raised.

    See also:    TFPGMap.Keys (678  ), TFPGMap.IndexOf (677  ), TFPGMap.KeyData (679  ), TFPGMap.Data
                (678  ), TFPSMap.Duplicates (700  )



                51.8.6         TFPGMap.Find

    Synopsis:    Find item based on key

Declaration:     function  Find(const  AKey:  TKey;out  Index:  Integer)  :  Boolean

    Visibility:   public

Description:     Find will search the first key smaller than or equal to AKey and return its index in AIndex.
                If the key was not found then -1 is returned.  The return value of the function is True if an
                exact match for AKey is found, False otherwise.

    See also:    TFPGMap.IndexOf (677  ), TFPGMap.IndexOfData (677  )



                                                                                 676

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.8.7         TFPGMap.IndexOf

    Synopsis:    Find index of a key in the list.

Declaration:     function  IndexOf(const  AKey:  TKey)  :  Integer

    Visibility:   public

Description:     IndexOf returns the index of  AKey in the list, or -1 if the key was not found in the list.

       Errors:   None.

    See also:    TFPGMap.Find (676  ), TFPGMap.IndexOfData (677  )



                51.8.8         TFPGMap.IndexOfData

    Synopsis:    Find index of data value in the list.

Declaration:     function  IndexOfData(const  AData:  TData)  :  Integer

    Visibility:   public

Description:     IndexOfData returns the index of  AData in the list, or -1 if the data was not found in the
                list.

       Errors:   None.

    See also:    TFPGMap.Find (676  ), TFPGMap.IndexOf (677  )



                51.8.9         TFPGMap.InsertKey

    Synopsis:    Insert a new key in the list

Declaration:     procedure  InsertKey(Index:  Integer;const  AKey:  TKey)

    Visibility:   public

Description:     InsertKey inserts key AKey at position Index in the list.  It is not allowed to insert a key
                in a sorted list.

       Errors:   If the index AIndex is out of range [0..Count-1], or the list is sorted, an EListError (666  )
                exception will be raised.

    See also:    TFPGMap.InsertKeyData (677  ), TFPGMap.Add (676  ), TFPSMap.Delete (697  ), TFPSMap.Remove
                (700  )



                51.8.10          TFPGMap.InsertKeyData

    Synopsis:    Insert a new key with associated data in the list

Declaration:     procedure  InsertKeyData(Index:  Integer;const  AKey:  TKey;
                                                      const  AData:  TData)

    Visibility:   public

Description:     InsertKey inserts key AKey with associated data AData at position Index in the list.  It is
                not allowed to insert a key in a sorted list.

       Errors:   If the index AIndex is out of range [0..Count-1], or the list is sorted, an EListError (666  )
                exception will be raised.

    See also:    TFPGMap.InsertKey (677  ), TFPGMap.Add (676  ), TFPSMap.Delete (697  ), TFPGMap.Remove
                (678  )



                                                                                 677

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.8.11          TFPGMap.Remove

    Synopsis:    Remove a key from the list

Declaration:     function  Remove(const  AKey:  TKey)  :  Integer

    Visibility:   public

Description:     Remove removes the key AKey from the list, together with its associated data.  The function
                returns the index of AKey prior to removal from the list, or -1 if AKey was not present in the
                list.

       Errors:   None.

    See also:    TFPGMap.InsertKey  (677  ),  TFPGMap.InsertKeyData  (677  ),  TFPGMap.Add  (676  ),  TF-
                PSMap.Delete (697  )



                51.8.12          TFPGMap.Keys

    Synopsis:    Indexed access to the keys in the list.

Declaration:     Property  Keys[Index:  Integer]:  TKey

    Visibility:   public

      Access:    Read,Write

Description:     Keys provides indexed access to the key values in the list.  Valid values for Index are in the
                range [0..Count-1].  Key values can always be read, but can only be written if the list is
                unsorted.

       Errors:   If the index AIndex is out of range [0..Count-1], an EListError (666  ) exception will be raised.
                The same exception is raised if a key is written and the list is sorted.

    See also:    TFPSList.Count (695  ), TFPGMap.Data (678  ), TFPGMap.KeyData (679  )



                51.8.13          TFPGMap.Data

    Synopsis:    Indexed access to the data in the list

Declaration:     Property  Data[Index:  Integer]:  TData

    Visibility:   public

      Access:    Read,Write

Description:     Data provides indexed access to the data values in the list.  Valid values for Index are in
                the range [0..Count-1].  Data can always be read or written.

       Errors:   If the index AIndex is out of range [0..Count-1], an EListError (666  ) exception will be raised.

    See also:    TFPSList.Count (695  ), TFPGMap.Keys (678  ), TFPGMap.KeyData (679  )



                                                                                 678

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.8.14          TFPGMap.KeyData

    Synopsis:    Access to data based on key

Declaration:     Property  KeyData[AKey:  TKey]:  TData;  default

    Visibility:   public

      Access:    Read,Write

Description:     KeyData allows access to the data based on the key value AKey.  The data can be read and
                written.  When writing, writing using an existing key will overwrite the current data.  If it
                does not exist yet, it will be created.  When reading, if the key is not present, an EListError
                (666  ) will be raised.

       Errors:   If the key does not exist, an EListError (666  ) exception will be raised.

    See also:    TFPSList.Count (695  ), TFPGMap.Keys (678  ), TFPGMap.Data (678  )



                51.8.15          TFPGMap.OnCompare

    Synopsis:    Alias for OnKeyCompare

Declaration:     Property  OnCompare  :  TKeyCompareFunc

    Visibility:   public

      Access:    Read,Write

Description:     OnCompare is a deprecated property, use TFPGMap.OnKeyCompare (679  ) instead.

    See also:    TFPGMap.OnKeyCompare (679  )



                51.8.16          TFPGMap.OnKeyCompare

    Synopsis:    Compare function for key values.

Declaration:     Property  OnKeyCompare  :  TKeyCompareFunc

    Visibility:   public

      Access:    Read,Write

Description:     OnKeyCompare can be set to a function that compares key values.  The default value for this
                event is a function that compares keys based on a byte-by-byte comparison of the memory
                block.  The function must have the following semantics:


                      oIf the result of this function is negative, the first key (key1) is assumed to be 'less' than
                       the second key (key2) and will be moved before the second in the list.

                      oIf the function result is positive, the first key (key1) pointer is assumed to be 'greater
                       than' the second key (key2)and will be moved after the second in the list.

                      oif the function result is zero, the keys are assumed to be 'equal' and no moving will take
                       place.


    See also:    TFPGMap.OnDataCompare (680  )



                                                                                 679

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.8.17          TFPGMap.OnDataCompare

    Synopsis:    Compare function for data values.

Declaration:     Property  OnDataCompare  :  TDataCompareFunc

    Visibility:   public

      Access:    Read,Write

Description:     OnDataCompare  can  be  set  to  a  function  that  compares  data  values.   The  default  value
                for this event is a function that compares data based on a byte-by-byte comparison of the
                memory block.  The function must have the following semantics:


                      oIf the result of this function is negative, the first data item (Data1) is assumed to be
                       'less'  than  the  second  data  item  (Data2)  and  will  be  moved  before  the  second  in  the
                       list.

                      oIf the function result is positive, the first data item (Data1) pointer is assumed to be
                       'greater than' the second data item (Data2)and will be moved after the second in the
                       list.

                      oif the function result is zero, the data items are assumed to be 'equal' and no moving
                       will take place.


    See also:    TFPGMap.OnKeyCompare (679  )



                51.9          TFPGMapInterfacedOb jectData



                51.9.1         Description

                TFPGInterfacedObjectMap is a generic map class.  It can be used to specialize a map for
                any key type, with associated data type that requires manual reference counting:  any type
                which implements IInterface.  For non-reference counted objects, TFPGMap (675  ) should
                be used.

                This map class is entirely equivalend to TFPGMap (675  ), but operates on data items that
                require additional reference counting code on the data.


    See also:    TFPGMap (675  )



                51.9.2         Method  overview

                __Page______Method__________________Description____________________________________________________________________*
 *___________
                  681       Add                     Add a key and value to the map
                  681       Create                  Create a new instance of the map
                  681       Find                    Find item based on key
                  682       IndexOf                 Find index of a key in the list.
                  682       IndexOfData             Find index of data value in the list.
                  682       InsertKey               Insert a new key in the list
                  682       InsertKeyData           Insert a new key with associated data in the list
                __683_______Remove__________________Remove_a_key_from_the_list_____________________________________________________*
 *___________



                                                                                 680

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.9.3         Property  overview

                __Page______Properties__________________Access______Description____________________________________________________*
 *___________
                  683       Data                        rw          Indexed access to the data in the list
                  684       KeyData                     rw          Access to data based on key
                  683       Keys                        rw          Indexed access to the keys in the list.
                  684       OnCompare                   rw          Alias for OnKeyCompare
                  685       OnDataCompare               rw          Compare function for data values.
                __684_______OnKeyCompare________________rw__________Compare_function_for_key_values._______________________________*
 *___________



                51.9.4         TFPGMapInterfacedObjectData.Create

    Synopsis:    Create a new instance of the map

Declaration:     constructor  Create

    Visibility:   public

Description:     Create instantiates a new map.  It mainly initializes the TFPSMap (697  ) parent with the
                sized of the key and data.

    See also:    TFPSMap.Create (697  )



                51.9.5         TFPGMapInterfacedObjectData.Add

    Synopsis:    Add a key and value to the map

Declaration:     function  Add(const  AKey:  TKey;const  AData:  TData)  :  Integer
                function  Add(const  AKey:  TKey)  :  Integer

    Visibility:   public

Description:     Add adds a new key AKey of generic type TKey with data value AData to the list and returns
                the position at which the key was added.

       Errors:   If the item could not be added, an EListError (666  ) exception is raised.  If Duplicates (700  )
                is set to dupError and a duplicate key is added, an EListError (666  ) exception is raised.

    See also:    TFPGMapInterfacedObjectData.Keys (683  ), TFPGMapInterfacedObjectData.IndexOf (682  ),
                TFPGMapInterfacedObjectData.KeyData (684  ), TFPGMapInterfacedObjectData.Data (683  ),
                TFPS.Duplicates (665  )



                51.9.6         TFPGMapInterfacedObjectData.Find

    Synopsis:    Find item based on key

Declaration:     function  Find(const  AKey:  TKey;out  Index:  Integer)  :  Boolean

    Visibility:   public

Description:     Find will search the first key smaller than or equal to AKey and return its index in AIndex.
                If the key was not found then -1 is returned.  The return value of the function is True if an
                exact match for AKey is found, False otherwise.

    See also:    TFPGMapInterfacedObjectData.IndexOf (682  ), TFPGMapInterfacedObjectData.IndexOfData
                (682  )



                                                                                 681

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.9.7         TFPGMapInterfacedObjectData.IndexOf

    Synopsis:    Find index of a key in the list.

Declaration:     function  IndexOf(const  AKey:  TKey)  :  Integer

    Visibility:   public

Description:     IndexOf returns the index of  AKey in the list, or -1 if the key was not found in the list.

       Errors:   None.

    See also:    TFPGMapInterfacedObjectData.Find (681  ), TFPGMapInterfacedObjectData.IndexOfData
                (682  )



                51.9.8         TFPGMapInterfacedObjectData.IndexOfData

    Synopsis:    Find index of data value in the list.

Declaration:     function  IndexOfData(const  AData:  TData)  :  Integer

    Visibility:   public

Description:     IndexOfData returns the index of  AData in the list, or -1 if the data was not found in the
                list.

       Errors:   None.

    See also:    TFPGMapInterfacedObjectData.Find (681  ), TFPGMapInterfacedObjectData.IndexOf (682  )



                51.9.9         TFPGMapInterfacedObjectData.InsertKey

    Synopsis:    Insert a new key in the list

Declaration:     procedure  InsertKey(Index:  Integer;const  AKey:  TKey)

    Visibility:   public

Description:     InsertKey inserts key AKey at position Index in the list.  It is not allowed to insert a key
                in a sorted list.

       Errors:   If the index AIndex is out of range [0..Count-1], or the list is sorted, an EListError (666  )
                exception will be raised.

    See also:    TFPGMapInterfacedObjectData.InsertKeyData (682  ), TFPGMapInterfacedObjectData.Add
                (681  ), TFPSMapInterfacedObjectData.Delete (665  ), TFPSMapInterfacedObjectData.Remove
                (665  )



                51.9.10          TFPGMapInterfacedObjectData.InsertKeyData

    Synopsis:    Insert a new key with associated data in the list

Declaration:     procedure  InsertKeyData(Index:  Integer;const  AKey:  TKey;
                                                      const  AData:  TData)

    Visibility:   public

Description:     InsertKey inserts key AKey with associated data AData at position Index in the list.  It is
                not allowed to insert a key in a sorted list.



                                                                                 682

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



       Errors:   If the index AIndex is out of range [0..Count-1], or the list is sorted, an EListError (666  )
                exception will be raised.

    See also:    TFPGMapInterfacedObjectData.InsertKey (682  ), TFPGMapInterfacedObjectData.Add (681  ),
                TFPSMapInterfacedObjectData.Delete (665  ), TFPGMapInterfacedObjectData.Remove (683  )



                51.9.11          TFPGMapInterfacedObjectData.Remove

    Synopsis:    Remove a key from the list

Declaration:     function  Remove(const  AKey:  TKey)  :  Integer

    Visibility:   public

Description:     Remove removes the key AKey from the list, together with its associated data.  The function
                returns the index of AKey prior to removal from the list, or -1 if AKey was not present in the
                list.

       Errors:   None.

    See also:    TFPGMap.InsertKey  (677  ),  TFPGMap.InsertKeyData  (677  ),  TFPGMap.Add  (676  ),  TF-
                PGMapInterfacedObjectData.Delete (680  )



                51.9.12          TFPGMapInterfacedObjectData.Keys

    Synopsis:    Indexed access to the keys in the list.

Declaration:     Property  Keys[Index:  Integer]:  TKey

    Visibility:   public

      Access:    Read,Write

Description:     Keys provides indexed access to the key values in the list.  Valid values for Index are in the
                range [0..Count-1].  Key values can always be read, but can only be written if the list is
                unsorted.

       Errors:   If the index AIndex is out of range [0..Count-1], an EListError (666  ) exception will be raised.
                The same exception is raised if a key is written and the list is sorted.

    See also:    TFPSList.Count  (695  ),  TFPGMapInterfacedObjectData.Data  (683  ),  TFPGMapInterface-
                dObjectData.KeyData (684  )



                51.9.13          TFPGMapInterfacedObjectData.Data

    Synopsis:    Indexed access to the data in the list

Declaration:     Property  Data[Index:  Integer]:  TData

    Visibility:   public

      Access:    Read,Write

Description:     Data provides indexed access to the data values in the list.  Valid values for Index are in
                the range [0..Count-1].  Data can always be read or written.

       Errors:   If the index AIndex is out of range [0..Count-1], an EListError (666  ) exception will be raised.

    See also:    TFPSList.Count  (695  ),  TFPGMapInterfacedObjectData.Keys  (683  ),  TFPGMapInterface-
                dObjectData.KeyData (684  )



                                                                                 683

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.9.14          TFPGMapInterfacedObjectData.KeyData

    Synopsis:    Access to data based on key

Declaration:     Property  KeyData[AKey:  TKey]:  TData;  default

    Visibility:   public

      Access:    Read,Write

Description:     KeyData allows access to the data based on the key value AKey.  The data can be read and
                written.  When writing, writing using an existing key will overwrite the current data.  If it
                does not exist yet, it will be created.  When reading, if the key is not present, an EListError
                (666  ) will be raised.

       Errors:   If the key does not exist, an EListError (666  ) exception will be raised.

    See also:    TFPSList.Count  (695  ),  TFPGMapInterfacedObjectData.Keys  (683  ),  TFPGMapInterface-
                dObjectData.Data (683  )



                51.9.15          TFPGMapInterfacedObjectData.OnCompare

    Synopsis:    Alias for OnKeyCompare

Declaration:     Property  OnCompare  :  TKeyCompareFunc

    Visibility:   public

      Access:    Read,Write

Description:     OnCompare is a deprecated property, use TFPGMapInterfacedObjectData.OnKeyCompare
                (684  ) instead.

    See also:    TFPGMapInterfacedObjectData.OnKeyCompare (684  )



                51.9.16          TFPGMapInterfacedObjectData.OnKeyCompare

    Synopsis:    Compare function for key values.

Declaration:     Property  OnKeyCompare  :  TKeyCompareFunc

    Visibility:   public

      Access:    Read,Write

Description:     OnKeyCompare can be set to a function that compares key values.  The default value for this
                event is a function that compares keys based on a byte-by-byte comparison of the memory
                block.  The function must have the following semantics:


                      oIf the result of this function is negative, the first key (key1) is assumed to be 'less' than
                       the second key (key2) and will be moved before the second in the list.

                      oIf the function result is positive, the first key (key1) pointer is assumed to be 'greater
                       than' the second key (key2)and will be moved after the second in the list.

                      oif the function result is zero, the keys are assumed to be 'equal' and no moving will take
                       place.


    See also:    TFPGMapInterfacedObjectData.OnDataCompare (685  )



                                                                                 684

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.9.17          TFPGMapInterfacedObjectData.OnDataCompare

    Synopsis:    Compare function for data values.

Declaration:     Property  OnDataCompare  :  TDataCompareFunc

    Visibility:   public

      Access:    Read,Write

Description:     OnDataCompare  can  be  set  to  a  function  that  compares  data  values.   The  default  value
                for this event is a function that compares data based on a byte-by-byte comparison of the
                memory block.  The function must have the following semantics:

                      oIf the result of this function is negative, the first data item (Data1) is assumed to be
                       'less'  than  the  second  data  item  (Data2)  and  will  be  moved  before  the  second  in  the
                       list.

                      oIf the function result is positive, the first data item (Data1) pointer is assumed to be
                       'greater than' the second data item (Data2)and will be moved after the second in the
                       list.

                      oif the function result is zero, the data items are assumed to be 'equal' and no moving
                       will take place.

    See also:    TFPGMapInterfacedObjectData.OnKeyCompare (684  )



                51.10            TFPGOb jectList



                51.10.1          Description

                TFPGList can be used to specialize a list for any class type T that does not require reference
                counting (such as interfaced objects).  It will specialize to a list with the same methods as
                TFPSList (689  ) or classes.TFPList (665  ) or TFPObjectList

    See also:    TFPSList (689  ), classes.TFPList (665  )



                51.10.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  686       Add                       Add new object of class T to the list.
                  687       Assign                    Copy objects from Source list
                  686       Create                    Instantiate a new object list.
                  686       Extract                   Extract an item from the list
                  686       GetEnumerator             Return a list enumerator for T.
                  687       IndexOf                   Index of item
                  687       Insert                    Insert a new object in the list
                  687       Remove                    Remove an object from the list.
                __688_______Sort______________________Sort_the_objects_in_the_list_________________________________________________*
 *___________



                51.10.3          Property  overview

                __Page______Properties___________Access______Description___________________________________________________________*
 *___________
                  688       First                rw          First non-nil item
                  689       FreeObjects          rw          Does the list own the objects or not?
                  688       Items                rw          Indexed access to objects in the list.
                  688       Last                 rw          Last non-Nil object
                __689_______List_________________r___________Internal_list_pointer_________________________________________________*
 *___________



                                                                                 685

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.10.4          TFPGObjectList.Create

    Synopsis:    Instantiate a new object list.

Declaration:     constructor  Create(FreeObjects:  Boolean)

    Visibility:   public

Description:     Create instantiates a new object list.  It will simply call the inherited constructor with the
                correct item size and will initialize TFPGObjectList.FreeObjects (689  ) with FreeObjects.

                If FreeObjects is true, then the list owns the objects.  Freeing or clearing the list will remove
                all objects from memory by calling the destructor.  Deleting or removing an item from the
                list will also dispose of the element.

    See also:    TFPGObjectList.FreeObjects (689  )



                51.10.5          TFPGObjectList.Add

    Synopsis:    Add new object of class T to the list.

Declaration:     function  Add(const  Item:  T)  :  Integer

    Visibility:   public

Description:     Add adds a new item Item of class type T to the list and returns the position at which the
                item was added.

       Errors:   If the item could not be added, an EListError (666  ) exception is raised.

    See also:    TFPGObjectList.Extract  (686  ),  TFPGObjectList.Items  (688  ),  TFPGObjectList.IndexOf
                (687  )



                51.10.6          TFPGObjectList.Extract

    Synopsis:    Extract an item from the list

Declaration:     function  Extract(const  Item:  T)  :  T

    Visibility:   public

Description:     Extract  removes  Item  from  the  list  and  returns  the  removed  item,  or  Nil  if  it  was  not
                found.

                The extracted object will not be destroyed even if the list owns the objects.

       Errors:   None.

    See also:    TFPSList.Delete (691  )



                51.10.7          TFPGObjectList.GetEnumerator

    Synopsis:    Return a list enumerator for T.

Declaration:     function  GetEnumerator  :  TFPGListEnumeratorSpec

    Visibility:   public

Description:     GetEnumerator returns an enumerator for the elements in the list.  It is a specialized version
                of TFPGListEnumerator (674  ).

    See also:    TFPGListEnumerator (674  )



                                                                                 686

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.10.8          TFPGObjectList.IndexOf

    Synopsis:    Index of item

Declaration:     function  IndexOf(const  Item:  T)  :  Integer

    Visibility:   public

Description:     IndexOf returns the index of  Item in the list, or -1 if the item does not appear in the list.

       Errors:   None.

    See also:    TFPGObjectList.Items (688  ), TFPGObjectList.Insert (687  ), TFPGObjectList.Add (686  )



                51.10.9          TFPGObjectList.Insert

    Synopsis:    Insert a new object in the list

Declaration:     procedure  Insert(Index:  Integer;const  Item:  T)

    Visibility:   public

Description:     Insert inserts a new object (Item) in the list at position Index.  The index is zero based
                and must be less than Count (695  ).

       Errors:   If an invalid index is specified, an EListError (666  ) exception is raised.

    See also:    TFPGList.Items (673  ), TFPGList.Insert (672  ), TFPSList.Add (691  )



                51.10.10           TFPGObjectList.Assign

    Synopsis:    Copy objects from Source list

Declaration:     procedure  Assign(Source:  TFPGObjectList)

    Visibility:   public

Description:     Assign clears the list and copies all items in Source to the list.  The source list must be of
                the same type as the destination list.

                Take care if both the list owns the objects (i.e.  have TFPGObjectList.FreeObjects (689  ) set
                to True), this may result to access violations.

    See also:    TFPSList.Clear (691  ), TFPGObjectList.Add (686  )



                51.10.11           TFPGObjectList.Remove

    Synopsis:    Remove an object from the list.

Declaration:     function  Remove(const  Item:  T)  :  Integer

    Visibility:   public

Description:     Remove removes the object Item from the list, and returns the index of the removed item.
                If no item was removed, -1 is returned.  Only the first object is removed.

                If  the  list  owns  the  objects,  (TFPGObjectList.FreeObjects  (689  )  is  set  to  True)  then  the
                object is freed.

       Errors:   None.

    See also:    TFPGObjectList.IndexOf (687  ), TFPSList.Delete (691  ), TFPGObjectList.FreeObjects (689  )



                                                                                 687

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.10.12           TFPGObjectList.Sort

    Synopsis:    Sort the objects in the list

Declaration:     procedure  Sort(Compare:  TCompareFunc)

    Visibility:   public

Description:     Sort sorts the elements in the list using the provided Compare function.  The list passes 2
                items to the compare function.  The result of this function determines how the items will be
                sorted:


                      oIf the result of this function is negative, the first object (Item1) is assumed to be 'less'
                       than the second object (Item2) and will be moved before the second in the list.

                      oIf the function result is positive, the first object (Item1) is assumed to be 'greater than'
                       the second object (Item2)and will be moved after the second in the list.

                      oif the function result is zero, the objects are assumed to be 'equal' and no moving will
                       take place.


       Errors:   None.



                51.10.13           TFPGObjectList.First

    Synopsis:    First non-nil item

Declaration:     Property  First  :  T

    Visibility:   public

      Access:    Read,Write

Description:     First returns the first non-nil item.  If no such element is present, Nil is returned.

    See also:    TFPSList.First (696  ), TFPGList.Last (673  ), TFPSList.Pack (694  )



                51.10.14           TFPGObjectList.Last

    Synopsis:    Last non-Nil object

Declaration:     Property  Last  :  T

    Visibility:   public

      Access:    Read,Write

Description:     Last returns the last non-Nil object.  If no such element is present, Nil.  is returned.

    See also:    TFPGObjectList.First (688  ), TFPSList.Last (696  )



                51.10.15           TFPGObjectList.Items

    Synopsis:    Indexed access to objects in the list.

Declaration:     Property  Items[Index:  Integer]:  T;  default

    Visibility:   public

      Access:    Read,Write



                                                                                 688

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



Description:     Items provides indexed access to the objects in the list.  The objects can be get or set.

                The index Index is zero based, and has a maximum value of Count-1 (695  ).

                If  the  list  owns  the  objects,  (TFPGObjectList.FreeObjects  (689  )  is  set  to  True)  then  the
                previous object at position Index is freed when setting the property.

       Errors:   If an invalid index is used, an EListError (666  ) exception is raised.

    See also:    TFPSList.Count (695  ), TFPGObjectList.FreeObjects (689  )



                51.10.16           TFPGObjectList.List

    Synopsis:    Internal list pointer

Declaration:     Property  List  :  PTypeList

    Visibility:   public

      Access:    Read

Description:     List is the internal list of objects.  It should not be used directly.

    See also:    TFPGObjectList.Items (688  )



                51.10.17           TFPGObjectList.FreeObjects

    Synopsis:    Does the list own the objects or not?

Declaration:     Property  FreeObjects  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     FreeObjects indicates whether the list owns the objects or not.  If set to True, freeing or
                clearing the list will remove all objects from memory by calling the destructor.  Deleting or
                removing an item from the list will also dispose of the element.

                The initial value for this property is set in the constructor and is True by default.

    See also:    TFPGObjectList.FreeObjects (689  )



                51.11            TFPSList



                51.11.1          Description

                TFPSList can be seen as the generalized equivalent of the classes unit TFPList (665  ) list.  It
                is used as a base class for the TFPGList (670  ), TFPGMap (675  ), TFPGObjectList (685  ),
                TFPGInterfacedObjectList (666  ) and TFPGMapInterfacedObjectData (680  ) generic classes.

                This list is not meant to be used directly, it is an auxiliary class for the actual generic list
                classes.


    See also:    classes.TFPList (665  ), TFPGMap (675  ), TFPGObjectList (685  ), TFPGInterfacedObjectList
                (666  ), TFPGMapInterfacedObjectData (680  )



                                                                                 689

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.11.2          Method  overview

                __Page______Method___________Description___________________________________________________________________________*
 *___________
                  691       Add              Add a new item to the list
                  693       Assign           Copy one list to another
                  691       Clear            Clear the list
                  690       Create           Create a new instance of  TFPSList
                  691       Delete           Delete an item from the list
                  690       Destroy          Destroy the list instance.
                  691       Error            Raise an EListError exception.
                  692       Exchange         Exchange two items in the list
                  692       Expand           Expand the capacity of the list
                  692       Extract          delete an element from the list
                  692       IndexOf          Search an item in the list
                  693       Insert           Insert a new item in the list.
                  693       Move             Moves an item from one position in the list to another.
                  694       Pack             Remove empty items from the list
                  694       Remove           Remove the item from the list
                __694_______Sort_____________Sort_the_list_________________________________________________________________________*
 *___________



                51.11.3          Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  695       Capacity          rw           Current capacity of the list
                  695       Count             rw           Current element count
                  696       First             rw           Pointer to first non-empty item in the list
                  695       Items             rw           Items in the list
                  696       ItemSize          r            Size of the items in the list
                  696       Last              rw           Pointer to last non-empty item in the list
                __696_______List______________r____________Internal_list_pointer___________________________________________________*
 *___________



                51.11.4          TFPSList.Create

    Synopsis:    Create a new instance of  TFPSList

Declaration:     constructor  Create(AItemSize:  Integer)

    Visibility:   public

Description:     Create creates a new instance of TFPSList, and initializes the item size to ItemSize, which
                defaults to the size of a pointer.

    See also:    TFPSList.ItemSize (696  ), TFPSList.Destroy (690  )



                51.11.5          TFPSList.Destroy

    Synopsis:    Destroy the list instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy clears and cleans up the list instance.  Depending on the descendant, this may also
                remove the items in the list from memory.

    See also:    TFPSList.Clear (691  )



                                                                                 690

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.11.6          TFPSList.Add

    Synopsis:    Add a new item to the list

Declaration:     function  Add(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Add adds the item pointed to by Item to the list.  It is not the pointer Item itself which is
                added to the list, but rather the TFPSList.ItemSize (696  ) bytes of memory to which Item
                is pointing.

                The function returns the index of the newly added item.

       Errors:   If the maximum list size is reached, an EListError (666  ) is raised.

    See also:    TFPSList.Delete (691  ), TFPSList.Items (695  ), TFPSList.Clear (691  )



                51.11.7          TFPSList.Clear

    Synopsis:    Clear the list

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear removes all the items in the list.  Depending on the descendent, the list items them-
                selves may be cleared as well.

    See also:    TFPSList.Delete (691  ), TFPSList.Items (695  ), TFPSList.Add (691  )



                51.11.8          TFPSList.Delete

    Synopsis:    Delete an item from the list

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete deletes the item at position Index from the list.  Depending on the descendent, the
                list items itself may be cleared as well.

       Errors:   If  Index is out of bounds, an EListError (666  ) exception is raised.

    See also:    TFPSList.Clear (691  ), TFPSList.Items (695  ), TFPSList.Add (691  )



                51.11.9          TFPSList.Error

    Synopsis:    Raise an EListError exception.

Declaration:     class  procedure  Error(const  Msg:  string;Data:  PtrInt)

    Visibility:   public

Description:     Error  is  an  auxiliary  routine  which  raises  an  EListError  (666  )  exception  formatted  from
                Msg and Data.

    See also:    EListError (666  )



                                                                                 691

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.11.10           TFPSList.Exchange

    Synopsis:    Exchange two items in the list

Declaration:     procedure  Exchange(Index1:  Integer;Index2:  Integer)

    Visibility:   public

Description:     Exchange will exchange 2 items at positions Index1 and Index2 in the list.

       Errors:   If  Index1 or Index2 are out of bounds, an EListError (666  ) exception is raised.



                51.11.11           TFPSList.Expand

    Synopsis:    Expand the capacity of the list

Declaration:     function  Expand  :  TFPSList

    Visibility:   public

Description:     Expand will expand the capacity of the list, and returns itself.

       Errors:   If the size will become larger than MaxListSize (665  ) an EListError (666  ) exception will be
                raised.

    See also:    MaxListSize (665  ), TFPSList.Capacity (695  )



                51.11.12           TFPSList.Extract

    Synopsis:    delete an element from the list

Declaration:     procedure  Extract(Item:  Pointer;ResultPtr:  Pointer)

    Visibility:   public

Description:     Extract  removes  the  item  pointed  to  by  Item  from  the  list.  It  returns  a  pointer  to  the
                actually removed item from the list.  The item is searched using TFPSList.IndexOf (692  ).  If
                the item is not found, nil is returned.

                Some descendents own the items in the list.  Extract will not dispose of the item, as TFP-
                SList.Delete (691  ) does.

       Errors:   None.

    See also:    TFPSList.Delete (691  ), TFPSList.Add (691  ), TFPSList.IndexOf (692  )



                51.11.13           TFPSList.IndexOf

    Synopsis:    Search an item in the list

Declaration:     function  IndexOf(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     IndexOf searches in the list for the item pointed to by Item, and returns the position (0-
                based index) of the item in the list, or -1 if it was not found.  The items are compared using
                system.CompareMem (665  ), so an exact memory layout match.

    See also:    TFPSList.Extract (692  )



                                                                                 692

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.11.14           TFPSList.Insert

    Synopsis:    Insert a new item in the list.

Declaration:     procedure  Insert(Index:  Integer;Item:  Pointer)
                function  Insert(Index:  Integer)  :  Pointer

    Visibility:   public

Description:     Insert comes in 2 overloaded version.  The version without Item creates a slot for a new
                item at position Index in the list, and returns a pointer to the new slot.  The slot will be of
                size TFPSList.ItemSize (696  ).

                The version with Item argument will allocate a slot in the list at position Index and will
                copy the item pointed to by Item to the slot in the list.

                In both cases, Index must be 0-based.

       Errors:   If  Index is invalid, an EListError (666  ) exception will be raised.

    See also:    TFPSList.Add (691  ), TFPSList.Delete (691  ), TFPSList.Extract (692  )



                51.11.15           TFPSList.Move

    Synopsis:    Moves an item from one position in the list to another.

Declaration:     procedure  Move(CurIndex:  Integer;NewIndex:  Integer)

    Visibility:   public

Description:     Move moves the item 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

       Errors:   If  CurIndex  or  Newindex  are  not  inside  the  valid  range  of  indices,  an  EListError  (666  )
                exception is raised.

    See also:    Exchange (692  )



                51.11.16           TFPSList.Assign

    Synopsis:    Copy one list to another

Declaration:     procedure  Assign(Obj:  TFPSList)

    Visibility:   public

Description:     Assign clears the list and will add all items from Obj to the list.  The items are copied one
                by one.

       Errors:   If  the  TFPSList.ItemSize  (696  )  differs  for  the  two  lists,  an  EListError  (666  )  exception  is
                raised.

    See also:    TFPSList.Add (691  )



                                                                                 693

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.11.17           TFPSList.Remove

    Synopsis:    Remove the item from the list

Declaration:     function  Remove(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Remove searches Item in the list,  and deletes it from the list.  It returns the index of the
                item that was removed, or -1 if it was not found.  Only the first match is removed.

                If a descendent of  TFPSList owns the object of the list, the item is removed from memory.
                If this is not desired, then TFPSList.Extract (692  ) must be used instead.

    See also:    TFPSList.Extract (692  ), TFPSList.IndexOf (692  )



                51.11.18           TFPSList.Pack

    Synopsis:    Remove empty items from the list

Declaration:     procedure  Pack

    Visibility:   public

Description:     Pack will remove all empty items from the list.  An item is considered to be empty if the
                memory location where the item is stored contains only zero bytes.

    See also:    TFPSList.Clear (691  ), TFPSList.Sort (694  )



                51.11.19           TFPSList.Sort

    Synopsis:    Sort the list

Declaration:     procedure  Sort(Compare:  TFPSListCompareFunc)

    Visibility:   public

Description:     Sort> sorts the items 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 item is assumed to be 'less' than the
                       second and will be moved before the second item in the list.

                      oIf the function result is positive, the first item is assumed to be 'greater than' the second
                       and will be moved after the second item 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.

    See also:    TFPSListCompareFunc (665  )



                                                                                 694

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.11.20           TFPSList.Capacity

    Synopsis:    Current capacity of the list

Declaration:     Property  Capacity  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Capacity  is  the  current  capacity  (maximum  amount  of  elements)  of  the  list.   The  list
                capacity will expand automatically if an item is added and the capacity is reached (i.e.  TF-
                PSList.Count (695  ) equals capacity.  Expanding the list is an expensive operation involving
                reallocation of memory and moving of list data in memort, so capacity can be set to a large
                amount to avoid frequent reallocations.

    See also:    TFPSList.Count (695  ), TFPSList.Expand (692  ), TFPSList.Items (695  )



                51.11.21           TFPSList.Count

    Synopsis:    Current element count

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Count is the current amount of elements in the list.  It is initially zero.  A valid item index
                is always a value between zero and Count-1.

    See also:    TFPSList.Items (695  ), TFPSList.Capacity (695  )



                51.11.22           TFPSList.Items

    Synopsis:    Items in the list

Declaration:     Property  Items[Index:  Integer]:  Pointer;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items  provides  indexed  access  to  the  items  in  the  list,  the  returned  pointers  are  not  the
                actual list items, but pointers to the elements in the list.  The items can be get or set.

                When assigning to the Items property, the memory area pointed to by the assigned pointer
                is copied to the list.  Exactly TFPSList.ItemSize (696  ) bytes are copied.

                The index Index is zero based, and has a maximum value of Count-1 (695  ).

       Errors:   If an invalid index is used, an EListError (666  ) exception is raised.

    See also:    TFPSList.ItemSize (696  ), TFPSList.Count (695  )



                                                                                 695

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.11.23           TFPSList.ItemSize

    Synopsis:    Size of the items in the list

Declaration:     Property  ItemSize  :  Integer

    Visibility:   public

      Access:    Read

Description:     ItemSize is the memory size of the items in the list.  It is specified in the constructor and
                cannot be changed during the lifetime of the list.

    See also:    TFPSList.Create (690  )



                51.11.24           TFPSList.List

    Synopsis:    Internal list pointer

Declaration:     Property  List  :  PByte

    Visibility:   public

      Access:    Read

Description:     List  is  a  pointer  to  the  memory  area  used  for  the  items  in  the  list.   It  should  not  be
                manipulated.



                51.11.25           TFPSList.First

    Synopsis:    Pointer to first non-empty item in the list

Declaration:     Property  First  :  Pointer

    Visibility:   public

      Access:    Read,Write

Description:     First returns the value of the first non-empty item in the list.  An item is considered empty
                if consists of TFPSList.ItemSize (696  ) zero bytes.

                If there are no non-empty items in the list, then Nil is returned.

    See also:    TFPSList.Last (696  ), TFPSList.Pack (694  )



                51.11.26           TFPSList.Last

    Synopsis:    Pointer to last non-empty item in the list

Declaration:     Property  Last  :  Pointer

    Visibility:   public

      Access:    Read,Write

Description:     Last returns the value of the last non-empty item in the list.  An item is considered empty
                if consists of TFPSList.ItemSize (696  ) zero bytes.

                If there are no non-empty items in the list, then Nil is returned.

    See also:    TFPSList.Last (696  ), TFPSList.Pack (694  )



                                                                                 696

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.12            TFPSMap



                51.12.1          Description

                TFPSMap can be used to create a map for any type T that does not require reference counting
                (such as interfaced objects).  It will specialize to a map which is a generalized list with an
                arbitrary type as the list index (called the key).

                This class should normally not be used directly, instead use one of the generic map objects
                such as TFPGMap (675  ).


    See also:    TFPGMap (675  )



                51.12.2          Method  overview

                __Page______Method__________________Description____________________________________________________________________*
 *___________
                  698       Add                     Add a key, value pair to the map.
                  697       Create                  Create a new map with given key and data size.
                  698       Find                    Find data using the associated key
                  698       IndexOf                 Index of key pointed to by AKey
                  699       IndexOfData             Index of data item AData
                  699       Insert                  Insert a new slot for key and associated data item in the list
                  699       InsertKey               Insert a key in the list
                  699       InsertKeyData           Insert a key and associated in the list
                  700       Remove                  Remove a key/value pair from the map.
                __700_______Sort____________________Sort_the_list_according_to_key_________________________________________________*
 *___________



                51.12.3          Property  overview

                __Page______Properties______________________Access_______Description_______________________________________________*
 *___________
                  701       Data                            rw           Indexed access to the locations of all data items
                  701       DataSize                        r            Size (in bytes) for the data associated with keys
                  700       Duplicates                      rw           What to do with duplicate key values
                  702       KeyData                         rw           Access to data locations using key
                  701       Keys                            rw           Indexed access to the locations of all keys
                  701       KeySize                         r            Size (in bytes) for the key
                  703       OnDataPtrCompare                rw           Callback to compare 2 data items
                  702       OnKeyPtrCompare                 rw           Callback to compare 2 keys
                  702       OnPtrCompare                    rw           Alias for OnKeyPtrCompare
                __702_______Sorted__________________________rw___________Is_the_map_permanently_sorted_on_key_?____________________*
 *___________



                51.12.4          TFPSMap.Create

    Synopsis:    Create a new map with given key and data size.

Declaration:     constructor  Create(AKeySize:  Integer;ADataSize:  Integer)

    Visibility:   public

Description:     Create  instantiates  a  new  TFPSMap  instance  and  initializes  TFPSMap.KeySize  (701  )  and
                TFPSMap.DataSize (701  ) with AKeySize and ADataSize, respectively.  It also initializes the
                TFPSMap.OnDataPtrCompare (703  ) and TFPSMap.OnKeyPtrCompare (702  ) properties to
                functions that compare memory blocks.

       Errors:   None.



                                                                                 697

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



    See also:    TFPSMap.Destroy (697  ), TFPSMap.KeySize (701  ), TFPSMap.DataSize (701  ), TFPSMap.OnDataPtrCompare
                (703  ), TFPSMap.OnKeyPtrCompare (702  )



                51.12.5          TFPSMap.Add

    Synopsis:    Add a key, value pair to the map.

Declaration:     function  Add(AKey:  Pointer;AData:  Pointer)  :  Integer
                function  Add(AKey:  Pointer)  :  Integer

    Visibility:   public

Description:     Add  adds  the  memory  pointed  to  by  AData  to  the  map  using  the  memory  pointed  to  by
                AKey as the key.  If no data is specified, it allocates a slot fot AKey and returns a pointer to
                that slot.

       Errors:   If the maximum amount of values is reached, Add will raise an EListError (666  ) exception.

    See also:    TFPSMap.Insert (699  ), TFPSMap.IndexOf (698  )



                51.12.6          TFPSMap.Find

    Synopsis:    Find data using the associated key

Declaration:     function  Find(AKey:  Pointer;out  Index:  Integer)  :  Boolean

    Visibility:   public

Description:     Find searches for the first key less than or equal to AKey and returns its index in the list in
                Index.  It returns True if an exact match for the key was found.  It returns False if the key
                was not found, and Index is then set to -1

                This function performs a binary search using the key comparing function specified in On-
                KeyPtrCompare (702  ).

       Errors:   if  OnKeyPtrCompare is not set, an access violation will occur.

    See also:    TFPSMap.OnKeyPtrCompare (702  )



                51.12.7          TFPSMap.IndexOf

    Synopsis:    Index of key pointed to by AKey

Declaration:     function  IndexOf(AKey:  Pointer)  :  Integer

    Visibility:   public

Description:     IndexOf returns the index of the element with a key pointed to by  AKey.  It returns -1 if
                the key was not found.

                If the list is sorted, then a binary search is performed, otherwise a linear search is used to
                find the key.

       Errors:   None.

    See also:    TFPSMap.Find (698  ), TFPSMap.IndexOfData (699  ), TFPSMap.Keys (701  ), TFPSMap.Data
                (701  )



                                                                                 698

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.12.8          TFPSMap.IndexOfData

    Synopsis:    Index of data item AData

Declaration:     function  IndexOfData(AData:  Pointer)  :  Integer

    Visibility:   public

Description:     IndexOfData returns the index of the element with data pointed to by AData.  It returns -1
                if the data item was not found.  The search is always performed using a linear search.

    See also:    TFPSMap.Find  (698  ),  TFPSMap.IndexOf  (698  ),  TFPSMap.Keys  (701  ),  TFPSMap.Data
                (701  )



                51.12.9          TFPSMap.Insert

    Synopsis:    Insert a new slot for key and associated data item in the list

Declaration:     function  Insert(Index:  Integer)  :  Pointer
                procedure  Insert(Index:  Integer;out  AKey:  Pointer;out  AData:  Pointer)

    Visibility:   public

Description:     Insert will allocate a new slot in the list.  It returns a pointer to the new slot.  If Akey and
                AData are given, then they will point to the positions in the slot for the key and data items.

       Errors:   If  the  maximum  amount  of  values  is  reached  or  an  invalid  index  is  specified,  Insert  will
                raise an EListError (666  ) exception.

    See also:    TFPSMap.Add (698  ), TFPSMap.InsertKey (699  ), TFPSMap.InsertKeyData (699  )



                51.12.10           TFPSMap.InsertKey

    Synopsis:    Insert a key in the list

Declaration:     procedure  InsertKey(Index:  Integer;AKey:  Pointer)

    Visibility:   public

Description:     InsertKey will allocate a new slot in the list for a key value as pointed to by  AKey,  and
                copy the key pointed to by AKey to the slot.

       Errors:   If the maximum amount of values is reached or an invalid index is specified, InsertKey will
                raise an EListError (666  ) exception.

    See also:    TFPSMap.Add (698  ), TFPSMap.Insert (699  ), TFPSMap.InsertKeyData (699  )



                51.12.11           TFPSMap.InsertKeyData

    Synopsis:    Insert a key and associated in the list

Declaration:     procedure  InsertKeyData(Index:  Integer;AKey:  Pointer;AData:  Pointer)

    Visibility:   public

Description:     InsertKeyData will allocate a new slot in the list for a key value as pointed to by  AKey,
                and copy the key pointed to by AKey as well as the data pointed to by AData to the newly
                allocated slot.



                                                                                 699

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



       Errors:   If the maximum amount of values is reached or an invalid index is specified, InsertKeyData
                will raise an EListError (666  ) exception.

    See also:    TFPSMap.Add (698  ), TFPSMap.Insert (699  ), TFPSMap.InsertKey (699  )



                51.12.12           TFPSMap.Remove

    Synopsis:    Remove a key/value pair from the map.

Declaration:     function  Remove(AKey:  Pointer)  :  Integer

    Visibility:   public

Description:     Remove removes the key/value pair pointing to by AKey from the map.  It returns the index
                of  Akey prior to removal from the list.  If  AKey was not found, -1 is returned.

       Errors:   None.

    See also:    TFPSList.Delete (691  ), TFPSMap.IndexOf (698  )



                51.12.13           TFPSMap.Sort

    Synopsis:    Sort the list according to key

Declaration:     procedure  Sort

    Visibility:   public

Description:     Sort  sorts  the  list  according  to  the  key  value,  using  the  compare  function  provided  in
                TFPSMap.OnKeyPtrCompare (702  )

       Errors:   None.

    See also:    TFPSMap.OnKeyPtrCompare (702  ), TFPSMap.OnDataPtrCompare (703  )



                51.12.14           TFPSMap.Duplicates

    Synopsis:    What to do with duplicate key values

Declaration:     Property  Duplicates  :  TDuplicates

    Visibility:   public

      Access:    Read,Write

Description:     Duplicates can be set to determine what to do with duplicate key values in the map:


                dupIgnore       Ignore the new item, do not add it to the list.

                dupAccept        Accept duplicates, adding them to the list.

                dupError       Raise an error when an attempt is made to add a duplicate.


                The value is ignored if Sorted (702  ) is False.

    See also:    TFPSMap.Sorted (702  ), types.TDuplicates (665  )



                                                                                 700

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.12.15           TFPSMap.KeySize

    Synopsis:    Size (in bytes) for the key

Declaration:     Property  KeySize  :  Integer

    Visibility:   public

      Access:    Read

Description:     KeySize  is  the  size  (in  bytes)  for  the  keys  in  the  map.  This  size  is  initialized  during  list
                construction and defaults to the size of a pointer.

    See also:    TFPSMap.Create (697  ), TFPSMap.DataSize (701  ), TFPSMap.Keys (701  ), TFPSMap.KeyData
                (702  )



                51.12.16           TFPSMap.DataSize

    Synopsis:    Size (in bytes) for the data associated with keys

Declaration:     Property  DataSize  :  Integer

    Visibility:   public

      Access:    Read

Description:     DataSize is the size (in bytes) for the data in the map.  This size is initialized during list
                construction and defaults to the size of a pointer.

    See also:    TFPSMap.Create (697  ), TFPSMap.KeySize (701  ), TFPSMap.Keys (701  ), TFPSMap.KeyData
                (702  ), TFPSMap.Data (701  )



                51.12.17           TFPSMap.Keys

    Synopsis:    Indexed access to the locations of all keys

Declaration:     Property  Keys[Index:  Integer]:  Pointer

    Visibility:   public

      Access:    Read,Write

Description:     Keys provides indexed access to all keys.  It does not return the key, but returns a pointer
                to the key value.  When setting the Keys property, a pointer to the key value must be set,
                and the key value is copied from the pointer.

    See also:    TFPSMap.KeySize (701  ), TFPSMap.KeyData (702  ), TFPSMap.Data (701  )



                51.12.18           TFPSMap.Data

    Synopsis:    Indexed access to the locations of all data items

Declaration:     Property  Data[Index:  Integer]:  Pointer

    Visibility:   public

      Access:    Read,Write

Description:     Data provides indexed access to all data.  It does not return the actual data, but returns a
                pointer to the data.  When setting the Data property, a pointer to the data value must be
                set, and the data value is copied from the pointer.

    See also:    TFPSMap.DataSize (701  ), TFPSMap.KeyData (702  ), TFPSMap.Keys (701  )



                                                                                 701

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



                51.12.19           TFPSMap.KeyData

    Synopsis:    Access to data locations using key

Declaration:     Property  KeyData[Key:  Pointer]:  Pointer;  default

    Visibility:   public

      Access:    Read,Write

Description:     KeyData provides access to the data items,  using their key value (as pointed to by  AKey)
                as an index.  When reading a non-existent key value, Nil is returned.  If the key is found, a
                pointer to the associated data's location is returned.  When writing, the key pointed to by
                Key is added if it was not present, and the data data is copied from the written pointer.

    See also:    TFPSMap.DataSize (701  ), TFPSMap.KeyData (702  ), TFPSMap.Data (701  ), TFPSMap.Keys
                (701  ), TFPSMap.KeySize (701  )



                51.12.20           TFPSMap.Sorted

    Synopsis:    Is the map permanently sorted on key ?

Declaration:     Property  Sorted  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Sorted can be set to true to keep the map permanently sorted on key value.  The sorting
                happens using TFPSMap.OnKeyPtrCompare (702  ).

    See also:    TFPSMap.OnKeyPtrCompare (702  ), TFPSMap.Sort (700  ), TFPSMap.Duplicates (700  )



                51.12.21           TFPSMap.OnPtrCompare

    Synopsis:    Alias for OnKeyPtrCompare

Declaration:     Property  OnPtrCompare  :  TFPSListCompareFunc

    Visibility:   public

      Access:    Read,Write

Description:     OnPtrCompare is a deprecated alias for OnKeyPtrCompare (702  ).

    See also:    TFPSMap.OnKeyPtrCompare (702  ), TFPSMap.OnDataPtrCompare (703  )



                51.12.22           TFPSMap.OnKeyPtrCompare

    Synopsis:    Callback to compare 2 keys

Declaration:     Property  OnKeyPtrCompare  :  TFPSListCompareFunc

    Visibility:   public

      Access:    Read,Write



                                                                                 702

                ________________________________________________________________CHAPTER_51.___REFERENCE_FOR_UNIT_'FGL'_____________*
 *___________________



Description:     OnKeyPtrCompare is used to compare the values of 2 keys.  By default it simply compares
                the byte values of the key memory block.  It can be set to any function that performs another
                comparison.  (e.g.  a function that treats the memory blocks as a string pointer and compare
                the actual strings).

                This function is used to sort the list or find a key.

    See also:    TFPSListCompareFunc (665  ), TFPSMap.OnDataPtrCompare (703  ), TFPSMap.Sort (700  ),
                TFPSMap.Find (698  ), TFPSMap.IndexOf (698  )



                51.12.23           TFPSMap.OnDataPtrCompare

    Synopsis:    Callback to compare 2 data items

Declaration:     Property  OnDataPtrCompare  :  TFPSListCompareFunc

    Visibility:   public

      Access:    Read,Write

Description:     OnKeyPtrCompare is used to compare the values of 2 keys.  By default it simply compares
                the byte values of the key memory block.  It can be set to any function that performs another
                comparison.  (e.g.  a function that treats the memory blocks as a string pointer and compare
                the actual strings).

                This function is used to find a data item (IndexOf (699  )).

    See also:    TFPSListCompareFunc (665  ), TFPSMap.OnKeyPtrCompare (702  ), TFPSMap.IndexOfData
                (699  )



                                                                                 703




Chapter   52



Reference   for   unit   'fpwidestring'



52.1          Used  units



                                Table 52.1:  Used units by unit 'fpwidestring'


                                                __Name________________Page_____
                                                  System               1235
                                                  unicodedata          1729



52.2          Overview


fpwidestring  implements  unicode  string  support  for  the  Free  Pascal  RTL  using  native
Object  Pascal  routines.  It  is  meant  to  be  used  on  operating  systems  where  the  operating
system does not natively support Unicode transformations and operations.

In general, it is sufficient to include the unit in the uses clause of a program.  The initialization
code of the unit will set the unicode string manager of the system unit to the object pascal
implementation contained in this unit.

This unit needs unicode collation and character set tables in order to be able to do its work
correctly.  These  must  be  registered  using  the  routines  of  the  unicodedata  (704  )  unit:  the
FPC project distributes some unicode collation data in .bco files which can be loaded using
the LoadCollation (1738   ) routine.

In order for sorting and comparing of strings to work, a collation must be used.  The collation
in general depends on the internationalization of the application.  Since the system unit does
not  know  about  collations,  the  collation  must  be  set  in  the  fpWideString  unit  using  the
SetActiveCollation (705  ) function.  The collation can be set on a per-thread basis.

New threads get DefaultCollationName (705  ) as the active collation name.

The fpwidestring unit performs conversions between unicode and single-byte ansistring con-
versions  (excluding  UTF8).   Support  for  various  single-byte  encodings  are  based  on  the
charset (704  ) unit.  This unit can be used to load single byte code pages.  Various code page
units such as cp895, cp932, cp950 are provided by the "rtl-unicode" package.

The  fpwidestring  requires  at  least  the  Default  Unicode  Collation  Element  Table  to  be  reg-
istered  (called  DUCET).  The  DUCET  encoding  is  provided  by  the  unicodeducet  unit.  More
information can be found in the unicodedata (704  ) unit.



                                                             704

                _____________________________________________CHAPTER_52.___REFERENCE_FOR_UNIT_'FPWIDESTRING'_______________________*
 *___________________



                52.3          Constants,  types  and  variables



                52.3.1         Variables

                DefaultCollationName  :  TCollationName  =  ''


                DefaultCollationName is the collation name for new threads.  It is empty by default.



                52.4          Procedures  and  functions



                52.4.1         GetActiveCollation

    Synopsis:    Return the currently active collation for the current thread

Declaration:     function  GetActiveCollation  :  PUCA_DataBook

    Visibility:   default

Description:     GetActiveCollation returns the currently active collation,  for the current thread,  as set
                using the SetActiveCollation (705  ) function.

                New  threads  get  DefaultCollationName  (705  )  as  the  active  collation  name.  The  collation
                can be changed per thread using the SetActiveCollation (705  ) function.

       Errors:   None.

    See also:    SetActiveCollation (705  ), DefaultCollationName (705  )



                52.4.2         SetActiveCollation

    Synopsis:    Set the active collation for the current thread.

Declaration:     function  SetActiveCollation(const  AName:  TCollationName)  :  Boolean
                function  SetActiveCollation(const  ACollation:  PUCA_DataBook)  :  Boolean

    Visibility:   default

Description:     SetActiveCollation sets the collation used in the current thread of the application.  This
                can be done using the name of the collation (AName) as registered or in the unicodedata (704  )
                unit or using the actual collation data (ACollation).

       Errors:   If the collation AName was not found, or ACollation is nil, then False is returned.

    See also:    GetActiveCollation (705  ), DefaultCollationName (705  )



                                                                                 705




Chapter   53



Reference   for   unit   'getopts'



53.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.



53.2          Constants,  types  and  variables



53.2.1         Constants

EndOfOptions  =  #255


Returned by getopt (708  ),getlongopts (708  ) 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.



                                                             706

_______________________________________________________CHAPTER_53.___REFERENCE_FOR_UNIT_'GETOPTS'__________________________________*
 *___



53.2.2         Types

Orderings  =  (require_order,permute,return_in_order)



                            Table 53.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.



Command-line ordering options.


POption  =  ^TOption


Pointer to TOption (707  ) 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 (708  ).  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.



53.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.



                                                                 707

                _______________________________________________________CHAPTER_53.___REFERENCE_FOR_UNIT_'GETOPTS'__________________*
 *___________________



                53.3          Procedures  and  functions



                53.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 (708  ) 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 (708  ).

    See also:    Getopt (708  )



                53.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 (708  )



                                                                                 708

_______________________________________________________CHAPTER_53.___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 ;



                                                                 709

_______________________________________________________CHAPTER_53.___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___._______________________________________________________________________________________________________________________



                                                                 710




Chapter   54



Reference   for   unit   'go32'



54.1          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



54.2          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 (736  )

     o  %DS:%ESI = 48 bit pointer 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



                                                             711

            _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________



            The  callback  procedure  can  then  extract  its  parameters  from  the  real  mode  register  data
            structure  and/or  copy  parameters  from  the  real  mode  stack  to  the  protected  mode  stack.
            Recall that the segment register fields of the real mode register data structure contain seg-
            ment or paragraph addresses that are not valid in protected mode.  Far pointers passed in
            the  real  mode  register  data  structure  must  be  translated  to  virtual  addresses  before  they
            can be used with a protected mode program.  The callback procedure exits by executing an
            IRET with the address of the real mode register data structure in %ES:%EDI, passing infor-
            mation back to the real mode caller by modifying the contents of the real mode register data
            structure and/or manipulating the contents of the real mode stack.  The callback procedure
            is responsible for setting the proper address for resumption of real mode execution into the
            real  mode  register  data  structure;  typically,  this  is  accomplished  by  extracting  the  return
            address from the real mode stack and placing it into the %CS:%EIP fields of the real mode
            register data structure.  After the IRET, the DPMI host switches the CPU back into real
            mode, loads ALL registers with the contents of the real mode register data structure, and
            finally  returns  control  to  the  real  mode  program.   All  variables  and  code  touched  by  the
            callback procedure MUST be locked to prevent page faults.


See also:    get_rm_callback (736  ), free_rm_callback (731  ), lock_code (744  ), lock_data (744  )



            54.3          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 (753  ) and
            it's linear address via transfer_buffer (754  ).  Another way is to allocate a completely new dos
            memory area via the global_dos_alloc (741  ) function for your use and supply its real mode
            address.


See also:    tb_size  (753  ),  transfer_buffer  (754  ),  global_dos_alloc  (741  ),  global_dos_free  (742  ),  realintr
            (746  )


            Listing:  ./go32ex/softint.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. ah   : =  $30   ;
                           r. a l  : =  $01   ;
                           r e a l i n t(r$21   ,  r ) ;
                           W r i t e l n('DOS    v ' ,  r . a l, ' . ', r .ah  ,   '  d e t e c t e d') ;
            end___.________________________________________________________________________________________________________________*
 *_______


            Listing:  ./go32ex/rmpmint.pp
            _______________________________________________________________________________________________________________________*
 *_______
             u s e s
                           c r t,



                                                                             712

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



              go32    ;


 v a r
               r  :   t r e a l r e g;s
               a x r e g :  Word    ;


               o l d i n t 2 1 h:   t s e g i n f o;
               n e w i n t 2 1 h:   t s e g i n f o;
 p r o c e d u r ei n t 2 1 h _h a n d l e r; a s s e m b l e r;
asm
              cmpw     $0x3001     ,  %  a x
               j n e  .L C a l l O l d
              movw     $0x3112     ,  %  a x
               i r e t


 .L C a l l O l d:
               l j m p%  c s :o l d i n t 2 1 h
end   ;


 p r o c e d u r er e s u m e;
 b e g i n
               W r i t e l n;
              Write    ( '--    p r e s s any    k e y  t o   r e s u m e--   ') ;  r e a d k e y;
              g o t o x y( 1 ,  wherey     ) ;  c l r e o l;
end   ;


 b e g i n
               c l r s c r;
               W r i t e l n('E x e c u t i n g r e a l mode     i n t e r r u p t') ;
              r e s u m e;
               r. ah   : =  $30   ;  r . a l  : =  $01   ;    r e a l i n t(r$21   ,  r ) ;
               W r i t e l n('DOS    v ' ,  r . a l, ' . ', r .ah  ,   '  d e t e c t e d') ;
              r e s u m e;
               W r i t e l n('E x e c u t i n g p r o t e c t e dmode     i n t e r r u p tw i t h o u t o u r  own   ',
                             '  h a n d l e r') ;
               W r i t e l n;
              asm
                            movb     $0x30    ,  % ah
                            movb     $0x01    ,  % a l
                             i n t $ 0 x 2 1
                            movw    %  ax  ,  a x r e g
              end   ;
               W r i t e l n('DOS    v ' ,  r . a l, ' . ', r .ah  ,   '  d e t e c t e d') ;
              r e s u m e;
               W r i t e l n('As   you    c a n  s e e  t h e  DPMI     h o s t s  d e f a u l t p r o t e c t e dmode   ' ,
                             'h a n d l e r') ;
               W r i t e l n('s i m p l y  r e d i r e c t si t  t o  t h e  r e a l  mode     h a n d l e r') ;
              r e s u m e;
               W r i t e l n('Now    e x c h a n g i n gt h e  p r o t e c t e d mode     i n t e r r u p tw i t h  o u r  ' ,
                             'own    h a n d l e r') ;
              r e s u m e;


               n e w i n t 2 1.ho f f s e t : =  @ i n t 2 1 h _h a n d l e r;
               n e w i n t 2 1.hs 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$21   ,  o l d i n t 2 1 h) ;
               s e t _p m _i n t e r r u p(t$21   ,  n e w i n t 2 1 h) ;


               W r i t e l n('E x e c u t i n g r e a l mode     i n t e r r u p t a g a i n') ;



                                                                 713

            _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________



                          r e s u m e;
                           r. ah   : =  $30   ;  r . a l  : =  $01   ;  r e a l i n t r($21  ,  r ) ;
                           W r i t e l n('DOS    v ' ,  r . a l, ' . ', r .ah  ,   '  d e t e c t e d') ;
                           W r i t e l n;
                           W r i t e l n('See   ,  i t  d i d n' ' t  c h a n g e i n  any    way   . ') ;
                          r e s u m e;
                           W r i t e l n('Now    c a l l i n g p r o t e c t e dmode     i n t e r r u p t') ;
                          r e s u m e;
                          asm
                                        movb     $0x30    ,  % ah
                                        movb     $0x01    ,  % a l
                                         i n t $ 0 x 2 1
                                        movw    %  ax  ,  a x r e g
                          end   ;
                           W r i t e l n('DOS    v ' ,  l o (a x r e g) , '. ' , h i( a x r e g) ,  '  d e t e c t e d') ;
                           W r i t e l n;
                           W r i t e l n('Now    you    c a n  s e e  t h a t  t h e r e' 's  a   d i s t i n c t i o nb e t w e e *
 *n ' ,
                                         't h e  two    ways     o f  c a l l i n g i n t e r r u p t s. . .') ;
                           s e t _p m _i n t e r r u p(t$21   ,  o l d i n t 2 1 h) ;
            end___.________________________________________________________________________________________________________________*
 *_______



            54.4          Software  interrupts


            Ordinarily, a handler installed with set_pm_interrupt (750  ) only services software interrupts
            that  are  executed  in  protected  mode;  real  mode  software  interrupts  can  be  redirected  by
            set_rm_interrupt (752  ).


See also:    set_rm_interrupt  (752  ),  get_rm_interrupt  (739  ),  set_pm_interrupt  (750  ),  get_pm_interrupt
            (735  ), lock_data (744  ), lock_code (744  ), enable (729  ), disable (728  ), outportb (745  )



            54.5          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.

            Listing:  ./go32ex/keyclick.pp
            _______________________________________________________________________________________________________________________*
 *_______
            { $ASMMODE        ATT  }



                                                                             714

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



{ $MODE     FPC   }


 u s e s
               c r t,
              go32    ;


 c o n s t
               k b d i n t=   $9  ;


 v a r
               o l d i n t 9 _h a n d l e r:  t s e g i n f o;
               n e w i n t 9 _h a n d l e r:  t s e g i n f o;


               c l i c k p r o c:   p o i n t e r;
              backupDS        :  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 9 _h a n d l e r; a s s e m b l e r;
asm
               c l i
               p u s h l%  d s
               p u s h l%  e s
               p u s h l%  f s
               p u s h l%  g s
               p u s h a l
              movw    %  c s :backupDS      ,  % a x
              movw    %  ax ,  %  d s
              movw    %  ax ,  %  e s
              movw     d o s m e m s e l e c t o,r % a x
              movw    %  ax ,  %  f s
               c a l l * c l i c k p r o c
               p o p a l
               p o p l%  g s
               p o p l%  f s
               p o p l%  e s
               p o p l%  d s
               l j m p%  c s :o l d i n t 9 _h a n d l e r
end   ;
 p r o c e d u r eint9 _dummy       ;  b e g i n end   ;


 p r o c e d u r ec l i c k e r;
 b e g i n
              s o u n d( 5 0 0 ) ;  d e l a y( 1 0 ) ; n o s o u n d;
end   ;
 p r o c e d u r ec l i c k e r _d u m m y; b e g i n end   ;


 p r o c e d u r ei n s t a l l _ c l i c;k
 b e g i n
               c l i c k p r o c: =  @ c l i c k e r;
               l o c k _d a t a(c l i c k p r o c, s i z e o f(c l i c k p r o c) ) ;
               l o c k _d a t a(d o s m e m s e l e c t o,r s i z e o f(d o s m e m s e l e c t o)r) ;


               l o c k _c o d e(@ c l i c k e r,
                             l o n g i n t(@ c l i c k e r _d u m m)y -   l o n g i n t(@ c l i c k e r) ) ;
               l o c k _c o d e(@ i n t 9 _h a n d l e r,
                             l o n g i n t(@int9 _dummy      )-  l o n g i n t(@ i n t 9 _h a n d l e r) ) ;
               n e w i n t 9 _h a n d l e.ro f f s e t: =   @ i n t 9 _h a n d l e r;
               n e w i n t 9 _h a n d l e.rs e g m e n t: =   g e t _c s;
               g e t _p m _i n t e r r u p(tk b d i n t,  o l d i n t 9 _h a n d l e)r;



                                                                 715

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



               s e t _p m _i n t e r r u p(tk b d i n t,  n e w i n t 9 _h a n d l e)r;
end   ;


 p r o c e d u r er e m o v e _c l i c k;
 b e g i n
               s e t _p m _i n t e r r u p(tk b d i n t,  o l d i n t 9 _h a n d l e)r;
               u n l o c k _d a t a(d o s m e m s e l e c t o,rs i z e o f( d o s m e m s e l e c t o)r) ;
               u n l o c k _d a t a(c l i c k p r o,c  s i z e o f(c l i c k p r o c) ) ;


               u n l o c k _c o d e(@ c l i c k e r,
                             l o n g i n t(@ c l i c k e r _d u m m)y-l o n g i n t(@ c l i c k e r) ) ;
               u n l o c k _c o d e(@ i n t 9 _h a n d l e,r
                             l o n g i n t(@int9 _dummy      )-  l o n g i n t(@ i n t 9 _h a n d l e r) ) ;
end   ;


 v a r
              ch    :  c h a r;


 b e g i n
               i n s t a l l _ c l i c;k
               W r i t e l n('E n t e r  any    m e s s a g e. P r e s s  r e t u r n when     f i n i s h e d') ;
               w h i l e ( ch  < >  #13)      do   b e g i n
                            ch   : =   r e a d k e y;  w r i t e(ch  ) ;
              end   ;
               r e m o v e _c l i c k;
end___._______________________________________________________________________________________________________________________



54.6          Disabling  interrupts


The GO32 unit provides the two procedures disable() and enable() to disable and enable all
interrupts.



54.7          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.



54.8          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.



                                                                 716

            _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________



            54.9          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.



            54.10            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.



            54.11            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 (731  ), get_ds (732  ), get_ss (740  )



            54.12            I/O  port  access


            The I/O port access is done via the various inportb (743  ), outportb (745  ) 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 (745  ), inportb (743  )



            54.13            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  (719  ),  dosmemput  (720  ),  dosmemmove  (719  ),  dosmemfillchar  (719  ),  dosmem-
            fillword (719  ), seg_move (749  ), seg_fillchar (748  ), seg_fillword (749  )



                                                                             717

            _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________



            54.14            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  (731  ),  get_ds  (732  ),  get_ss  (740  ),  allocate_ldt_descriptors  (724  ),  free_ldt_descriptor
            (730  ), segment_to_descriptor (747  ), get_next_selector_increment_value (734  ), get_segment_base_address
            (740  ), set_segment_base_address (752  ), set_segment_limit (752  ), create_code_segment_alias_descriptor
            (727  )



            54.15            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.



            54.16            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.



            54.17            Constants,  types  and  variables



            54.17.1          Constants

            auxcarryflag  =  $010


            Check for auxiliary carry flag in trealregs (723  )


            carryflag  =  $001


            Check for carry flag in trealregs (723  )


            directionflag  =  $400


            Check for direction flag in trealregs (723  )



                                                                             718

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



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.


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 (741  ).


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.



                                                                 719

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



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.

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 (741  ).


interruptflag  =  $200


Check for interrupt flag in trealregs (723  )


overflowflag  =  $800


Check for overflow flag in trealregs (723  )


parityflag  =  $004


Check for parity flag in trealregs (723  )


rm_dpmi  =  4


get_run_mode (739  ) return value:  DPMI (e.g.  dos box or 386Max)


rm_raw  =  1


get_run_mode (739  ) return value:  raw (without HIMEM)


rm_unknown  =  0


get_run_mode (739  ) return value:  Unknown runmode


rm_vcpi  =  3


get_run_mode (739  ) return value:  VCPI (with HIMEM and EMM386)



                                                                 720

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



rm_xms  =  2


get_run_mode (739  ) return value:  XMS (with HIMEM, without EMM386)


signflag  =  $080


Check for sign flag in trealregs (723  )


trapflag  =  $100


Check for trap flag in trealregs (723  )


zeroflag  =  $040


Check for zero flag in trealregs (723  )



54.17.2          Types

registers  =  trealregs


Alias for trealregs (723  )


tdpmiversioninfo  =  record
    major  :  Byte;
    minor  :  Byte;
    flags  :  Word;
    cpu  :  Byte;
    master_pic  :  Byte;
    slave_pic  :  Byte;
end



tdpmiversioninfo describes the dpmi version information, as returned by get_dpmi_version
(732  ).  The CPU field can have the following values:


$02H      80286

$03H      80386

$04H      80486

$05H-      Newer than 80486


The flags field is a bitmask with the following bits:


0   0 for 16 bit DPMI, 1 for 32-bit

1   0 for virtual 86 mode for reflected interrupts, 1 for return to real mode.

2   0 for no virtual memory support, 1 for virtual memory support.



                                                                 721

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



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
case  Integer  of
1:  (
   EDI  :  LongInt;
   ESI  :  LongInt;
   EBP  :  LongInt;
   Res  :  LongInt;
   EBX  :  LongInt;
   EDX  :  LongInt;
   ECX  :  LongInt;
   EAX  :  LongInt;
   Flags  :  Word;
   ES  :  Word;
   DS  :  Word;
   FS  :  Word;
   GS  :  Word;
   IP  :  Word;
   CS  :  Word;
   SP  :  Word;
   SS  :  Word;
);
2:  (
   DI  :  Word;
   DI2  :  Word;
   SI  :  Word;
   SI2  :  Word;
   BP  :  Word;
   BP2  :  Word;
   R1  :  Word;
   R2  :  Word;
   BX  :  Word;
   BX2  :  Word;



                                                                 722

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



   DX  :  Word;
   DX2  :  Word;
   CX  :  Word;
   CX2  :  Word;
   AX  :  Word;
   AX2  :  Word;
);
3:  (
   stuff  :  Array[1..4]  of  LongInt;
   BL  :  Byte;
   BH  :  Byte;
   BL2  :  Byte;
   BH2  :  Byte;
   DL  :  Byte;
   DH  :  Byte;
   DL2  :  Byte;
   DH2  :  Byte;
   CL  :  Byte;
   CH  :  Byte;
   CL2  :  Byte;
   CH2  :  Byte;
   AL  :  Byte;
   AH  :  Byte;
   AL2  :  Byte;
   AH2  :  Byte;
);
4:  (
   RealEDI  :  LongInt;
   RealESI  :  LongInt;
   RealEBP  :  LongInt;
   RealRES  :  LongInt;
   RealEBX  :  LongInt;
   RealEDX  :  LongInt;
   RealECX  :  LongInt;
   RealEAX  :  LongInt;
   RealFlags  :  Word;
   RealES  :  Word;
   RealDS  :  Word;
   RealFS  :  Word;
   RealGS  :  Word;
   RealIP  :  Word;
   RealCS  :  Word;
   RealSP  :  Word;
   RealSS  :  Word;
);
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;



                                                                 723

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                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



                54.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.



                54.18            Procedures  and  functions



                54.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
                (734  ) function.

       Errors:   Check the int31error (724  ) variable.

    See also:    free_ldt_descriptor (730  ), get_next_selector_increment_value (734  ), segment_to_descriptor (747  ),
                create_code_segment_alias_descriptor (727  ), set_segment_limit (752  ), set_segment_base_address
                (752  )


                Listing:  ./go32ex/seldes.pp



                                                                                 724

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



______________________________________________________________________________________________________________________________
{ $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   ;


 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 ,



                                                                 725

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                              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 *
 *   '+
                               '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___.____________________________________________________________________________________________________________*
 *___________



                54.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.



                                                                                 726

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



       Errors:   Check the int31error (724  ) variable.

    See also:    free_memory_block (730  )



                54.18.3          copyfromdos

    Synopsis:    Copy data from DOS 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 (724  ) variable.

    See also:    tb_size (753  ), transfer_buffer (754  ), copytodos (727  )



                54.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 (724  ) variable.

    See also:    tb_size (753  ), transfer_buffer (754  ), copyfromdos (727  )



                54.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.



                                                                                 727

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                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 (724  ) variable.

    See also:    allocate_ldt_descriptors (724  ), set_segment_limit (752  ), set_segment_base_address (752  )



                54.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 (729  )



                54.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 (729  ), dpmi_dosmemget (729  ), dpmi_dosmemmove (729  ), dpmi_dosmemfillword
                (728  )



                54.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 (729  ), dpmi_dosmemget (729  ), dpmi_dosmemfillchar (728  ), dpmi_dosmemmove
                (729  )



                                                                                 728

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.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 (729  ), dpmi_dosmemmove (729  ), dpmi_dosmemfillchar (728  ), dpmi_dosmemfillword
                (728  )



                54.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 (729  ), dpmi_dosmemget (729  ), dpmi_dosmemfillchar (728  ), dpmi_dosmemfillword
                (728  )



                54.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 (729  ), dpmi_dosmemmove (729  ), dpmi_dosmemfillchar (728  ), dpmi_dosmemfillword
                (728  )



                54.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 (728  )



                                                                                 729

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.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 (724  ) 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 (724  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    allocate_ldt_descriptors (724  ), get_next_selector_increment_value (734  )



                54.18.14           free__linear__addr__mapping

    Synopsis:    ?  No description available

Declaration:     function  free_linear_addr_mapping(linear_addr:  dword)  :  Boolean

    Visibility:   default



                54.18.15           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  (726  )  .   This  function  doesn't  free  any  descriptors
                mapped to this block, it's the application's responsibility.

       Errors:   Check int31error (724  ) variable.

    See also:    allocate_memory_block (726  )



                                                                                 730

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.16           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
                (736  ) function.

                Parameters:


                intaddr     real mode address buffer returned by get_rm_callback (736  ) .


                Return values:  True if successful, False if not

                For an example, see get_rm_callback (736  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    set_rm_interrupt (752  ), get_rm_callback (736  )



                54.18.17           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 (750  ).

       Errors:   None.

    See also:    get_ds (732  ), get_ss (740  )



                54.18.18           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 (724  ) variable.

    See also:    set_descriptor_access_right (750  )



                                                                                 731

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.19           get__dpmi__version

    Synopsis:    Return DPMI information

Declaration:     function  get_dpmi_version(var  version:  tdpmiversioninfo)  :  Boolean

    Visibility:   default

Description:     get_dpmi_version  returns  version  information  (Int  $31  Function  $0400)  in  Version  and
                returns True if the information was retrieved successfully, false if the call failed.

       Errors:   The call returns false if the information could not be retrieved.

    See also:    tdpmiversioninfo (721  )



                54.18.20           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 (731  ), get_ss (740  )



                54.18.21           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 (750  ), get_pm_exception_handler (735  )



                54.18.22           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.

                size  Size of region to map in bytes.



                                                                                 732

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                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 (724  ) variable.

    See also:    allocate_ldt_descriptors (724  ), set_segment_limit (752  ), set_segment_base_address (752  )



                54.18.23           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 (734  ) function.

       Errors:   Check the int31error (724  ) variable.

    See also:    get_page_size (734  )


                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;
                                                           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 :   ' ,



                                                                                 733

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                                                                                      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___.____________________________________________________________________________________________________________*
 *___________



                54.18.24           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 (724  ).

                Return value:  Selector increment value.

 Remark:         Notes:  Because allocate_ldt_descriptors (724  ) 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 (724  ) variable.

    See also:    allocate_ldt_descriptors (724  ), free_ldt_descriptor (730  )



                54.18.25           get__page__attributes

    Synopsis:    ?  No description available

Declaration:     function  get_page_attributes(handle:  dword;offset:  dword;
                                                              pagecount:  dword;buf:  pointer)  :  Boolean

    Visibility:   default



                54.18.26           get__page__size

    Synopsis:    Return the page size

Declaration:     function  get_page_size  :  LongInt



                                                                                 734

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



    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 (733  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    get_meminfo (733  )



                54.18.27           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 (732  ), set_pm_exception_handler (750  )



                54.18.28           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 (750  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    set_pm_interrupt (750  ), set_rm_interrupt (752  ), get_rm_interrupt (739  )



                                                                                 735

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.29           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.

                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 (724  ) variable.

    See also:    free_rm_callback (731  )


                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



                                                                                 736

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



      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


      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) ) ;



                                                                 737

_______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



               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 ) ;
               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;



                                                                 738

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                end___.____________________________________________________________________________________________________________*
 *___________



                54.18.30           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:


                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 (724  ) variable.

    See also:    set_rm_interrupt (752  ), set_pm_interrupt (750  ), get_pm_interrupt (735  )



                54.18.31           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 (739  )


                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     ') ;



                                                                                 739

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                                            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___.____________________________________________________________________________________________________________*
 *___________



                54.18.32           get__segment__base__address

    Synopsis:    Return base address from descriptor table

Declaration:     function  get_segment_base_address(d:  Word)  :  LongInt

    Visibility:   default

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 (724  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    allocate_ldt_descriptors (724  ), set_segment_base_address (752  ), allocate_ldt_descriptors (724  ),
                set_segment_limit (752  ), get_segment_limit (740  )



                54.18.33           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 (724  ), set_segment_limit (752  ), set_segment_base_address (752  ), get_segment_base_ad*
 *dress
                (740  )



                54.18.34           get__ss

    Synopsis:    Return SS selector

Declaration:     function  get_ss  :  Word

    Visibility:   default



                                                                                 740

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



Description:     Returns the ss selector.

                Return values:  The content of the ss segment register.

       Errors:   None.

    See also:    get_ds (732  ), get_cs (731  )



                54.18.35           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 (742  ) call.

       Errors:   Check the int31error (724  ) variable.

    See also:    global_dos_free (742  )


                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



                                                                                 741

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                                             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   ;


                               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___.____________________________________________________________________________________________________________*
 *___________



                54.18.36           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
                (741  ).



                                                                                 742

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                For an example, see global_dos_alloc (741  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    global_dos_alloc (741  )



                54.18.37           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 (745  ), inportw (743  ), inportl (743  )



                54.18.38           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 (745  ), inportb (743  ), inportw (743  )



                54.18.39           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 (746  ), inportb (743  ), inportl (743  )



                                                                                 743

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.40           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 (736  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    lock_linear_region (744  ), lock_data (744  ), unlock_linear_region (755  ), unlock_data (754  ), un-
                lock_code (754  )



                54.18.41           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 (736  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    lock_linear_region (744  ), lock_code (744  ), unlock_linear_region (755  ), unlock_data (754  ), un-
                lock_code (754  )



                54.18.42           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.



                                                                                 744

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                size size in bytes to be locked.


                Return value:  True if successful, False otherwise.

       Errors:   Check the int31error (724  ) variable.

    See also:    lock_data (744  ), lock_code (744  ), unlock_linear_region (755  ), unlock_data (754  ), unlock_code
                (754  )



                54.18.43           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.



                54.18.44           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 (743  ), outportl (746  ), outportw (746  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 745

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.45           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 (745  ).

       Errors:   None.

    See also:    inportl (743  ), outportw (746  ), outportb (745  )



                54.18.46           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 (745  ).

       Errors:   None.

    See also:    inportw (743  ), outportl (746  ), outportb (745  )



                54.18.47           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.



                                                                                 746

                _______________________________________________________________CHAPTER_54.___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 (724  ) 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___.____________________________________________________________________________________________________________*
 *___________



                54.18.48           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.



                54.18.49           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.



                                                                                 747

                _______________________________________________________________CHAPTER_54.___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 (724  ) and change the
                base address as necessary.

                For an example, see seg_fillchar (748  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    allocate_ldt_descriptors (724  ), free_ldt_descriptor (730  ), set_segment_base_address (752  )



                54.18.50           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 (749  ), seg_fillword (749  ), dosmemfillchar (719  ), dosmemfillword (719  ), dosmemget
                (719  ), dosmemput (720  ), dosmemmove (719  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 748

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.51           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 (724  ).

       Errors:   None.

    See also:    seg_move (749  ), seg_fillchar (748  ), dosmemfillchar (719  ), dosmemfillword (719  ), dosmemget
                (719  ), dosmemput (720  ), dosmemmove (719  )



                54.18.52           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 (724  ).

       Errors:   None.

    See also:    seg_fillchar (748  ), seg_fillword (749  ), dosmemfillchar (719  ), dosmemfillword (719  ), dosmemget
                (719  ), dosmemput (720  ), dosmemmove (719  )



                                                                                 749

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.53           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



                54.18.54           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 (732  ), set_pm_exception_handler (750  )



                54.18.55           set__page__attributes

    Synopsis:    ?  No description available

Declaration:     function  set_page_attributes(handle:  dword;offset:  dword;
                                                              pagecount:  dword;buf:  pointer)  :  Boolean

    Visibility:   default



                54.18.56           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 (750  ), get_pm_exception_handler (735  )



                54.18.57           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:



                                                                                 750

               _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'______________*
 *__________________



               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 (724  ) variable.

   See also:    get_pm_interrupt (735  ), set_rm_interrupt (752  ), get_rm_interrupt (739  )


               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___._____________________________________________________________________________________________________________*
 *__________



                                                                                751

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.58           set__rm__interrupt

    Synopsis:    Set real mode interrupt handler

Declaration:     function  set_rm_interrupt(vector:  Byte;const  intaddr:  tseginfo)
                                                           :  Boolean

    Visibility:   default

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 (736  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    get_rm_interrupt (739  ), set_pm_interrupt (750  ), get_pm_interrupt (735  ), get_rm_callback (736  )



                54.18.59           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 (724  ) variable.

    See also:    allocate_ldt_descriptors (724  ), get_segment_base_address (740  ), allocate_ldt_descriptors (724  ),
                set_segment_limit (752  ), get_segment_base_address (740  ), get_segment_limit (740  )



                54.18.60           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.



                                                                                 752

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                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 (724  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    allocate_ldt_descriptors (724  ), set_segment_base_address (752  ), get_segment_limit (740  ), set_segment_limit
                (752  )



                54.18.61           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 (754  ), tb_segment (753  ), tb_size (753  )



                54.18.62           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 (754  ), tb_offset (753  ), tb_size (753  )



                54.18.63           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 (754  ), copyfromdos (727  ), copytodos (727  )



                                                                                 753

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.64           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 (753  )



                54.18.65           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 (736  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    unlock_linear_region (755  ), unlock_data (754  ), lock_linear_region (744  ), lock_data (744  ), lock_code
                (744  )



                54.18.66           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 (736  ).

       Errors:   Check the int31error (724  ) variable.

    See also:    unlock_linear_region  (755  ),  unlock_code  (754  ),  lock_linear_region  (744  ),  lock_data  (744  ),
                lock_code (744  )



                                                                                 754

                _______________________________________________________________CHAPTER_54.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                54.18.67           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.

                size  size bytes to be unlocked.


                Return values:  True if successful, False otherwise.

       Errors:   Check the int31error (724  ) variable.

    See also:    unlock_data  (754  ),  unlock_code  (754  ),  lock_linear_region  (744  ),  lock_data  (744  ),  lock_code
                (744  )



                                                                                 755




Chapter   55



Reference   for   unit   'gpm'



55.1          Used  units



                                      Table 55.1:  Used units by unit 'gpm'


                                                  _Name_____________Page______
                                                    BaseUnix           113
                                                    System           1235



55.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.



55.3          Constants,  types  and  variables



55.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



                                                             756

_______________________________________________________________CHAPTER_55.___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 (764  ).


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



                                                                 757

_______________________________________________________________CHAPTER_55.___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.



55.3.2         Types

Pgpmconnect  =  Pgpm_connect


Pointer to TGpmConnect (759  ) record.


Pgpmevent  =  Pgpm_event



                                                                 758

_______________________________________________________________CHAPTER_55.___REFERENCE_FOR_UNIT_'GPM'______________________________*
 *___



Pointer to TGpmEvent (759  ) record


Pgpmroi  =  Pgpm_roi


Pointer to TGpmRoi (759  ) record.


Pgpm_connect  =  ^TGpm_connect


Pointer to TGpm_Connect (760  ) record.


Pgpm_event  =  ^Tgpm_event


Pointer to TGpm_Event (760  ) record


Pgpm_roi  =  ^Tgpm_roi


Pointer to Tgpm_roi (760  ) record.


Tgpmconnect  =  Tgpm_connect


Alias for TGpm_Connect (760  ) record.


TGpmEtype  =  LongInt


Type for event type.


Tgpmevent  =  Tgpm_event


Alias for TGPM_EVent (760  ) 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 (760  )Record


Tgpm_connect  =  record
   eventMask  :  Word;
   defaultMask  :  Word;
   minMod  :  Word;
   maxMod  :  Word;
   pid  :  LongInt;
   vc  :  LongInt;
end



                                                                 759

_______________________________________________________________CHAPTER_55.___REFERENCE_FOR_UNIT_'GPM'______________________________*
 *___



GPM server connection information.


Tgpm_event  =  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  =  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.



55.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



                                                                 760

                _______________________________________________________________CHAPTER_55.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



                Internal gpm library variable.  Do not use.


                gpm_roi_handler  :  TGpmHandler


                Internal gpm library variable.  Do not use.



                55.4          Procedures  and  functions



                55.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 (766  ), Gpm_AnySingle (761  ), Gpm_StrictDouble (766  ), Gpm_StrictTriple
                (766  ), Gpm_AnyTriple (761  )



                55.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 (766  ), Gpm_AnyDouble (761  ), Gpm_StrictDouble (766  ), Gpm_StrictTriple
                (766  ), Gpm_AnyTriple (761  )



                55.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 (766  ), Gpm_AnyDouble (761  ), Gpm_StrictDouble (766  ), Gpm_StrictTriple
                (766  ), Gpm_AnySingle (761  )



                                                                                 761

                _______________________________________________________________CHAPTER_55.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



                55.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 (762  ).

       Errors:   None.

    See also:    Gpm_Open (764  )



                55.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 (762  )



                55.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 (762  )



                55.4.7         gpm__getevent

    Synopsis:    Get event from event queue.

Declaration:     function  gpm_getevent(var  event:  Tgpm_event)  :  LongInt

    Visibility:   default



                                                                                 762

                _______________________________________________________________CHAPTER_55.___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 (764  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 763

                _______________________________________________________________CHAPTER_55.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



                55.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 (762  )



                55.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 (765  ), Gpm_PopRoi (765  ), Gpm_PushRoi (765  )



                55.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 (759  ).

                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 (762  ).

       Errors:   On Error, the return value is -1.

    See also:    Gpm_Open (764  )



                                                                                 764

                _______________________________________________________________CHAPTER_55.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



                55.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 (765  ), Gpm_LowerRoi (764  ), Gpm_PushRoi (765  )



                55.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 (765  ), Gpm_PopRoi (765  ), Gpm_LowerRoi (764  )



                55.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 (765  ), Gpm_PopRoi (765  ), Gpm_LowerRoi (764  )



                55.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.



                                                                                 765

                _______________________________________________________________CHAPTER_55.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



       Errors:   None.

    See also:    Gpm_GetEvent (762  )



                55.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  (766  ),  Gpm_AnyTriple  (761  ),  Gpm_AnyDouble  (761  ),  Gpm_StrictTriple
                (766  ), Gpm_AnySingle (761  )



                55.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 (761  ), Gpm_StrictDouble (766  ), Gpm_AnyDouble (761  ), Gpm_StrictTriple
                (766  ), Gpm_AnySingle (761  )



                55.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 (761  ), Gpm_StrictDouble (766  ), Gpm_AnyDouble (761  ), Gpm_StrictSingle
                (766  ), Gpm_AnySingle (761  )



                                                                                 766




Chapter   56



Reference   for   unit   'Graph'



56.1          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 recom-
mended to use another set of graphical routines, suited to the platform the program should
work on.



56.2          Categorized  functions:   Text  and  font  handling


Functions to set texts on the screen.



                                                       Table 56.1:

                  __Name________________________________Description_________________________________________
                    GetTextSettings (807  )            Get current text settings
                    InstallUserFont (810  )            Install a new font
                    OutText (812  )                    Write text at current cursor position
                    OutTextXY (799  )                  Write text at coordinates X,Y
                    RegisterBGIFont (813  )            Register a new font
                    SetTextJustify (816  )             Set text justification
                    SetTextStyle (817  )               Set text style
                    SetUserCharSize (817  )            Set text size
                    TextHeight (818  )                 Calculate height of text
                    TextWidth (818  )                  Calculate width of text



56.3          Categorized  functions:   Filled  drawings


Functions for drawing filled regions.



                                                             767

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



                                                       Table 56.2:

                         __Name_____________________________Description______________________________
                           Bar3D (800  )                    Draw a filled 3D-style bar
                           Bar (800  )                      Draw a filled rectangle
                           FloodFill (803  )                Fill starting from coordinate
                           FillEllipse (802  )              Draw a filled ellipse
                           FillPoly (802  )                 Draw a filled polygone
                           GetFillPattern (804  )           Get current fill pattern
                           GetFillSettings (805  )          Get current fill settings
                           SetFillPattern (814  )           Set current fill pattern
                           SetFillStyle (815  )             Set current fill settings



56.4          Categorized  functions:   Drawing  primitives


Functions for simple drawing.



                                                       Table 56.3:

        __Name______________________________Description_______________________________________________________________
          Arc (800  )                       Draw an arc
          Circle (797  )                    Draw a complete circle
          DrawPoly (801  )                  Draw a polygone with N points
          Ellipse (802  )                   Draw an ellipse
          GetArcCoords (803  )              Get arc coordinates
          GetLineSettings (805  )           Get current line drawing settings
          Line (799  )                      Draw line between 2 points
          LineRel (810  )                   Draw line relative to current position
          LineTo (811  )                    Draw line from current position to absolute position
          MoveRel (811  )                   Move cursor relative to current position
          MoveTo (811  )                    Move cursor to absolute position
          PieSlice (812  )                  Draw a pie slice
          PutPixel (799  )                  Draw 1 pixel
          Rectangle (812  )                 Draw a non-filled rectangle
          Sector (813  )                    Draw a sector
          SetLineStyle (815  )              Set current line drawing style



56.5          Categorized  functions:   Color  management


All functions related to color management.



                                                                 768

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



                                                       Table 56.4:

                  __Name_________________________________Description________________________________________
                    GetBkColor (798  )                   Get current background color
                    GetColor (803  )                     Get current foreground color
                    GetDefaultPalette (804  )            Get default palette entries
                    GetMaxColor (805  )                  Get maximum valid color
                    GetPaletteSize (807  )               Get size of palette for current mode
                    GetPixel (798  )                     Get color of selected pixel
                    GetPalette (807  )                   Get palette entry
                    SetAllPalette (799  )                Set all colors in palette
                    SetBkColor (799  )                   Set background color
                    SetColor (814  )                     Set foreground color
                    SetPalette (816  )                   Set palette entry
                    SetRGBPalette (800  )                Set palette entry with RGB values



56.6          Categorized  functions:   Screen  management


General drawing screen management functions.



                                                       Table 56.5:

                   _Name_______________________________Description___________________________________________
                     ClearViewPort (798  )              Clear the current viewport
                     GetImage (798  )                   Copy image from screen to memory
                     GetMaxX (806  )                    Get maximum X coordinate
                     GetMaxY (806  )                    Get maximum Y coordinate
                     GetX (808  )                       Get current X position
                     GetY (808  )                       Get current Y position
                     ImageSize (798  )                  Get size of selected image
                     GetViewSettings (808  )            Get current viewport settings
                     PutImage (799  )                   Copy image from memory to screen
                     SetActivePage (799  )              Set active video page
                     SetAspectRatio (814  )             Set aspect ratio for drawing routines
                     SetViewPort (818  )                Set current viewport
                     SetVisualPage (800  )              Set visual page
                     SetWriteMode (818  )               Set write mode for screen operations



56.7          Categorized  functions:   Initialization


Initialization of the graphics screen.



                                                                 769

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



                                                       Table 56.6:

            __Name__________________________________Description___________________________________________________
              ClearDevice (801  )                   Empty the graphics screen
              CloseGraph (801  )                    Finish drawing session, return to text mode
              DetectGraph (801  )                   Detect graphical modes
              GetAspectRatio (803  )                Get aspect ratio of screen
              GetModeRange (807  )                  Get range of valid modes for current driver
              GraphDefaults (1 )                    Set defaults
              GetDriverName (804  )                 Return name of graphical driver
              GetGraphMode (805  )                  Return current or last used graphics mode
              GetMaxMode (806  )                    Get maximum mode for current driver
              GetModeName (806  )                   Get name of current mode
              GraphErrorMsg (1 )                    String representation of graphical error
              GraphResult (1 )                      Result of last drawing operation
              InitGraph (809  )                     Initialize graphics drivers
              InstallUserDriver (810  )             Install a new driver
              RegisterBGIDriver (813  )             Register a new driver
              RestoreCRTMode (813  )                Go back to text mode
              SetGraphMode (815  )                  Set graphical mode



56.8          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


/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.

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.



                                                                 770

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



56.9          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.



56.10            A  word  about  mode  selection


The  graph  unit  was  implemented  for  compatibility  with  the  old  Turbo  Pascal  graph  unit.
For this reason, the mode constants as they were defined in the Turbo Pascal graph unit are
retained.

However, since


    1.  Video cards have evolved very much

    2.  Free Pascal runs on multiple platforms


it was decided to implement new mode and graphic driver constants, which are more inde-
pendent of the specific platform the program runs on.

In this section we give a short explanation of the new mode system.  the following drivers
were defined:


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)  }



                                                                 771

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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.

Thus, the getmoderange function can be used to detect all available modes and drivers, as
in the third example below:

Listing:__./graphex/inigraph1.pp______________________________________________________________________________________________

Program        i n i g r a p h;1


{   Program       t o  d e m o n s t r a t es t a t i c g r a p h i c s mode     s e l e c t i o n}


 u s e s g r a p h;



 c o n s t
    T h e L i n e=    'We    a r e now     i n 6 4 0  x   4 8 0  x  2 5 6   c o l o r s!'+
                      '  ( p r e s s<  R e t u r n>  t o  c o n t i n u e)' ;


 v a r
    gd  ,  gm  ,  l o ,  h i ,  e r r o r,tw  , t h:   i n t e g e r;
    f o u n d:  b o o l e a n;


 b e g i n
    {  We    want    an    8  b i t  mode     }
    gd   : =   D 8 b i t;
    gm   : =  m640x480       ;
    i n i t g r a p h(gd ,gm  , ' ' ) ;
    {  Make     s u r e  you    a l w a y s c h e c k  g r a p h r e s u l!t }
    e r r o r : =   g r a p h R e s u l;t
    i f  ( e r r o r <>    grOk   )  Then
        b e g i n
        w r i t e l n('640  x 4 8 0 x 2 5 6 i s  n o t  s u p p o r t e d!' ) ;
        h a l t( 1 )



                                                                 772

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



       end   ;
    {  We    a r e now     i n  6 4 0x 4 8 0 x 2 5 6 }
    s e t C o l o r(c y a n) ;
    r e c t a n g l e( 0 , 0g,etmaxx     ,g e t m a x y) ;
    {   W r i t e a   n i c e m e s s a g e i n  t h e  c e n t e r  o f  t h e  s c r e e n }
    s e t T e x t S t y l(ed e f a u l t F o n,th o r i z D i r, 1 ) ;
    tw :=  T e x t W i d t h(T h e L i n e) ;
    t h:=  T e x t H e i g h(tT h e L i n e) ;
    outTextXY       ( (getMaxX       -  TW  )   d i v 2 ,
                     ( getMaxY       -  TH  )   d i v 2 , T h e L i n e) ;
    {  Wait     f o r  r e t u r n }
    r e a d l n;
    {  Back     t o   t e x t mode     }
    c l o s e g r a p h;
end___._______________________________________________________________________________________________________________________


Listing:__./graphex/inigraph2.pp______________________________________________________________________________________________

Program        i n i g r a p h;2


{   Program       t o  d e m o n s t r a t ed y n a m i c g r a p h i c s mode     s e l e c t i o n}


 u s e s g r a p h;


 c o n s t
    T h e L i n e=    'We    a r e now     i n 6 4 0  x   4 8 0  x  2 5 6   c o l o r s!'+
                      '  ( p r e s s<  R e t u r n>  t o  c o n t i n u e)' ;


 v a r
    th  ,tw  ,gd  ,  gm  ,  l o ,  h i ,   e r r o r:  i n t e g e r;
    f o u n d:  b o o l e a n;


 b e g i n
    {  We    want    an    8  b i t  mode     }
    gd   : =   D 8 b i t;
    {  Get     a l l  a v a i l a b l er e s o l u t i o n sf o r  t h i s  b i t d e p t h}
    g e t m o d e r a n g(egd , l o ,h i ) ;
    {   I f  t h e  h i g h e s t a v a i l a b l emode     number      i s  -1 ,
       no    r e s o l u t i o n sa r e  s u p p o r t e df o r  t h i s  b i t d e p t h  }
    i f  h i  =  -1    then
        b e g i n
        w r i t e l n('no   8   b i t  modes     s u p p o r t e d!' ) ;
        h a l t
       end   ;
    f o u n d : =   f a l s e;
    {   S e a r c h a l l  r e s o l u t i o n sf o r 6 4 0 x 4 8 0 }
    f o r  gm   : =   l o  t o  h i  do
        b e g i n
        i n i t g r a p(hgd  ,gm  , '' ) ;
       {   Make     s u r e you    a l w a y s  c h e c k g r a p h r e s u l!t  }
        e r r o r : =  g r a p h R e s u l t;
        i f  ( e r r o r=   grOk    )  and
             (g e t m a x x =  6 3 9 )  and    ( g e t m a x y =  4 7 9 )  then
           b e g i n
           f o u n d : =   t r u e;
           b r e a k;
           end  ;
       end   ;
    i f  not    f o u n d  then



                                                                 773

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



           C l o s e G r a p h( ) ;
        b e g i n
        w r i t e l n('640  x 4 8 0 x 2 5 6 i s  n o t  s u p p o r t e d!' ) ;
        h a l t( 1 )
       end   ;
    {  We    a r e now     i n  6 4 0x 4 8 0 x 2 5 6 }
    s e t C o l o r(c y a n) ;
    r e c t a n g l e( 0 , 0g,etmaxx     ,g e t m a x y) ;
    {   W r i t e a   n i c e m e s s a g e i n  t h e  c e n t e r  o f  t h e  s c r e e n }
    s e t T e x t S t y l(ed e f a u l t F o n,th o r i z D i r, 1 ) ;
   TW  :=  T e x t W i d t h(T h e L i n e) ;
    TH :=  T e x t H e i g h(tT h e L i n e) ;
    outTextXY       ( (getMaxX       -  TW  )   d i v 2 ,
                     ( getMaxY       -  TH  )   d i v 2 , T h e L i n e) ;
    {  Wait     f o r  r e t u r n }
    r e a d l n;
    {  Back     t o   t e x t mode     }
    c l o s e g r a p h;
end___._______________________________________________________________________________________________________________________


Listing:__./graphex/modrange.pp_______________________________________________________________________________________________

Program       GetModeRange _Example               ;


{   T h i s  p r o g r a m d e m o n s t r a t e show   t o   f i n d  a l l a v a i l a b l e g r a p h modes     }


 u s e s g r a p h;



 c o n s t
    {   C u r r e n t l,y  o n l y 4 ,  8 ,  1 5   and    1 6  b i t  modes      a r e  s u p p o r t e d
        b u t  t h i s may      c h a n g e i n  t h e  f u t u r e }
    gdnames      :  a r r a y[D 4 b i t. .D 1 6 b i t]  o f   s t r i n g[ 6 ]  =
        ( '4   b i t' , '6   b i t' ,' 8   b i t' ,' 1 2  b i t ', ' 1 5  b i t' , '1 6   b i t' ) ;


 p r o c e d u r eW r i t e R e s(c o n s t d e p t h  :  i n t e g e r) ;
 v a r
    tw  ,  t h  :   i n t e g e r;
    v ,  t e x t  :   S t r i n g;
 b e g i n
    t e x t : =   ' C u r r e n t r e s o l u t i o ni s  ' ;  s t r (g e t m a x x+1 ,  v ) ;
    t e x t : =   t e x t +   v  +   ' x ' ;  s t r( g e t m a x y+1 ,  v ) ;
    t e x t : =   t e x t +   v  +   ' x '  +   gdnames     [ d e p t h] ;
    s e t T e x t S t y l(ed e f a u l t F o n,th o r i z D i r, 1 ) ;
   TW  :=  T e x t W i d t h(t e x t) ;
    TH :=  T e x t H e i g h(tt e x t) ;
    outTextXY       ( (getMaxX       -  TW  )   d i v 2 ,
                     ( getMaxY       -  TH  )   d i v 2 , t e x t) ;
end   ;


 v a r
    t :  t e x t;
    l i n e  :  s t r i n g;
    gd  ,  c ,  low   ,  h i g h,   r e s:  i n t e g e r;
 b e g i n
    a s s i g n(t , 'modes    . t x t' ) ;
    r e w r i t e(t ) ;
    c l o s e( t) ;
    f o r  gd   : =  D 4 b i t  t o  D 1 6 b i t do



                                                                 774

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



        b e g i n
       {   Get    t h e  a v a i l a b l emode     numbers       f o r  t h i s  d r i v e r }
       getModeRange         ( gd  ,low   ,h i g h ) ;
       append     ( t ) ;
        w r i t e(t ,gdnames      [gd  ] ) ;
        W r i t e l n(t, ' :  l o w  modenr      =   ' ,low   , ' ,  h i g h modenr      =   ' ,h i g h ) ;
        c l o s e(t ) ;
       {   I f  h i g h  i s  -1 ,
             no   r e s o l u t i o n sa r e  s u p p o r t e df o r  t h i s  b i t d e p t h }
        i f  h i g h =  -1    then
           b e g i n
           append    ( t ) ;
           w r i t e l n(t , '   No    modes     s u p p o r t e d!' ) ;
           w r i t e l n(t ) ;
           c l o s e( t) ;
           end
        e l s e
           {   E n t e r a l l  s u p p o r t e d r e s o l u t i o n sf o r t h i s  b i t d e p t h
              and     w r i t e t h e i r  c h a r a c t e r i s t i ctso   t h e  f i l e }
           f o r  c  : =   low    t o  h i g h do
              b e g i n
              append     ( t ) ;
               w r i t e l n(t, '    t e s t i n g mode     n r  ' ,c ) ;
               c l o s e(t ) ;
               i n i t g r a p(hgd  ,c , ' ') ;
               r e s : =   g r a p h r e s u l;t
              append     ( t ) ;
              {   An   e r r o r  o c c u r r e dwhen     e n t e r i n g t h e  mode   ?  }
               i f  r e s <>    g r o k  then
                  w r i t e l n(t ,g r a p h e r r o r m s(gr e s) )
               e l s e
                  b e g i n
                  w r i t e(t , 'maxx    :  ' , getmaxx     , ' ,  maxy   :   ', g e t m a x y) ;
                  W r i t e l n(t , ' ,  m a x c o l o r: ' , g e t m a x c o l o)r;
                  c l o s e g r a p h;
                  end  ;
               w r i t e l n(t) ;
                  W r i t e R e s(gd ) ;
               c l o s e(t ) ;
              end   ;
       append     ( t ) ;
        w r i t e l n(t) ;
        c l o s e(t ) ;
       end   ;
    W r i t e l n(' A l l  s u p p o r t e dmodes      a r e  l i s t e d i n  modes    . t x t  f i l e s') ;
end___._______________________________________________________________________________________________________________________



56.11            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).



                                                                 775

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



56.12            Constants,  types  and  variables



56.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,  #@


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


brown  =  6


Color code:  brown


CenterLn  =  2


Line style:  centered line


CenterText  =  1


Horizontal text alignment:  Center text


CGA  =  1


Graphic driver for CGA cards


CGAC0  =  0


CGA Graphic driver mode C0



                                                                 776

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



CGAC1  =  1


CGA Graphic driver mode C1


CGAC2  =  2


CGA Graphic driver mode C2


CGAC3  =  3


CGA Graphic driver mode C3


CGAHi  =  4


CGA Graphic driver Hi-res mode


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



                                                                 777

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



D1bit  =  11


Mode:  Depth 1 bit


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.



                                                                 778

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



detectMode  =  30000


Mode:  Autodetect optimal mode


DottedLn  =  1


Line style:  Dotted line


DrawTextBackground  :  Boolean  =  False


Should the background of texts be drawn or should it be left untouched ?


EGA  =  3


Graphic driver for EGA cards


EGA64  =  4


Graphic driver for EGA 64 cards


EGA64Hi  =  1


EGA64 graphic driver high resolution mode


EGA64Lo  =  0


EGA64 graphic driver low resolution mode


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



                                                                 779

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



EGAHi  =  1


EGA graphic driver high resolution mode


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


EGALightred  =  60


Color code:  EGA light red


EGALo  =  0


EGA graphic driver low resolution mode


EGAMagenta  =  5


Color code:  EGA magenta


EGAMono  =  5


Graphic driver for EGA monochrome cards


EGAMonoHi  =  3


EGAMono graphic driver high resolution mode


EGARed  =  4


Color code:  EGA red


EGAWhite  =  63


Color code:  EGA white



                                                                 780

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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,  $f*
 *f,  $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,@


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


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



                                                                 781

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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


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



                                                                 782

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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


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



                                                                 783

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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


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



                                                                 784

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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


grInvalidFontNum  =  -14


Error:  Invalid font number


grInvalidMode  =  -10


Error:  Invalid mode specified.


grInvalidVersion  =  -18


Error:  Invalid version.


grIOerror  =  -12


Error:  Unspecified Input/Output error.



                                                                 785

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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


HercMonoHi  =  0


Mode:  Hercules card, monochrome, high resolution


highNewDriver  =  21


Mode:  highest number for new driver


highNewMode  =  m2048x1536


Mode:  Highest possible value of the new modes.


HorizDir  =  0


Text write direction:  Horizontal



                                                                 786

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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


LineFill  =  2


Fill style:  Fill using horizontal lines


lowNewDriver  =  11


Mode:  lowest number for new driver


lowNewMode  =  m320x200


Mode:  Lowest possible value of the new modes.


LowRes  =  6


Mode:  Low resolution.



                                                                 787

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



LtBkSlashFill  =  6


Fill style:  Light diagonal (backslash) lines


LtSlashFill  =  3


Fill style:  Light diagonal (slash) lines


m1024x768  =  detectMode  +  12


Mode:  Resolution 1024x768


m1280x1024  =  detectMode  +  13


Mode:  Resolution 1280x1024


m1600x1200  =  detectMode  +  14


Mode:  Resolution 1600x1200


m2048x1536  =  detectMode  +  15


Mode:  Resolution 2048x1536


m320x200  =  detectMode  +  1


Mode:  Resolution 320x200


m320x256  =  detectMode  +  2


Mode:  Resolution 320x256


m320x400  =  detectMode  +  3


Mode:  Resolution 320x400


m512x384  =  detectMode  +  4


Mode:  Resolution 512x384


m640x200  =  detectMode  +  5


Mode:  Resolution 640x200


m640x256  =  detectMode  +  6


Mode:  Resolution 640x256


m640x350  =  detectMode  +  7


Mode:  Resolution 640x350



                                                                 788

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



m640x400  =  detectMode  +  8


Mode:  Resolution 640x400


m640x480  =  detectMode  +  9


Mode:  Resolution 640x480


m800x600  =  detectMode  +  10


Mode:  Resolution 800x600


m832x624  =  detectMode  +  11


Mode:  Resolution 832x624


magenta  =  5


Color code:  Magenta


MaxColors  =  255


Max amount of colors in a palette


maxsmallint  =  (smallint)


Maximum value for smallint type


MCGA  =  2


Graphic driver for MCGA cards


MCGAC0  =  0


MCGA Graphic driver mode C0


MCGAC1  =  1


MCGA Graphic driver mode C1


MCGAC2  =  2


MCGA Graphic driver mode C2


MCGAC3  =  3


MCGA Graphic driver mode C3


MCGAHi  =  5


MCGA Graphic driver high resolution mode



                                                                 789

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



MCGAMed  =  4


MCGA Graphic driver medium resolution mode


NormalPut  =  0


Draw operation:  Use Normal (copy) operation


NormWidth  =  1


Line width:  Normal width


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:  *
 *400),  (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:  128@


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



                                                                 790

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



SolidFill  =  1


Fill style:  Solid fill.


SolidLn  =  0


Line style:  Solid line


ThickWidth  =  3


Line width:  double width


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.



                                                                 791

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



VGA  =  9


Mode:  VGA graphics adaptor.


VGAHi  =  2


Mode:  VGA high resolution (640x480)


VGALo  =  0


Mode:  VGA low resolution (640x200)


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



56.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)



                                                                 792

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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.


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


GetBkColorProc  =  function  :  Word


GetBkColorProc  is  the  procedure  prototype  for  the  GetBkColor  (798  )  method  handler  in
TModeInfo (797  ).  The function should return the color code of the background color.


getimageproc  =  procedure(X1:  SmallInt;Y1:  SmallInt;X2:  SmallInt;
                                         Y2:  SmallInt;var  Bitmap)


Standard GetImage (798  ) 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 (798  )


getscanlineproc  =  procedure(X1:  SmallInt;X2:  SmallInt;Y:  SmallInt;
                                              var  data)



                                                                 793

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



This routine is used for FloodFill (803  ) 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


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 (798  ) 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 (799  )


PaletteType  =  record
   Size  :  LongInt;
   Colors  :  Array[0..MaxColors]  of  RGBRec;
end



                                                                 794

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



Record describing palette.


patternlineproc  =  procedure(x1:  SmallInt;x2:  SmallInt;y:  SmallInt)


Standard procedure prototype to draw a patterned line


PCharsetTransTable  =  ^TCharsetTransTable


Pointer to TCharsetTransTable (796  ) array.


PModeInfo  =  ^TModeInfo


Pointer to TModeInfo (797  ) record


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 (799  ) 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 (799  ) procedure prototype.



                                                                 795

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



SetAllPaletteProc  =  procedure(const  Palette:  PaletteType)


This routine prototype is a hook for SetAllPalette (799  )


SetBkColorProc  =  procedure(ColorNum:  Word)


SetBkColorProc  is  the  procedure  prototype  for  the  SetBkColor  (799  )  method  handler  in
TModeInfo (797  ).  The procedure gets passed the color code for the color to set as background
color.


setrgbpaletteproc  =  procedure(ColorNum:  SmallInt;RedValue:  SmallInt;
                                                 GreenValue:  SmallInt;BlueValue:  SmallInt)


This routine prototype is a hook for SetRGBPalette (800  )


setvisualpageproc  =  procedure(page:  Word)


Standard SetVisualPage (800  ) procedure prototype.


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;



                                                                 796

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



   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;
   SetBKColor  :  SetBkColorProc;
   GetBKColor  :  GetBkColorProc;
   next  :  PModeInfo;
end



Record describing a graphical mode.


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



56.12.3          Variables

Circle  :  CircleProc


Circle draws a complete circle with center at (X,Y), radius radius.



                                                                 797

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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.


GetBkColor  :  GetBkColorProc


GetBkColor returns the current background color (the palette entry).


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



                                                                 798

___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



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


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


SetBkColor  :  SetBkColorProc


Sets the background color to Color.


SetRGBPalette  :  setrgbpaletteproc



                                                                 799

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                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



                56.13            Procedures  and  functions



                56.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 (797  ), Ellipse (802  ), GetArcCoords (803  ), PieSlice (812  ), Sector (813  )



                56.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 (800  ), Rectangle (812  )



                56.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.



                                                                                 800

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



       Errors:   None.

    See also:    Bar (800  ), Rectangle (812  )



                56.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 (798  ), SetBkColor (799  )



                56.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 (809  )



                56.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 (809  )



                56.13.7          DrawPoly

    Synopsis:    Draw a polygone

Declaration:     procedure  DrawPoly(NumPoints:  Word;var  polypoints)

    Visibility:   default



                                                                                 801

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



Description:     DrawPoly  draws  a  polygone  with  NumberOfPoints  corner  points,  using  the  current  color
                and line-style.  PolyPoints is an array of type PointType (795  ).

       Errors:   None.

    See also:    Bar (800  ), Bar3D (800  ), Rectangle (812  )



                56.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 (800  ), Circle (797  ), FillEllipse (802  )



                56.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 (800  ), Circle (797  ), GetArcCoords (803  ), PieSlice (812  ), Sector (813  )



                56.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 (800  ), Bar3D (800  ), Rectangle (812  )



                                                                                 802

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.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 (814  ), SetBkColor (799  )



                56.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 (800  ), Ellipse (802  )



                56.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 (809  ), SetAspectRatio (814  )



                56.13.14           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 (803  ), SetBkColor (799  )



                                                                                 803

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.15           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 (803  ), GetBkColor (798  )



                56.13.16           GetDirectVideo

    Synopsis:    Determine whether direct video mode is active.

Declaration:     function  GetDirectVideo  :  Boolean

    Visibility:   default

Description:     Determine whether direct video mode is active.



                56.13.17           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 (806  ), InitGraph (809  )



                56.13.18           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 (814  )



                                                                                 804

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.19           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 (814  )



                56.13.20           GetGraphMode

    Synopsis:    Get current graphical modus

Declaration:     function  GetGraphMode  :  SmallInt

    Visibility:   default

Description:     GetGraphMode returns the current graphical modus

       Errors:   None.

    See also:    InitGraph (809  )



                56.13.21           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 (815  )



                56.13.22           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 (814  ), GetPaletteSize (807  )



                                                                                 805

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.23           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 (809  )



                56.13.24           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 (806  )



                56.13.25           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 (806  )



                56.13.26           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 (804  ), InitGraph (809  )



                                                                                 806

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.27           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 (809  )



                56.13.28           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 (807  ), SetPalette (816  )



                56.13.29           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 (807  ), SetPalette (816  )



                56.13.30           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 (817  ), SetTextJustify (816  )



                                                                                 807

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.31           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 (818  )



                56.13.32           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 (808  )



                56.13.33           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 (808  )



                56.13.34           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 (818  ), SetFillStyle (815  ), SetColor (814  ), SetBkColor (799  ), SetLineStyle (815  )



                                                                                 808

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.35           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 (1 )



                56.13.36           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 (810  )

                      oSetLineStyle (815  )

                      oSetWriteMode (818  )

                      oSetFillStyle (815  )

                      oSetTextJustify (816  )

                      oSetGraphMode (815  )

                      oSetTextStyle (817  )


       Errors:   None.

    See also:    GraphErrorMsg (1 )



                56.13.37           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:



                                                                                 809

                ___________________________________________________________CHAPTER_56.___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 (771  ), DetectGraph (801  ), CloseGraph (801  ), GraphResult (1 )



                56.13.38           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 (809  ), InstallUserFont (810  )



                56.13.39           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 (809  ), InstallUserDriver (810  )



                56.13.40           LineRel

    Synopsis:    Draw a line starting from current position in given direction

Declaration:     procedure  LineRel(Dx:  SmallInt;Dy:  SmallInt)

    Visibility:   default



                                                                                 810

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



Description:     LineRel draws a line starting from the current pointer position to the point(DX,DY), rela-
                tive 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 (799  ), LineTo (811  )



                56.13.41           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), 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 (810  ), Line (799  )



                56.13.42           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 (811  )



                56.13.43           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 (811  )



                                                                                 811

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.44           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 (799  )



                56.13.45           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 (800  ), Circle (797  ), Sector (813  )



                56.13.46           queryadapterinfo

    Synopsis:    Function called to retrieve the current video adapter settings.

Declaration:     function  queryadapterinfo  :  PModeInfo

    Visibility:   default



                56.13.47           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 (800  ), Bar3D (800  )



                                                                                 812

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.48           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 (810  ), RegisterBGIFont (813  )



                56.13.49           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 (810  ), RegisterBGIDriver (813  )



                56.13.50           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 (809  )



                56.13.51           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 (800  ), Circle (797  ), PieSlice (812  )



                                                                                 813

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.52           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 (809  ), GetAspectRatio (803  )



                56.13.53           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 (803  ), SetBkColor (799  ), SetWriteMode (818  )



                56.13.54           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.



                56.13.55           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 (804  ), SetFillStyle (815  ), SetWriteMode (818  )



                                                                                 814

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.56           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 (814  ), SetWriteMode (818  )



                56.13.57           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 (809  )



                56.13.58           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:



                                                                                 815

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                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 (805  ), SetWriteMode (818  )



                56.13.59           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 (799  ), SetRGBPalette (800  )



                56.13.60           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.

                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 (812  ), OutTextXY (799  )



                                                                                 816

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.61           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 (807  )



                56.13.62           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 (817  )



                                                                                 817

                ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                56.13.63           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 (808  )



                56.13.64           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 (814  ), SetBkColor (799  ), SetLineStyle (815  ), SetFillStyle (815  )



                56.13.65           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 (818  )



                56.13.66           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.



                                                                                 818

            ___________________________________________________________CHAPTER_56.___REFERENCE_FOR_UNIT_'GRAPH'____________________*
 *_______________



   Errors:   None.

See also:    TextHeight (818  )



                                                                             819




Chapter   57



Reference   for   unit   'heaptrc'



57.1          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.



57.2          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 (822  ) variable is set to True

disabled       If this string occurs, then the UseHeapTrace (823  ) 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  (822  )  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 (825  ))


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.



                                                             820

_______________________________________________________CHAPTER_57.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________________________*
 *___



57.3          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:


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.

Listing:  ./heapex/heapex.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;


 b e g i n
    New  ( P1  ) ;
    //   c a u s e s  p r e v i o u sa l l o c a t i o nn o t  t o  be    de - a l l o c a t e d
    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 ) ;



                                                                 821

_______________________________________________________CHAPTER_57.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________________________*
 *___



       //   When      I  i s  e v e n,   d e a l l o c a t eb l o c k.  We   l o o s e  5  t i m e s 1 2 8
       //    b y t e s t h i s  way  .
        I f  ( I  mod    2 )  =  0   Then     FreeMem     ( P2 , 1 2 8 ) ;
       end   ;
    GetMem    ( P2  , 1 2 8 ) ;
    //   T h i s  w i l l  p r o v o k e an   e r r o r and    a   memory      dump
    Freemem       (P2  , 6 4 ) ;
end___._______________________________________________________________________________________________________________________



57.4          Constants,  types  and  variables



57.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.


HaltOnNotReleased  :  Boolean  =  False


HaltOnNotReleased can be set to True to make the DumpHeap (824  ) 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.


maxprintedblocklength  :  Integer  =  128


maxprintedblocklength determines the maximum number of bytes written by a memory
block dump, as produced when printleakedblock (823  ) or printfaultyblock (822  ) are true.  If
the size of the memory block is larger than this size, then only the first maxprintedblocklength
will be included in the dump.


printfaultyblock  :  Boolean  =  False


printleakedblock can be set to True to print a memory dump of daulty memory blocks
(in case a memory override occurs) The block is printed as a series of hexadecimal numbers,
representing the bytes in the memory block.  At most maxprintedblocklength (822  ) bytes of
the memory block will be printed.


printleakedblock  :  Boolean  =  False



                                                                 822

                _______________________________________________________CHAPTER_57.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________*
 *___________________



                printleakedblock can be set to True to print a memory dump of unreleased blocks when
                the heaptrc unit produces a summary of memory leaks.  The block is printed as a series of
                hexadecimal  numbers,  representing  the  bytes  in  the  memory  block.  At  most  maxprinted-
                blocklength (822  ) bytes of the memory block will be printed.


                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.



                57.4.2         Types

                tdisplayextrainfoProc  =  procedure(var  ptext:  text;p:  pointer)


                The TDisplayExtraInfoType is a procedural type used in the SetHeapExtraInfo (824  ) call
                to display a memory location which was previously filled with TFillExtraInfoProc (823  )


                tFillExtraInfoProc  =  procedure(p:  pointer)


                The TFillExtraInfoProc is a procedural type used in the SetHeapExtraInfo (824  ) call to
                fill a memory location with extra data for displaying.



                57.5          Procedures  and  functions



                57.5.1         CheckPointer

    Synopsis:    Check if a pointer is in the address range of the application

Declaration:     procedure  CheckPointer(p:  pointer)

    Visibility:   default

Description:     CheckPointer checks if the pointer is in the address range of the application, more specifi-
                cally, if it is in the heap.  if not, it prints an error and stops the program with aruntime error
                204.



                                                                                 823

                _______________________________________________________CHAPTER_57.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________*
 *___________________



                57.5.2         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.



                57.5.3         SetHeapExtraInfo

    Synopsis:    Store extra information in blocks.

Declaration:     procedure  SetHeapExtraInfo(size:  ptruint;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 (824  ) is executed.

    See also:    DumpHeap (824  ), SetHeapTraceOutput (825  )


                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;


                 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;



                                                                                 824

                _______________________________________________________CHAPTER_57.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                57.5.4         SetHeapTraceOutput

    Synopsis:    Specify filename for heap trace output.

Declaration:     procedure  SetHeapTraceOutput(const  name:  string);    Overload
                procedure  SetHeapTraceOutput(var  ATextOutput:  Text);    Overload

    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.

    See also:    SetHeapExtraInfo (824  )



                                                                                 825




Chapter   58



Reference   for   unit   'ipc'



58.1          Used  units



                                       Table 58.1:  Used units by unit 'ipc'


                                                  _Name_____________Page______
                                                    BaseUnix           113
                                                    System           1235
                                                    unixtype         1798



58.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.



58.3          Constants,  types  and  variables



58.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



                                                             826

_________________________________________________________________CHAPTER_58.___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


MSG_NOERROR  =  1  shl  12


Internal Message control code.  Do not use


SEM_A  =  2  shl  6


Constant to describe alter permissions on Semaphores


SEM_R  =  4  shl  6


Constant to describe read permissions on Semaphores


SEM_UNDO  =  1  shl  12


Constant for use in semop (841  )


SHM_LOCK  =  11


This constant is used in the shmctl (842  ) call.


SHM_R  =  IPC_R


This constant is used in the shmctl (842  ) call.


SHM_RDONLY  =  1  shl  12


This constant is used in the shmctl (842  ) call.


SHM_RND  =  2  shl  12


This constant is used in the shmctl (842  ) call.


SHM_UNLOCK  =  12


This constant is used in the shmctl (842  ) call.


SHM_W  =  IPC_W


This constant is used in the shmctl (842  ) call.



                                                                 827

_________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



58.3.2         Types

key_t  =  TKey


Alias for TKey (829  ) type


msglen_t  =  culong


Message length type


msgqnum_t  =  culong


Message queue number type


PIPC_Perm  =  ^TIPC_Perm


Pointer to TIPC_Perm (829  ) record.


PMSG  =  ^TMSG


Pointer to TMSG (829  ) record


PMSGbuf  =  ^TMSGbuf


Pointer to TMsgBuf (829  ) rcord


PMSGinfo  =  ^TMSGinfo


Pointer to TMSGinfo (830  ) record


PMSQid_ds  =  ^TMSQid_ds


Pointer to TMSQid_ds (830  )


PSEM  =  ^TSEM


Pointer to TSEM


PSEMbuf  =  ^TSEMbuf


Pointer to TSembuf (830  ) record.


PSEMid_ds  =  ^TSEMid_ds


Pointer to TSEMid_ds (831  ) record.


PSEMinfo  =  ^TSEMinfo


Pointer to TSEMinfo (831  ) record.


PSEMun  =  ^TSEMun



                                                                 828

_________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



Pointer to TSEMun (831  ) record


PShmid_DS  =  ^TShmid_ds


Pointer to TSHMid_ds (826  ) record.


PSHMinfo  =  ^TSHMinfo



TIPC_Perm  =  record
   key  :  TKey;
   uid  :  kernel_uid_t;
   gid  :  kernel_gid_t;
   cuid  :  kernel_uid_t;
   cgid  :  kernel_gid_t;
   mode  :  kernel_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 (831  ) key generating function.


TMSG  =  record
end



Record used in the handling of message queues.  Do not use directly.


TMSGbuf  =  record
   mtype  :  clong;
   mtext  :  Array[0..0]  of  Char;
end



The TMSGbuf record is a record containing the data of a record.  you should never use this
record directly, instead you should make your own record that follows the structure of the
TMSGbuf record, but that has a size that is big enough to accomodate your messages.  The
mtype field should always be present, and should always be filled.


TMSGinfo  =  record
   msgmax  :  cint;
   msgmni  :  cint;
   msgmnb  :  cint;
   msgtql  :  cint;
   msgssz  :  cint;
   msgseg  :  cint;
end



                                                                 829

_________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



Internal message system record.  Do not use directly.


TMSQid_ds  =  record
   msg_perm  :  TIPC_Perm;
   msg_first  :  PMSG;
   msg_last  :  PMSG;
   msg_cbytes  :  msglen_t;
   msg_qnum  :  msgqnum_t;
   msg_qbytes  :  msglen_t;
   msg_lspid  :  pid_t;
   msg_lrpid  :  pid_t;
   msg_stime  :  time_t;
   msg_pad1  :  clong;
   msg_rtime  :  time_t;
   msg_pad2  :  clong;
   msg_ctime  :  time_t;
   msg_pad3  :  clong;
   msg_pad4  :  Array[0..3]  of  clong;
end



This  record  should  never  be  used  directly,  it  is  an  internal  kernel  record.   It's  fields  may
change at any time.


TSEM  =  record
end



TSEM  is  a  semaphore  description  record.   It  should  be  considered  opaque,  it's  structure  is
highly OS and CPU dependent.


TSEMbuf  =  record
   sem_num  :  cushort;
   sem_op  :  cshort;
   sem_flg  :  cshort;
end



The TSEMbuf record is used in the semop (841  ) call, and is used to specify which operations
you want to do.


TSEMid_ds  =  record
   sem_perm  :  TIPC_Perm;
   sem_base  :  PSEM;
   sem_nsems  :  cushort;
   sem_otime  :  time_t;
   sem_pad1  :  cint;
   sem_ctime  :  time_t;
   sem_pad2  :  cint;
   sem_pad3  :  Array[0..3]  of  cint;
end



                                                                 830

                _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                Structure returned by the semctl (836  ) 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
                case  cint  of
                0:  (
                   val  :  cint;
                );
                1:  (
                   buf  :  PSEMid_ds;
                );
                2:  (
                   arr  :  PWord;
                );
                end



                Record used in semctl (836  ) call.


                TSHMinfo  =  record
                   shmmax  :  cint;
                   shmmin  :  cint;
                   shmmni  :  cint;
                   shmseg  :  cint;
                   shmall  :  cint;
                end



                Record used by the shared memory system, Do not use directly.



                58.4          Procedures  and  functions



                58.4.1         ftok

    Synopsis:    Create token from filename

Declaration:     function  ftok(Path:  PChar;ID:  cint)  :  TKey



                                                                                 831

                _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



    Visibility:  default

Description:     ftok returns a key that can be used in a semget (841  )shmget (845  ) or msgget (834  ) 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 (832  ), semctl (836  ) or shmctl (842  ).

       Errors:   ftok returns -1 if the file in Path doesn't exist.

    See also:    semget (841  ), shmget (845  ), msgget (834  )



                58.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 (834  ), msgsnd (835  ), msgrcv (835  )


                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
                    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   ;



                                                                                 832

_________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



 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
      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   ;



                                                                 833

                _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                58.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):



                                                                                 834

                _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                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 (832  ).

       Errors:   On error, -1 is returned, and IPCError is set.

    See also:    ftok (831  ), msgsnd (835  ), msgrcv (835  ), msgctl (832  )



                58.4.4         msgrcv

    Synopsis:    Retrieve a message from the queue

Declaration:     function  msgrcv(msqid:  cint;msgp:  PMSGbuf;msgsz:  size_t;msgtyp:  clong;
                                         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  immediately,  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 (832  ).

       Errors:   In case of error, False is returned, and IPCerror is set.

    See also:    msgget (834  ), msgsnd (835  ), msgctl (832  )



                58.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):



                                                                                 835

                _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                0No special meaning.  The message will be written to the queue.  If the queue is full, then
                      the process is blocked.

                IPC__NOWAIT            If the queue is full, then no message is written, and the call returns imme-
                      diately.


                The function returns True if the message was sent successfully, False otherwise.

                For an example, see msgctl (832  ).

       Errors:   In case of error, the call returns False, and IPCerror is set.

    See also:    msgget (834  ), msgrcv (835  ), msgctl (832  )



                58.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.

                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 (841  )
                       call.



                                                                                 836

            _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'________________*
 *_______________



            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 (841  ), semop (841  )


            Listing:  ./ipcex/semtool.pp
            _______________________________________________________________________________________________________________________*
 *_______
            Program        s e m t o o l;


            {   Program       t o  d e m o n s t r a t et 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) ;
             v a r
                e r r o r:  c i n t;
             b e g i n
                e r r o r:= f p g e t e r r n o;
                W r i t e l n ( ' E r r o r :   ', msg  , '  Code     :   ' ,e r r o r) ;
                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) ;


             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



                                                                             837

_________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



       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') ;
      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) ;



                                                                 838

_________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



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   ) ;
    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 ) ;



                                                                 839

_________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



    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   > ' ) ;
    W r i t e l n ( '                            p ( r i n t) ' ) ;
    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 ) ) ) ;
                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



                                                                 840

                _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                                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___.____________________________________________________________________________________________________________*
 *___________



                58.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 (831  ), semop (841  ), semctl (836  )



                58.4.8         semop

    Synopsis:    Perform semaphore operation.

Declaration:     function  semop(semid:  cint;sops:  PSEMbuf;nsops:  cuint)  :  cint

    Visibility:   default

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 (830  ) structure


                TSEMbuf  =  record
                       sem_num  :  word;
                       sem_op    :  integer;
                       sem_flg  :  integer;


                should be filled as follows:



                                                                                 841

                _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                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 (841  ), semctl (836  )



                58.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 (842  ).

       Errors:   If an error occurs, -1 is returned, and IPCerror is set.

    See also:    shmget (845  ), shmdt (845  ), shmctl (842  )



                58.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



                                                                                 842

                _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



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 (845  ), shmat (842  ), shmdt (845  )


                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 ) ;
                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') ;



                                                                                 843

_________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



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   ;
    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



                                                                 844

                _________________________________________________________________CHAPTER_58.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                        w r i t e l n( p a r a m s t r( 1 ) ) ;
                        u s a g e;
                       end   ;
                    end  ;
                end___.____________________________________________________________________________________________________________*
 *___________



                58.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 (842  ).

                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 (845  ), shmat (842  ), shmctl (842  )



                58.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.



                                                                                 845




Chapter   59



Reference   for   unit   'keyboard'



59.1          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 (860  ) function, which will return a driver-dependent key
event.  This key event can be translated to a interpretable event by the TranslateKeyEvent
(869  ) 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 (868  ) function.  The
current keyboard driver can be retrieved using the GetKeyboardDriver (860  ) function.  The
last section of this chapter demonstrates how to make a keyboard driver.



59.2          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.



                                                             846

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



     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:


           -  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.



59.3          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;



                                                                 847

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



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 (860  ).  Must wait for and return the next key event.
       It should NOT store keys.

PollKeyEvent           Called by PollKeyEvent (865  ).  It must return the next key event if there is
       one.  Should not store keys.

GetShiftState          Called by PollShiftStateEvent (866  ).  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.

Listing:  ./kbdex/logkeys.pp
______________________________________________________________________________________________________________________________
 u n i t l o g k e y s;


 i n t e r f a c e


 P r o c e d u r eS t a r t K e y L o g g i n;g
 P r o c e d u r eS t o p K e y L o g g i n;g
 F u n c t i o n  I s K e y L o g g i n g:  B o o l e a n;
 P r o c e d u r e  S e t K e y L o g F i l e N a(mFei l e N a m e :  S t r i n g) ;



 i m p l e m e n t a t i o n


 u s e s s y s u t i l s,k e y b o a r d;


 v a r
    N e w K e y B o a r d D r i v e,r
    O l d K e y B o a r d D r i v e r: T K e y b o a r d D r i v e;r
    A c t i v e,L o g g i n g :   B o o l e a n;
    L o g F i l e N a m e:   S t r i n g;
    KeyLog      :   T e x t;



                                                                 848

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



 F u n c t i o nTimeStamp         :  S t r i n g;


 b e g i n
    TimeStamp       := FormatDateTime           ( 'hh  :nn  : s s' ,Time    ( ) ) ;
end   ;


 P r o c e d u r eS t a r t K e y L o g g i n;g


 b e g i n
    L o g g i n g:= True   ;
    W r i t e l n(KeyLog     , 'S t a r t  l o g g i n gk e y s t r o k e s a t:   ' ,TimeStamp       ) ;
end   ;


 P r o c e d u r eS t o p K e y L o g g i n;g


 b e g i n
    W r i t e l n(KeyLog     , 'S t o p  l o g g i n g k e y s t r o k e sa t :  ' ,TimeStamp       ) ;
    L o g g i n g:= F a l s e;
end   ;


 F u n c t i o nI s K e y L o g g i n g:  B o o l e a n;


 b e g i n
    I s K e y L o g g i n:g=L o g g i n g;
end   ;


 F u n c t i o nL o g G e t K e y E v e n t:  TKeyEvent       ;


Var
    K   :  TKeyEvent       ;


 b e g i n
    K := O l d k e y b o a r d D r i v e.rG e t K e y E v e n(t) ;
    I f  L o g g i n g then
        b e g i n
       Write    ( KeyLog     ,TimeStamp       , ' :  Key    e v e n t:  ' ) ;
        W r i t e l n(KeyLog    , K e y E v e n t T o S t r i n(gT r a n s l a t e K e y E v e(nKt) ) ) ;
       end   ;
    L o g G e t K e y E v e n:t=K ;
end   ;


 P r o c e d u r eL o g I n i t K e y B o a r;d


 b e g i n
    O l d K e y B o a r d D r i v e.rI n i t D r i v e(r) ;
    A s s i g n(KeyLog     ,l o g F i l e N a m e) ;
    R e w r i t e(KeyLog     ) ;
    A c t i v e:= True   ;
    S t a r t K e y L o g g i n;g
end   ;


 P r o c e d u r eLogDoneKeyBoard           ;


 b e g i n
    S t o p K e y L o g g i n;g
    C l o s e(KeyLog     ) ;
    A c t i v e:= F a l s e;



                                                                 849

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



    O l d K e y B o a r d D r i v e.rD o n e D r i v e(r) ;
end   ;


 P r o c e d u r eS e t K e y L o g F i l e N a m(eF i l e N a m e:  S t r i n g) ;


 b e g i n
    I f  Not    A c t i v e then
       L o g F i l e N a m e:=F i l e N a m e;
end   ;


 I n i t i a l i z a t i o n
    G e t K e y B o a r d D r i v e(rO l d K e y B o a r d D r i v)e;r
    N e w K e y B o a r d D r i v e:r=O l d K e y B o a r d D r i v;e r
    N e w K e y B o a r d D r i v e.rG e t K e y E v e:n=t@LogGetKeyEvent           ;
    N e w K e y B o a r d D r i v e.rI n i t D r i v e:r=@ L o g I n i t K e y b o a;r d
    N e w K e y B o a r d D r i v e.rD o n e D r i v e:r=@LogDoneKeyboard           ;
    L o g F i l e N a m:e= 'k e y b o a r d.l o g ';
    L o g g i n g:= F a l s e;
    S e t K e y b o a r d D r i v e(rN e w K e y B o a r d D r i v)e;r
end___._______________________________________________________________________________________________________________________


Listing:  ./kbdex/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 l o g k e y s u n i t  }


 u s e s k e y b o a r d,l o g k e y s;


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   ,  " s "  t o g g l e s l o g g i n g.' ) ;
    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) ;
        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) ) ;
        i f  G e t K e y E v e n t C h a(rK)= ' s '  then
           i f  I s K e y L o g g i n gthen
              S t o p K e y L o g g i n g
           e l s e
               S t a r t K e y L o g g i n;g
    U n t i l ( G e t K e y E v e n t C h a(rK)=  'q ' ) ;
    DoneKeyBoard         ;
end___._______________________________________________________________________________________________________________________



59.4          Keyboard  scan  codes


Special physical keys are encoded with the DOS scan codes for these keys in the second byte
of the TKeyEvent (857  ) 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.



                                                                 850

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



                                             Table 59.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



                                                                 851

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



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.



                                       Table 59.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        5B                  65                 6F
                         F9               43        5C                  66                 70
                         F10              44        5D                  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



59.5          Constants,  types  and  variables



59.5.1         Constants

AltPrefix  :  Byte  =  0


Keycode for alternate prefix key for Alt key.  Unix Only


CtrlPrefix  :  Byte  =  0


Keycode for alternate prefix key for Ctrl key.  Unix only


errKbdBase  =  1010


Base of keyboard routine error reporting constants.


errKbdInitError  =  errKbdBase  +  0



                                                                 852

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



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


F10 function key pressed.


kbdF11  =  $FF0B


F12 function key pressed.


kbdF12  =  $FF0C


F12 function key pressed.


kbdF13  =  $FF0D



                                                                 853

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



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


F4 function key pressed.


kbdF5  =  $FF05


F5 function key pressed.


kbdF6  =  $FF06


F6 function key pressed.


kbdF7  =  $FF07



                                                                 854

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



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


Arrow right key pressed


kbdRWin  =  $FF16


Right windows key pressed.


kbdUp  =  $FF21


Arrow up key pressed


kbFnKey  =  $02



                                                                 855

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



function key pressed.


kbLeftShift  =  1


Left shift key modifier


kbPhys  =  $03


Physical key code event


kbReleased  =  $04


Key release event (not implemented in FPC)


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


Keycode for alternate prefix key for Shift key.  Unix Only


SKeyPad  :  Array[0..($FF2F-kbdHome)]  of  string  =  ('Home',  'Up',  'PgUp',  'Left',  'Middle',  'Right',  'End',  'Down',  'PgD*
 *n',  'Insert',  'Delete',  '',  '',  '',  '',  '')


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.


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.



                                                                 856

____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



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.



59.5.2         Types

PTreeElement  =  ^TTreeElement


Pointer to TTreeElement (858  ) record


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 (868  ) function.

The various fields correspond to the different functions of the keyboard unit interface.  For
more information about this record see kbddriver (847  )


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
(858  ) type.


TKeyRecord  =  packed  record
    Flags  :  Byte;
    ShiftState  :  Byte;
    KeyCode  :  Word;
end



                                                                 857

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                The structure of a TKeyRecord structure is explained in the following table:



                                                     Table 59.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 translated ASCII/unicode character.
                  ShiftState        Shift-state when this key was pressed (or shortly after)
                  Flags             Determine how to interpret KeyCode



                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).


                Tprocedure  =  procedure


                Procedure prototype


                TTreeElement  =  record
                   Next  :  PTreeElement;
                   Parent  :  PTreeElement;
                   Child  :  PTreeElement;
                   CanBeTerminal  :  Boolean;
                   char  :  Byte;
                   ScanValue  :  Byte;
                   CharValue  :  Byte;
                   SpecialHandler  :  Tprocedure;
                end



                TTreeELement is used to describe key scancode sequences, and is used to handle special key
                combinations in AddSpecialSequence (858  ) on unix platforms.  There should be no need to
                handle records of this type.



                59.6          Procedures  and  functions



                59.6.1         AddSequence

Declaration:     procedure  AddSequence(const  St:  string;AChar:  Byte;AScan:  Byte)

    Visibility:   default



                59.6.2         AddSpecialSequence

    Synopsis:    Add a handler for a special key sequence



                                                                                 858

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



Declaration:     function  AddSpecialSequence(const  St:  string;Proc:  Tprocedure)
                                                              :  PTreeElement

    Visibility:  default

Description:     AddSpecialSequence adds a sequence of key combinations to the keyboard handler.  When
                the key combination specified in st is encountered, then Proc will be executed.  The function
                returns the element in the special key sequence handling tree which handles st.

    See also:    AddSequence (858  )



                59.6.3         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
                (864  ).   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 (864  )



                59.6.4         FindSequence

Declaration:     function  FindSequence(const  St:  string;var  AChar:  Byte;var  Ascan:  Byte)
                                                     :  Boolean

    Visibility:   default



                59.6.5         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 (869  ), KeyEventToString (865  )



                                                                                 859

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                59.6.6         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 (847  ).

       Errors:   None.

    See also:    SetKeyboardDriver (868  )



                59.6.7         GetKeyEvent

    Synopsis:    Get the next raw key event, wait if needed.

Declaration:     function  GetKeyEvent  :  TKeyEvent

    Visibility:   default

Description:     GetKeyEvent returns the last keyevent if it is available, or waits for one if none is available.
                A non-blocking version is available in PollKeyEvent (865  ).

                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  (869  )  or  TranslateKeyEventUniCode  (869  ).   See
                the types section for a description of how the key is described.



                                                                                 860

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



       Errors:   If no key became available (e.g.  when the driver does not support it), 0 is returned.

    See also:    PutKeyEvent (867  ), PollKeyEvent (865  ), TranslateKeyEvent (869  ), TranslateKeyEventU-
                niCode (869  )


                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___.____________________________________________________________________________________________________________*
 *___________



                59.6.8         GetKeyEventChar

    Synopsis:    Get the character key part of a key event.

Declaration:     function  GetKeyEventChar(KeyEvent:  TKeyEvent)  :  Char

    Visibility:   default

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 (860  )

       Errors:   None.

    See also:    GetKeyEventUniCode (863  ), GetKeyEventShiftState (863  ), GetKeyEventFlags (862  ), GetKeyEvent-
                Code (862  ), GetKeyEvent (860  )



                                                                                 861

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                59.6.9         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 (863  ), GetKeyEventShiftState (863  ), GetKeyEventFlags (862  ), GetKeyEventChar
                (861  ), GetKeyEvent (860  )


                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___.____________________________________________________________________________________________________________*
 *___________



                59.6.10          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 (860  )

       Errors:   None.

    See also:    GetKeyEventUniCode (863  ), GetKeyEventShiftState (863  ), GetKeyEventCode (862  ), GetKeyEventChar
                (861  ), GetKeyEvent (860  )



                                                                                 862

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                59.6.11          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 (863  ), GetKeyEventFlags (862  ), GetKeyEventCode (862  ), GetKeyEventChar
                (861  ), GetKeyEvent (860  )


                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
                           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___.____________________________________________________________________________________________________________*
 *___________



                59.6.12          GetKeyEventUniCode

    Synopsis:    Return the unicode key event.

Declaration:     function  GetKeyEventUniCode(KeyEvent:  TKeyEvent)  :  Word

    Visibility:   default



                                                                                 863

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



Description:     GetKeyEventUniCode returns the unicode part of the given KeyEvent if it contains a trans-
                lated unicode character.

       Errors:   None.

    See also:    GetKeyEventShiftState (863  ), GetKeyEventFlags (862  ), GetKeyEventCode (862  ), GetKeyEventChar
                (861  ), GetKeyEvent (860  )



                59.6.13          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 (859  ) function should also be called before exiting the program or
                changing the keyboard driver with SetKeyboardDriver (868  ).

                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 (859  ), SetKeyboardDriver (868  )



                59.6.14          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.

       Errors:   None.

    See also:    GetKeyEvent (860  )


                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       ;



                                                                                 864

                ____________________________________________________CHAPTER_59.___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   . ') ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                59.6.15          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 (859  ), ShiftStateToString (869  )



                59.6.16          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 (865  ) and
                checks for a valid result.

       Errors:   None.

    See also:    PollKeyEvent (865  ), GetKeyEvent (860  )



                59.6.17          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 (860  ) function.



                                                                                 865

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



       Errors:   None.

    See also:    PutKeyEvent (867  ), GetKeyEvent (860  )


                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___.____________________________________________________________________________________________________________*
 *___________



                59.6.18          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.

    See also:    PollKeyEvent (865  ), GetKeyEvent (860  )


                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       ;



                                                                                 866

                ____________________________________________________CHAPTER_59.___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   . ') ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                59.6.19          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 (865  ), GetKeyEvent (860  )


                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       ;


                 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



                                                                                 867

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                              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___.____________________________________________________________________________________________________________*
 *___________



                59.6.20          RawReadKey

Declaration:     function  RawReadKey  :  Char

    Visibility:   default



                59.6.21          RawReadString

Declaration:     function  RawReadString  :  string

    Visibility:   default



                59.6.22          RestoreStartMode

Declaration:     procedure  RestoreStartMode

    Visibility:   default



                59.6.23          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
                does nothing.  Before setting the driver, the currently active driver should be disabled with
                a call to DoneKeyboard (859  ).

                The function returns True if the driver was set, False if not.

                For more information on setting the keyboard driver, see kbddriver (847  ).

       Errors:   None.

    See also:    GetKeyboardDriver (860  ), DoneKeyboard (859  )



                                                                                 868

                ____________________________________________________CHAPTER_59.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                59.6.24          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 (866  ).

       Errors:   None.

    See also:    FunctionKeyName (859  ), KeyEventToString (865  )



                59.6.25          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 (860  )

       Errors:   None.

    See also:    TranslateKeyEventUniCode (869  )



                59.6.26          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 (869  )



                                                                                 869




                Chapter   60



                Reference   for   unit   'lineinfo'



                60.1          Overview


                The  lineinfo  provides  a  routine  that  reads  the  debug  information  of  an  executable  (if  any
                exists) and returns source code information about this address.  It works with Stabs debug
                information.  Note  that  this  unit  is  not  thread-safe,  and  that  its  behaviour  is  undefined  if
                multiple threads try to write a backtrace at the same time.

                For DWARF debug information, the lnfodwrf (899  ) unit must be used.



                60.2          Procedures  and  functions



                60.2.1         CloseStabs

Declaration:     procedure  CloseStabs

    Visibility:   default



                60.2.2         GetLineInfo

    Synopsis:    Return source line information about an address.

Declaration:     function  GetLineInfo(addr:  ptruint;var  func:  string;var  source:  string;
                                                 var  line:  LongInt)  :  Boolean

    Visibility:   default

Description:     GetLineInfo returns source line information about the address addr.  It searches this in-
                formation in the stabs debugging information found in the binary:  If the file was compiled
                without debug information, nothing will be returned.  Upon succesful retrieval of the debug
                information, True is returned, and the func parameter is filled with the name of the function
                in which the address is located.  The source parameter contains the name of the file in which
                the function was implemented, and line contains the line number in the source file for addr.

       Errors:   If no debug information is found, False is returned.



                60.2.3         StabBackTraceStr

Declaration:     function  StabBackTraceStr(addr:  CodePointer)  :  string



                                                                             870

            _______________________________________________________CHAPTER_60.___REFERENCE_FOR_UNIT_'LINEINFO'_____________________*
 *_______________



Visibility:  default



                                                                             871




Chapter   61



Reference   for   unit   'Linux'



61.1          Used  units



                                     Table 61.1:  Used units by unit 'Linux'


                                                  _Name_____________Page______
                                                    BaseUnix           113
                                                    System           1235
                                                    unixtype         1798



61.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 (1761   ), baseunix (113  ) and unixutil (1813   ) units.

The X86-specific parts have been moved to the X86 (1849   ) unit.



61.3          Constants,  types  and  variables



61.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



                                                             872

_____________________________________________________________CHAPTER_61.___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



                                                                 873

_____________________________________________________________CHAPTER_61.___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



                                                                 874

_____________________________________________________________CHAPTER_61.___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


CLOCKS_MASK  =  CLOCK_REALTIME  or  CLOCK_MONOTONIC


Mask for supported clocks


CLOCKS_MONO  =  CLOCK_MONOTONIC


Monotonic clocks mask


CLOCK_MONOTONIC  =  1


Monotonic system time since some undetermined start point.  Can change if time is set.


CLOCK_MONOTONIC_COARSE  =  6


Less precise (but faster) version of  CLOCK_MONOTONIC


CLOCK_MONOTONIC_RAW  =  4


Like CLOCK_MONOTONIC, not subject to NTP adjustments


CLOCK_PROCESS_CPUTIME_ID  =  2


Processs-specific high-resolution timer from the CPU.


CLOCK_REALTIME  =  0


System wide real-time clock.  Can only be set by root.


CLOCK_REALTIME_COARSE  =  5


Less precise (but faster) version of  CLOCK_REALTIME


CLOCK_SGI_CYCLE  =  10


High resolution timer


CLOCK_THREAD_CPUTIME_ID  =  3


Thread-specific high-resolution timer from the CPU.



                                                                 875

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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 (890  ) option:  open files shared between processes


CLONE_FS  =  $00000200


Clone (890  ) 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 (890  ) option:  PID shared between processes


CLONE_PTRACE  =  $00002000


Clone options:  if parent is traced, trace child also


CLONE_SETTLS  =  $00080000


Clone option:  The newtls parameter is the TLS descriptor of the child


CLONE_SIGHAND  =  $00000800


Clone (890  ) option:  signal handlers shared between processes


CLONE_STOPPED  =  $02000000


Clone option:  Start child in stopped state.



                                                                 876

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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 (890  ) option:  VM shared between processes


CSIGNAL  =  $000000ff


Clone (890  ) option:  Signal mask to be sent at exit


EPOLLERR  =  $08


event_wait error condition on file descriptor


EPOLLET  =  $80000000


Set event_wait edge trigger behaviour on file descriptor


EPOLLHUP  =  $10


event_wait hang up event


EPOLLIN  =  $01


event_wait input file descriptor ready event


EPOLLONESHOT  =  $40000000


Set single-shot behaviour on epoll_wait.


EPOLLOUT  =  $04


event_wait output file descriptor ready event


EPOLLPRI  =  $02


event_wait high priority data available on input file descriptor



                                                                 877

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


FUTEX_OP_CMP_LE  =  3


Futex operation:  Undocumented


FUTEX_OP_CMP_LT  =  2


Futex operation:  Undocumented



                                                                 878

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


GIO_CMAP  =  $4B70


IOCTL: Get colour palette on VGA+


GIO_FONT  =  $4B60


IOCTL: Get font in expanded form.



                                                                 879

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


IN_ACCESS  =  $00000001


Data was read from file.


IN_ALL_EVENTS  =  IN_ACCESS  or  IN_MODIFY  or  IN_ATTRIB  or  IN_CLOSE  or  IN_OPEN  or  IN_MOVE  or  IN_CREATE  or  IN_DELETE  or*
 *  IN_DELETE_SELF  or  IN_MOVE_SELF


All possible events OR-ed together.


IN_ATTRIB  =  $00000004


File attributes changed.


IN_CLOEXEC  =  &02000000


IN_CLOEXEC can be set to indicate that the inotify file handle must be closed on exec.


IN_CLOSE  =  IN_CLOSE_WRITE  or  IN_CLOSE_NOWRITE


File was closed (read or write)


IN_CLOSE_NOWRITE  =  $00000010


File opened for read was closed


IN_CLOSE_WRITE  =  $00000008


File opened for write was closed


IN_CREATE  =  $00000100


A file was created in the directory.


IN_DELETE  =  $00000200


A file was deleted from the directory.



                                                                 880

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



IN_DELETE_SELF  =  $00000400


Directory or file under observation was deleted.


IN_DONT_FOLLOW  =  $02000000


Do not follow symlinks


IN_IGNORED  =  $00008000


Watch was ignored (removed).  Only reported.


IN_ISDIR  =  $40000000


Event subject is a directory (reported only)


IN_MASK_ADD  =  $20000000


Add events to existing watch (OR-ing the sets) if one exists.


IN_MODIFY  =  $00000002


Data was written to file.


IN_MOVE  =  IN_MOVED_FROM  or  IN_MOVED_TO


File was moved (in or out of directory)


IN_MOVED_FROM  =  $00000040


File was moved away from watched directory


IN_MOVED_TO  =  $00000080


File was moved into watched directory


IN_MOVE_SELF  =  $00000800


Directory or file under observation was moved.


IN_NONBLOCK  =  &00004000


IN_NONBLOCK can be set to indicate that the inotify file handle should not block read opera-
tions.


IN_ONESHOT  =  $80000000


Only report one event, then remove the watch.


IN_ONLYDIR  =  $01000000



                                                                 881

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



Only watch filename if it is a directory.


IN_OPEN  =  $00000020


File was opened


IN_Q_OVERFLOW  =  $00004000


Queue overflowed.  Only reported.


IN_UNMOUNT  =  $00002000


File system on which file resides was unmounted.  Only reported.


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


KDFONTOP  =  $4B72


IOCTL: font operations


KDGETKEYCODE  =  $4B4C


IOCTL: read kernel keycode table entry


KDGETLED  =  $4B31



                                                                 882

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


KDUNMAPDISP  =  $4B3D


IOCTL: unmap display from address space


KD_GRAPHICS  =  1


IOCTL: Tty modes:  graphics mode


KD_TEXT  =  0



                                                                 883

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


MAP_LOCKED  =  $2000


Memory pages are locked


MAP_NORESERVE  =  $4000


Do not check for reservations


MAX_CLOCKS  =  16



                                                                 884

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



Maximum number of clocks in the system


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


POLLMSG  =  $0400


Unused in linux


POLLRDHUP  =  $2000


Peer Shutdown/closed writing half of connection


POLLREMOVE  =  $1000


Undocumented linux extension of Poll


SPLICE_F_GIFT  =  8


Pages spliced in are a gift


SPLICE_F_MORE  =  4



                                                                 885

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



Expect more data


SPLICE_F_MOVE  =  1


Move pages instead of copying


SPLICE_F_NONBLOCK  =  2


Don't block on pipe splicing operations


SYNC_FILE_RANGE_WAIT_AFTER  =  4


Wait upon write-out of specified pages in the range after performing any write.


SYNC_FILE_RANGE_WAIT_BEFORE  =  1


Wait for write-out of previously-submitted specified pages before writing more data.


SYNC_FILE_RANGE_WRITE  =  2


Initiate write of all dirty pages in the specified range.



61.3.2         Types

clockid_t  =  cint


Clock id type


EPoll_Data  =  record
case  Integer  of
0:  (
    ptr  :  pointer;
);
1:  (
    fd  :  cint;
);
2:  (
    u32  :  cuint;
);
3:  (
    u64  :  cuint64;
);
end



Data structure used in EPOLL IOCTL call.


EPoll_Event  =  record
    Events  :  cuint32;
    Data  :  TEPoll_Data;
end



                                                                 886

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



Structure used in epoll_ctl (892  ) call.


inotify_event  =  record
   wd  :  cint;
   mask  :  cuint32;
   cookie  :  cuint32;
   len  :  cuint32;
   name  :  Char;
end



inotify_event is the structure used to report changes in a directory.  When reading a inotify
file descriptor, one or more inotify_event records can be read from the file descriptor.


PEPoll_Data  =  ^EPoll_Data


Pointer to EPoll_Data (886  ) record


PEpoll_Event  =  ^EPoll_Event


Pointer to EPoll_Event (887  ) type


Pinotify_event  =  ^inotify_event


Pointer to inotify_event (887  ) structure.


PSysInfo  =  ^TSysInfo


Pointer to TSysInfo (888  ) record.


Puser_cap_data  =  ^user_cap_data


Pointer to user_cap_data (888  ) record


Puser_cap_header  =  ^user_cap_header


Pointer to user_cap_header (888  ) record


TCloneFunc  =  function(args:  pointer)  :  LongInt


Clone function prototype.


TEPoll_Data  =  EPoll_Data


Alias for EPoll_Data (886  ) type


TEPoll_Event  =  EPoll_Event


Alias for EPoll_Event (887  ) type



                                                                 887

                _____________________________________________________________CHAPTER_61.___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 (897  ) call.


                user_cap_data  =  record
                   effective  :  cuint32;
                   permitted  :  cuint32;
                   inheritable  :  cuint32;
                end



                user_cap_data describes the set of capabilities for the indicated thread.


                user_cap_header  =  record
                   version  :  cuint32;
                   pid  :  cint;
                end



                user_cap_header describes the root user capabilities for the current thread, as set by capget
                (888  ) and capset (889  )



                61.4          Procedures  and  functions



                61.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 (889  )



                                                                                 888

                _____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                61.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 (888  )



                61.4.3         clock__getres

    Synopsis:    Get clock resolution

Declaration:     function  clock_getres(clk_id:  clockid_t;res:  ptimespec)  :  cint

    Visibility:   default

Description:     clock_getres returns the resolution of the clock specified in clk_id in the res structure.
                It can be Nil.  if the clock exists and the resolution can be retrieved, 0 is returned.

       Errors:   On Error, -1 is returned.  fpgeterrno can be used to get more detailed error information.

    See also:    clock_gettime (889  ), clock_settime (889  )



                61.4.4         clock__gettime

    Synopsis:    Get the time of a clock

Declaration:     function  clock_gettime(clk_id:  clockid_t;tp:  ptimespec)  :  cint

    Visibility:   default

Description:     clock_gettime returns the current time of the clock specified in clk_id in the tp structure.
                If the clock exists and the time can be retrieved, 0 is returned.

       Errors:   On Error, -1 is returned.  fpgeterrno can be used to get more detailed error information.

    See also:    clock_getres (889  ), clock_settime (889  )



                61.4.5         clock__settime

    Synopsis:    Set the time of a clock

Declaration:     function  clock_settime(clk_id:  clockid_t;tp:  ptimespec)  :  cint

    Visibility:   default

Description:     clock_settime sets the current time of the clock specified in clk_id.  The time is specified
                in  the  tp  structure.  If  the  clock  exists  and  the  time  can  be  retrieved,  0  is  returned.  The
                resolution is truncated to the resolution supported by the specified clock.  Note that not all
                clocks can be set.

       Errors:   On Error, -1 is returned.  fpgeterrno can be used to get more detailed error information.

    See also:    clock_getres (889  ), clock_gettime (889  )



                                                                                 889

                _____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                61.4.6         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 FpFork (166  )
                does.  In difference with Fork, however, the child process shares some parts of it's execution
                context with its parent, so it is suitable for the implementation of threads:  many instances
                of a program that share the same memory.

                When the child process is created, it starts executing the function Func, and passes it Args.
                The return value of  Func is either the explicit return value of the function, or the exit code
                of the child process.

                The  sp  pointer  points  to  the  memory  reserved  as  stack  space  for  the  child  process.  This
                address should be the top of the memory block to be used as stack.

                The Flags determine the behaviour of the Clone call.  The low byte of the Flags contains
                the number of the signal that will be sent to the parent when the child dies.  This may be
                bitwise OR'ed with the following constants:


                CLONE__VM           Parent and child share the same memory space, including memory (un)mapped
                       with subsequent mmap calls.

                CLONE__FS          Parent and child have the same view of the filesystem; the chroot, chdir and
                       umask calls affect both processes.

                CLONE__FILES            the file descriptor table of parent and child is shared.

                CLONE__SIGHAND                  the  parent  and  child  share  the  same  table  of  signal  handlers.   The
                       signal masks are different, though.

                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:    #rtl.baseunix.FpFork (166  )


                Listing:  ./linuxex/ex71.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       TestC    { l o n e} ;


                {  $ i f d e f L i n u x}
                //    c l o s e i s   v e r y L i n u x  s p e c i f i c.  1 . 9 .x  t h r e a d i n gi s  done     v i a  p t h r *
 *e a d s.


                 u s e s
                    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;



                                                                                 890

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



 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 , 0 , 0 , 0 , 6 0 0 ) ;
    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 , 0 , 0 , 0 , 3 0 0 ) ;
        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   ;


 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   ;



                                                                 891

                _____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                       end   ;
                    FreeMem     (   t h e S t a c k, S t a c k S z e ) ;
                { $ e l s e}
                 b e g i n
                { $ e n d i f}
                end___.____________________________________________________________________________________________________________*
 *___________



                61.4.7         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  (892  )  or
                epoll_wait (893  ) calls, and should be closed using the fpClose (160  ) call.

       Errors:   On error, -1 is returned, and errno (169  ) is set.

    See also:    epoll_ctl (892  ), epoll_wait (893  ), fpClose (160  )



                61.4.8         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 (892  ), epoll_wait (893  ), fpClose (160  )



                                                                                 892

                _____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                61.4.9         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
                immediately, 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 (892  ), epoll_ctl (892  ), fpClose (160  )



                61.4.10          fdatasync

    Synopsis:    Synchronize the data in memory with the data on storage device

Declaration:     function  fdatasync(fd:  cint)  :  cint

    Visibility:   default

Description:     fdatasync  does  the  same  as  fpfsync  but  does  not  flush  the  metadata,  unless  it  is  vital
                to  the  correct  reading/writing  of  the  file.  In  practice,  this  means  that  unless  the  file  size
                changed, the file metadata will not be synced.

    See also:    #rtl.unix.fsync (1761   )



                61.4.11          futex

    Synopsis:    Perform a futex operation

Declaration:     function  futex(uaddr:  pcint;op:  cint;val:  cint;timeout:  ptimespec;
                                       addr2:  pcint;val3:  cint)  :  cint
                function  futex(var  uaddr;op:  cint;val:  cint;timeout:  ptimespec;
                                       var  addr2;val3:  cint)  :  cint
                function  futex(var  uaddr;op:  cint;val:  cint;var  timeout:  TTimeSpec;
                                       var  addr2;val3:  cint)  :  cint
                function  futex(uaddr:  pcint;op:  cint;val:  cint;timeout:  ptimespec)
                                         :  cint
                function  futex(var  uaddr;op:  cint;val:  cint;timeout:  ptimespec)  :  cint
                function  futex(var  uaddr;op:  cint;val:  cint;var  timeout:  TTimeSpec)
                                         :  cint

    Visibility:   default

Description:     futex performs an operation on a memory futex as described in the kernel manual page for
                futex.  The mutex is located at uaddr, the operation op is one of the following constants:


                FUTEX__WAIT             Futex option:  Wait on futex till wake call arrives.

                FUTEX__WAKE              Futex option:  Wait on futex till wake call arrives.



                                                                                 893

                _____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                FUTEX__FD          Futex option:  Associate file descriptor with futex.

                FUTEX__REQUEUE                  Futex option:  requeue waiting processes on other futex.

                FUTEX__CMP__REQUEUE                      Futex option:  requeue waiting processes on other futex,  but
                      check it's value first


                The value to check for is indicated in val, and a timeout can be specified in timeout.  The op-
                tional arguments addr2 and val3 are used only with the FUTEX_REQUEUE and FUTEX_CMP_REQUEUE
                operations.

                In case of an error, -1 is return.  All other return values must be interpreted according to the
                operation performed.

                This  call  directly  interfaces  with  the  Linux  kernel,  more  information  can  be  found  in  the
                kernel manual pages.

       Errors:   On error, -1 is returned.  Use #rtl.baseunix.fpgeterrno (169  ) to get the error code.



                61.4.12          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);



                61.4.13          inotify__add__watch

    Synopsis:    Add a watch to a notify file descriptor

Declaration:     function  inotify_add_watch(fd:  cint;name:  PChar;mask:  cuint32)  :  cint

    Visibility:   default

Description:     inotify_add_watch can be used to add a watch to an initialized inotify file descriptor (fd).
                The file or directory to watch can be specified in the name parameter, and the events that
                must be reported can be specified in mask.  The following flags can be specified:


                IN_ACCESS      Data was read from file.

                IN_MODIFY      Data was written to file.

                IN_ATTRIB      File attributes changed.

                IN_CLOSE_WRITE        File opened for write was closed

                IN_CLOSE_NOWRITE          File opened for read was closed

                IN_CLOSE     File was closed (read or write)

                IN_OPEN    File was opened

                IN_MOVED_FROM        File was moved away from watched directory

                IN_MOVED_TO      File was moved into watched directory



                                                                                 894

                _____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                IN_MOVE    File was moved (in or out of directory)

                IN_CREATE     A file was created in the directory.

                IN_DELETE     A file was deleted from the directory.

                IN_DELETE_SELF        Directory or file under observation was deleted.

                IN_MOVE_SELF      Directory or file under observation was moved.

                IN_ALL_EVENTS       All possible events OR-ed together.


                These events can be OR-ed with some flags, controlling the behaviour of the watch:


                IN_ONLYDIR      Only watch filename if it is a directory.

                IN_ISDIR    Event occurred against directory.

                IN_DONT_FOLLOW        Do not follow symlinks

                IN_MASK_ADD      Add events to existing watch (OR-ing the sets) if one exists.

                IN_ONESHOT      Only report one event, then remove the watch.


                On return, the function returns a watch descriptor, which will be reported in the inotify_event
                (887  ) structure's wd.

       Errors:   On Error, -1 is returned.  fpgeterrno can be used to get more detailed error information.

    See also:    inotify_init (895  ), inotify_init1 (895  ), inotify_rm_watch (896  ), inotify_event (887  )



                61.4.14          inotify__init

    Synopsis:    Initialize a new inotify file descriptor

Declaration:     function  inotify_init  :  cint

    Visibility:   default

Description:     inotify_init  initializes  a  new  INotify  file  descriptor.  No  options  can  be  specified.  On
                return, the file descriptor is returned.

       Errors:   On Error, -1 is returned.  fpgeterrno can be used to get more detailed error information

    See also:    inotify_init1 (895  ), inotify_add_watch (894  ), inotify_rm_watch (896  )



                61.4.15          inotify__init1

    Synopsis:    Initialize a new inotify file descriptor with extra options.

Declaration:     function  inotify_init1(flags:  cint)  :  cint

    Visibility:   default

Description:     inotify_init1 initializes a new INotify file descriptor.  The following options can be OR-
                ed and passed in flags:


                IN__NONBLOCK               Do not block on read

                IN__CLOEXEC            Inotify close on exec flag.


       Errors:   On Error, -1 is returned.  fpgeterrno can be used to get more detailed error information.

    See also:    inotify_init (895  ), inotify_add_watch (894  ), inotify_rm_watch (896  )



                                                                                 895

                _____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                61.4.16          inotify__rm__watch

    Synopsis:    Remove watch from Inotify file descriptor.

Declaration:     function  inotify_rm_watch(fd:  cint;wd:  cint)  :  cint

    Visibility:   default

Description:     inotify_rm_watch removes watch descriptor wd from inotify descriptor fd.  On success, 0 is
                returned.

       Errors:   On Error, -1 is returned.  fpgeterrno can be used to get more detailed error information.

    See also:    inotify_init (895  ), inotify_init1 (895  ), inotify_add_watch (894  ), inotify_event (887  )



                61.4.17          sched__yield

    Synopsis:    Yield the processor to another thread.

Declaration:     procedure  sched_yield

    Visibility:   default

Description:     sched_yield yields the processor to another thread.  The current thread is put at the back
                of its queue.  If there is only 1 thread in the application, the thread continues to run.  The
                call always returns zero.



                61.4.18          setregid

Declaration:     function  setregid(rgid:  uid_t;egid:  uid_t)  :  cint

    Visibility:   default



                61.4.19          setreuid

Declaration:     function  setreuid(ruid:  uid_t;euid:  uid_t)  :  cint

    Visibility:   default



                61.4.20          sync__file__range

    Synopsis:    Force committing of data to disk

Declaration:     function  sync_file_range(fd:  cint;offset:  off64_t;nbytes:  off64_t;
                                                        flags:  cuint)  :  cint

    Visibility:   default

Description:     sync_file_range  forces  the  linux  kernel  to  write  any  data  pages  of  a  specified  file  (file
                descriptor fd) to disk.  The range of the file is specified by the offset offset and the number
                of bytes nbytes.  Options is an OR-ed combination of


                SYNC__FILE__RANGE__WAIT__BEFORE                               Wait for write-out of previously-submitted spec-
                       ified pages before writing more data.

                SYNC__FILE__RANGE__WRITE                         Initiate write of all dirty pages in the specified range.

                SYNC__FILE__RANGE__WAIT__AFTER                              Wait  upon  write-out  of  specified  pages  in  the
                       range after performing any write.



                                                                                 896

                _____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                If none is specified, the operation does nothing.

       Errors:   On return -1 is returned and fperrno is set to the actual error code.  See the linux man page
                for more on the error codes.

    See also:    fdatasync (893  )



                61.4.21          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 (205  )


                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;
                       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 ) ;



                                                                                 897

_____________________________________________________________CHAPTER_61.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



    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___._______________________________________________________________________________________________________________________



                                                                 898




                Chapter   62



                Reference   for   unit   'lnfodwrf '



                62.1          Overview


                The lnfodwrf  provides a routine that reads the debug information of an executable (if any
                exists) and returns source code information about this address.  It works with DWARF debug
                information.  Note  that  this  unit  is  not  thread-safe,  and  that  its  behaviour  is  undefined  if
                multiple threads try to write a backtrace at the same time.

                For stabs debug information, the lineinfo (870  ) unit must be used.



                62.2          Procedures  and  functions



                62.2.1         GetLineInfo

    Synopsis:    Return source line information about an address.

Declaration:     function  GetLineInfo(addr:  ptruint;var  func:  string;var  source:  string;
                                                 var  line:  LongInt)  :  Boolean

    Visibility:   default

Description:     GetLineInfo returns source line information about the address addr.  It searches this infor-
                mation in the DWARF debugging information found in the binary:  If the file was compiled
                without debug information, nothing will be returned.  Upon succesful retrieval of the debug
                information, True is returned, and the func parameter is filled with the name of the function
                in which the address is located.  The source parameter contains the name of the file in which
                the function was implemented, and line contains the line number in the source file for addr.

       Errors:   If no debug information is found, False is returned.



                                                                             899




Chapter   63



Reference   for   unit   'math'



63.1          Used  units



                                     Table 63.1:  Used units by unit 'math'


                                                   __Name__________Page_____
                                                     System        1235
                                                     sysutils      1489



63.2          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.



63.3          Cash  flow  functions


The cash flow functions in the math unit resolve the following equation:


FV  +  PV  *  q^n  +  PMT  (q^n  -  1)  /  (q  -  1)  =  0


In this formula, the following variables are present:


FV     Future value



                                                             900

            _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'___________________*
 *_______________



            PV    Present value

            PMT       Payment per period

            n  Number of payments (number of periods)

            q>   Interest Rate (return rate)


            The  financial  functions  FutureValue  (917  ),  NumberOfPeriods  (933  ),  Payment  (933  ),  Pre-
            sentValue (936  ) and InterestRate (920  ) solve this equation for one of the variables, when the
            other variables are known.


See also:    FutureValue  (917  ),  NumberOfPeriods  (933  ),  Payment  (933  ),  PresentValue  (936  ),  TPay-
            mentTime (906  )



            63.4          Geometrical  functions



                                                                   Table 63.2:

                                                __Name_______________Description_______________________
                                                  hypot (919  )       Hypotenuse of triangle
                                                  norm (932  )        Euclidian norm



            63.5          Statistical  functions



                                                                   Table 63.3:

                          __Name_____________________________________Description____________________________________________
                            mean (927  )                            Mean of values
                            meanandstddev (928  )                   Mean and standard deviation of values
                            momentskewkurtosis (931  )              Moments, skew and kurtosis
                            popnstddev (933  )                      Population standarddeviation
                            popnvariance (934  )                    Population variance
                            randg (938  )                           Gaussian distributed randum value
                            stddev (942  )                          Standard deviation
                            sum (943  )                             Sum of values
                            sumofsquares (944  )                    Sum of squared values
                            sumsandsquares (945  )                  Sum of values and squared values
                            totalvariance (947  )                   Total variance of values
                            variance (948  )                        variance of values



                                                                             901

_____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



63.6          Number  converting



                                                       Table 63.4:

                               _Name_______________Description___________________________________
                                 ceil (910  )       Round to infinity
                                 floor (916  )      Round to minus infinity
                                 frexp (916  )      Return mantissa and exponent



63.7          Exponential  and  logarithmic  functions



                                                       Table 63.5:

                             __Name____________________Description_______________________________
                               intpower (920  )        Raise float to integer power
                               ldexp (922  )           Calculate $2^p x$
                               lnxp1 (922  )           calculate log(x+1)
                               log10 (923  )           calculate 10-base log
                               log2 (923  )            calculate 2-base log
                               logn (924  )            calculate N-base log
                               power (935  )           raise float to arbitrary power



63.8          Hyperbolic  functions



                                                       Table 63.6:

                          __Name_________________Description________________________________________
                            arcosh (907  )       caculate reverse hyperbolic cosine
                            arsinh (909  )       caculate reverse hyperbolic sine
                            artanh (910  )       caculate reverse hyperbolic tangent
                            cosh (912  )         calculate hyperbolic cosine
                            sinh (942  )         calculate hyperbolic sine
                            tanh (947  )         calculate hyperbolic tangent



                                                                 902

_____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



63.9          Trigoniometric  functions



                                                       Table 63.7:

                                 __Name__________________Description__________________________
                                   arccos (906  )        calculate reverse cosine
                                   arcsin (908  )        calculate reverse sine
                                   arctan2 (909  )       calculate reverse tangent
                                   cotan (913  )         calculate cotangent
                                   sincos (941  )        calculate sine and cosine
                                   tan (946  )           calculate tangent



63.10            Angle  unit  conversion


Routines to convert angles between different angle units.



                                                       Table 63.8:

                              __Name______________________Description___________________________
                                cycletorad (913  )        convert cycles to radians
                                degtograd (914  )         convert degrees to grads
                                degtorad (915  )          convert degrees to radians
                                gradtodeg (918  )         convert grads to degrees
                                gradtorad (918  )         convert grads to radians
                                radtocycle (936  )        convert radians to cycles
                                radtodeg (937  )          convert radians to degrees
                                radtograd (937  )         convert radians to grads



63.11            Min/max  determination


Functions to determine the minimum or maximum of numbers:



                                                       Table 63.9:

                    __Name_________________________Description_____________________________________________
                      max (924  )                   Maximum of 2 values
                      maxIntValue (925  )           Maximum of an array of integer values
                      maxvalue (926  )              Maximum of an array of values
                      min (928  )                   Minimum of 2 values
                      minIntValue (929  )           Minimum of an array of integer values
                      minvalue (930  )              Minimum of an array of values



                                                                 903

_____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



63.12            Constants,  types  and  variables



63.12.1          Constants

EqualsValue  =  0


Values are the same


GreaterThanValue  =  (TValueRelationship)


First values is greater than second value


Infinity  =  1.0  /  0.0


Value is infinity


LessThanValue  =  (TValueRelationship)


First value is less than second value


MaxComp  =  9.223372036854775807e  +  18



MaxDouble  =  1.7e  +  308



MaxExtended  =  1.1e  +  4932


Maximum value of extended type


MaxFloat  =  0


Maximum value of float type


MaxSingle  =  3.4e  +  38



MinComp  =  -9.223372036854775807e  +  18



MinDouble  =  5.0e  -  324



MinExtended  =  3.4e  -  4932


Minimum value (closest to zero) of extended type


MinFloat  =  0


Minimum value (closest to zero) of float type


MinSingle  =  1.5e  -  45



                                                                 904

_____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



NaN  =  0.0  /  0.0


Value is Not a Number


NegativeValue  =  (TValueSign)


Value is negative


NegInfinity  =  (-1.0)  /  0.0


Value is negative (minus) infinity


PositiveValue  =  (TValueSign)


Value is positive


ZeroValue  =  0


Value is zero



63.12.2          Types

Float  =  MaxFloatType


All calculations are done with the Float type which is the largest float type available for the
current CPU. This allows to recompile the unit with a different float type to obtain a desired
precision.  The pointer type PFloat (905  ) is used in functions that accept an array of values
of arbitrary length.


Float  =  MaxFloatType


All calculations are done with the Float type which is the largest float type available for the
current CPU. This allows to recompile the unit with a different float type to obtain a desired
precision.  The pointer type PFloat (905  ) is used in functions that accept an array of values
of arbitrary length.


PFloat  =  ^Float


Pointer to Float (905  ) type.


PInteger  =  ObjPas.PInteger


Pointer to integer type


TFPUException  =  system.TFPUException


Type describing Floating Point processor exceptions.


TFPUExceptionMask  =  system.TFPUExceptionMask


Type to set the Floating Point Unit exception mask.



                                                                 905

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                TFPUPrecisionMode  =  system.TFPUPrecisionMode


                Type describing the default precision for the Floating Point processor.


                TFPURoundingMode  =  system.TFPURoundingMode


                Type describing the rounding mode for the Floating Point processor.


                tpaymenttime  =  (ptendofperiod,ptstartofperiod)



                                        Table 63.10:  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 (939  ) function.


                TValueRelationship  =  -1..1


                Type to describe relational order between values


                TValueSign  =  -1..1


                Type indicating sign of a valuea



                63.13            Procedures  and  functions



                63.13.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 (908  ), arcosh (907  ), arsinh (909  ), artanh (910  )


                Listing:  ./mathex/ex1.pp



                                                                                 906

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.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 (907  ), provided for Delphi compatibility.

    See also:    arcosh (907  )



                63.13.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 (912  ), sinh (942  ), arcsin (908  ), arsinh (909  ), artanh (910  ), tanh (947  )


                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   ;



                                                                                 907

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'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___.____________________________________________________________________________________________________________*
 *___________



                63.13.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 (906  ), arcosh (907  ), arsinh (909  ), artanh (910  )


                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 ) ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                63.13.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 (909  ), provided for Delphi compatibility.

    See also:    arsinh (909  )



                                                                                 908

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.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.

    See also:    arccos (906  ), arcosh (907  ), arsinh (909  ), artanh (910  )


                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( 2 , 1 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                63.13.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 (910  ), provided for Delphi compatibility.

    See also:    artanh (910  )



                63.13.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.



                                                                                 909

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    See also:    arcosh (907  ), arccos (906  ), arcsin (908  ), artanh (910  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.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 (907  ), arccos (906  ), arcsin (908  ), artanh (910  )


                Listing:  ./mathex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.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.



                                                                                 910

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    See also:    floor (916  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.11           ClearExceptions

    Synopsis:    Clear Floating Point Unit exceptions

Declaration:     procedure  ClearExceptions(RaisePending:  Boolean)

    Visibility:   default

Description:     Clear Floating Point Unit exceptions



                63.13.12           CompareValue

    Synopsis:    Compare 2 values

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:  Single;const  B:  Single;delta:  Single)
                                                     :  TValueRelationship
                function  CompareValue(const  A:  Double;const  B:  Double;delta:  Double)
                                                     :  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

                0 if  A=B

                1 if  A>B


    See also:    TValueRelationship (906  )



                                                                                 911

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.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 (940  )



                63.13.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 (907  ), sinh (942  ), arsinh (909  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.15           cot

    Synopsis:    Alias for Cotan

Declaration:     function  cot(x:  Float)  :  Float

    Visibility:   default

Description:     cot is an alias for the cotan (913  ) function.

    See also:    cotan (913  )



                                                                                 912

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.16           cotan

    Synopsis:    Return cotangent

Declaration:     function  cotan(x:  Float)  :  Float

    Visibility:   default

Description:     Cotan  returns  the  cotangent  of  it's  argument  x.  The  argument  x  must  be  in  radians.  x
                should be different from zero.

       Errors:   If  x is zero then a overflow error will occur.

    See also:    tanh (947  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.17           csc

    Synopsis:    Alias for cosecant

Declaration:     function  csc(x:  Float)  :  Float

    Visibility:   default

Description:     csc is an alias for the cosecant (912  ) function.

    See also:    cosecant (912  )



                63.13.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 (914  ), degtorad (915  ), radtodeg (937  ), radtograd (937  ), radtocycle (936  )


                Listing:  ./mathex/ex10.pp



                                                                                 913

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.19           DegNormalize

    Synopsis:    Normalize an angle measured in degrees

Declaration:     function  DegNormalize(deg:  single)  :  single
                function  DegNormalize(deg:  Double)  :  Double
                function  DegNormalize(deg:  extended)  :  extended

    Visibility:   default

Description:     DegNormalize returns the angle deg as a positive angle between 0 and 360 degrees.



                63.13.20           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 (913  ), degtorad (915  ), radtodeg (937  ), radtograd (937  ), radtocycle (936  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 914

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.21           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 (913  ), degtograd (914  ), radtodeg (937  ), radtograd (937  ), radtocycle (936  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.22           DivMod

    Synopsis:    Return DIV and MOD of arguments

Declaration:     procedure  DivMod(Dividend:  LongInt;Divisor:  Word;var  Result:  Word;
                                           var  Remainder:  Word)
                procedure  DivMod(Dividend:  LongInt;Divisor:  Word;var  Result:  SmallInt;
                                           var  Remainder:  SmallInt)
                procedure  DivMod(Dividend:  DWord;Divisor:  DWord;var  Result:  DWord;
                                           var  Remainder:  DWord)
                procedure  DivMod(Dividend:  LongInt;Divisor:  LongInt;var  Result:  LongInt;
                                           var  Remainder:  LongInt)

    Visibility:   default

Description:     DivMod returns Dividend DIV Divisor in Result, and Dividend MOD Divisor in Remainder



                63.13.23           EnsureRange

    Synopsis:    Change value to it falls in specified range.

Declaration:     function  EnsureRange(const  AValue:  Integer;const  AMin:  Integer;
                                                 const  AMax:  Integer)  :  Integer;    Overload
                function  EnsureRange(const  AValue:  Int64;const  AMin:  Int64;
                                                 const  AMax:  Int64)  :  Int64;    Overload
                function  EnsureRange(const  AValue:  Double;const  AMin:  Double;
                                                 const  AMax:  Double)  :  Double;    Overload



                                                                                 915

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    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 (920  )



                63.13.24           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 (910  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.25           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) ;



                                                                                 916

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                 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   ') ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                63.13.26           FutureValue

    Synopsis:    Calculate the future value of an investment.

Declaration:     function  FutureValue(ARate:  Float;NPeriods:  Integer;APayment:  Float;
                                                 APresentValue:  Float;APaymentTime:  tpaymenttime)
                                                   :  Float

    Visibility:   default

Description:     FutureValue  calculates  the  future  value  of  an  investment  (FV)  in  the  cash  flow  formula
                (see CashFlowFunctions (900  )) The function result is the future value of an investment of
                APresentValue (PV), where APayment (PMT) is invested for NPeriods (n) at the rate of ARate
                (q) per period.

                The APaymentTime parameter determines whether the investment (payment) is an ordinary
                annuity or an annuity due:  ptEndOfPeriod must be used if payments are at the end of each
                period.  If the payments are at the beginning of the periode, ptStartOfPeriod must be used.

    See also:    InterestRate  (920  ),  NumberOfPeriods  (933  ),  Payment  (933  ),  PresentValue  (936  ),  TPay-
                mentTime (906  ), CashFlowFunctions (900  )



                63.13.27           GetExceptionMask

    Synopsis:    Get the Floating Point Unit exception mask.

Declaration:     function  GetExceptionMask  :  TFPUExceptionMask

    Visibility:   default

Description:     Get the Floating Point Unit exception mask.



                63.13.28           GetPrecisionMode

    Synopsis:    Return the Floating Point Unit precision mode.

Declaration:     function  GetPrecisionMode  :  TFPUPrecisionMode



                                                                                 917

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    Visibility:  default

Description:     Return the Floating Point Unit precision mode.



                63.13.29           GetRoundMode

    Synopsis:    Return the Floating Point Unit rounding mode.

Declaration:     function  GetRoundMode  :  TFPURoundingMode

    Visibility:   default

Description:     Return the Floating Point Unit rounding mode.



                63.13.30           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 (913  ), degtograd (914  ), radtodeg (937  ), radtograd (937  ), radtocycle (936  ), grad-
                torad (918  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.31           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.



                                                                                 918

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    See also:    cycletorad (913  ), degtograd (914  ), radtodeg (937  ), radtograd (937  ), radtocycle (936  ), grad-
                todeg (918  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.32           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.


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.33           ifthen

    Synopsis:    Return one of two values, depending on a boolean condition

Declaration:     function  ifthen(val:  Boolean;const  iftrue:  Integer;
                                         const  iffalse:  Integer)  :  Integer;    Overload
                function  ifthen(val:  Boolean;const  iftrue:  Int64;const  iffalse:  Int64)
                                           :  Int64;    Overload
                function  ifthen(val:  Boolean;const  iftrue:  Double;const  iffalse:  Double)
                                           :  Double;    Overload

    Visibility:   default

Description:     ifthen returns iftrue if  val is True, and iffalse if  val is False.

                This function can be used in expressions.



                                                                                 919

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.34           InRange

    Synopsis:    Check whether value is in range.

Declaration:     function  InRange(const  AValue:  Integer;const  AMin:  Integer;
                                           const  AMax:  Integer)  :  Boolean;    Overload
                function  InRange(const  AValue:  Int64;const  AMin:  Int64;
                                           const  AMax:  Int64)  :  Boolean;    Overload
                function  InRange(const  AValue:  Double;const  AMin:  Double;
                                           const  AMax:  Double)  :  Boolean;    Overload

    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 (915  )



                63.13.35           InterestRate

    Synopsis:    Calculate the interest rate value of an investment

Declaration:     function  InterestRate(NPeriods:  Integer;APayment:  Float;
                                                   APresentValue:  Float;AFutureValue:  Float;
                                                   APaymentTime:  tpaymenttime)  :  Float

    Visibility:   default

Description:     InterestRate calculates the future value of an investment (q) in the cash flow formula (see
                CashFlowFunctions (900  )).  The function result is the interest rate value in case of a future
                value AFutureValue for an investment of a start value APresentValue (PV), where APayment
                (PMT) is invested for NPeriods (n).

                The APaymentTime parameter determines whether the investment (payment) is an ordinary
                annuity or an annuity due:  ptEndOfPeriod must be used if payments are at the end of each
                period.  If the payments are at the beginning of the periode, ptStartOfPeriod must be used.

    See also:    FutureValue  (917  ),  NumberOfPeriods  (933  ),  Payment  (933  ),  PresentValue  (936  ),  TPay-
                mentTime (906  ), CashFlowFunctions (900  )



                63.13.36           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.

       Errors:   If  base is zero and the exponent is negative, then an overflow error will occur.

    See also:    power (935  )


                Listing:  ./mathex/ex18.pp



                                                                                 920

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.37           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 (921  ), IsInfinite (921  )



                63.13.38           IsNan

    Synopsis:    Check whether value is Not a Number

Declaration:     function  IsNan(const  d:  Single)  :  Boolean;    Overload
                function  IsNan(const  d:  Double)  :  Boolean;    Overload
                function  IsNan(const  d:  Extended)  :  Boolean;    Overload

    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 (921  ), IsInfinite (921  )



                63.13.39           IsZero

    Synopsis:    Check whether value is zero



                                                                                 921

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



Declaration:     function  IsZero(const  A:  Single;Epsilon:  Single)  :  Boolean;    Overload
                function  IsZero(const  A:  Single)  :  Boolean;    Overload
                function  IsZero(const  A:  Double;Epsilon:  Double)  :  Boolean;    Overload
                function  IsZero(const  A:  Double)  :  Boolean;    Overload
                function  IsZero(const  A:  Extended;Epsilon:  Extended)  :  Boolean
                                        ;    Overload
                function  IsZero(const  A:  Extended)  :  Boolean;    Overload

    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 depends on the type of the argument:  it is 1E-4 for Single,
                1E-12 for Double and 1E-16 for extended.

    See also:    IsNan (921  ), IsInfinite (921  ), SameValue (939  )



                63.13.40           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 (922  ), log10 (923  ), log2 (923  ), logn (924  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.41           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.

    See also:    ldexp (922  ), log10 (923  ), log2 (923  ), logn (924  )



                                                                                 922

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.42           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 (922  ), lnxp1 (922  ), log2 (923  ), logn (924  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.43           log2

    Synopsis:    Return 2-based logarithm

Declaration:     function  log2(x:  Float)  :  Float

    Visibility:   default

Description:     Log2 returns the 2-base logarithm of  X.

       Errors:   If  x is less than or equal to 0 an 'invalid fpu operation' error will occur.



                                                                                 923

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    See also:    ldexp (922  ), lnxp1 (922  ), log10 (923  ), logn (924  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.44           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 (922  ), lnxp1 (922  ), log10 (923  ), log2 (923  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.45           Max

    Synopsis:    Return largest of 2 values



                                                                                 924

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



Declaration:     function  Max(a:  Integer;b:  Integer)  :  Integer;    Overload
                function  Max(a:  Int64;b:  Int64)  :  Int64;    Overload
                function  Max(a:  Single;b:  Single)  :  Single;    Overload
                function  Max(a:  Double;b:  Double)  :  Double;    Overload
                function  Max(a:  Extended;b:  Extended)  :  Extended;    Overload

    Visibility:  default

Description:     Max returns the maximum of  Int1 and Int2.

       Errors:   None.

    See also:    min (928  ), maxIntValue (925  ), maxvalue (926  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.46           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 (926  ) function instead.

       Errors:   None.

    See also:    maxvalue (926  ), minvalue (930  ), minIntValue (929  )


                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
                    TExArray       =   A r r a y[ 1 . . 1 0 0 ] o f  I n t e g e r;



                                                                                 925

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.47           maxvalue

    Synopsis:    Return largest value in array

Declaration:     function  maxvalue(const  data:  Array  of  Single)  :  Single
                function  maxvalue(const  data:  PSingle;const  N:  Integer)  :  Single
                function  maxvalue(const  data:  Array  of  Double)  :  Double
                function  maxvalue(const  data:  PDouble;const  N:  Integer)  :  Double
                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 (925  ), minvalue (930  ), minIntValue (929  )


                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 ] ;



                                                                                 926

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                    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('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___.____________________________________________________________________________________________________________*
 *___________



                63.13.48           mean

    Synopsis:    Return mean value of array

Declaration:     function  mean(const  data:  Array  of  Single)  :  Float
                function  mean(const  data:  PSingle;const  N:  LongInt)  :  Float
                function  mean(const  data:  Array  of  Double)  :  Float
                function  mean(const  data:  PDouble;const  N:  LongInt)  :  Float
                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 (928  ), momentskewkurtosis (931  ), sum (943  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 927

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.49           meanandstddev

    Synopsis:    Return mean and standard deviation of array

Declaration:     procedure  meanandstddev(const  data:  Array  of  Single;var  mean:  Float;
                                                      var  stddev:  Float)
                procedure  meanandstddev(const  data:  PSingle;const  N:  LongInt;
                                                      var  mean:  Float;var  stddev:  Float)
                procedure  meanandstddev(const  data:  Array  of  Double;var  mean:  Float;
                                                      var  stddev:  Float)
                procedure  meanandstddev(const  data:  PDouble;const  N:  LongInt;
                                                      var  mean:  Float;var  stddev:  Float)
                procedure  meanandstddev(const  data:  Array  of  Extended;var  mean:  Float;
                                                      var  stddev:  Float)
                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 (927  ), sum (943  ), sumofsquares (944  ), momentskewkurtosis (931  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.50           Min

    Synopsis:    Return smallest of two values.



                                                                                 928

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



Declaration:     function  Min(a:  Integer;b:  Integer)  :  Integer;    Overload
                function  Min(a:  Int64;b:  Int64)  :  Int64;    Overload
                function  Min(a:  Single;b:  Single)  :  Single;    Overload
                function  Min(a:  Double;b:  Double)  :  Double;    Overload
                function  Min(a:  Extended;b:  Extended)  :  Extended;    Overload

    Visibility:  default

Description:     min returns the smallest value of  Int1 and Int2;

       Errors:   None.

    See also:    max (924  )


                Listing:  ./mathex/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  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___.____________________________________________________________________________________________________________*
 *___________



                63.13.51           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 (930  ), maxIntValue (925  ), maxvalue (926  )


                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;



                                                                                 929

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.52           minvalue

    Synopsis:    Return smallest value in array

Declaration:     function  minvalue(const  data:  Array  of  Single)  :  Single
                function  minvalue(const  data:  PSingle;const  N:  Integer)  :  Single
                function  minvalue(const  data:  Array  of  Double)  :  Double
                function  minvalue(const  data:  PDouble;const  N:  Integer)  :  Double
                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 (925  ), maxvalue (926  ), minIntValue (929  )


                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 ] ;



                                                                                 930

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                63.13.53           momentskewkurtosis

    Synopsis:    Return 4 first moments of distribution

Declaration:     procedure  momentskewkurtosis(const  data:  Array  of  Single;out  m1:  Float;
                                                              out  m2:  Float;out  m3:  Float;out  m4:  Float;
                                                              out  skew:  Float;out  kurtosis:  Float)
                procedure  momentskewkurtosis(const  data:  PSingle;const  N:  Integer;
                                                              out  m1:  Float;out  m2:  Float;out  m3:  Float;
                                                              out  m4:  Float;out  skew:  Float;
                                                              out  kurtosis:  Float)
                procedure  momentskewkurtosis(const  data:  Array  of  Double;out  m1:  Float;
                                                              out  m2:  Float;out  m3:  Float;out  m4:  Float;
                                                              out  skew:  Float;out  kurtosis:  Float)
                procedure  momentskewkurtosis(const  data:  PDouble;const  N:  Integer;
                                                              out  m1:  Float;out  m2:  Float;out  m3:  Float;
                                                              out  m4:  Float;out  skew:  Float;
                                                              out  kurtosis:  Float)
                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 (927  ), meanandstddev (928  )


                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   ;



                                                                                 931

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'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___.____________________________________________________________________________________________________________*
 *___________



                63.13.54           norm

    Synopsis:    Return Euclidian norm

Declaration:     function  norm(const  data:  Array  of  Single)  :  Float
                function  norm(const  data:  PSingle;const  N:  Integer)  :  Float
                function  norm(const  data:  Array  of  Double)  :  Float
                function  norm(const  data:  PDouble;const  N:  Integer)  :  Float
                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.

    See also:    sumofsquares (944  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 932

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.55           NumberOfPeriods

    Synopsis:    Calculate the number of periods for an investment

Declaration:     function  NumberOfPeriods(ARate:  Float;APayment:  Float;
                                                        APresentValue:  Float;AFutureValue:  Float;
                                                        APaymentTime:  tpaymenttime)  :  Float

    Visibility:   default

Description:     NumberOfPeriods calculates the number of periods (n) needed to obtain future value of an
                investment in the cash flow formula (see CashFlowFunctions (900  )).  The function result is
                the number of periods a payment APayment (PMT) must be paid in order to obtain a future
                value AFutureValue for an investment of a start value APresentValue (PV), where APayment
                (PMT) is invested at a rate ARate (q).

                The APaymentTime parameter determines whether the investment (payment) is an ordinary
                annuity or an annuity due: ptEndOfPeriod NumberOfPeriodsmust be used if payments are at
                the end of each period.  If the payments are at the beginning of the periode, ptStartOfPeriod
                must be used.

    See also:    FutureValue (917  ), InterestRate (920  ), Payment (933  ), PresentValue (936  ), TPaymentTime
                (906  ), CashFlowFunctions (900  )



                63.13.56           Payment

    Synopsis:    Calculate the payment for an investment

Declaration:     function  Payment(ARate:  Float;NPeriods:  Integer;APresentValue:  Float;
                                           AFutureValue:  Float;APaymentTime:  tpaymenttime)  :  Float

    Visibility:   default

Description:     Payment  calculates  the  amount  that  must  be  payed  (PMT)  during  number  of  periods  (n)
                needed to obtain future value of an investment in the cash flow formula (see CashFlowFunc-
                tions (900  )).  The function result is the amount (PMT) that must be paid in order to obtain
                a future value AFutureValue for an investment of a start value APresentValue (PV), where
                the amount must be payed NPeriods (PMT) and the interest rate isARate (q).

                The APaymentTime parameter determines whether the investment (payment) is an ordinary
                annuity or an annuity due: ptEndOfPeriod NumberOfPeriodsmust be used if payments are at
                the end of each period.  If the payments are at the beginning of the periode, ptStartOfPeriod
                must be used.

    See also:    FutureValue (917  ), InterestRate (920  ), NumberOfPeriods (933  ), PresentValue (936  ), TPay-
                mentTime (906  ), CashFlowFunctions (900  )



                63.13.57           popnstddev

    Synopsis:    Return population variance

Declaration:     function  popnstddev(const  data:  Array  of  Single)  :  Float
                function  popnstddev(const  data:  PSingle;const  N:  Integer)  :  Float
                function  popnstddev(const  data:  Array  of  Double)  :  Float
                function  popnstddev(const  data:  PDouble;const  N:  Integer)  :  Float
                function  popnstddev(const  data:  Array  of  Extended)  :  Float
                function  popnstddev(const  data:  PExtended;const  N:  Integer)  :  Float



                                                                                 933

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    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 (934  ), mean (927  ), meanandstddev (928  ), stddev (942  ), momentskewkurtosis
                (931  )


                Listing:  ./mathex/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  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___.____________________________________________________________________________________________________________*
 *___________



                63.13.58           popnvariance

    Synopsis:    Return population variance

Declaration:     function  popnvariance(const  data:  PSingle;const  N:  Integer)  :  Float
                function  popnvariance(const  data:  Array  of  Single)  :  Float
                function  popnvariance(const  data:  PDouble;const  N:  Integer)  :  Float
                function  popnvariance(const  data:  Array  of  Double)  :  Float
                function  popnvariance(const  data:  PExtended;const  N:  Integer)  :  Float
                function  popnvariance(const  data:  Array  of  Extended)  :  Float

    Visibility:   default

Description:     Popnvariance  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  (933  ),  mean  (927  ),  meanandstddev  (928  ),  stddev  (942  ),  momentskewkurtosis
                (931  )



                                                                                 934

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                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 ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                63.13.59           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 (920  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 935

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.60           power(Float,Float):Float

Declaration:     operator  **(bas:  Float;expo:  Float)  :  Float

    Visibility:   default



                63.13.61           power(Int64,Int64):Int64

Declaration:     operator  **(bas:  Int64;expo:  Int64)  :  Int64

    Visibility:   default



                63.13.62           PresentValue

    Synopsis:    Calculate the present value given the future value of an investment.

Declaration:     function  PresentValue(ARate:  Float;NPeriods:  Integer;APayment:  Float;
                                                   AFutureValue:  Float;APaymentTime:  tpaymenttime)
                                                     :  Float

    Visibility:   default

Description:     PresentValue calculates the present (start) value of an investment (PV) in the cash flow for-
                mula (see CashFlowFunctions (900  )) The function result is the start value of an investment,
                when the future value is AFutureValue (FV) and APayment (PMT) is invested for NPeriods
                (n) at the rate of  ARate (q) per period.

                The APaymentTime parameter determines whether the investment (payment) is an ordinary
                annuity or an annuity due:  ptEndOfPeriod must be used if payments are at the end of each
                period.  If the payments are at the beginning of the periode, ptStartOfPeriod must be used.

    See also:    FutureValue (917  ), InterestRate (920  ), NumberOfPeriods (933  ), Payment (933  ), TPayment-
                Time (906  ), CashFlowFunctions (900  )



                63.13.63           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 (914  ), degtorad (915  ), radtodeg (937  ), radtograd (937  ), cycletorad (913  )


                Listing:  ./mathex/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  r a d t o c y c l ef u n c t i o n.  }


                Uses     math   ;


                 b e g i n



                                                                                 936

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                63.13.64           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 (914  ), degtorad (915  ), radtocycle (936  ), radtograd (937  ), cycletorad (913  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.65           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 (914  ), degtorad (915  ), radtocycle (936  ), radtodeg (937  ), cycletorad (913  )


                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   ;



                                                                                 937

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'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___.____________________________________________________________________________________________________________*
 *___________



                63.13.66           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 (927  ), stddev (942  ), meanandstddev (928  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.67           RandomFrom

    Synopsis:    Return a random element of an array of numbers

Declaration:     function  RandomFrom(const  AValues:  Array  of  Double)  :  Double;    Overload
                function  RandomFrom(const  AValues:  Array  of  Integer)  :  Integer
                                                ;    Overload
                function  RandomFrom(const  AValues:  Array  of  Int64)  :  Int64;    Overload

    Visibility:   default

Description:     RandomFrom returns a random element from the array AValues.  The return value has the
                same type as the type of the array elements.

    See also:    #rtl.system.Random (1410   ), RandomRange (939  )



                                                                                 938

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.68           RandomRange

    Synopsis:    Return a random number in a range

Declaration:     function  RandomRange(const  aFrom:  Integer;const  aTo:  Integer)  :  Integer
                function  RandomRange(const  aFrom:  Int64;const  aTo:  Int64)  :  Int64

    Visibility:   default

Description:     RandomRange  returns  a  random  value  in  the  range  AFrom  to  ATo.  AFrom  and  ATo  do  not
                need to be in increasing order.  The upper border is not included in the generated value, but
                the lower border is.

    See also:    #rtl.system.Random (1410   ), RandomFrom (938  )



                63.13.69           RoundTo

    Synopsis:    Round to the specified number of digits

Declaration:     function  RoundTo(const  AValue:  Double;const  Digits:  TRoundToRange)
                                            :  Double
                function  RoundTo(const  AVAlue:  Extended;const  Digits:  TRoundToRange)
                                            :  Extended
                function  RoundTo(const  AValue:  Single;const  Digits:  TRoundToRange)
                                            :  Single

    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 (906  ), SimpleRoundTo (941  )



                63.13.70           SameValue

    Synopsis:    Check whether 2 float values are the same

Declaration:     function  SameValue(const  A:  Extended;const  B:  Extended)  :  Boolean
                                              ;    Overload
                function  SameValue(const  A:  Double;const  B:  Double)  :  Boolean;    Overload
                function  SameValue(const  A:  Single;const  B:  Single)  :  Boolean;    Overload
                function  SameValue(const  A:  Extended;const  B:  Extended;
                                              Epsilon:  Extended)  :  Boolean;    Overload
                function  SameValue(const  A:  Double;const  B:  Double;Epsilon:  Double)
                                                :  Boolean;    Overload
                function  SameValue(const  A:  Single;const  B:  Single;Epsilon:  Single)
                                                :  Boolean;    Overload

    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.

                If unspecified, the default value for Epsilon is 0.0.

    See also:    MinFloat (904  ), IsZero (921  )



                                                                                 939

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.71           sec

    Synopsis:    Alias for secant

Declaration:     function  sec(x:  Float)  :  Float

    Visibility:   default

Description:     sec is an alias for the secant (940  ) function.

    See also:    secant (940  )



                63.13.72           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 (912  )



                63.13.73           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.



                63.13.74           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.



                63.13.75           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.



                                                                                 940

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.76           Sign

    Synopsis:    Return sign of argument

Declaration:     function  Sign(const  AValue:  Integer)  :  TValueSign;    Overload
                function  Sign(const  AValue:  Int64)  :  TValueSign;    Overload
                function  Sign(const  AValue:  Single)  :  TValueSign;    Overload
                function  Sign(const  AValue:  Double)  :  TValueSign;    Overload
                function  Sign(const  AValue:  Extended)  :  TValueSign;    Overload

    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.



                63.13.77           SimpleRoundTo

    Synopsis:    Round to the specified number of digits (rounding up if needed)

Declaration:     function  SimpleRoundTo(const  AValue:  Single;const  Digits:  TRoundToRange)
                                                      :  Single
                function  SimpleRoundTo(const  AValue:  Double;const  Digits:  TRoundToRange)
                                                      :  Double
                function  SimpleRoundTo(const  AValue:  Extended;
                                                     const  Digits:  TRoundToRange)  :  Extended

    Visibility:   default

Description:     SimpleRoundTo  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 (906  ), RoundTo (939  )



                63.13.78           sincos

    Synopsis:    Return sine and cosine of argument

Declaration:     procedure  sincos(theta:  single;out  sinus:  single;out  cosinus:  single)
                procedure  sincos(theta:  Double;out  sinus:  Double;out  cosinus:  Double)
                procedure  sincos(theta:  extended;out  sinus:  extended;
                                           out  cosinus:  extended)

    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 (908  ), arccos (906  )


                Listing:  ./mathex/ex41.pp



                                                                                 941

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.79           sinh

    Synopsis:    Return hyperbolic sine

Declaration:     function  sinh(x:  Float)  :  Float

    Visibility:   default

Description:     Sinh returns the hyperbolic sine of its argument x.

    See also:    cosh (912  ), arsinh (909  ), tanh (947  ), artanh (910  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.80           stddev

    Synopsis:    Return standard deviation of data



                                                                                 942

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



Declaration:     function  stddev(const  data:  Array  of  Single)  :  Float
                function  stddev(const  data:  PSingle;const  N:  Integer)  :  Float
                function  stddev(const  data:  Array  of  Double)  :  Float
                function  stddev(const  data:  PDouble;const  N:  Integer)  :  Float
                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 (927  ), meanandstddev (928  ), variance (948  ), totalvariance (947  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.81           sum

    Synopsis:    Return sum of values

Declaration:     function  sum(const  data:  Array  of  Single)  :  Float
                function  sum(const  data:  PSingle;const  N:  LongInt)  :  Float
                function  sum(const  data:  Array  of  Double)  :  Float
                function  sum(const  data:  PDouble;const  N:  LongInt)  :  Float
                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 (944  ), sumsandsquares (945  ), totalvariance (947  ), variance (948  )



                                                                                 943

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.82           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.



                63.13.83           sumofsquares

    Synopsis:    Return sum of squares of values

Declaration:     function  sumofsquares(const  data:  Array  of  Single)  :  Float
                function  sumofsquares(const  data:  PSingle;const  N:  Integer)  :  Float
                function  sumofsquares(const  data:  Array  of  Double)  :  Float
                function  sumofsquares(const  data:  PDouble;const  N:  Integer)  :  Float
                function  sumofsquares(const  data:  Array  of  Extended)  :  Float
                function  sumofsquares(const  data:  PExtended;const  N:  Integer)  :  Float

    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 (943  ), sumsandsquares (945  ), totalvariance (947  ), variance (948  )


                Listing:  ./mathex/ex45.pp



                                                                                 944

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.84           sumsandsquares

    Synopsis:    Return sum and sum of squares of values.

Declaration:     procedure  sumsandsquares(const  data:  Array  of  Single;var  sum:  Float;
                                                        var  sumofsquares:  Float)
                procedure  sumsandsquares(const  data:  PSingle;const  N:  Integer;
                                                        var  sum:  Float;var  sumofsquares:  Float)
                procedure  sumsandsquares(const  data:  Array  of  Double;var  sum:  Float;
                                                        var  sumofsquares:  Float)
                procedure  sumsandsquares(const  data:  PDouble;const  N:  Integer;
                                                        var  sum:  Float;var  sumofsquares:  Float)
                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 (943  ), sumofsquares (944  ), totalvariance (947  ), variance (948  )


                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   ;


                Var



                                                                                 945

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                63.13.85           tan

    Synopsis:    Return tangent

Declaration:     function  tan(x:  Float)  :  Float

    Visibility:   default

Description:     Tan returns the tangent of  x.  The argument x must be in radians.

       Errors:   If  x (normalized) is pi/2 or 3pi/2 then an overflow will occur.

    See also:    tanh (947  ), arcsin (908  ), sincos (941  ), arccos (906  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 946

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                63.13.86           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 (908  ), sincos (941  ), arccos (906  )


                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___.____________________________________________________________________________________________________________*
 *___________



                63.13.87           totalvariance

    Synopsis:    Return total varians of values

Declaration:     function  totalvariance(const  data:  Array  of  Single)  :  Float
                function  totalvariance(const  data:  PSingle;const  N:  Integer)  :  Float
                function  totalvariance(const  data:  Array  of  Double)  :  Float
                function  totalvariance(const  data:  PDouble;const  N:  Integer)  :  Float
                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 (948  ), stddev (942  ), mean (927  )


                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



                                                                                 947

                _____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                    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       ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                63.13.88           variance

    Synopsis:    Return variance of values

Declaration:     function  variance(const  data:  Array  of  Single)  :  Float
                function  variance(const  data:  PSingle;const  N:  Integer)  :  Float
                function  variance(const  data:  Array  of  Double)  :  Float
                function  variance(const  data:  PDouble;const  N:  Integer)  :  Float
                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 (947  ), stddev (942  ), mean (927  )


                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 ) ;



                                                                                 948

_____________________________________________________________CHAPTER_63.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



    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___._______________________________________________________________________________________________________________________



63.14            EInvalidArgument



63.14.1          Description

Exception raised when invalid arguments are passed to a function.



                                                                 949




Chapter   64



Reference   for   unit   'matrix'



64.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.



                                                             950

__________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________________________*
 *___



64.2          Constants,  types  and  variables



64.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.



                                                                 951

__________________________________________________________CHAPTER_64.___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



                                                                 952

                __________________________________________________________CHAPTER_64.___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.



                64.3          Procedures  and  functions



                64.3.1         add(Tmatrix2__double,Double):Tmatrix2__double

    Synopsis:    Add scalar to two-dimensional double precision matrix

Declaration:     operator  +(const  m:  Tmatrix2_double;const  x:  Double)  :  Tmatrix2_double

    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.



                64.3.2         add(Tmatrix2__double,Tmatrix2__double):Tmatrix2__double

    Synopsis:    Add two two-dimensional double precision matrices together.

Declaration:     operator  +(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.



                                                                                 953

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.3         add(Tmatrix2__extended,extended):Tmatrix2__extended

    Synopsis:    Add scalar to two-dimensional extended precision matrix

Declaration:     operator  +(const  m:  Tmatrix2_extended;const  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.



                64.3.4         add(Tmatrix2__extended,Tmatrix2__extended):Tmatrix2__extended

    Synopsis:    Add two two-dimensional extended precision matrices together.

Declaration:     operator  +(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.



                64.3.5         add(Tmatrix2__single,single):Tmatrix2__single

    Synopsis:    Add scalar to two-dimensional single precision matrix

Declaration:     operator  +(const  m:  Tmatrix2_single;const  x:  single)  :  Tmatrix2_single

    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.



                64.3.6         add(Tmatrix2__single,Tmatrix2__single):Tmatrix2__single

    Synopsis:    Add two two-dimensional single precision matrices together.

Declaration:     operator  +(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.



                64.3.7         add(Tmatrix3__double,Double):Tmatrix3__double

    Synopsis:    Add scalar to three-dimensional double precision matrix

Declaration:     operator  +(const  m:  Tmatrix3_double;const  x:  Double)  :  Tmatrix3_double

    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.



                                                                                 954

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.8         add(Tmatrix3__double,Tmatrix3__double):Tmatrix3__double

    Synopsis:    Add two three-dimensional double precision matrices together.

Declaration:     operator  +(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.



                64.3.9         add(Tmatrix3__extended,extended):Tmatrix3__extended

    Synopsis:    Add scalar to three-dimensional extended precision matrix

Declaration:     operator  +(const  m:  Tmatrix3_extended;const  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.



                64.3.10          add(Tmatrix3__extended,Tmatrix3__extended):Tmatrix3__extended

    Synopsis:    Add two three-dimensional extended precision matrices together.

Declaration:     operator  +(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.



                64.3.11          add(Tmatrix3__single,single):Tmatrix3__single

    Synopsis:    Add scalar to three-dimensional single precision matrix

Declaration:     operator  +(const  m:  Tmatrix3_single;const  x:  single)  :  Tmatrix3_single

    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.



                64.3.12          add(Tmatrix3__single,Tmatrix3__single):Tmatrix3__single

    Synopsis:    Add two three-dimensional single precision matrices together.

Declaration:     operator  +(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.



                                                                                 955

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.13          add(Tmatrix4__double,Double):Tmatrix4__double

    Synopsis:    Add scalar to four-dimensional double precision matrix

Declaration:     operator  +(const  m:  Tmatrix4_double;const  x:  Double)  :  Tmatrix4_double

    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.



                64.3.14          add(Tmatrix4__double,Tmatrix4__double):Tmatrix4__double

    Synopsis:    Add two four-dimensional double precision matrices together.

Declaration:     operator  +(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.



                64.3.15          add(Tmatrix4__extended,extended):Tmatrix4__extended

    Synopsis:    Add scalar to four-dimensional extended precision matrix

Declaration:     operator  +(const  m:  Tmatrix4_extended;const  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.



                64.3.16          add(Tmatrix4__extended,Tmatrix4__extended):Tmatrix4__extended

    Synopsis:    Add two four-dimensional extended precision matrices together.

Declaration:     operator  +(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.



                64.3.17          add(Tmatrix4__single,single):Tmatrix4__single

    Synopsis:    Add scalar to four-dimensional single precision matrix

Declaration:     operator  +(const  m:  Tmatrix4_single;const  x:  single)  :  Tmatrix4_single

    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.



                                                                                 956

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.18          add(Tmatrix4__single,Tmatrix4__single):Tmatrix4__single

    Synopsis:    Add two four-dimensional single precision matrices together.

Declaration:     operator  +(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.



                64.3.19          add(Tvector2__double,Double):Tvector2__double

    Synopsis:    Add scalar to two-dimensional double precision vector

Declaration:     operator  +(const  x:  Tvector2_double;y:  Double)  :  Tvector2_double

    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.



                64.3.20          add(Tvector2__double,Tvector2__double):Tvector2__double

    Synopsis:    Add two-dimensional double precision vectors together

Declaration:     operator  +(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.



                64.3.21          add(Tvector2__extended,extended):Tvector2__extended

    Synopsis:    Add scalar to two-dimensional extended precision vector

Declaration:     operator  +(const  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.



                64.3.22          add(Tvector2__extended,Tvector2__extended):Tvector2__extended

    Synopsis:    Add two-dimensional extended precision vectors together

Declaration:     operator  +(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.



                                                                                 957

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.23          add(Tvector2__single,single):Tvector2__single

    Synopsis:    Add scalar to two-dimensional single precision vector

Declaration:     operator  +(const  x:  Tvector2_single;y:  single)  :  Tvector2_single

    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.



                64.3.24          add(Tvector2__single,Tvector2__single):Tvector2__single

    Synopsis:    Add two-dimensional single precision vectors together

Declaration:     operator  +(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.



                64.3.25          add(Tvector3__double,Double):Tvector3__double

    Synopsis:    Add scalar to three-dimensional double precision vector

Declaration:     operator  +(const  x:  Tvector3_double;y:  Double)  :  Tvector3_double

    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.



                64.3.26          add(Tvector3__double,Tvector3__double):Tvector3__double

    Synopsis:    Add three-dimensional double precision vectors together

Declaration:     operator  +(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.



                64.3.27          add(Tvector3__extended,extended):Tvector3__extended

    Synopsis:    Add scalar to three-dimensional extended precision vector

Declaration:     operator  +(const  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.



                                                                                 958

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.28          add(Tvector3__extended,Tvector3__extended):Tvector3__extended

    Synopsis:    Add three-dimensional extended precision vectors together

Declaration:     operator  +(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.



                64.3.29          add(Tvector3__single,single):Tvector3__single

    Synopsis:    Add scalar to three-dimensional single precision vector

Declaration:     operator  +(const  x:  Tvector3_single;y:  single)  :  Tvector3_single

    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.



                64.3.30          add(Tvector3__single,Tvector3__single):Tvector3__single

    Synopsis:    Add three-dimensional extended precision vectors together

Declaration:     operator  +(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.



                64.3.31          add(Tvector4__double,Double):Tvector4__double

    Synopsis:    Add scalar to four-dimensional double precision vector

Declaration:     operator  +(const  x:  Tvector4_double;y:  Double)  :  Tvector4_double

    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.



                64.3.32          add(Tvector4__double,Tvector4__double):Tvector4__double

    Synopsis:    Add four-dimensional double precision vectors together

Declaration:     operator  +(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.



                                                                                 959

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.33          add(Tvector4__extended,extended):Tvector4__extended

    Synopsis:    Add scalar to four-dimensional extended precision vector

Declaration:     operator  +(const  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.



                64.3.34          add(Tvector4__extended,Tvector4__extended):Tvector4__extended

    Synopsis:    Add four-dimensional extended precision vectors together

Declaration:     operator  +(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.



                64.3.35          add(Tvector4__single,single):Tvector4__single

    Synopsis:    Add scalar to four-dimensional single precision vector

Declaration:     operator  +(const  x:  Tvector4_single;y:  single)  :  Tvector4_single

    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.



                64.3.36          add(Tvector4__single,Tvector4__single):Tvector4__single

    Synopsis:    Add four-dimensional single precision vectors together

Declaration:     operator  +(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.



                64.3.37          assign(Tmatrix2__double):Tmatrix2__extended

    Synopsis:    Allow assignment of two-dimensional double precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_double)  :  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.



                                                                                 960

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.38          assign(Tmatrix2__double):Tmatrix2__single

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_double)  :  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.



                64.3.39          assign(Tmatrix2__double):Tmatrix3__double

    Synopsis:    Allow assignment of two-dimensional double precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_double)  :  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.



                64.3.40          assign(Tmatrix2__double):Tmatrix3__extended

    Synopsis:    Allow assignment of two-dimensional double precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_double)  :  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.



                64.3.41          assign(Tmatrix2__double):Tmatrix3__single

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_double)  :  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.



                                                                                 961

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.42          assign(Tmatrix2__double):Tmatrix4__double

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_double)  :  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.



                64.3.43          assign(Tmatrix2__double):Tmatrix4__extended

    Synopsis:    Allow assignment of two-dimensional double precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_double)  :  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.



                64.3.44          assign(Tmatrix2__double):Tmatrix4__single

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  matrix  to  four-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_double)  :  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.



                64.3.45          assign(Tmatrix2__extended):Tmatrix2__double

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to two-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_extended)  :  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.



                                                                                 962

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.46          assign(Tmatrix2__extended):Tmatrix2__single

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to two-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_extended)  :  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.



                64.3.47          assign(Tmatrix2__extended):Tmatrix3__double

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_extended)  :  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.



                64.3.48          assign(Tmatrix2__extended):Tmatrix3__extended

    Synopsis:    Allow  assignment  of  two-dimensional  extended  precision  matrix  to  three-dimensional  ex-
                tended precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_extended)  :  Tmatrix3_extended

    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.



                64.3.49          assign(Tmatrix2__extended):Tmatrix3__single

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to three-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_extended)  :  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.



                                                                                 963

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.50          assign(Tmatrix2__extended):Tmatrix4__double

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to four-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_extended)  :  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.



                64.3.51          assign(Tmatrix2__extended):Tmatrix4__extended

    Synopsis:    Allow  assignment  of  two-dimensional  extended  precision  matrix  to  four-dimensional  ex-
                tended precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_extended)  :  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 single precision is expected.  The extra fields are set to
                0.



                64.3.52          assign(Tmatrix2__extended):Tmatrix4__single

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to four-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_extended)  :  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.



                64.3.53          assign(Tmatrix2__single):Tmatrix2__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_single)  :  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.



                64.3.54          assign(Tmatrix2__single):Tmatrix2__extended

    Synopsis:    Allow assignment of two-dimensional single precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_single)  :  Tmatrix2_extended



                                                                                 964

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.55          assign(Tmatrix2__single):Tmatrix3__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  three-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_single)  :  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.



                64.3.56          assign(Tmatrix2__single):Tmatrix3__extended

    Synopsis:    Allow assignment of two-dimensional single precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_single)  :  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.



                64.3.57          assign(Tmatrix2__single):Tmatrix3__single

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_single)  :  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.



                64.3.58          assign(Tmatrix2__single):Tmatrix4__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_single)  :  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.



                                                                                 965

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.59          assign(Tmatrix2__single):Tmatrix4__extended

    Synopsis:    Allow assignment of two-dimensional single precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_single)  :  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.



                64.3.60          assign(Tmatrix2__single):Tmatrix4__single

    Synopsis:    Allow assignment of two-dimensional single precision matrix to four-dimensional single pre-
                cision matrix

Declaration:     operator  :=(const  v:  Tmatrix2_single)  :  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.



                64.3.61          assign(Tmatrix3__double):Tmatrix2__double

    Synopsis:    Allow assignment of three-dimensional double precision matrix to two-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_double)  :  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.



                64.3.62          assign(Tmatrix3__double):Tmatrix2__extended

    Synopsis:    Allow assignment of three-dimensional double precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_double)  :  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.



                                                                                 966

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.63          assign(Tmatrix3__double):Tmatrix2__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_double)  :  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.



                64.3.64          assign(Tmatrix3__double):Tmatrix3__extended

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  matrix  to  three-dimensional  ex-
                tended precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_double)  :  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.



                64.3.65          assign(Tmatrix3__double):Tmatrix3__single

    Synopsis:    Allow assignment of three-dimensional double precision matrix to three-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_double)  :  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.



                64.3.66          assign(Tmatrix3__double):Tmatrix4__double

    Synopsis:    Allow assignment of three-dimensional double precision matrix to four-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_double)  :  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.



                64.3.67          assign(Tmatrix3__double):Tmatrix4__extended

    Synopsis:    Allow assignment of three-dimensional double precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_double)  :  Tmatrix4_extended



                                                                                 967

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.68          assign(Tmatrix3__double):Tmatrix4__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  matrix  to  four-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_double)  :  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.



                64.3.69          assign(Tmatrix3__extended):Tmatrix2__double

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to two-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_extended)  :  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.



                64.3.70          assign(Tmatrix3__extended):Tmatrix2__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  matrix  to  two-dimensional  ex-
                tended precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_extended)  :  Tmatrix2_extended

    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.



                64.3.71          assign(Tmatrix3__extended):Tmatrix2__single

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to two-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_extended)  :  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.



                                                                                 968

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.72          assign(Tmatrix3__extended):Tmatrix3__double

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to three-dimensional dou-
                ble precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_extended)  :  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.



                64.3.73          assign(Tmatrix3__extended):Tmatrix3__single

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to three-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_extended)  :  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.



                64.3.74          assign(Tmatrix3__extended):Tmatrix4__double

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to four-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_extended)  :  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.



                64.3.75          assign(Tmatrix3__extended):Tmatrix4__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  matrix  to  four-dimensional  ex-
                tended precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_extended)  :  Tmatrix4_extended

    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.



                64.3.76          assign(Tmatrix3__extended):Tmatrix4__single

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to four-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_extended)  :  Tmatrix4_single



                                                                                 969

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.77          assign(Tmatrix3__single):Tmatrix2__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_single)  :  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.



                64.3.78          assign(Tmatrix3__single):Tmatrix2__extended

    Synopsis:    Allow assignment of three-dimensional single precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_single)  :  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.



                64.3.79          assign(Tmatrix3__single):Tmatrix2__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_single)  :  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.



                64.3.80          assign(Tmatrix3__single):Tmatrix3__double

    Synopsis:    Allow assignment of three-dimensional single precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_single)  :  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.



                                                                                 970

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.81          assign(Tmatrix3__single):Tmatrix3__extended

    Synopsis:    Allow assignment of three-dimensional single precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_single)  :  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.



                64.3.82          assign(Tmatrix3__single):Tmatrix4__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_single)  :  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.



                64.3.83          assign(Tmatrix3__single):Tmatrix4__extended

    Synopsis:    Allow assignment of three-dimensional single precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_single)  :  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.



                64.3.84          assign(Tmatrix3__single):Tmatrix4__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  four-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix3_single)  :  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.



                64.3.85          assign(Tmatrix4__double):Tmatrix2__double

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_double)  :  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.



                                                                                 971

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.86          assign(Tmatrix4__double):Tmatrix2__extended

    Synopsis:    Allow assignment of four-dimensional double precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_double)  :  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.



                64.3.87          assign(Tmatrix4__double):Tmatrix2__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_double)  :  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.



                64.3.88          assign(Tmatrix4__double):Tmatrix3__double

    Synopsis:    Allow assignment of four-dimensional double precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_double)  :  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.



                64.3.89          assign(Tmatrix4__double):Tmatrix3__extended

    Synopsis:    Allow assignment of four-dimensional double precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_double)  :  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.



                                                                                 972

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.90          assign(Tmatrix4__double):Tmatrix3__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_double)  :  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.



                64.3.91          assign(Tmatrix4__double):Tmatrix4__extended

    Synopsis:    Allow assignment of four-dimensional double precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_double)  :  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.



                64.3.92          assign(Tmatrix4__double):Tmatrix4__single

    Synopsis:    Allow assignment of four-dimensional single precision matrix to four-dimensional single pre-
                cision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_double)  :  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.



                64.3.93          assign(Tmatrix4__extended):Tmatrix2__double

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to two-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_extended)  :  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.



                64.3.94          assign(Tmatrix4__extended):Tmatrix2__extended

    Synopsis:    Allow  assignment  of  four-dimensional  extended  precision  matrix  to  two-dimensional  ex-
                tended precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_extended)  :  Tmatrix2_extended



                                                                                 973

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.95          assign(Tmatrix4__extended):Tmatrix2__single

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to two-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_extended)  :  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.



                64.3.96          assign(Tmatrix4__extended):Tmatrix3__double

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_extended)  :  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.



                64.3.97          assign(Tmatrix4__extended):Tmatrix3__extended

    Synopsis:    Allow  assignment  of  four-dimensional  extended  precision  matrix  to  three-dimensional  ex-
                tended precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_extended)  :  Tmatrix3_extended

    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.



                64.3.98          assign(Tmatrix4__extended):Tmatrix3__single

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to three-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_extended)  :  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.



                                                                                 974

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.99          assign(Tmatrix4__extended):Tmatrix4__double

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to four-dimensional double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_extended)  :  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.



                64.3.100           assign(Tmatrix4__extended):Tmatrix4__single

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to four-dimensional single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_extended)  :  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.



                64.3.101           assign(Tmatrix4__single):Tmatrix2__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_single)  :  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.



                64.3.102           assign(Tmatrix4__single):Tmatrix2__extended

    Synopsis:    Allow assignment of four-dimensional single precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_single)  :  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.



                64.3.103           assign(Tmatrix4__single):Tmatrix2__single

    Synopsis:    Allow assignment of four-dimensional single precision matrix to two-dimensional single pre-
                cision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_single)  :  Tmatrix2_single



                                                                                 975

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.104           assign(Tmatrix4__single):Tmatrix3__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  three-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_single)  :  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.



                64.3.105           assign(Tmatrix4__single):Tmatrix3__extended

    Synopsis:    Allow assignment of four-dimensional single precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_single)  :  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.



                64.3.106           assign(Tmatrix4__single):Tmatrix3__single

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_single)  :  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.



                64.3.107           assign(Tmatrix4__single):Tmatrix4__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_single)  :  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.



                                                                                 976

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.108           assign(Tmatrix4__single):Tmatrix4__extended

    Synopsis:    Allow assignment of four-dimensional single precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  :=(const  v:  Tmatrix4_single)  :  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.



                64.3.109           assign(Tvector2__double):Tvector2__extended

    Synopsis:    Allow assignment of double precision vector to extended precision vector

Declaration:     operator  :=(const  v:  Tvector2_double)  :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to use a vector with double precision values wherever an extended
                precision vector is expected.



                64.3.110           assign(Tvector2__double):Tvector2__single

    Synopsis:    Allow assignment of double precision vector to single precision vector

Declaration:     operator  :=(const  v:  Tvector2_double)  :  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.



                64.3.111           assign(Tvector2__double):Tvector3__double

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  vector  to  three-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_double)  :  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.



                64.3.112           assign(Tvector2__double):Tvector3__extended

    Synopsis:    Allow assignment of two-dimensional double precision vector to three-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_double)  :  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.



                                                                                 977

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.113           assign(Tvector2__double):Tvector3__single

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_double)  :  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.



                64.3.114           assign(Tvector2__double):Tvector4__double

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_double)  :  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.



                64.3.115           assign(Tvector2__double):Tvector4__extended

    Synopsis:    Allow assignment of two-dimensional double precision vector to four-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_double)  :  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.



                64.3.116           assign(Tvector2__double):Tvector4__single

    Synopsis:    Allow assignment of two-dimensional double precision vector to four-dimensional single pre-
                cision vector

Declaration:     operator  :=(const  v:  Tvector2_double)  :  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.



                                                                                 978

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.117           assign(Tvector2__extended):Tvector2__double

    Synopsis:    Allow assignment of extended precision vector to double precision vector

Declaration:     operator  :=(const  v:  Tvector2_extended)  :  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.



                64.3.118           assign(Tvector2__extended):Tvector2__single

    Synopsis:    Allow assignment of extended precision vector to single precision vector

Declaration:     operator  :=(const  v:  Tvector2_extended)  :  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.



                64.3.119           assign(Tvector2__extended):Tvector3__double

    Synopsis:    Allow assignment of two-dimensional extended precision vector to three-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_extended)  :  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.



                64.3.120           assign(Tvector2__extended):Tvector3__extended

    Synopsis:    Allow assignment of two-dimensional extened precision vector to three-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_extended)  :  Tvector3_extended

    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.



                64.3.121           assign(Tvector2__extended):Tvector3__single

    Synopsis:    Allow assignment of two-dimensional extended precision vector to three-dimensional single
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_extended)  :  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.



                                                                                 979

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.122           assign(Tvector2__extended):Tvector4__double

    Synopsis:    Allow assignment of two-dimensional extended precision vector to four-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_extended)  :  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.



                64.3.123           assign(Tvector2__extended):Tvector4__extended

    Synopsis:    Allow assignment of two-dimensiona extended precision vector to four-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_extended)  :  Tvector4_extended

    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.



                64.3.124           assign(Tvector2__extended):Tvector4__single

    Synopsis:    Allow assignment of two-dimensional extended precision vector to four-dimensional single
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_extended)  :  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.



                64.3.125           assign(Tvector2__single):Tvector2__double

    Synopsis:    Allow assignment of single precision vector to double precision vector

Declaration:     operator  :=(const  v:  Tvector2_single)  :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  vector  with  single  precision  values  wherever  a  double
                precision vector is expected.



                64.3.126           assign(Tvector2__single):Tvector2__extended

    Synopsis:    Allow assignment of single precision vector to extended precision vector

Declaration:     operator  :=(const  v:  Tvector2_single)  :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to use a vector with single precision values wherever an extended
                precision vector is expected.



                                                                                 980

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.127           assign(Tvector2__single):Tvector3__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  vector  to  three-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_single)  :  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.



                64.3.128           assign(Tvector2__single):Tvector3__extended

    Synopsis:    Allow assignment of two-dimensional single precision vector to three-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_single)  :  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.



                64.3.129           assign(Tvector2__single):Tvector3__single

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_single)  :  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.



                64.3.130           assign(Tvector2__single):Tvector4__double

    Synopsis:    Allow assignment of two-dimensional single precision vector to four-dimensional double pre-
                cision vector

Declaration:     operator  :=(const  v:  Tvector2_single)  :  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.



                                                                                 981

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.131           assign(Tvector2__single):Tvector4__extended

    Synopsis:    Allow assignment of two-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector2_single)  :  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.



                64.3.132           assign(Tvector2__single):Tvector4__single

    Synopsis:    Allow assignment of two-dimensional single precision vector to four-dimensional single pre-
                cision vector

Declaration:     operator  :=(const  v:  Tvector2_single)  :  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.



                64.3.133           assign(Tvector3__double):Tvector2__double

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  two-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_double)  :  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.



                64.3.134           assign(Tvector3__double):Tvector2__extended

    Synopsis:    Allow assignment of three-dimensional double precision vector to two-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_double)  :  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.



                                                                                 982

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.135           assign(Tvector3__double):Tvector2__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  two-dimensional  single
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_double)  :  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.



                64.3.136           assign(Tvector3__double):Tvector3__extended

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  three-dimensional  ex-
                tended precision vector

Declaration:     operator  :=(const  v:  Tvector3_double)  :  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.



                64.3.137           assign(Tvector3__double):Tvector3__single

    Synopsis:    Allow assignment of three-dimensional double precision vector to three-dimensional single
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_double)  :  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.



                64.3.138           assign(Tvector3__double):Tvector4__double

    Synopsis:    Allow assignment of three-dimensional double precision vector to four-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_double)  :  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.



                64.3.139           assign(Tvector3__double):Tvector4__extended

    Synopsis:    Allow assignment of three-dimensional double precision vector to four-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_double)  :  Tvector4_extended



                                                                                 983

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.140           assign(Tvector3__double):Tvector4__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  four-dimensional  single
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_double)  :  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.



                64.3.141           assign(Tvector3__extended):Tvector2__double

    Synopsis:    Allow assignment of three-dimensional extended precision vector to two-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_extended)  :  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.



                64.3.142           assign(Tvector3__extended):Tvector2__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  vector  to  two-dimensional  ex-
                tended precision vector

Declaration:     operator  :=(const  v:  Tvector3_extended)  :  Tvector2_extended

    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.



                64.3.143           assign(Tvector3__extended):Tvector2__single

    Synopsis:    Allow assignment of three-dimensional extended precision vector to two-dimensional single
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_extended)  :  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.



                                                                                 984

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.144           assign(Tvector3__extended):Tvector3__double

    Synopsis:    Allow assignment of three-dimensional extended precision vector to three-dimensional dou-
                ble precision vector

Declaration:     operator  :=(const  v:  Tvector3_extended)  :  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.



                64.3.145           assign(Tvector3__extended):Tvector3__single

    Synopsis:    Allow assignment of three-dimensional single precision vector to three-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_extended)  :  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.



                64.3.146           assign(Tvector3__extended):Tvector4__double

    Synopsis:    Allow assignment of three-dimensional extended precision vector to four-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_extended)  :  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.



                64.3.147           assign(Tvector3__extended):Tvector4__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  vector  to  four-dimensional  ex-
                tended precision vector

Declaration:     operator  :=(const  v:  Tvector3_extended)  :  Tvector4_extended

    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.



                                                                                 985

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.148           assign(Tvector3__extended):Tvector4__single

    Synopsis:    Allow assignment of three-dimensional extended precision vector to four-dimensional single
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_extended)  :  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.



                64.3.149           assign(Tvector3__single):Tvector2__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  two-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_single)  :  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.



                64.3.150           assign(Tvector3__single):Tvector2__extended

    Synopsis:    Allow assignment of three-dimensional single precision vector to two-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_single)  :  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.



                64.3.151           assign(Tvector3__single):Tvector2__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  two-dimensional  single
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_single)  :  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.



                                                                                 986

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.152           assign(Tvector3__single):Tvector3__double

    Synopsis:    Allow assignment of three-dimensional single precision vector to three-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_single)  :  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.



                64.3.153           assign(Tvector3__single):Tvector3__extended

    Synopsis:    Allow assignment of three-dimensional single precision vector to three-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_single)  :  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.



                64.3.154           assign(Tvector3__single):Tvector4__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_single)  :  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.



                64.3.155           assign(Tvector3__single):Tvector4__extended

    Synopsis:    Allow assignment of three-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_single)  :  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.



                64.3.156           assign(Tvector3__single):Tvector4__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  four-dimensional  single
                precision vector

Declaration:     operator  :=(const  v:  Tvector3_single)  :  Tvector4_single



                                                                                 987

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.157           assign(Tvector4__double):Tvector2__double

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  vector  to  two-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_double)  :  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.



                64.3.158           assign(Tvector4__double):Tvector2__extended

    Synopsis:    Allow assignment of four-dimensional double precision vector to two-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_double)  :  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.



                64.3.159           assign(Tvector4__double):Tvector2__single

    Synopsis:    Allow assignment of four-dimensional double precision vector to two-dimensional single pre-
                cision vector

Declaration:     operator  :=(const  v:  Tvector4_double)  :  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.



                64.3.160           assign(Tvector4__double):Tvector3__double

    Synopsis:    Allow assignment of four-dimensional double precision vector to three-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_double)  :  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.



                                                                                 988

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.161           assign(Tvector4__double):Tvector3__extended

    Synopsis:    Allow assignment of four-dimensional double precision vector to three-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_double)  :  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.



                64.3.162           assign(Tvector4__double):Tvector3__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_double)  :  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.



                64.3.163           assign(Tvector4__double):Tvector4__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_double)  :  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.



                64.3.164           assign(Tvector4__double):Tvector4__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  vector  to  four-dimensional  single
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_double)  :  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.



                64.3.165           assign(Tvector4__extended):Tvector2__double

    Synopsis:    Allow assignment of four-dimensional extended precision vector to two-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_extended)  :  Tvector2_double



                                                                                 989

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.166           assign(Tvector4__extended):Tvector2__extended

    Synopsis:    Allow assignment of four-dimensional extended precision vector to two-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_extended)  :  Tvector2_extended

    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.



                64.3.167           assign(Tvector4__extended):Tvector2__single

    Synopsis:    Allow assignment of four-dimensional extended precision vector to two-dimensional single
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_extended)  :  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.



                64.3.168           assign(Tvector4__extended):Tvector3__double

    Synopsis:    Allow assignment of four-dimensional extended precision vector to three-dimensional double
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_extended)  :  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.



                64.3.169           assign(Tvector4__extended):Tvector3__extended

    Synopsis:    Allow  assignment  of  four-dimensional  extended  precision  vector  to  three-dimensional  ex-
                tended precision vector

Declaration:     operator  :=(const  v:  Tvector4_extended)  :  Tvector3_extended

    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.



                                                                                 990

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.170           assign(Tvector4__extended):Tvector3__single

    Synopsis:    Allow assignment of four-dimensional extended precision vector to three-dimensional single
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_extended)  :  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.



                64.3.171           assign(Tvector4__extended):Tvector4__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_extended)  :  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.



                64.3.172           assign(Tvector4__extended):Tvector4__single

    Synopsis:    Allow assignment of four-dimensional extended precision vector to four-dimensional single
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_extended)  :  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.



                64.3.173           assign(Tvector4__single):Tvector2__double

    Synopsis:    Allow assignment of four-dimensional single precision vector to two-dimensional double pre-
                cision vector

Declaration:     operator  :=(const  v:  Tvector4_single)  :  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.



                                                                                 991

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.174           assign(Tvector4__single):Tvector2__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to two-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_single)  :  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.



                64.3.175           assign(Tvector4__single):Tvector2__single

    Synopsis:    Allow assignment of four-dimensional single precision vector to two-dimensional single pre-
                cision vector

Declaration:     operator  :=(const  v:  Tvector4_single)  :  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.



                64.3.176           assign(Tvector4__single):Tvector3__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  three-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_single)  :  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.



                64.3.177           assign(Tvector4__single):Tvector3__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to three-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_single)  :  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.



                                                                                 992

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.178           assign(Tvector4__single):Tvector3__single

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_single)  :  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.



                64.3.179           assign(Tvector4__single):Tvector4__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_single)  :  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.



                64.3.180           assign(Tvector4__single):Tvector4__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     operator  :=(const  v:  Tvector4_single)  :  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.



                64.3.181           divide(Tmatrix2__double,Double):Tmatrix2__double

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  /(const  m:  Tmatrix2_double;const  x:  Double)  :  Tmatrix2_double

    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.



                64.3.182           divide(Tmatrix2__extended,extended):Tmatrix2__extended

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  /(const  m:  Tmatrix2_extended;const  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.



                                                                                 993

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.183           divide(Tmatrix2__single,single):Tmatrix2__single

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  /(const  m:  Tmatrix2_single;const  x:  single)  :  Tmatrix2_single

    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.



                64.3.184           divide(Tmatrix3__double,Double):Tmatrix3__double

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  /(const  m:  Tmatrix3_double;const  x:  Double)  :  Tmatrix3_double

    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.



                64.3.185           divide(Tmatrix3__extended,extended):Tmatrix3__extended

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  /(const  m:  Tmatrix3_extended;const  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.



                64.3.186           divide(Tmatrix3__single,single):Tmatrix3__single

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  /(const  m:  Tmatrix3_single;const  x:  single)  :  Tmatrix3_single

    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.



                64.3.187           divide(Tmatrix4__double,Double):Tmatrix4__double

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  /(const  m:  Tmatrix4_double;const  x:  Double)  :  Tmatrix4_double

    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.



                                                                                 994

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.188           divide(Tmatrix4__extended,extended):Tmatrix4__extended

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  /(const  m:  Tmatrix4_extended;const  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.



                64.3.189           divide(Tmatrix4__single,single):Tmatrix4__single

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  /(const  m:  Tmatrix4_single;const  x:  single)  :  Tmatrix4_single

    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.



                64.3.190           divide(Tvector2__double,Double):Tvector2__double

    Synopsis:    Divide a two-dimensional double precision vector by a scalar

Declaration:     operator  /(const  x:  Tvector2_double;y:  Double)  :  Tvector2_double

    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.



                64.3.191           divide(Tvector2__extended,extended):Tvector2__extended

    Synopsis:    Divide a two-dimensional extended precision vector by a scalar

Declaration:     operator  /(const  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.



                64.3.192           divide(Tvector2__single,single):Tvector2__single

    Synopsis:    Divide a two-dimensional single precision vector by a scalar

Declaration:     operator  /(const  x:  Tvector2_single;y:  single)  :  Tvector2_single

    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.



                                                                                 995

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.193           divide(Tvector3__double,Double):Tvector3__double

    Synopsis:    Divide a three-dimensional double precision vector by a scalar

Declaration:     operator  /(const  x:  Tvector3_double;y:  Double)  :  Tvector3_double

    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.



                64.3.194           divide(Tvector3__extended,extended):Tvector3__extended

    Synopsis:    Divide a three-dimensional extended precision vector by a scalar

Declaration:     operator  /(const  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.



                64.3.195           divide(Tvector3__single,single):Tvector3__single

    Synopsis:    Divide a three-dimensional single precision vector by a scalar

Declaration:     operator  /(const  x:  Tvector3_single;y:  single)  :  Tvector3_single

    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.



                64.3.196           divide(Tvector4__double,Double):Tvector4__double

    Synopsis:    Divide a four-dimensional double precision vector by a scalar

Declaration:     operator  /(const  x:  Tvector4_double;y:  Double)  :  Tvector4_double

    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.



                64.3.197           divide(Tvector4__extended,extended):Tvector4__extended

    Synopsis:    Divide a four-dimensional extended precision vector by a scalar

Declaration:     operator  /(const  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.



                                                                                 996

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.198           divide(Tvector4__single,single):Tvector4__single

    Synopsis:    Divide a four-dimensional single precision vector by a scalar

Declaration:     operator  /(const  x:  Tvector4_single;y:  single)  :  Tvector4_single

    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.



                64.3.199           multiply(Tmatrix2__double,Double):Tmatrix2__double

    Synopsis:    Multiply a two-dimensional double precision matrix by a scalar

Declaration:     operator  *(const  m:  Tmatrix2_double;const  x:  Double)  :  Tmatrix2_double

    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.



                64.3.200           multiply(Tmatrix2__double,Tmatrix2__double):Tmatrix2__double

    Synopsis:    Give product of two two-dimensional double precision matrices

Declaration:     operator  *(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.



                64.3.201           multiply(Tmatrix2__double,Tvector2__double):Tvector2__double

    Synopsis:    Give product of a two-dimendional double precision matrix and vector

Declaration:     operator  *(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.



                64.3.202           multiply(Tmatrix2__extended,extended):Tmatrix2__extended

    Synopsis:    Multiply a two-dimensional extended precision matrix by a scalar

Declaration:     operator  *(const  m:  Tmatrix2_extended;const  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.



                                                                                 997

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.203           multiply(Tmatrix2__extended,Tmatrix2__extended):Tmatrix2__extended

    Synopsis:    Give product of two two-dimensional extended precision matrices

Declaration:     operator  *(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.



                64.3.204           multiply(Tmatrix2__extended,Tvector2__extended):Tvector2__extended

    Synopsis:    Give product of a two-dimendional extended precision matrix and vector

Declaration:     operator  *(const  m:  Tmatrix2_extended;const  v:  Tvector2_extended)
                                  :  Tvector2_extended

    Visibility:   default

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.



                64.3.205           multiply(Tmatrix2__single,single):Tmatrix2__single

    Synopsis:    Multiply a two-dimensional single precision matrix by a scalar

Declaration:     operator  *(const  m:  Tmatrix2_single;const  x:  single)  :  Tmatrix2_single

    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.



                64.3.206           multiply(Tmatrix2__single,Tmatrix2__single):Tmatrix2__single

    Synopsis:    Give product of two two-dimensional single precision matrices

Declaration:     operator  *(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.



                64.3.207           multiply(Tmatrix2__single,Tvector2__single):Tvector2__single

    Synopsis:    Give product of a two-dimendional single precision matrix and vector

Declaration:     operator  *(const  m:  Tmatrix2_single;const  v:  Tvector2_single)
                                  :  Tvector2_single



                                                                                 998

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.208           multiply(Tmatrix3__double,Double):Tmatrix3__double

    Synopsis:    Multiply a three-dimensional double precision matrix by a scalar

Declaration:     operator  *(const  m:  Tmatrix3_double;const  x:  Double)  :  Tmatrix3_double

    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.



                64.3.209           multiply(Tmatrix3__double,Tmatrix3__double):Tmatrix3__double

    Synopsis:    Give product of two three-dimensional double precision matrices

Declaration:     operator  *(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.



                64.3.210           multiply(Tmatrix3__double,Tvector3__double):Tvector3__double

    Synopsis:    Give product of a three-dimendional double precision matrix and vector

Declaration:     operator  *(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.



                64.3.211           multiply(Tmatrix3__extended,extended):Tmatrix3__extended

    Synopsis:    Multiply a three-dimensional extended precision matrix by a scalar

Declaration:     operator  *(const  m:  Tmatrix3_extended;const  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.



                                                                                 999

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.212           multiply(Tmatrix3__extended,Tmatrix3__extended):Tmatrix3__extended

    Synopsis:    Give product of two three-dimensional extended precision matrices

Declaration:     operator  *(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.



                64.3.213           multiply(Tmatrix3__extended,Tvector3__extended):Tvector3__extended

    Synopsis:    Give product of a three-dimendional extended precision matrix and vector

Declaration:     operator  *(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.



                64.3.214           multiply(Tmatrix3__single,single):Tmatrix3__single

    Synopsis:    Multiply a three-dimensional single precision matrix by a scalar

Declaration:     operator  *(const  m:  Tmatrix3_single;const  x:  single)  :  Tmatrix3_single

    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.



                64.3.215           multiply(Tmatrix3__single,Tmatrix3__single):Tmatrix3__single

    Synopsis:    Give product of two three-dimensional single precision matrices

Declaration:     operator  *(const  m1:  Tmatrix3_single;const  m2:  Tmatrix3_single)
                                  :  Tmatrix3_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.



                64.3.216           multiply(Tmatrix3__single,Tvector3__single):Tvector3__single

    Synopsis:    Give product of a three-dimendional single precision matrix and vector

Declaration:     operator  *(const  m:  Tmatrix3_single;const  v:  Tvector3_single)
                                  :  Tvector3_single



                                                                                1000

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.217           multiply(Tmatrix4__double,Double):Tmatrix4__double

    Synopsis:    Multiply a four-dimensional double precision matrix by a scalar

Declaration:     operator  *(const  m:  Tmatrix4_double;const  x:  Double)  :  Tmatrix4_double

    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.



                64.3.218           multiply(Tmatrix4__double,Tmatrix4__double):Tmatrix4__double

    Synopsis:    Give product of two four-dimensional double precision matrices

Declaration:     operator  *(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.



                64.3.219           multiply(Tmatrix4__double,Tvector4__double):Tvector4__double

    Synopsis:    Give product of a four-dimendional double precision matrix and vector

Declaration:     operator  *(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.



                64.3.220           multiply(Tmatrix4__extended,extended):Tmatrix4__extended

    Synopsis:    Multiply a four-dimensional extended precision matrix by a scalar

Declaration:     operator  *(const  m:  Tmatrix4_extended;const  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.



                                                                                1001

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.221           multiply(Tmatrix4__extended,Tmatrix4__extended):Tmatrix4__extended

    Synopsis:    Give product of two four-dimensional extended precision matrices

Declaration:     operator  *(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.



                64.3.222           multiply(Tmatrix4__extended,Tvector4__extended):Tvector4__extended

    Synopsis:    Give product of a four-dimendional extended precision matrix and vector

Declaration:     operator  *(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.



                64.3.223           multiply(Tmatrix4__single,single):Tmatrix4__single

    Synopsis:    Multiply a four-dimensional single precision matrix by a scalar

Declaration:     operator  *(const  m:  Tmatrix4_single;const  x:  single)  :  Tmatrix4_single

    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.



                64.3.224           multiply(Tmatrix4__single,Tmatrix4__single):Tmatrix4__single

    Synopsis:    Give product of two four-dimensional single precision matrices

Declaration:     operator  *(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.



                64.3.225           multiply(Tmatrix4__single,Tvector4__single):Tvector4__single

    Synopsis:    Give product of a four-dimendional single precision matrix and vector

Declaration:     operator  *(const  m:  Tmatrix4_single;const  v:  Tvector4_single)
                                  :  Tvector4_single



                                                                                1002

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.3.226           multiply(Tvector2__double,Double):Tvector2__double

    Synopsis:    Multiply a two-dimensional double precision vector by a scalar

Declaration:     operator  *(const  x:  Tvector2_double;y:  Double)  :  Tvector2_double

    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.



                64.3.227           multiply(Tvector2__double,Tvector2__double):Tvector2__double

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  *(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.



                64.3.228           multiply(Tvector2__extended,extended):Tvector2__extended

    Synopsis:    Multiply a two-dimensional extended precision vector by a scalar

Declaration:     operator  *(const  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.



                64.3.229           multiply(Tvector2__extended,Tvector2__extended):Tvector2__extended

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  *(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.



                                                                                1003

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.230           multiply(Tvector2__single,single):Tvector2__single

    Synopsis:    Multiply a two-dimensional single precision vector by a scalar

Declaration:     operator  *(const  x:  Tvector2_single;y:  single)  :  Tvector2_single

    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.



                64.3.231           multiply(Tvector2__single,Tvector2__single):Tvector2__single

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  *(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.



                64.3.232           multiply(Tvector3__double,Double):Tvector3__double

    Synopsis:    Multiply a three-dimensional double precision vector by a scalar

Declaration:     operator  *(const  x:  Tvector3_double;y:  Double)  :  Tvector3_double

    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.



                64.3.233           multiply(Tvector3__double,Tvector3__double):Tvector3__double

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  *(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.



                64.3.234           multiply(Tvector3__extended,extended):Tvector3__extended

    Synopsis:    Multiply a three-dimensional extended precision vector by a scalar

Declaration:     operator  *(const  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.



                                                                                1004

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.235           multiply(Tvector3__extended,Tvector3__extended):Tvector3__extended

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  *(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.



                64.3.236           multiply(Tvector3__single,single):Tvector3__single

    Synopsis:    Multiply a three-dimensional single precision vector by a scalar

Declaration:     operator  *(const  x:  Tvector3_single;y:  single)  :  Tvector3_single

    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.



                64.3.237           multiply(Tvector3__single,Tvector3__single):Tvector3__single

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  *(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.



                64.3.238           multiply(Tvector4__double,Double):Tvector4__double

    Synopsis:    Multiply a four-dimensional double precision vector by a scalar

Declaration:     operator  *(const  x:  Tvector4_double;y:  Double)  :  Tvector4_double

    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.



                64.3.239           multiply(Tvector4__double,Tvector4__double):Tvector4__double

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  *(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.



                                                                                1005

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.240           multiply(Tvector4__extended,extended):Tvector4__extended

    Synopsis:    Multiply a four-dimensional extended precision vector by a scalar

Declaration:     operator  *(const  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.



                64.3.241           multiply(Tvector4__extended,Tvector4__extended):Tvector4__extended

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  *(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.



                64.3.242           multiply(Tvector4__single,single):Tvector4__single

    Synopsis:    Multiply a four-dimensional single precision vector by a scalar

Declaration:     operator  *(const  x:  Tvector4_single;y:  single)  :  Tvector4_single

    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.



                64.3.243           multiply(Tvector4__single,Tvector4__single):Tvector4__single

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  *(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.



                64.3.244           negative(Tmatrix2__double):Tmatrix2__double

    Synopsis:    Negate two-dimensional double precision matrix.

Declaration:     operator  -(const  m1:  Tmatrix2_double)  :  Tmatrix2_double

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                                                                                1006

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.245           negative(Tmatrix2__extended):Tmatrix2__extended

    Synopsis:    Negate two-dimensional extended precision matrix.

Declaration:     operator  -(const  m1:  Tmatrix2_extended)  :  Tmatrix2_extended

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                64.3.246           negative(Tmatrix2__single):Tmatrix2__single

    Synopsis:    Negate two-dimensional single precision matrix.

Declaration:     operator  -(const  m1:  Tmatrix2_single)  :  Tmatrix2_single

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                64.3.247           negative(Tmatrix3__double):Tmatrix3__double

    Synopsis:    Negate three-dimensional double precision matrix.

Declaration:     operator  -(const  m1:  Tmatrix3_double)  :  Tmatrix3_double

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                64.3.248           negative(Tmatrix3__extended):Tmatrix3__extended

    Synopsis:    Negate three-dimensional extended precision matrix.

Declaration:     operator  -(const  m1:  Tmatrix3_extended)  :  Tmatrix3_extended

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                64.3.249           negative(Tmatrix3__single):Tmatrix3__single

    Synopsis:    Negate three-dimensional single precision matrix.

Declaration:     operator  -(const  m1:  Tmatrix3_single)  :  Tmatrix3_single

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                64.3.250           negative(Tmatrix4__double):Tmatrix4__double

    Synopsis:    Negate four-dimensional double precision matrix.

Declaration:     operator  -(const  m1:  Tmatrix4_double)  :  Tmatrix4_double

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                                                                                1007

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.251           negative(Tmatrix4__extended):Tmatrix4__extended

    Synopsis:    Negate four-dimensional extended precision matrix.

Declaration:     operator  -(const  m1:  Tmatrix4_extended)  :  Tmatrix4_extended

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                64.3.252           negative(Tmatrix4__single):Tmatrix4__single

    Synopsis:    Negate four-dimensional single precision matrix.

Declaration:     operator  -(const  m1:  Tmatrix4_single)  :  Tmatrix4_single

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                64.3.253           negative(Tvector2__double):Tvector2__double

    Synopsis:    Negate two-dimensional vector.

Declaration:     operator  -(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.



                64.3.254           negative(Tvector2__extended):Tvector2__extended

    Synopsis:    Negate two-dimensional vector.

Declaration:     operator  -(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.



                64.3.255           negative(Tvector2__single):Tvector2__single

    Synopsis:    Negate two-dimensional vector.

Declaration:     operator  -(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.



                                                                                1008

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.256           negative(Tvector3__double):Tvector3__double

    Synopsis:    Negate three-dimensional vector.

Declaration:     operator  -(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.



                64.3.257           negative(Tvector3__extended):Tvector3__extended

    Synopsis:    Negate three-dimensional vector.

Declaration:     operator  -(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.



                64.3.258           negative(Tvector3__single):Tvector3__single

    Synopsis:    Negate three-dimensional vector.

Declaration:     operator  -(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.



                64.3.259           negative(Tvector4__double):Tvector4__double

    Synopsis:    Negate four-dimensional vector.

Declaration:     operator  -(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.



                64.3.260           negative(Tvector4__extended):Tvector4__extended

    Synopsis:    Negate four-dimensional vector.

Declaration:     operator  -(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.



                                                                                1009

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.261           negative(Tvector4__single):Tvector4__single

    Synopsis:    Negate four-dimensional vector.

Declaration:     operator  -(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.



                64.3.262           power(Tvector2__double,Tvector2__double):Double

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  **(const  x:  Tvector2_double;const  y:  Tvector2_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.



                64.3.263           power(Tvector2__extended,Tvector2__extended):extended

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  **(const  x:  Tvector2_extended;const  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.



                64.3.264           power(Tvector2__single,Tvector2__single):single

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  **(const  x:  Tvector2_single;const  y:  Tvector2_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.



                64.3.265           power(Tvector3__double,Tvector3__double):Double

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  **(const  x:  Tvector3_double;const  y:  Tvector3_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.



                                                                                1010

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.266           power(Tvector3__extended,Tvector3__extended):extended

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  **(const  x:  Tvector3_extended;const  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.



                64.3.267           power(Tvector3__single,Tvector3__single):single

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  **(const  x:  Tvector3_single;const  y:  Tvector3_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.



                64.3.268           power(Tvector4__double,Tvector4__double):Double

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  **(const  x:  Tvector4_double;const  y:  Tvector4_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.



                64.3.269           power(Tvector4__extended,Tvector4__extended):extended

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  **(const  x:  Tvector4_extended;const  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.



                64.3.270           power(Tvector4__single,Tvector4__single):single

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  **(const  x:  Tvector4_single;const  y:  Tvector4_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.



                                                                                1011

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.271           subtract(Tmatrix2__double,Double):Tmatrix2__double

    Synopsis:    Subtract scalar to two-dimensional double precision matrix

Declaration:     operator  -(const  m:  Tmatrix2_double;const  x:  Double)  :  Tmatrix2_double

    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.



                64.3.272           subtract(Tmatrix2__double,Tmatrix2__double):Tmatrix2__double

    Synopsis:    Subtract a two-dimensional double precision matrix from another.

Declaration:     operator  -(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.



                64.3.273           subtract(Tmatrix2__extended,extended):Tmatrix2__extended

    Synopsis:    Add scalar to two-dimensional extended precision matrix

Declaration:     operator  -(const  m:  Tmatrix2_extended;const  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.



                64.3.274           subtract(Tmatrix2__extended,Tmatrix2__extended):Tmatrix2__extended

    Synopsis:    Subtract a two-dimensional extended precision matrix from another.

Declaration:     operator  -(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.



                64.3.275           subtract(Tmatrix2__single,single):Tmatrix2__single

    Synopsis:    Subtract scalar to two-dimensional single precision matrix

Declaration:     operator  -(const  m:  Tmatrix2_single;const  x:  single)  :  Tmatrix2_single

    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.



                                                                                1012

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.276           subtract(Tmatrix2__single,Tmatrix2__single):Tmatrix2__single

    Synopsis:    Subtract a two-dimensional single precision matrix from another.

Declaration:     operator  -(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.



                64.3.277           subtract(Tmatrix3__double,Double):Tmatrix3__double

    Synopsis:    Add scalar to three-dimensional double precision matrix

Declaration:     operator  -(const  m:  Tmatrix3_double;const  x:  Double)  :  Tmatrix3_double

    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.



                64.3.278           subtract(Tmatrix3__double,Tmatrix3__double):Tmatrix3__double

    Synopsis:    Subtract a three-dimensional double precision matrix from another.

Declaration:     operator  -(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.



                64.3.279           subtract(Tmatrix3__extended,extended):Tmatrix3__extended

    Synopsis:    Add scalar to three-dimensional extended precision matrix

Declaration:     operator  -(const  m:  Tmatrix3_extended;const  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.



                64.3.280           subtract(Tmatrix3__extended,Tmatrix3__extended):Tmatrix3__extended

    Synopsis:    Subtract a three-dimensional extended precision matrix from another.

Declaration:     operator  -(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.



                                                                                1013

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.281           subtract(Tmatrix3__single,single):Tmatrix3__single

    Synopsis:    Add scalar to three-dimensional single precision matrix

Declaration:     operator  -(const  m:  Tmatrix3_single;const  x:  single)  :  Tmatrix3_single

    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.



                64.3.282           subtract(Tmatrix3__single,Tmatrix3__single):Tmatrix3__single

    Synopsis:    Subtract a three-dimensional single precision matrix from another.

Declaration:     operator  -(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.



                64.3.283           subtract(Tmatrix4__double,Double):Tmatrix4__double

    Synopsis:    Add scalar to four-dimensional double precision matrix

Declaration:     operator  -(const  m:  Tmatrix4_double;const  x:  Double)  :  Tmatrix4_double

    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.



                64.3.284           subtract(Tmatrix4__double,Tmatrix4__double):Tmatrix4__double

    Synopsis:    Subtract a four-dimensional double precision matrix from another.

Declaration:     operator  -(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.



                64.3.285           subtract(Tmatrix4__extended,extended):Tmatrix4__extended

    Synopsis:    Add scalar to four-dimensional extended precision matrix

Declaration:     operator  -(const  m:  Tmatrix4_extended;const  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.



                                                                                1014

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.286           subtract(Tmatrix4__extended,Tmatrix4__extended):Tmatrix4__extended

    Synopsis:    Subtract a four-dimensional extended precision matrix from another.

Declaration:     operator  -(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.



                64.3.287           subtract(Tmatrix4__single,single):Tmatrix4__single

    Synopsis:    Add scalar to four-dimensional single precision matrix

Declaration:     operator  -(const  m:  Tmatrix4_single;const  x:  single)  :  Tmatrix4_single

    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.



                64.3.288           subtract(Tmatrix4__single,Tmatrix4__single):Tmatrix4__single

    Synopsis:    Subtract a four-dimensional single precision matrix from another.

Declaration:     operator  -(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.



                64.3.289           subtract(Tvector2__double,Double):Tvector2__double

    Synopsis:    Subtract scalar from two-dimensional double precision vector

Declaration:     operator  -(const  x:  Tvector2_double;y:  Double)  :  Tvector2_double

    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.



                64.3.290           subtract(Tvector2__double,Tvector2__double):Tvector2__double

    Synopsis:    Subtract two-dimensional double precision vectors from each other

Declaration:     operator  -(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.



                                                                                1015

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.291           subtract(Tvector2__extended,extended):Tvector2__extended

    Synopsis:    Subtract scalar from two-dimensional extended precision vector

Declaration:     operator  -(const  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.



                64.3.292           subtract(Tvector2__extended,Tvector2__extended):Tvector2__extended

    Synopsis:    Subtract two-dimensional extended precision vectors from each other

Declaration:     operator  -(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.



                64.3.293           subtract(Tvector2__single,single):Tvector2__single

    Synopsis:    Subtract scalar from two-dimensional single precision vector

Declaration:     operator  -(const  x:  Tvector2_single;y:  single)  :  Tvector2_single

    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.



                64.3.294           subtract(Tvector2__single,Tvector2__single):Tvector2__single

    Synopsis:    Subtract two-dimensional single precision vectors from each other

Declaration:     operator  -(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.



                64.3.295           subtract(Tvector3__double,Double):Tvector3__double

    Synopsis:    Subtract scalar from three-dimensional double precision vector

Declaration:     operator  -(const  x:  Tvector3_double;y:  Double)  :  Tvector3_double

    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.



                                                                                1016

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.296           subtract(Tvector3__double,Tvector3__double):Tvector3__double

    Synopsis:    Subtract three-dimensional double precision vectors from each other

Declaration:     operator  -(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.



                64.3.297           subtract(Tvector3__extended,extended):Tvector3__extended

    Synopsis:    Subtract scalar from three-dimensional extended precision vector

Declaration:     operator  -(const  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.



                64.3.298           subtract(Tvector3__extended,Tvector3__extended):Tvector3__extended

    Synopsis:    Subtract three-dimensional extended precision vectors from each other

Declaration:     operator  -(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.



                64.3.299           subtract(Tvector3__single,single):Tvector3__single

    Synopsis:    Subtract scalar from three-dimensional single precision vector

Declaration:     operator  -(const  x:  Tvector3_single;y:  single)  :  Tvector3_single

    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.



                64.3.300           subtract(Tvector3__single,Tvector3__single):Tvector3__single

    Synopsis:    Subtract three-dimensional single precision vectors from each other

Declaration:     operator  -(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.



                                                                                1017

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.301           subtract(Tvector4__double,Double):Tvector4__double

    Synopsis:    Subtract scalar from four-dimensional double precision vector

Declaration:     operator  -(const  x:  Tvector4_double;y:  Double)  :  Tvector4_double

    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.



                64.3.302           subtract(Tvector4__double,Tvector4__double):Tvector4__double

    Synopsis:    Subtract four-dimensional double precision vectors from each other

Declaration:     operator  -(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.



                64.3.303           subtract(Tvector4__extended,extended):Tvector4__extended

    Synopsis:    Subtract scalar from four-dimensional extended precision vector

Declaration:     operator  -(const  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.



                64.3.304           subtract(Tvector4__extended,Tvector4__extended):Tvector4__extended

    Synopsis:    Subtract four-dimensional extended precision vectors from each other

Declaration:     operator  -(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.



                64.3.305           subtract(Tvector4__single,single):Tvector4__single

    Synopsis:    Subtract scalar from four-dimensional single precision vector

Declaration:     operator  -(const  x:  Tvector4_single;y:  single)  :  Tvector4_single

    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.



                                                                                1018

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.3.306           subtract(Tvector4__single,Tvector4__single):Tvector4__single

    Synopsis:    Subtract four-dimensional single precision vectors from each other

Declaration:     operator  -(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.



                64.3.307           symmetricaldifference(Tvector3__double,Tvector3__double):Tvector3__double

    Synopsis:    Calculate the external product of two three-dimensional vectors

Declaration:     operator  ><(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.



                64.3.308           symmetricaldifference(Tvector3__extended,Tvector3__extended):Tvector3__extended

    Synopsis:    Calculate the external product of two three-dimensional vectors

Declaration:     operator  ><(const  x:  Tvector3_extended;const  y:  Tvector3_extended)
                                    :  Tvector3_extended

    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.



                64.3.309           symmetricaldifference(Tvector3__single,Tvector3__single):Tvector3__single

    Synopsis:    Calculate the external product of two three-dimensional vectors

Declaration:     operator  ><(const  x:  Tvector3_single;const  y:  Tvector3_single)
                                    :  Tvector3_single

    Visibility:   default



                                                                                1019

                __________________________________________________________CHAPTER_64.___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.



                64.4          Tmatrix2 __double



                64.4.1         Description

                The Tmatrix2_double object provides a matrix of 2*2 double precision scalars.



                64.4.2         Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  1021      determinant           Calculates the determinant of the matrix.
                  1021      get\_column           Returns the c-th column of the matrix as vector.
                  1021      get\_row              Returns the r-th row of the matrix as vector.
                  1020      init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  1020      init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  1020      init\_zero            Initializes the matrix and sets its elements to zero
                  1022      inverse               Calculates the inverse of the matrix.
                  1021      set\_column           Sets c-th column of the matrix with a vector.
                  1021      set\_row              Sets r-th row of the matrix with a vector.
                __1022______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                64.4.3         Tmatrix2__double.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.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.



                64.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)



                                                                                1020

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



    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.



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                                                                                1021

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.5          Tmatrix2 __extended



                64.5.1         Description

                The Tmatrix2_extended object provides a matrix of 2*2 extended precision scalars.



                64.5.2         Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  1024      determinant           Calculates the determinant of the matrix.
                  1023      get\_column           Returns the c-th column of the matrix as vector.
                  1023      get\_row              Returns the r-th row of the matrix as vector.
                  1023      init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  1023      init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  1022      init\_zero            Initializes the matrix and sets its elements to zero
                  1024      inverse               Calculates the inverse of the matrix.
                  1023      set\_column           Sets c-th column of the matrix with a vector.
                  1023      set\_row              Sets r-th row of the matrix with a vector.
                __1024______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                64.5.3         Tmatrix2__extended.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                                                                                1022

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                                                                                1023

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.6          Tmatrix2 __single



                64.6.1         Description

                The Tmatrix2_single object provides a matrix of 2*2 single precision scalars.



                64.6.2         Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  1026      determinant           Calculates the determinant of the matrix.
                  1025      get\_column           Returns the c-th column of the matrix as vector.
                  1025      get\_row              Returns the r-th row of the matrix as vector.
                  1025      init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  1025      init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  1025      init\_zero            Initializes the matrix and sets its elements to zero
                  1026      inverse               Calculates the inverse of the matrix.
                  1025      set\_column           Sets c-th column of the matrix with a vector.
                  1026      set\_row              Sets r-th row of the matrix with a vector.
                __1026______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                                                                                1024

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.6.3         Tmatrix2__single.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                                                                                1025

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.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.



                64.7          Tmatrix3 __double



                64.7.1         Description

                The Tmatrix3_double object provides a matrix of 3*3 double precision scalars.



                                                                                1026

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.7.2         Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  1028      determinant           Calculates the determinant of the matrix.
                  1027      get\_column           Returns the c-th column of the matrix as vector.
                  1028      get\_row              Returns the r-th row of the matrix as vector.
                  1027      init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  1027      init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  1027      init\_zero            Initializes the matrix and sets its elements to zero
                  1028      inverse               Calculates the inverse of the matrix.
                  1028      set\_column           Sets c-th column of the matrix with a vector.
                  1028      set\_row              Sets r-th row of the matrix with a vector.
                __1028______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                64.7.3         Tmatrix3__double.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.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.



                64.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.



                64.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.



                                                                                1027

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                                                                                1028

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.8          Tmatrix3 __extended



                64.8.1         Description

                The Tmatrix3_extended object provides a matrix of 3*3 extended precision scalars.



                64.8.2         Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  1030      determinant           Calculates the determinant of the matrix.
                  1030      get\_column           Returns the c-th column of the matrix as vector.
                  1030      get\_row              Returns the r-th row of the matrix as vector.
                  1029      init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  1029      init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  1029      init\_zero            Initializes the matrix and sets its elements to zero
                  1030      inverse               Calculates the inverse of the matrix.
                  1030      set\_column           Sets r-th column of the matrix with a vector.
                  1030      set\_row              Sets r-th row of the matrix with a vector.
                __1031______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                64.8.3         Tmatrix3__extended.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.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.



                64.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.



                                                                                1029

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                                                                                1030

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.9          Tmatrix3 __single



                64.9.1         Description

                The Tmatrix3_single object provides a matrix of 3*3 single precision scalars.



                64.9.2         Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  1032      determinant           Calculates the determinant of the matrix.
                  1032      get\_column           Returns the c-th column of the matrix as vector.
                  1032      get\_row              Returns the r-th row of the matrix as vector.
                  1032      init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  1031      init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  1031      init\_zero            Initializes the matrix and sets its elements to zero
                  1033      inverse               Calculates the inverse of the matrix.
                  1032      set\_column           Sets c-th column of the matrix with a vector.
                  1032      set\_row              Sets r-th row of the matrix with a vector.
                __1033______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                64.9.3         Tmatrix3__single.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.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.



                                                                                1031

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                                                                                1032

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.10            Tmatrix4 __double



                64.10.1          Description

                The Tmatrix4_double object provides a matrix of 4*4 double precision scalars.



                64.10.2          Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  1035      determinant           Calculates the determinant of the matrix.
                  1034      get\_column           Returns the c-th column of the matrix as vector.
                  1034      get\_row              Returns the r-th row of the matrix as vector.
                  1034      init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  1034      init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  1033      init\_zero            Initializes the matrix and sets its elements to zero
                  1035      inverse               Calculates the inverse of the matrix.
                  1034      set\_column           Sets c-th column of the matrix with a vector.
                  1035      set\_row              Sets r-th row of the matrix with a vector.
                __1035______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                64.10.3          Tmatrix4__double.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                                                                                1033

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                                                                                1034

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.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.



                64.11            Tmatrix4 __extended



                64.11.1          Description

                The Tmatrix4_extended object provides a matrix of 4*4 extended precision scalars.



                                                                                1035

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.11.2          Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  1037      determinant           Calculates the determinant of the matrix.
                  1036      get\_column           Returns the c-th column of the matrix as vector.
                  1037      get\_row              Returns the r-th row of the matrix as vector.
                  1036      init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  1036      init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  1036      init\_zero            Initializes the matrix and sets its elements to zero
                  1037      inverse               Calculates the inverse of the matrix.
                  1037      set\_column           Sets c-th column of the matrix with a vector.
                  1037      set\_row              Sets r-th row of the matrix with a vector.
                __1038______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                64.11.3          Tmatrix4__extended.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.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.



                64.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.



                64.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.



                                                                                1036

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                                                                                1037

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.12            Tmatrix4 __single



                64.12.1          Description

                The Tmatrix4_single object provides a matrix of 4*4 single precision scalars.



                64.12.2          Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                  1040      determinant           Calculates the determinant of the matrix.
                  1039      get\_column           Returns the c-th column of the matrix as vector.
                  1039      get\_row              Returns the r-th row of the matrix as vector.
                  1039      init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  1038      init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  1038      init\_zero            Initializes the matrix and sets its elements to zero
                  1040      inverse               Calculates the inverse of the matrix.
                  1039      set\_column           Sets c-th column of the matrix with a vector.
                  1039      set\_row              Sets r-th row of the matrix with a vector.
                __1040______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                64.12.3          Tmatrix4__single.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.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.



                                                                                1038

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.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.



                64.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.



                                                                                1039

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.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.



                64.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.



                64.13            Tvector2 __double



                64.13.1          Description

                The Tvector2_double object provides a vector of two double precision scalars.



                64.13.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  1041      init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  1041      init\_one                 Initializes the vector and sets its elements to one
                  1040      init\_zero                Initializes the vector and sets its elements to zero
                  1041      length                    Calculates the length of the vector.
                __1041______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                64.13.3          Tvector2__double.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                                                                                1040

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.13.4          Tvector2__double.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                64.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



                64.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
                (1041   ) if you are able to, as it is faster.



                64.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.



                64.14            Tvector2 __extended



                64.14.1          Description

                The Tvector2_extended object provides a vector of two extended precision scalars.



                64.14.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  1042      init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  1042      init\_one                 Initializes the vector and sets its elements to one
                  1042      init\_zero                Initializes the vector and sets its elements to zero
                  1042      length                    Calculates the length of the vector.
                __1042______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                                                                                1041

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.14.3          Tvector2__extended.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.14.4          Tvector2__extended.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                64.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



                64.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
                (1042   ) if you are able to, as it is faster.



                64.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.



                64.15            Tvector2 __single



                64.15.1          Description

                The Tvector2_single object provides a vector of two single precision scalars.



                                                                                1042

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.15.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  1043      init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  1043      init\_one                 Initializes the vector and sets its elements to one
                  1043      init\_zero                Initializes the vector and sets its elements to zero
                  1043      length                    Calculates the length of the vector.
                __1043______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                64.15.3          Tvector2__single.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.15.4          Tvector2__single.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                64.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



                64.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
                (1043   ) if you are able to, as it is faster.



                64.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.



                                                                                1043

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.16            Tvector3 __double



                64.16.1          Description

                The Tvector3_double object provides a vector of three double precision scalars.



                64.16.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  1044      init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  1044      init\_one                 Initializes the vector and sets its elements to one
                  1044      init\_zero                Initializes the vector and sets its elements to zero
                  1044      length                    Calculates the length of the vector.
                __1045______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                64.16.3          Tvector3__double.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.16.4          Tvector3__double.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                64.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



                64.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 (1045   ) if you are able to, as it is faster.



                                                                                1044

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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.



                64.17            Tvector3 __extended



                64.17.1          Description

                The Tvector3_extended object provides a vector of three extended precision scalars.



                64.17.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  1045      init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  1045      init\_one                 Initializes the vector and sets its elements to one
                  1045      init\_zero                Initializes the vector and sets its elements to zero
                  1046      length                    Calculates the length of the vector.
                __1046______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                64.17.3          Tvector3__extended.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.17.4          Tvector3__extended.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                64.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



                                                                                1045

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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 (1046   ) if you are able to, as it is faster.



                64.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.



                64.18            Tvector3 __single



                64.18.1          Description

                The Tvector3_single object provides a vector of three single precision scalars.



                64.18.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  1047      init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  1046      init\_one                 Initializes the vector and sets its elements to one
                  1046      init\_zero                Initializes the vector and sets its elements to zero
                  1047      length                    Calculates the length of the vector.
                __1047______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                64.18.3          Tvector3__single.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.18.4          Tvector3__single.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                                                                                1046

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.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



                64.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 (1047   ) if you are able to, as it is faster.



                64.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.



                64.19            Tvector4 __double



                64.19.1          Description

                The Tvector4_double object provides a vector of four double precision scalars.



                64.19.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  1048      init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  1048      init\_one                 Initializes the vector and sets its elements to one
                  1047      init\_zero                Initializes the vector and sets its elements to zero
                  1048      length                    Calculates the length of the vector.
                __1048______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                64.19.3          Tvector4__double.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                                                                                1047

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.19.4          Tvector4__double.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                64.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



                64.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 (1048   ) if you are able to, as it is faster.



                64.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.



                64.20            Tvector4 __extended



                64.20.1          Description

                The Tvector4_extended object provides a vector of four extended precision scalars.



                64.20.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  1049      init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  1049      init\_one                 Initializes the vector and sets its elements to one
                  1049      init\_zero                Initializes the vector and sets its elements to zero
                  1049      length                    Calculates the length of the vector.
                __1049______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                                                                                1048

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.20.3          Tvector4__extended.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.20.4          Tvector4__extended.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                64.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



                64.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 (1049   ) if you are able to, as it is faster.



                64.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.



                64.21            Tvector4 __single



                64.21.1          Description

                The Tvector4_single object provides a vector of four single precision scalars.



                                                                                1049

                __________________________________________________________CHAPTER_64.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                64.21.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                  1050      init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  1050      init\_one                 Initializes the vector and sets its elements to one
                  1050      init\_zero                Initializes the vector and sets its elements to zero
                  1050      length                    Calculates the length of the vector.
                __1050______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                64.21.3          Tvector4__single.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                64.21.4          Tvector4__single.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                64.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



                64.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 (1050   ) if you are able to, as it is faster.



                64.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.



                                                                                1050




Chapter   65



Reference   for   unit   'mmx'



65.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.



65.2          Constants,  types  and  variables



65.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.



                                                            1051

_______________________________________________________________CHAPTER_65.___REFERENCE_FOR_UNIT_'MMX'______________________________*
 *___



65.2.2         Types

pmmxbyte  =  ^tmmxbyte


Pointer to tmmxbyte (1052   ) array type


pmmxcardinal  =  ^tmmxcardinal


Pointer to tmmxcardinal (1052   ) array type


pmmxinteger  =  ^tmmxinteger


Pointer to tmmxinteger (1052   ) array type


pmmxlongint  =  ^tmmxlongint


Pointer to tmmxlongint (1052   ) array type


pmmxshortint  =  ^tmmxshortint


Pointer to tmmxshortint (1052   ) array type


pmmxsingle  =  ^tmmxsingle


Pointer to tmmxsingle (1052   ) array type


pmmxword  =  ^tmmxword


Pointer to tmmxword (1052   ) 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



                                                                1052

                _______________________________________________________________CHAPTER_65.___REFERENCE_FOR_UNIT_'MMX'______________*
 *___________________



                65.3          Procedures  and  functions



                65.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 (1053   )



                65.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 (1053   )



                                                                                1053




Chapter   66



Reference   for   unit   'Mouse'



66.1          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.



66.2          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.

Listing:  ./mouseex/logmouse.pp
______________________________________________________________________________________________________________________________
 u n i t l o g m o u s e;


 i n t e r f a c e


 P r o c e d u r eS t a r t M o u s e L o g g i n;g
 P r o c e d u r eS t o p M o u s e L o g g i n;g
 F u n c t i o n  I s M o u s e L o g g i n g:  B o o l e a n;
 P r o c e d u r eS e t M o u s e L o g F i l e N a(mFei l e N a m e :  S t r i n g) ;



 i m p l e m e n t a t i o n


 u s e s s y s u t i l s,Mouse    ;


 v a r
    NewMouseDriver           ,
    O l d M o u s e D r i v e r:  T M o u s e D r i v e;r
    A c t i v e,L o g g i n g :   B o o l e a n;
    L o g F i l e N a m e:   S t r i n g;



                                                            1054

___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'________________________________*
 *___



    MouseLog        :  T e x t;


 F u n c t i o nTimeStamp         :  S t r i n g;


 b e g i n
    TimeStamp       := FormatDateTime           ( 'hh  :nn  : s s' ,Time    ( ) ) ;
end   ;


 P r o c e d u r eS t a r t M o u s e L o g g i n;g


 b e g i n
    L o g g i n g:= True   ;
    W r i t e l n(MouseLog      , ' S t a r t l o g g i n g mouse     e v e n t s  a t:   ' ,TimeStamp       ) ;
end   ;


 P r o c e d u r eS t o p M o u s e L o g g i n;g


 b e g i n
    W r i t e l n(MouseLog      , 'S t o p  l o g g i n g mouse      e v e n t s a t:   ' ,TimeStamp       ) ;
    L o g g i n g:= F a l s e;
end   ;


 F u n c t i o nI s M o u s e L o g g i n g:  B o o l e a n;


 b e g i n
    I s M o u s e L o g g i n:g=L o g g i n g;
end   ;


 P r o c e d u r eL o g G e t M o u s e E v e n(tVar   E v e n t :  TMouseEvent         ) ;


Var
   M    :  TMouseEvent        ;


 b e g i n
    O l d M o u s e D r i v e.rG e t M o u s e E v e n(tM) ;
    I f  L o g g i n g then
        b e g i n
       Write    ( MouseLog      , TimeStamp       ,' :  Mouse      ' ) ;
       With     M   do
           b e g i n
           Case     A c t i o n o f
              MouseActionDown              :  Write    (MouseLog      , ' down   ' ) ;
              MouseActionUp                :  Write    (MouseLog      , ' up  ') ;
              MouseActionMove              :  Write    (MouseLog      , ' move   ' ) ;
           end  ;
           Write    (MouseLog       ,'   e v e n t a t   ',X  , ', ' ,Y ) ;
           I f  ( B u t t o n s<>0)    then
              b e g i n
              Write    ( MouseLog      , '  f o r  b u t t o n s:  ' ) ;
               I f  (B u t t o n s and    M o u s e L e f t b u t t o)n<>0   then
                  Write    (MouseLog       ,' L e f t  ' ) ;
               I f  (B u t t o n s and    M o u s e R i g h t b u t t o)n<>0   then
                  Write    (MouseLog       ,' R i g h t  ') ;
               I f  (B u t t o n s and    M o u s e M i d d l e b u t t o)n<>0   then
                  Write    (MouseLog       ,' M i d d l e ' ) ;
              end   ;
           W r i t e l n(MouseLog      ) ;
           end  ;



                                                                1055

___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'________________________________*
 *___



       end   ;
end   ;


 P r o c e d u r eL o g I n i t M o u s;e


 b e g i n
    O l d M o u s e D r i v e.rI n i t D r i v e(r) ;
    A s s i g n(MouseLog      , l o g F i l e N a m)e;
    R e w r i t e(MouseLog      ) ;
    A c t i v e:= True   ;
    S t a r t M o u s e L o g g i n;g
end   ;


 P r o c e d u r eLogDoneMouse         ;


 b e g i n
    S t o p M o u s e L o g g i n;g
    C l o s e(MouseLog       ) ;
    A c t i v e:= F a l s e;
    O l d M o u s e D r i v e.rD o n e D r i v e(r) ;
end   ;


 P r o c e d u r eS e t M o u s e L o g F i l e N a(mFei l e N a m e :  S t r i n g) ;


 b e g i n
    I f  Not    A c t i v e then
       L o g F i l e N a m e:=F i l e N a m e;
end   ;


 I n i t i a l i z a t i o n
    G e t M o u s e D r i v e(rO l d M o u s e D r i v e)r;
    N e w M o u s e D r i v e:r=O l d M o u s e D r i v e;r
    N e w M o u s e D r i v e.rG e t M o u s e E v e n:t=@LogGetMouseEvent            ;
    N e w M o u s e D r i v e.rI n i t D r i v e:r=@ L o g I n i t M o u s;e
    N e w M o u s e D r i v e.rD o n e D r i v e:r=@LogDoneMouse          ;
    L o g F i l e N a m:e= 'Mouse    . l o g' ;
    L o g g i n g:= F a l s e;
    S e t M o u s e D r i v e(rN e w M o u s e D r i v e)r;
end___._______________________________________________________________________________________________________________________



66.3          Constants,  types  and  variables



66.3.1         Constants

errMouseBase  =  1030


Base for mouse error codes.


errMouseInitError  =  errMouseBase  +  0


Mouse initialization error


errMouseNotImplemented  =  errMouseBase  +  1


Mouse driver not implemented.



                                                                1056

___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'________________________________*
 *___



MouseActionDown  =  $0001


Mouse button down event signal.


MouseActionMove  =  $0004


Mouse cursor move event signal.


MouseActionUp  =  $0002


Mouse button up event signal.


MouseButton4  =  $08


4th mouse button event


MouseButton5  =  $10


5th mouse button event


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.



66.3.2         Types

PMouseEvent  =  ^TMouseEvent


Pointer to TMouseEvent (1058   ) record.


TMouseDriver  =  record
    UseDefaultQueue  :  Boolean;
    InitDriver  :  procedure;
    DoneDriver  :  procedure;
    DetectMouse  :  function  :  Byte;
    ShowMouse  :  procedure;
    HideMouse  :  procedure;
    GetMouseX  :  function  :  Word;



                                                                1057

            ___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'____________________*
 *_______________



               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 (1064   )
            function.  Its fields must be filled in before calling the SetMouseDriver (1064   ) function.


            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.



            66.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.



            66.4          Procedures  and  functions



            66.4.1         DetectMouse

Synopsis:    Detect the presence of a mouse.



                                                                            1058

                ___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'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 (1063   ), DoneMouse (1059   )


                Listing:  ./mouseex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                66.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 (1058   ), InitMouse (1063   )



                                                                                1059

                ___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



                66.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 (1061   ), GetMouseX (1061   ), GetMouseY (1062   )


                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___.____________________________________________________________________________________________________________*
 *___________



                66.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 (1054   ).

                For an example, see the section on writing a custom mouse driver, mousedrv (1054   )

       Errors:   None.

    See also:    SetMouseDriver (1064   )



                                                                                1060

                ___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



                66.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 (1063   ).

       Errors:   None.

    See also:    GetMouseButtons (1060   ), GetMouseX (1061   ), GetMouseY (1062   )



                66.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 (1060   ), GetMouseEvent (1061   ), GetMouseY (1062   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1061

                ___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



                66.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 (1061   )

       Errors:   None.

    See also:    GetMouseButtons (1060   ), GetMouseEvent (1061   ), GetMouseX (1061   )



                66.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 (1065   )


                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;



                                                                                1062

                ___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



                             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___.____________________________________________________________________________________________________________*
 *___________



                66.4.9         InitMouse

    Synopsis:    Initialize the FPC mouse driver.

Declaration:     procedure  InitMouse

    Visibility:   default

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  (1059   )  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 (1059   ), DetectMouse (1058   )



                66.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 (1061   ), PutMouseEvent (1063   )



                66.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
                (1061   ) or PollMouseEvent will then return MouseEvent.

                Please note that depending on the implementation the mouse event queue can hold only one
                value.



                                                                                1063

                ___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



       Errors:   None.

    See also:    GetMouseEvent (1061   ), PollMouseEvent (1063   )



                66.4.12          SetMouseDriver

    Synopsis:    Set a new mouse driver.

Declaration:     procedure  SetMouseDriver(const  Driver:  TMouseDriver)

    Visibility:   default

Description:     SetMouseDriver  sets  the  mouse  driver  to  Driver.  This  function  should  be  called  before
                InitMouse (1063   ) 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 (1054   ).

                For an example, see mousedrv (1054   )

    See also:    InitMouse (1063   ), DoneMouse (1059   ), GetMouseDriver (1060   )



                66.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 (1061   ), GetMouseY (1062   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1064

                ___________________________________________________________CHAPTER_66.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



                66.4.14          ShowMouse

    Synopsis:    Show the mouse cursor.

Declaration:     procedure  ShowMouse

    Visibility:   default

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 (1062   )

       Errors:   None.

    See also:    HideMouse (1062   )



                                                                                1065




Chapter   67



Reference   for   unit   'Ob jects'



67.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.



67.2          Constants,  types  and  variables



67.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  (Pointer)


Maximum collection size (in items)


MaxPtrs  =  MaxBytes  div  (Pointer)


Maximum data size (in pointers)



                                                            1066

________________________________________________________CHAPTER_67.___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  (Word)


Maximum data size (in words)


RCollection  :  TStreamRec  =  (ObjType:  50;  VmtLink:  (^(TCollection));  Load:  @TCollection  .  Load;  Store:  @TCollection  . *
 * Store;  Next:  Nil)


Default stream record for the TCollection (1083   ) object.


RStrCollection  :  TStreamRec  =  (ObjType:  69;  VmtLink:  (^(TStrCollection));  Load:  @TStrCollection  .  Load;  Store:  @TStrCo*
 *llection  .  Store;  Next:  Nil)


Default stream record for the TStrCollection (1122   ) object.


RStringCollection  :  TStreamRec  =  (ObjType:  51;  VmtLink:  (^(TStringCollection));  Load:  @TStringCollection  .  Load;  Store:*
 *  @TStringCollection  .  Store;  Next:  Nil)


Default stream record for the TStringCollection (1133   ) object.


RStringList  :  TStreamRec  =  (ObjType:  52;  VmtLink:  (^(TStringList));  Load:  @TStringList  .  Load;  Store:  Nil;  Next:  Nil)


Default stream record for the TStringList (1135   ) object.


RStrListMaker  :  TStreamRec  =  (ObjType:  52;  VmtLink:  (^(TStrListMaker));  Load:  Nil;  Store:  @TStrListMaker  .  Store;  Nex*
 *t:  Nil)


Default stream record for the TStrListMaker (1136   ) 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



                                                                1067

________________________________________________________CHAPTER_67.___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  :  CodePointer  =  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).



67.2.2         Types

AsciiZ  =  Array[0..255]  of  Char


Filename - null terminated array of characters.


FNameStr  =  String


Filename - shortstring version.



                                                                1068

________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___



LongRec  =  packed  record
   Hi  :  Word;
   Lo  :  Word;
end



Record describing a longint (in Words)


PBufStream  =  ^TBufStream


Pointer to TBufStream (1079   ) object.


PByteArray  =  ^TByteArray


Pointer to TByteArray (1071   )


PCharSet  =  ^TCharSet


Pointer to TCharSet (1071   ).


PCollection  =  ^TCollection


Pointer to TCollection (1083   ) object.


PDosStream  =  ^TDosStream


Pointer to TDosStream (1098   ) object.


PItemList  =  ^TItemList


Pointer to TItemList (1071   ) object.


PMemoryStream  =  ^TMemoryStream


Pointer to TMemoryStream (1102   ) object.


PObject  =  ^TObject


Pointer to TObject (1104   ) object.


PPoint  =  ^TPoint


Pointer to TPoint (1106   ) record.


PPointerArray  =  ^TPointerArray


Pointer to TPointerArray (1071   )


PRect  =  ^TRect


Pointer to TRect (1106   ) object.



                                                                1069

________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___



PResourceCollection  =  ^TResourceCollection


Pointer to TResourceCollection (1112   ) object.


PResourceFile  =  ^TResourceFile


Pointer to TResourceFile (1114   ) object.


PSortedCollection  =  ^TSortedCollection


Pointer to TSortedCollection (1117   ) object.


PStrCollection  =  ^TStrCollection


Pointer to TStrCollection (1122   ) object.


PStream  =  ^TStream


Pointer type to TStream (1124   )


PStreamRec  =  ^TStreamRec


Pointer to TStreamRec (1071   )


PStrIndex  =  ^TStrIndex


Pointer to TStrIndex (1071   ) array.


PString  =  PShortString


Pointer to a shortstring.


PStringCollection  =  ^TStringCollection


Pointer to TStringCollection (1133   ) object.


PStringList  =  ^TStringList


Pointer to TStringList (1135   ) object.


PStrListMaker  =  ^TStrListMaker


Pointer to TStrListMaker (1136   ) object.


PtrRec  =  packed  record
   Ofs  :  Word;
   Seg  :  Word;
end



Record describing a pointer to a memory location.



                                                                1070

________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___



PUnSortedStrCollection  =  ^TUnSortedStrCollection


Pointer to TUnSortedStrCollection (1138   ) object.


PWordArray  =  ^TWordArray


Pointer to TWordArray (1072   )


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 (1083   )


TPointerArray  =  Array[0..MaxPtrs-1]  of  Pointer


Array with maxmimum allowed number of pointers


TStreamRec  =  packed  record
   ObjType  :  Sw_Word;
   VmtLink  :  pointer;
   Load  :  CodePointer;
   Store  :  CodePointer;
   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 (1135   )



                                                                1071

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                TStrIndexRec  =  packed  record
                   Key  :  Sw_Word;
                   Count  :  Word;
                   Offset  :  Word;
                end



                Record type used in a TStringList (1135   ) 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)



                67.2.3         Variables

                invalidhandle  :  THandle


                Value for invalid handle.  Initial value for file stream handles or when the stream is closed.



                67.3          Procedures  and  functions



                67.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.



                67.3.2         CallPointerConstructor

    Synopsis:    Call a constructor with a pointer argument.

Declaration:     function  CallPointerConstructor(Ctor:  codepointer;Obj:  pointer;
                                                                   VMT:  pointer;Param1:  pointer)  :  pointer

    Visibility:   default



                                                                                1072

                ________________________________________________________CHAPTER_67.___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 (1074   ), CallPointerMethod (1073   ), CallVoidLocal (1074   ), CallPointer-
                Local (1073   ), CallVoidMethodLocal (1075   ), CallPointerMethodLocal (1073   )



                67.3.3         CallPointerLocal

    Synopsis:    Call a local nested function with a pointer argument

Declaration:     function  CallPointerLocal(Func:  codepointer;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 (1073   ), CallVoidMethod (1074   ), CallVoidLocal (1074   ), CallVoidMethod-
                Local (1075   ), CallPointerMethodLocal (1073   ), CallVoidConstructor (1074   ), CallPointerCon-
                structor (1072   )



                67.3.4         CallPointerMethod

    Synopsis:    Call a method with a single pointer argument

Declaration:     function  CallPointerMethod(Method:  codepointer;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 (1074   ),  CallVoidLocal (1074   ),  CallPointerLocal (1073   ),  CallVoidMethod-
                Local (1075   ), CallPointerMethodLocal (1073   ), CallVoidConstructor (1074   ), CallPointerCon-
                structor (1072   )



                67.3.5         CallPointerMethodLocal

    Synopsis:    Call a local procedure of a method with a pointer argument

Declaration:     function  CallPointerMethodLocal(Func:  codepointer;Frame:  Pointer;
                                                                   Obj:  pointer;Param1:  pointer)  :  pointer



                                                                                1073

                ________________________________________________________CHAPTER_67.___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 (1073   ), CallVoidMethod (1074   ), CallPointerLocal (1073   ), CallVoidLocal
                (1074   ),  CallVoidMethodLocal  (1075   ),  CallVoidConstructor  (1074   ),  CallPointerConstructor
                (1072   )



                67.3.6         CallVoidConstructor

    Synopsis:    Call a constructor with no arguments

Declaration:     function  CallVoidConstructor(Ctor:  codepointer;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 (1072   ), CallPointerMethod (1073   ), CallVoidLocal (1074   ), CallPoint-
                erLocal (1073   ), CallVoidMethodLocal (1075   ), CallPointerMethodLocal (1073   )



                67.3.7         CallVoidLocal

    Synopsis:    Call a local nested procedure.

Declaration:     function  CallVoidLocal(Func:  codepointer;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 (1073   ), CallVoidMethod (1074   ), CallPointerLocal (1073   ), CallVoidMethod-
                Local (1075   ), CallPointerMethodLocal (1073   ), CallVoidConstructor (1074   ), CallPointerCon-
                structor (1072   )



                67.3.8         CallVoidMethod

    Synopsis:    Call an object method

Declaration:     function  CallVoidMethod(Method:  codepointer;Obj:  pointer)  :  pointer

    Visibility:   default

Description:     CallVoidMethod calls the method with address Method for instance Obj.  It returns a pointer
                to the instance.



                                                                                1074

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   If the method expects parameters, the stack may become corrupted.

    See also:    CallPointerMethod (1073   ), CallVoidLocal (1074   ), CallPointerLocal (1073   ), CallVoidMethod-
                Local (1075   ), CallPointerMethodLocal (1073   ), CallVoidConstructor (1074   ), CallPointerCon-
                structor (1072   )



                67.3.9         CallVoidMethodLocal

    Synopsis:    Call a local procedure of a method

Declaration:     function  CallVoidMethodLocal(Func:  codepointer;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 (1073   ), CallVoidMethod (1074   ), CallPointerLocal (1073   ), CallVoidLocal
                (1074   ), CallPointerMethodLocal (1073   ), CallVoidConstructor (1074   ), CallPointerConstruc-
                tor (1072   )



                67.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 (1076   ).

       Errors:   None.

    See also:    NewStr (1076   ), SetStr (1078   )



                67.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 (1076   )



                                                                                1075

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1075   )



                67.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 (1075   ), SetStr (1078   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.3.14          RegisterObjects

    Synopsis:    Register standard objects.

Declaration:     procedure  RegisterObjects

    Visibility:   default



                                                                                1076

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



Description:     RegisterObjects registers the following objects for streaming:


                     1.TCollection, see TCollection (1083   ).

                     2.TStringCollection, see TStringCollection (1133   ).

                     3.TStrCollection, see TStrCollection (1122   ).


       Errors:   None.

    See also:    RegisterType (1077   )



                67.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     ) ;



                                                                                1077

            ________________________________________________________CHAPTER_67.___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___.________________________________________________________________________________________________________________*
 *_______



            67.3.16          SetStr

Synopsis:    Allocate a copy of a shortstring on the heap.



                                                                            1078

                ________________________________________________________CHAPTER_67.___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 (1076   ), 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 (1075   ), NewStr (1076   )



                67.4          TBufStream



                67.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.



                67.4.2         Method  overview

                __Page______Method___________Description___________________________________________________________________________*
 *___________
                  1080      Close            Flush data and Close the file.
                  1080      Done             Close the file and cleans up the instance.
                  1080      Flush            FLush data from buffer, and write it to stream.
                  1079      Init             Initialize an instance of  TBufStream and open the file.
                  1082      Open             Open the file if it is closed.
                  1082      Read             Read data from the file to a buffer in memory.
                  1081      Seek             Set current position in file.
                  1081      Truncate         Flush buffer, and truncate the file at current position.
                __1082______Write____________Write_data_to_the_file_from_a_buffer_in_memory._______________________________________*
 *___________



                67.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.



                                                                                1079

                ________________________________________________________CHAPTER_67.___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 (1080   ).

       Errors:   On error, Status is set to stInitError, and ErrorInfo is set to the dos error code.

    See also:    TDosStream.Init (1098   ), TBufStream.Done (1080   )



                67.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 (1080   ).

       Errors:   None.

    See also:    TDosStream.Done (1098   ), TBufStream.Init (1079   ), TBufStream.Close (1080   )



                67.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
                (1080   ) it does not clean up the instance of  TBufStream

                For an example see TBufStream.Flush (1080   ).

       Errors:   None.

    See also:    TStream.Close (1129   ), TBufStream.Init (1079   ), TBufStream.Done (1080   )



                67.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 (1082   ) for more info on the
                errors.



                                                                                1080

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



    See also:    TStream.Close (1129   ), TBufStream.Init (1079   ), TBufStream.Done (1080   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1099   ).

       Errors:   Errors can be those of Flush (1080   ) or TDosStream.Truncate (1099   ).

    See also:    TStream.Truncate (1130   ), TDosStream.Truncate (1099   ), TStream.GetSize (1127   )



                67.4.8         TBufStream.Seek

    Synopsis:    Set current position in file.

Declaration:     procedure  Seek(Pos:  LongInt);    Virtual



                                                                                1081

                ________________________________________________________CHAPTER_67.___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 (1131   );

       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 (1131   ), TStream.GetPos (1127   )



                67.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 (1080   ) call.

                For an example, see TDosStream.Open (1101   ).

       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 (1128   ), TBufStream.Close (1080   )



                67.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 (1131   ).

       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 (1131   ), TBufStream.Write (1082   )



                67.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



                                                                                1082

                ________________________________________________________CHAPTER_67.___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 (1131   ).

       Errors:   In  case  of  an  error,  Status  is  set  to  StWriteError,  and  ErrorInfo  gets  the  OS  specific
                error.

    See also:    TStream.Write (1132   ), TBufStream.Read (1082   )



                67.5          TCollection



                67.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.



                67.5.2         Method  overview

                __Page______Method____________Description__________________________________________________________________________*
 *___________
                  1085      At                Return the item at a certain index.
                  1094      AtDelete          Delete item at certain position.
                  1093      AtFree            Free an item at the indicates position, calling it's destructor.
                  1096      AtInsert          Insert an element at a certain position in the collection.
                  1096      AtPut             Set collection item, overwriting an existing value.
                  1092      Delete            Delete an item from the collection, but does not destroy it.
                  1090      DeleteAll         Delete all elements from the collection.  Objects are not destroyed.
                  1085      Done              Clean up collection, release all memory.
                  1095      Error             Set error code.
                  1088      FirstThat         Return first item which matches a test.
                  1094      ForEach           Execute procedure for each item in the list.
                  1091      Free              Free item from collection, calling it's destructor.
                  1089      FreeAll           Release all objects from the collection.
                  1093      FreeItem          Destroy a non-nil item.
                  1087      GetItem           Read one item off the stream.
                  1086      IndexOf           Find the position of a certain item.
                  1083      Init              Instantiate a new collection.
                  1092      Insert            Insert a new item in the collection at the end.
                  1087      LastThat          Return last item which matches a test.
                  1084      Load              Initialize a new collection and load collection from a stream.
                  1089      Pack              Remove all >Nil pointers from the collection.
                  1097      PutItem           Put one item on the stream
                  1095      SetLimit          Set maximum number of elements in the collection.
                __1097______Store_____________Write_collection_to_a_stream.________________________________________________________*
 *___________



                67.5.3         TCollection.Init

    Synopsis:    Instantiate a new collection.



                                                                                1083

                ________________________________________________________CHAPTER_67.___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 allocated in case ALimit is reached, and another element is added to the collection.

                For an example, see TCollection.ForEach (1094   ).

       Errors:   None.

    See also:    TCollection.Load (1084   ), TCollection.Done (1085   )



                67.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 (1087   ).

    See also:    TCollection.Init (1083   ), TCollection.GetItem (1087   ), TCollection.Done (1085   )


                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    ) ;



                                                                                1084

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1094   ).

       Errors:   None.

    See also:    TCollection.Init (1083   ), TCollection.FreeAll (1089   )



                67.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 (1092   )


                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 ) ;



                                                                                1085

                ________________________________________________________CHAPTER_67.___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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1085   ), TCollection.GetItem (1087   ), TCollection.Insert (1092   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1086

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1125   ).

    See also:    TStream.Get (1125   ), TCollection.Store (1097   )



                67.5.9         TCollection.LastThat

    Synopsis:    Return last item which matches a test.

Declaration:     function  LastThat(Test:  CodePointer)  :  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 (1088   )


                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   ;



                                                                                1087

                ________________________________________________________CHAPTER_67.___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___.____________________________________________________________________________________________________________*
 *___________



                67.5.10          TCollection.FirstThat

    Synopsis:    Return first item which matches a test.

Declaration:     function  FirstThat(Test:  CodePointer)  :  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 (1087   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1088

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1095   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.5.12          TCollection.FreeAll

    Synopsis:    Release all objects from the collection.

Declaration:     procedure  FreeAll

    Visibility:   default



                                                                                1089

                ________________________________________________________CHAPTER_67.___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.

    See also:    TCollection.DeleteAll (1090   ), TCollection.FreeItem (1093   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1089   ), DeletAll doesn't call the destructor of the objects.

       Errors:   None.

    See also:    TCollection.FreeAll (1089   ), TCollection.Delete (1092   )


                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.
                }


                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}



                                                                                1090

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1093   )


                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
                       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.' ) ;



                                                                                1091

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1096   ), TCollection.AtPut (1096   )



                67.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 (1091   ) call is provided.

       Errors:   If the Item is not in the collection, Error will be called with coIndexError.

    See also:    TCollection.AtDelete (1094   ), TCollection.Free (1091   )


                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
                       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') ;



                                                                                1092

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1095   ) is called with CoIndexError.

    See also:    TCollection.Free (1091   ), TCollection.AtDelete (1094   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.5.18          TCollection.FreeItem

    Synopsis:    Destroy a non-nil item.

Declaration:     procedure  FreeItem(Item:  Pointer);    Virtual

    Visibility:   default

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.



                                                                                1093

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   None.

    See also:    TCollection.Free (1091   ), TCollection.AtFree (1093   )



                67.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 (1095   ) is called with CoIndexError.

    See also:    TCollection.Delete (1092   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.5.20          TCollection.ForEach

    Synopsis:    Execute procedure for each item in the list.

Declaration:     procedure  ForEach(Action:  CodePointer)

    Visibility:   default

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.



                                                                                1094

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   None.

    See also:    TCollection.FirstThat (1088   ), TCollection.LastThat (1087   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1089   ).

       Errors:   None.

    See also:    TCollection.Init (1083   )



                67.5.22          TCollection.Error

    Synopsis:    Set error code.

Declaration:     procedure  Error(Code:  Integer;Info:  Integer);    Virtual



                                                                                1095

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



    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.

    See also:    Abstract (1072   )



                67.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 (1089   ).

       Errors:   If  Index isn't valid then Error (1095   ) is called with CoIndexError.



                67.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 (1095   ) is called with CoIndexError.  If the collection fails to
                expand, then coOverFlow is passd to Error.

    See also:    TCollection.Insert (1092   )


                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;


                 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   ;



                                                                                1096

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                67.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
                (1084   ).

                For an example, see TCollection.Load (1084   ).

       Errors:   Errors returned are those by TStream.Put (1130   ).

    See also:    TCollection.Load (1084   ), TCollection.PutItem (1097   )



                67.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 (1130   ).

    See also:    Store (1097   ), GetItem (1087   )



                                                                                1097

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.6          TDosStream



                67.6.1         Description

                TDosStream is a stream that stores it's contents in a file.  it overrides a couple of methods of
                TStream (1124   ) for this.

                In addition to the fields inherited from TStream (see TStream (1124   )), 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 (1079   ).



                67.6.2         Method  overview

                __Page______Method___________Description___________________________________________________________________________*
 *___________
                  1099      Close            Close the file.
                  1098      Done             Closes the file and cleans up the instance.
                  1098      Init             Instantiate a new instance of TDosStream.
                  1101      Open             Open the file stream
                  1101      Read             Read data from the stream to a buffer.
                  1100      Seek             Set file position.
                  1099      Truncate         Truncate the file on the current position.
                __1102______Write____________Write_data_from_a_buffer_to_the_stream._______________________________________________*
 *___________



                67.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 (1099   ).

       Errors:   On error, Status (??  ) is set to stInitError, and ErrorInfo is set to the dos error code.

    See also:    TDosStream.Done (1098   )



                67.6.4         TDosStream.Done

    Synopsis:    Closes the file and cleans up the instance.

Declaration:     destructor  Done;    Virtual

    Visibility:   default



                                                                                1098

                ________________________________________________________CHAPTER_67.___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 (1099   ).

       Errors:   None.

    See also:    TDosStream.Init (1098   ), TDosStream.Close (1099   )



                67.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 (1098   ) it does
                not clean up the instance of  TDosStream

                For an example, see TDosStream.Open (1101   ).

       Errors:   None.

    See also:    TStream.Close (1129   ), TDosStream.Init (1098   ), TDosStream.Done (1098   )



                67.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 (1130   ), TStream.GetSize (1127   )


                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  ) ;



                                                                                1099

                ________________________________________________________CHAPTER_67.___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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1131   ), TStream.GetPos (1127   )


                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') ;



                                                                                1100

                ________________________________________________________CHAPTER_67.___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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1099   ) 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 (1128   ), TDosStream.Close (1099   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.6.9         TDosStream.Read

    Synopsis:    Read data from the stream to a buffer.



                                                                                1101

                ________________________________________________________CHAPTER_67.___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 (1131   ).

       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 (1131   ), TDosStream.Write (1102   )



                67.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 (1131   ).

       Errors:   In  case  of  an  error,  Status  is  set  to  StWriteError,  and  ErrorInfo  gets  the  OS  specific
                error.

    See also:    TStream.Write (1132   ), TDosStream.Read (1101   )



                67.7          TMemoryStream



                67.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
                size of the memory blocks being used.


    See also:    TStream (1124   )



                67.7.2         Method  overview

                __Page______Method___________Description___________________________________________________________________________*
 *___________
                  1103      Done             Clean up memory and destroy the object instance.
                  1102      Init             Initialize memory stream, reserves memory for stream data.
                  1104      Read             Read data from the stream to a location in memory.
                  1103      Truncate         Set the stream size to the current position.
                __1104______Write____________Write_data_to_the_stream._____________________________________________________________*
 *___________



                67.7.3         TMemoryStream.Init

    Synopsis:    Initialize memory stream, reserves memory for stream data.

Declaration:     constructor  Init(ALimit:  LongInt;ABlockSize:  Word)



                                                                                1102

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



    Visibility:  default

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 (1132   ).

       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 (1103   )



                67.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 (1132   ).

       Errors:   None.

    See also:    TMemoryStream.Init (1102   )



                67.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 (1130   )


                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          ;



                                                                                1103

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                        I  :   L o n g i n t;


                 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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1131   ).

       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 (1131   ), TMemoryStream.Write (1104   )



                67.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 (1102   )) as needed.

                For an example, see TStream.Read (1131   ).

       Errors:   If the stream cannot allocate more memory, then the status is set to stWriteError

    See also:    TStream.Write (1132   ), TMemoryStream.Read (1104   )



                67.8          TOb ject



                67.8.1         Description

                This type serves as the basic object for all other objects in the Objects unit.



                                                                                1104

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.8.2         Method  overview

                __Page______Method_____________Description_________________________________________________________________________*
 *___________
                  1106      Done               Destroy an object.
                  1105      Free               Destroy an object and release all memory.
                  1105      Init               Construct (initialize) a new object
                __1106______Is\_Object_________Check_whether_a_pointer_points_to_an_object.________________________________________*
 *___________



                67.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 (1105   )

       Errors:   None.

    See also:    TObject.Free (1105   ), TObject.Done (1106   )



                67.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 (1105   ), TObject.Done (1106   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1105

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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.



                67.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 (1105   ) method.

                The destructore Done does not free the memory occupied by the object.

       Errors:   None.

    See also:    TObject.Free (1105   ), TObject.Init (1105   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.9          TPoint



                67.9.1         Description

                Record describing a point in a 2 dimensional plane.



                67.10            TRect



                67.10.1          Description

                Describes a rectangular region in a plane.



                                                                                1106

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.10.2          Method  overview

                __Page______Method__________Description____________________________________________________________________________*
 *___________
                  1112      Assign          Set rectangle corners.
                  1108      Contains        Determine if a point is inside the rectangle
                  1108      Copy            Copy cornerpoints from another rectangle.
                  1107      Empty           Is the surface of the rectangle zero
                  1108      Equals          Do the corners of the rectangles match
                  1111      Grow            Expand rectangle with certain size.
                  1110      Intersect       Reduce rectangle to intersection with another rectangle
                  1110      Move            Move rectangle along a vector.
                __1109______Union___________Enlarges_rectangle_to_encompas_another_rectangle.______________________________________*
 *___________



                67.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 (1108   ), TRect.Contains (1108   )


                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



                                                                                1107

                ________________________________________________________CHAPTER_67.___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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1107   )

       Errors:   None.

    See also:    TRect.Empty (1107   ), TRect.Contains (1108   )



                67.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 (1110   ), TRect.Equals (1108   )



                67.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.



                                                                                1108

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   None.

    See also:    TRect.Assign (1112   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1110   )


                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



                                                                                1109

                ________________________________________________________CHAPTER_67.___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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1109   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.10.9          TRect.Move

    Synopsis:    Move rectangle along a vector.

Declaration:     procedure  Move(ADX:  Sw_Integer;ADY:  Sw_Integer)

    Visibility:   default



                                                                                1110

                ________________________________________________________CHAPTER_67.___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 (1111   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1110   )


                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;



                                                                                1111

                ________________________________________________________CHAPTER_67.___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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1108   ).

       Errors:   None.

    See also:    TRect.Copy (1108   )



                67.11            TResourceCollection



                67.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.



                                                                                1112

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.11.2          Method  overview

                __Page______Method__________Description____________________________________________________________________________*
 *___________
                  1113      FreeItem        Release memory occupied by item.
                  1113      GetItem         Read an item from the stream.
                  1113      KeyOf           Return the key of an item in the collection.
                __1114______PutItem_________Write_an_item_to_the_stream.___________________________________________________________*
 *___________



                67.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 (1134   )



                67.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 (1084   ) method.

       Errors:   Errors returned are those by TStream.Read (1131   )

    See also:    TCollection.Load (1084   ), TStream.Read (1131   )



                67.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 (1093   )



                                                                                1113

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1097   ) method.

       Errors:   Errors returned are those by TStream.Write (1132   ).

    See also:    TCollection.Store (1097   )



                67.12            TResourceFile



                67.12.1          Description

                TResourceFile (1114   ) represents the resources in a binary file image.



                67.12.2          Method  overview

                __Page______Method___________Description___________________________________________________________________________*
 *___________
                  1115      Count            Number of resources in the file
                  1116      Delete           Delete a resource from the file
                  1115      Done             Destroy the instance and remove it from memory.
                  1116      Flush            Writes the resources to the stream.
                  1115      Get              Return a resource by key name.
                  1114      Init             Instantiate a new instance.
                  1115      KeyAt            Return the key of the item at a certain position.
                  1116      Put              Set a resource by key name.
                __1116______SwitchTo_________Write_resources_to_a_new_stream.______________________________________________________*
 *___________



                67.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 (1115   )



                                                                                1114

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1114   )



                67.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 (1114   )



                67.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 (1115   )



                67.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



                                                                                1115

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1131   ) and TStream.Write (1132   ).

    See also:    TResourceFile.Flush (1116   )



                67.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 (1131   ) and TStream.Write (1132   ).

    See also:    TResourceFile.SwitchTo (1116   )



                67.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 (1116   )



                67.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.



                                                                                1116

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   Errors returned may be those by TStream.Put (1130   ) and TStream.Seek

    See also:    Get (1115   )



                67.13            TSortedCollection



                67.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 (1119   ) method.

                Because the collection is ordered, TSortedCollection overrides some TCollection methods,
                to provide faster routines for lookup.

                The Compare (1119   ) 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.



                67.13.2          Method  overview

                __Page______Method___________Description___________________________________________________________________________*
 *___________
                  1119      Compare          Compare two items in the collection.
                  1118      IndexOf          Return index of an item in the collection.
                  1117      Init             Instantiates a new instance of a TSortedCollection
                  1121      Insert           Insert new item in collection.
                  1118      KeyOf            Return the key of an item
                  1118      Load             Instantiates a new instance of a TSortedCollection and loads it from
                                             stream.
                  1119      Search           Search for item with given key.
                __1122______Store____________Write_the_collection_to_the_stream.___________________________________________________*
 *___________



                67.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 (1083   )) 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 (1118   ), TCollection.Done (1085   )



                                                                                1117

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1084   )) 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 (1084   ).

       Errors:   None.

    See also:    TSortedCollection.Init (1117   ), TCollection.Done (1085   )



                67.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 (1118   ), TSortedCollection.Compare (1119   )



                67.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 (1086   )

       Errors:   None.

    See also:    TSortedCollection.Search (1119   ), TSortedCollection.Compare (1119   )



                                                                                1118

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1119   ) method and
                in the Insert (1121   ) 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 (1118   ), TSortedCollection.Search (1119   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.13.8          TSortedCollection.Search

    Synopsis:    Search for item with given key.

Declaration:     function  Search(Key:  Pointer;var  Index:  Sw_Integer)  :  Boolean;    Virtual

    Visibility:   default



                                                                                1119

                ________________________________________________________CHAPTER_67.___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  (1119   )  function  to  implement  this
                search.

                If the item is found, Search returns True, otherwise False is returned.

       Errors:   None.

    See also:    TCollection.IndexOf (1086   )


                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;



                                                                                1120

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                    D i s p o s e(M ,Done    ) ;
                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1096   ), 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 (1096   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1121

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1097   ), and then writing the Duplicates flag to the stream.

                After a Store, the collection can be loaded from the stream with the constructor Load (1118   )

                For an example, see TCollection.Load (1084   ).

       Errors:   Errors can be those of TStream.Put (1130   ).

    See also:    TSortedCollection.Load (1118   )



                67.14            TStrCollection



                67.14.1          Description

                The TStrCollection object manages a sorted collection of null-terminated strings (pchar
                strings).  To this end, it overrides the Compare (1119   ) method of  TSortedCollection, and
                it introduces methods to read/write strings from a stream.



                67.14.2          Method  overview

                __Page______Method___________Description___________________________________________________________________________*
 *___________
                  1122      Compare          Compare two strings in the collection.
                  1123      FreeItem         Free null-terminated string from the collection.
                  1123      GetItem          Read a null-terminated string from the stream.
                __1124______PutItem__________Write_a_null-terminated_string_to_the_stream._________________________________________*
 *___________



                67.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 (1119   )


                Listing:  ./objectex/ex38.pp



                                                                                1122

                ________________________________________________________CHAPTER_67.___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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1126   ).

    See also:    TStrCollection.PutItem (1124   )



                67.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.



                                                                                1123

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   None.

    See also:    TCollection.FreeItem (1093   )



                67.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 (1130   ).

    See also:    TStrCollection.GetItem (1123   )



                67.15            TStream



                67.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.


    See also:    PStream (1070   ), TDosStream (1098   ), TMemoryStream (1102   )



                                                                                1124

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.15.2          Method  overview

                __Page______Method_____________Description_________________________________________________________________________*
 *___________
                  1129      Close              Close the stream
                  1132      CopyFrom           Copy data from another stream.
                  1131      Error              Set stream status
                  1129      Flush              Flush the stream data from the buffer, if any.
                  1125      Get                Read an object definition from the stream.
                  1127      GetPos             Return current position in the stream
                  1127      GetSize            Return the size of the stream.
                  1125      Init               Constructor for TStream instance
                  1128      Open               Open the stream
                  1130      Put                Write an object to the stream.
                  1131      Read               Read data from stream to buffer.
                  1128      ReadStr            Read a shortstring from the stream.
                  1129      Reset              Reset the stream
                  1131      Seek               Set stream position.
                  1126      StrRead            Read a null-terminated string from the stream.
                  1130      StrWrite           Write a null-terminated string to the stream.
                  1130      Truncate           Truncate the stream size on current position.
                  1132      Write              Write a number of bytes to the stream.
                __1131______WriteStr___________Write_a_pascal_string_to_the_stream.________________________________________________*
 *___________



                67.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.



                67.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 (1130   )


                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      }



                                                                                1125

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                67.15.5          TStream.StrRead

    Synopsis:    Read a null-terminated string from the stream.

Declaration:     function  StrRead  :  PChar

    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 (1130   ), TStream.ReadStr (1128   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1126

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1131   ), TStream.GetSize (1127   )


                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;


                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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1131   ), TStream.GetPos (1127   )


                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;



                                                                                1127

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                       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___.____________________________________________________________________________________________________________*
 *___________



                67.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.

       Errors:   On error (e.g.  not enough memory), Nil is returned.

    See also:    TStream.StrRead (1126   )


                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___.____________________________________________________________________________________________________________*
 *___________



                67.15.9          TStream.Open

    Synopsis:    Open the stream



                                                                                1128

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



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 (1101   ).

       Errors:   None.

    See also:    TStream.Close (1129   ), TStream.Reset (1129   )



                67.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 (1101   ).

       Errors:   None.

    See also:    TStream.Open (1128   ), TStream.Reset (1129   )



                67.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 (1128   ), TStream.Close (1129   )



                67.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 (1080   ).

       Errors:   None.

    See also:    TStream.Truncate (1130   )



                                                                                1129

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1099   ).

       Errors:   None.

    See also:    TStream.Seek (1131   )



                67.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 (1077   ).

                After the object has been written, it can be read again with Get (1125   ).

                For an example, see TStream.Get (1125   );

       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 (1125   )



                67.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 (1126   ).

       Errors:   None.

    See also:    TStream.WriteStr (1131   ), TStream.StrRead (1126   ), TStream.ReadStr (1128   )



                                                                                1130

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1128   ).

       Errors:   None.

    See also:    TStream.StrWrite (1130   ), TStream.StrRead (1126   ), TStream.ReadStr (1128   )



                67.15.17           TStream.Seek

    Synopsis:    Set stream position.

Declaration:     procedure  Seek(Pos:  LongInt);    Virtual

    Visibility:   default

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 (1100   ).

       Errors:   If  Pos is larger than the stream size, Status is set to StSeekError.

    See also:    TStream.GetPos (1127   ), TStream.GetSize (1127   )



                67.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.



                67.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.



                                                                                1131

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   No checking is done to see if  Buf is large enough to contain Count bytes.

    See also:    TStream.Write (1132   ), TStream.ReadStr (1128   ), TStream.StrRead (1126   )


                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   ) ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1131   ).

       Errors:   No checking is done to see if  Buf actually contains Count bytes.

    See also:    TStream.Read (1131   ), TStream.WriteStr (1131   ), TStream.StrWrite (1130   )



                67.15.21           TStream.CopyFrom

    Synopsis:    Copy data from another stream.

Declaration:     procedure  CopyFrom(var  S:  TStream;Count:  LongInt)

    Visibility:   default



                                                                                1132

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



Description:     CopyFrom reads Count bytes from stream S and stores them in the current stream.  It uses
                the  Read  (1131   )  method  to  read  the  data,  and  the  Write  (1132   )  method  to  write  in  the
                current stream.

       Errors:   None.

    See also:    Read (1131   ), Write (1132   )


                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' ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                67.16            TStringCollection



                67.16.1          Description

                The TStringCollection object manages a sorted collection of pascal strings.  To this end,
                it overrides the Compare (1119   ) method of TSortedCollection, and it introduces methods
                to read/write strings from a stream.



                67.16.2          Method  overview

                __Page______Method___________Description___________________________________________________________________________*
 *___________
                  1134      Compare          Compare two strings in the collection.
                  1135      FreeItem         Dispose a string in the collection from memory.
                  1134      GetItem          Get string from the stream.
                __1135______PutItem__________Write_a_string_to_the_stream._________________________________________________________*
 *___________



                                                                                1133

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1128   ).

    See also:    TStringCollection.PutItem (1135   )



                67.16.4          TStringCollection.Compare

    Synopsis:    Compare two strings in the collection.

Declaration:     function  Compare(Key1:  Pointer;Key2:  Pointer)  :  Sw_Integer;    Virtual

    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.

                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 (1119   )


                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 ) ) ;



                                                                                1134

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                       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___.____________________________________________________________________________________________________________*
 *___________



                67.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 (1093   )



                67.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 (1131   ).

    See also:    TStringCollection.GetItem (1134   )



                67.17            TStringList



                67.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  (1077   )  function,  you  cannot  register  the
                TStrListMaker object.



                67.17.2          Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  1136      Done           Clean up the instance
                  1136      Get            Return a string by key name
                __1136______Load___________Load_stringlist_from_stream.____________________________________________________________*
 *___________



                                                                                1135

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1136   )



                67.17.4          TStringList.Done

    Synopsis:    Clean up the instance

Declaration:     destructor  Done;    Virtual

    Visibility:   default

Description:     The Done destructor frees the memory occupied by the string descriptions, and destroys the
                object.

       Errors:   None.

    See also:    Load (1136   ), TObject.Done (1106   )



                67.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 (1137   )



                67.18            TStrListMaker



                67.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 (1077   )
                function, you cannot register the TStringList object.



                                                                                1136

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.18.2          Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  1137      Done           Clean up the instance and free all related memory.
                  1137      Init           Instantiate a new instance of  TStrListMaker
                  1137      Put            Add a new string to the list with associated key.
                __1138______Store__________Write_the_strings_to_the_stream.________________________________________________________*
 *___________



                67.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 (1105   ), TStrListMaker.Done (1137   )



                67.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 (1106   ), TStrListMaker.Init (1137   )



                67.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 (1138   ) method.

       Errors:   None.

    See also:    TStrListMaker.Store (1138   )



                                                                                1137

                ________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                67.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 (1136   ), TStrListMaker.Put (1137   )



                67.19            TUnSortedStrCollection



                67.19.1          Description

                The  TUnSortedStrCollection  object  manages  an  unsorted  list  of  strings.   To  this  end,
                it  overrides  the  TSortedCollection.Insert  (1121   )  method  to  add  strings  at  the  end  of  the
                collection, rather than in the alphabetically correct position.

                Take  care,  the  Search  (1119   )  and  IndexOf  (1086   )  methods  will  not  work  on  an  unsorted
                string collection.



                67.19.2          Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                __1138______Insert_________Insert_a_new_string_in_the_collection.__________________________________________________*
 *___________



                67.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 (1092   )


                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;



                                                                                1138

________________________________________________________CHAPTER_67.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___



 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___._______________________________________________________________________________________________________________________



                                                                1139




Chapter   68



Reference   for   unit   'ob jpas'



68.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
mode 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.



68.2          Constants,  types  and  variables



68.2.1         Constants

MaxInt  =  MaxLongint


Maximum value for Integer (1140   ) type.



68.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 (1140   )


PInteger  =  ^Integer


Pointer to Integer (1140   ) type.


PIntegerArray  =  ^IntegerArray


Pointer to TIntegerArray (1141   ) type.



                                                            1140

__________________________________________________________CHAPTER_68.___REFERENCE_FOR_UNIT_'OBJPAS'________________________________*
 *___



PointerArray  =  Array[0..512*1024*1024-2]  of  Pointer


Generic Array of pointers.


PPointerArray  =  ^PointerArray


Pointer to PointerArray (1141   )


PString  =  PAnsiString


Pointer to ansistring type.


TBoundArray  =  Array  of  Integer


Array of integer, used in interfaces.


TIntegerArray  =  IntegerArray


Alias for IntegerArray (1140   )


TPointerArray  =  PointerArray


Alias for PointerArray (1141   )



                                                                1141




Chapter   69



Reference   for   unit   'ports'



69.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.



69.2          Constants,  types  and  variables



69.2.1         Variables

port  :  tport


Default instance of type TPort (1143   ).  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 (1143   ).  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



                                                            1142

                ____________________________________________________________CHAPTER_69.___REFERENCE_FOR_UNIT_'PORTS'_______________*
 *___________________



                portl  :  tportl


                Default instance of type TPortL (1144   ).  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 (1144   ).  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



                69.3          tport



                69.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.


    See also:    port (1142   ), TPortW (1144   ), TPortL (1144   )



                69.3.2         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __1143______pp________________rw___________Access_integer-sized_port_by_port_number________________________________*
 *___________



                69.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



                                                                                1143

                ____________________________________________________________CHAPTER_69.___REFERENCE_FOR_UNIT_'PORTS'_______________*
 *___________________



                69.4          tportl



                69.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.


    See also:    portw (1143   ), TPort (1143   ), TPortL (1144   )



                69.4.2         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __1144______pp________________rw___________Access_Longint-sized_port_by_port_number________________________________*
 *___________



                69.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



                69.5          tportw



                69.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.


    See also:    portw (1143   ), TPort (1143   ), TPortL (1144   )



                69.5.2         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __1144______pp________________rw___________Access_word-sized_port_by_port_number___________________________________*
 *___________



                69.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



                                                                                1144




                Chapter   70



                Reference   for   unit   'printer'



                70.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  all  supported  systems,
                although there are minor differences on Linux and UNIX.



                70.2          Constants,  types  and  variables



                70.2.1         Variables

                Lst  :  text


                Lst is the standard printing device.
                On Linux, Lst is set up using AssignLst('/tmp/PID.lst').



                70.3          Procedures  and  functions



                70.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|'}:  Same  as  previous,  only  the  file  is  not  sent  to  lpr,  nor  is  it  deleted.
                       (useful for opening /dev/printer or for later printing)



                                                                            1145

                ________________________________________________________CHAPTER_70.___REFERENCE_FOR_UNIT_'PRINTER'_________________*
 *___________________



    See also:    lst (1145   )


                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___.____________________________________________________________________________________________________________*
 *___________



                70.3.2         InitPrinter

    Synopsis:    Initialize the printer

Declaration:     procedure  InitPrinter(const  PrinterName:  string)

    Visibility:   default

Description:     Initialize the printer



                70.3.3         IsLstAvailable

    Synopsis:    Determine whether printer is available.

Declaration:     function  IsLstAvailable  :  Boolean

    Visibility:   default

Description:     Determine whether printer is available.



                                                                                1146




Chapter   71



Reference   for   unit   'sharemem'



71.1          Overview


sharemem implements a shared memory manager.  Including this unit will replace the stan-
dard memory manager with a memory manager which uses shared memory.  This means the
memory allocated by this unit can be managed by a program and a DLL if they both use
the shared memory manager:  it allows, amongst other things, to pass ansistrings or unicode
strings from a program to a DLL and vice versa.

This unit does not implement any routines:  all actions to replace the memory manager are
performed in the initialization section of the unit.  The unit should be placed as the first unit
in a program or DLL's uses section, memory corruption may occur if the unit is not placed
first.

This unit requires the fpcmemdll.dll library to be distributed with both program and dll that
use this unit.  This DLL is distributed with the windows Free Pascal distribution.



                                                            1147




Chapter   72



Reference   for   unit   'Sockets'



72.1          Used  units



                                    Table 72.1:  Used units by unit 'Sockets'


                                                  _Name_____________Page______
                                                    BaseUnix           113
                                                    System           1235
                                                    unixtype         1798



72.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.



72.3          Constants,  types  and  variables



72.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



                                                            1148

________________________________________________________CHAPTER_72.___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



                                                                1149

________________________________________________________CHAPTER_72.___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



                                                                1150

________________________________________________________CHAPTER_72.___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



                                                                1151

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



INADDR_ANY  =  (0)


A bitmask matching any IP address on the local machine.


INADDR_NONE  =  ($FFFFFFFF)


A bitmask matching no valid IP address


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.



                                                                1152

________________________________________________________CHAPTER_72.___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.



                                                                1153

________________________________________________________CHAPTER_72.___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


Change the IPV6 address into a different address family.  Deprecated


IPV6_ADD_MEMBERSHIP  =  IPV6_JOIN_GROUP


Undocumented Getsockopt option ?


IPV6_AUTHHDR  =  10


GetSockOpt/SetSockopt:  Deliver authentication header messages


IPV6_CHECKSUM  =  7


Undocumented Getsockopt option ?


IPV6_DROP_MEMBERSHIP  =  IPV6_LEAVE_GROUP


Undocumented Getsockopt option ?


IPV6_DSTOPTS  =  4


Deliver destination option control messages


IPV6_HOPLIMIT  =  8


Deliver an integer containing the HOP count


IPV6_HOPOPTS  =  3


Deliver hop option control messages


IPV6_IPSEC_POLICY  =  34


Undocumented Getsockopt option ?



                                                                1154

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



IPV6_JOIN_ANYCAST  =  27


Undocumented Getsockopt option ?


IPV6_JOIN_GROUP  =  20


GetSockOpt/SetSockopt:  Control membership (join group) in multicast groups


IPV6_LEAVE_ANYCAST  =  28


Undocumented Getsockopt option ?


IPV6_LEAVE_GROUP  =  21


GetSockOpt/SetSockopt:  Control membership (leave group)in multicast groups


IPV6_MTU  =  24


GetSockOpt/SetSockopt:  Get/Set the MTU for the socket


IPV6_MTU_DISCOVER  =  23


GetSockOpt/SetSockopt:  Get/Set Control path MTU Discovery on the socket


IPV6_MULTICAST_HOPS  =  18


GetSockOpt/SetSockopt:  Get/Set the multicast hop limit.


IPV6_MULTICAST_IF  =  17


GetSockOpt/SetSockopt:  Get/Set device for multicast packages on the socket.


IPV6_MULTICAST_LOOP  =  19


GetSockOpt/SetSockopt:  Control  whether  socket  sees  multicast  packages  that  it  has  sent
itself


IPV6_NEXTHOP  =  9


sendmsg:  set next hop for IPV6 datagram


IPV6_PKTINFO  =  2


Change delivery options for incoming IPV6 datagrams


IPV6_PKTOPTIONS  =  6


Undocumented Getsockopt option ?


IPV6_PMTUDISC_DO  =  2



                                                                1155

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Always DF.


IPV6_PMTUDISC_DONT  =  0


Never send DF frames.


IPV6_PMTUDISC_WANT  =  1


Use per route hints.


IPV6_RECVERR  =  25


GetSockOpt/SetSockopt:  Control receiving of asynchroneous error options


IPV6_ROUTER_ALERT  =  22


GetSockOpt/SetSockopt:  Get/Set Pass all forwarded packets containing router alert option


IPV6_RTHDR  =  5


Deliver routing header control messages


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


GetSockOpt/SetSockopt:  Get/Set unicast hop limit


IPV6_V6ONLY  =  26



                                                                1156

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



GetSockOpt/SetSockopt:  Handle IPV6 connections only


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


Maximum group memberships for multicast messages


IP_MSFILTER  =  41


Undocumented ?


IP_MTU_DISCOVER  =  10


Undocumented ?


IP_MULTICAST_IF  =  32



                                                                1157

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



set/get IP multicast i/f


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



                                                                1158

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Undocumented ?


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



                                                                1159

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



leave source-spec group


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



                                                                1160

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Receive flags:  receive out-of-band data.


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



                                                                1161

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Protocol family:  Ash


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



                                                                1162

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Protocol family:  Linux LLC


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



                                                                1163

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Protocol family:  Unix domain 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 (1174   ) call.


SOCK_RAW  =  3


Type of socket:  raw socket


SOCK_RDM  =  4


Type of socket:  reliably-delivered message


SOCK_SEQPACKET  =  5



                                                                1164

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Type of socket:  sequential packet socket


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



                                                                1165

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Socket option:  ?


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



                                                                1166

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Socket option:  ?


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


TCP_CONGESTION  =  13


Get/set the congestion-control algorithm for this socket


TCP_CORK  =  3



                                                                1167

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Get/Set CORK algorithm:  Send only complete packets


TCP_DEFER_ACCEPT  =  9


Get/Set deferred accept on server socket


TCP_INFO  =  11


Get TCP connection information (linux only)


TCP_KEEPCNT  =  6


Get/Set retry count for unacknowledged KEEPALIVE transmissions.


TCP_KEEPIDLE  =  4


Get/Set inactivity interval between KEEPALIVE transmissions.


TCP_KEEPINTVL  =  5


Get/Set retry interval for unacknowledged KEEPALIVE transmissions.


TCP_LINGER2  =  8


Get/Set Linger2 flag


TCP_MAXSEG  =  2


Get/Set Maximum segment size


TCP_MD5SIG  =  14


Get/Set TCP MD5 signature option


TCP_NODELAY  =  1


Get/Set No delay flag:  disable Nagle algorithm


TCP_QUICKACK  =  12


Get/Set quik ACK packet option.


TCP_SYNCNT  =  7


Get/Set number of SYN packets to send before givin up on connection establishment


TCP_WINDOW_CLAMP  =  10


Get/Set maximum packet size


UDP_CORK  =  1



                                                                1168

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Get/Set UDP CORK algorithm on datagram sockets


UDP_ENCAP  =  100


Get/Set UDP encapsulation flag for IPSec datagram sockets


UDP_ENCAP_ESPINUDP  =  2


?  Undocumented datagram option, IPSec related


UDP_ENCAP_ESPINUDP_NON_IKE  =  1


?  Undocumented datagram option, IPSec related


UDP_ENCAP_L2TPINUDP  =  3


?  Undocumented datagram option, IPSec related



72.3.2         Types

in6_addr  =  packed  record
case  Byte  of
0:  (
    u6_addr8  :  Array[0..15]  of  Byte;
);
1:  (
    u6_addr16  :  Array[0..7]  of  Word;
);
2:  (
    u6_addr32  :  Array[0..3]  of  Cardinal;
);
3:  (
    s6_addr8  :  Array[0..15]  of  ShortInt;
);
4:  (
    s6_addr  :  Array[0..15]  of  ShortInt;
);
5:  (
    s6_addr16  :  Array[0..7]  of  SmallInt;
);
6:  (
    s6_addr32  :  Array[0..3]  of  LongInt;
);
end



Record used to describe a general IPV6 address.


in_addr  =  packed  record
case  Boolean  of
True:  (
    s_addr  :  cuint32;



                                                                1169

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



);
False:  (
   s_bytes  :  packed  Array[1..4]  of  Byte;
);
end



General inet socket address.


linger  =  packed  record
   l_onoff  :  cint;
   l_linger  :  cint;
end



This record is used in the fpsetsockopt (1184   ) call to specify linger options.


PIn6Addr  =  pin6_addr


Pointer to in6_addr (1169   ) type.


pin6_addr  =  ^in6_addr


Pointer to Tin6_addr (1172   )


PInAddr  =  pin_addr


Alias for pin_addr (1170   )


PInetSockAddr  =  psockaddr_in


Pointer to sockaddr_in (1171   )


PInetSockAddr6  =  psockaddr_in6


Pointer to sockaddr_in6 (1171   ) type


pin_addr  =  ^in_addr


Pointer to in_addr (1170   ) record.


plinger  =  ^linger


Pointer to linger (1170   ) type.


psockaddr  =  ^sockaddr


Pointer to TSockAddr (1172   )


psockaddr_in  =  ^sockaddr_in



                                                                1170

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



Pointer to sockaddr_in (1171   )


psockaddr_in6  =  ^sockaddr_in6


Pointer to sockaddr_in6 (1171   )


psockaddr_un  =  ^sockaddr_un


Pointer to sockaddr_un (1172   ) type.


sa_family_t  =  cushort


Address family type


sockaddr  =  packed  record
case  Integer  of
0:  (
   sa_family  :  sa_family_t;
   sa_data  :  packed  Array[0..13]  of  cuint8;
);
1:  (
   sin_family  :  sa_family_t;
   sin_port  :  cushort;
   sin_addr  :  in_addr;
   sin_zero  :  packed  Array[0..7]  of  cuint8;
);
end



sockaddr  is  used  to  store  a  general  socket  addres  for  the  FPBind  (1178   ),  FPRecv  (1182   )
and FPSend (1183   ) calls.


sockaddr_in  =  packed  record
   sin_family  :  sa_family_t;
   sin_port  :  cushort;
   sin_addr  :  in_addr;
   xpad  :  Array[0..7]  of  Char;
end



sockaddr_in is used to store a INET socket addres for the FPBind (1178   ), FPRecv (1182   )
and FPSend (1183   ) 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 (1171   )



                                                                1171

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



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 FPBind (1178   ), FPRecv (1182   )
and FPSend (1183   ) calls.


TIn6Addr  =  in6_addr


Alias for in6_addr (1169   ) type.


Tin6_addr  =  in6_addr


Alias for sockaddr_in6 (1171   )


TInAddr  =  in_addr


Alias for in_addr (1170   ) record type.


TInetSockAddr  =  sockaddr_in


Alias for sockaddr_in (1171   )


TInetSockAddr6  =  sockaddr_in6


Alias for sockaddr_in6 (1171   )


TIn_addr  =  in_addr


Alias for in_addr (1170   ) record type.


TLinger  =  linger


Alias for linger (1170   )


TSockAddr  =  sockaddr



TSockArray  =  Array[1..2]  of  LongInt


Type returned by the FPSocketPair (1185   ) call.


Tsocket  =  LongInt


Alias for easy kylix porting


TSockLen  =  BaseUnix.TSocklen


The actual type of  TSockLen depends on the platform.



                                                                1172

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                TSockPairArray  =  Array[0..1]  of  LongInt


                Array of sockets, used in FPSocketPair (1185   ) call.


                TUnixSockAddr  =  packed  record
                   family  :  sa_family_t;
                   path  :  Array[0..107]  of  Char;
                end



                Alias for sockaddr_un (1172   )



                72.4          Procedures  and  functions



                72.4.1         Accept

    Synopsis:    Accept a connection from a socket (deprecated).

Declaration:     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 (1173   ) command, with the Text or File parameters are
                equivalent  to  subsequently  calling  the  regular  Accept  (1173   )  function  and  the  Sock2Text
                (1189   ) or Sock2File (1189   ) 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:


                ESockEBADF (1151   )              The socket descriptor is invalid.

                ESockENOTSOCK (1151   )                   The descriptor is not a socket.

                SYS__EOPNOTSUPP                   The socket type doesn't support the Listen operation.

                ESockEFAULT (1151   )              Addr points outside your address space.

                ESockEWOULDBLOCK (1151   )                         The requested operation would block the process.


    See also:    FPListen (1182   ), Connect (1175   ), FPConnect (1179   ), FPBind (1178   )


                Listing:  ./sockex/socksvr.pp



                                                                                1173

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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
                }
                { $mode      f p c}
                 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) ;
                    h a l t( 1 0 0 ) ;
                end   ;


                 b e g i n
                    S := f p 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 ) ;
                    SAddr    . s i n _a d d r.s _a d d r : = 0 ;
                    i f  f p B i n d(S , @SAddr     ,s i z e o f(s a d d r))= -1    then
                      P E r r o r ( ' S e r v e r :  B i n d  :   ') ;
                    i f  f p L i s t e n (S ,1)= -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  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___.____________________________________________________________________________________________________________*
 *___________



                72.4.2         Bind

    Synopsis:    Alias for fpBind.

Declaration:     function  Bind(Sock:  LongInt;const  addr:  string)  :  Boolean

    Visibility:   default



                                                                                1174

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



Description:     Bind is an alias for fpBind (1178   ) which binds to either a socket struct (Addr) or a string
                indicating a unix socket file (unix socket).

                This function is deprecated, use fpBind instead.

    See also:    FPBind (1178   )



                72.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:    FPSocket (1185   )



                72.4.4         Connect

    Synopsis:    Open a connection to a server socket (deprecated).

Declaration:     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 (1175   ) command with the Text or File arguments are equivalent
                to subsequently calling the regular Connect function and the Sock2Text (1189   ) or Sock2File
                (1189   ) 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:    FPListen (1182   ), FPBind (1178   ), Accept (1173   ), FPAccept (1177   )


                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
                }



                                                                                1175

________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



 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 := f p S o c k e t (AF _INET     ,SOCK_STREAM         , 0 ) ;
    i f  s =-1    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 ) ;
    {   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 := f p 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



                                                                1176

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                        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   ;
                    f p S h u t d o w(ns , 2 ) ;
                    c l o s e ( s i n ) ;
                    c l o s e ( s o u t) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                72.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:


                ESockEBADF (1151   )              The socket descriptor is invalid.

                ESockENOTSOCK (1151   )                   The descriptor is not a socket.

                SYS__EOPNOTSUPP                   The socket type doesn't support the Listen operation.

                ESockEFAULT (1151   )              Addr points outside your address space.

                ESockEWOULDBLOCK (1151   )                         The requested operation would block the process.


    See also:    fpListen (1182   ), fpConnect (1179   ), fpBind (1178   )


                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
                }
                { $mode      f p c}



                                                                                1177

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                 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) ;
                    h a l t( 1 0 0 ) ;
                end   ;


                 b e g i n
                    S := f p 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 ) ;
                    SAddr    . s i n _a d d r.s _a d d r : = 0 ;
                    i f  f p B i n d(S , @SAddr     ,s i z e o f(s a d d r))= -1    then
                      P E r r o r ( ' S e r v e r :  B i n d  :   ') ;
                    i f  f p L i s t e n (S ,1)= -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  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___.____________________________________________________________________________________________________________*
 *___________



                72.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:


                ESockEBADF (1151   )              The socket descriptor is invalid.

                ESockEINVAL (1151   )              The socket is already bound to an address,

                ESockEACCESS (1151   )                Address is protected and you don't have permission to open it.



                                                                                1178

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                More errors can be found in the Unix man pages.

    See also:    FPSocket (1185   )



                72.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 uses the socket s to open 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 are trying to make, but is generally one of  TSockAddr or TUnixSockAddr.

                The fpConnect function returns zero 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 (1182   ), fpBind (1178   ), fpAccept (1177   )


                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 := f p S o c k e t (AF _INET     ,SOCK_STREAM         , 0 ) ;
                    i f  s =-1    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 ) ;
                    {   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  :  ' ) ;



                                                                                1179

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                    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 := f p 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   ;
                    f p S h u t d o w(ns , 2 ) ;
                    c l o s e ( s i n ) ;
                    c l o s e ( s o u t) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                72.4.8         fpgetpeername

    Synopsis:    Return the name (address) of the connected peer.

Declaration:     function  fpgetpeername(s:  cint;name:  psockaddr;namelen:  pSockLen)  :  cint

    Visibility:   default



                                                                                1180

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



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.

       Errors:   Errors are reported in SocketError, and include the following:


                ESockEBADF (1151   )             The socket descriptor is invalid.

                ESockENOBUFS (1151   )                The system doesn't have enough buffers to perform the opera-
                      tion.

                ESockENOTSOCK (1151   )                  The descriptor is not a socket.

                ESockEFAULT (1151   )             Addr points outside your address space.

                ESockENOTCONN (1151   )                   The socket isn't connected.


    See also:    fpConnect (1179   ), fpSocket (1185   )



                72.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:


                ESockEBADF (1151   )              The socket descriptor is invalid.

                ESockENOBUFS (1151   )                 The system doesn't have enough buffers to perform the opera-
                       tion.

                ESockENOTSOCK (1151   )                   The descriptor is not a socket.

                ESockEFAULT (1151   )              Addr points outside your address space.


    See also:    fpBind (1178   )



                72.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.



                                                                                1181

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                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:


                ESockEBADF (1151   )             The socket descriptor is invalid.

                ESockENOTSOCK (1151   )                  The descriptor is not a socket.

                ESockEFAULT (1151   )             OptVal points outside your address space.


    See also:    fpSetSockOpt (1184   )



                72.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:


                ESockEBADF (1151   )              The socket descriptor is invalid.

                ESockENOTSOCK (1151   )                   The descriptor is not a socket.

                SYS__EOPNOTSUPP                   The socket type doesn't support the Listen operation.


    See also:    fpSocket (1185   ), fpBind (1178   ), fpConnect (1179   )



                72.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:



                                                                                1182

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                ESockEBADF (1151   )             The socket descriptor is invalid.

                ESockENOTCONN (1151   )                   The socket isn't connected.

                ESockENOTSOCK (1151   )                  The descriptor is not a socket.

                ESockEFAULT (1151   )             The address is outside your address space.

                ESockEMSGSIZE (1151   )                The message cannot be sent atomically.

                ESockEWOULDBLOCK (1151   )                        The requested operation would block the process.

                ESockENOBUFS (1151   )                The system doesn't have enough free buffers available.

    See also:    FPSend (1183   )



                72.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 (1185   ), fprecv (1182   )



                72.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:

                ESockEBADF (1151   )              The socket descriptor is invalid.

                ESockENOTSOCK (1151   )                   The descriptor is not a socket.

                ESockEFAULT (1151   )              The address is outside your address space.

                ESockEMSGSIZE (1151   )                 The message cannot be sent atomically.

                ESockEWOULDBLOCK (1151   )                         The requested operation would block the process.

                ESockENOBUFS (1151   )                 The system doesn't have enough free buffers available.

    See also:    fpRecv (1182   )



                                                                                1183

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                72.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 (1185   ), fpSend (1183   ), fpRecvFrom (1183   )



                72.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:


                ESockEBADF (1151   )              The socket descriptor is invalid.

                ESockENOTSOCK (1151   )                   The descriptor is not a socket.

                ESockEFAULT (1151   )              OptVal points outside your address space.


    See also:    fpGetSockOpt (1181   )



                72.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.



                                                                                1184

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                On succes, the function returns 0, on error -1 is returned.

       Errors:   SocketError is used to report errors, and includes the following:


                ESockEBADF (1151   )             The socket descriptor is invalid.

                ESockENOTCONN (1151   )                   The socket isn't connected.

                ESockENOTSOCK (1151   )                  The descriptor is not a socket.


    See also:    fpSocket (1185   ), fpConnect (1179   )



                72.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  (1178   )  call.   If  unsuccesfull,  the
                function returns -1.

                for an example, see Accept (1173   ).

       Errors:   Errors are returned in SocketError, and include the follwing:


                ESockEPROTONOSUPPORT (1151   )                             The protocol type or the specified protocol is not
                       supported within this domain.

                ESockEMFILE (1151   )              The per-process descriptor table is full.

                SYS__ENFILE           The system file table is full.

                ESockEACCESS (1151   )                Permission to create a socket of the specified type and/or protocol
                       is denied.

                ESockENOBUFS (1151   )                 Insufficient buffer space is available.  The socket cannot be cre-
                       ated until sufficient resources are freed.


    See also:    FPSocketPair (1185   )



                72.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 FPSocket (1185   )

    See also:    Str2UnixSockAddr (1189   )



                                                                                1185

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                72.4.20          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 (1187   ), but with the bytes in correct order.

    See also:    NetAddrToStr (1187   ), StrToHostAddr (1190   ), StrToNetAddr (1190   )



                72.4.21          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 (1187   ), but with the bytes in correct order.

    See also:    NetAddrToStr (1187   ), StrToHostAddr (1190   ), StrToNetAddr (1190   ), StrToHostAddr6 (1190   )



                72.4.22          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 (1187   ), NToHS (1188   ), HToNS (1187   ), ShortHostToNet (1188   ), ShortNetToHost
                (1188   )



                72.4.23          htonl

    Synopsis:    Convert long integer from host ordered to network ordered

Declaration:     function  htonl(host:  Cardinal)  :  Cardinal;    Overload

    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 (1187   ), ntohl (1188   ), ntohs (1188   )



                                                                                1186

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                72.4.24          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 (1186   ), ntohl (1188   ), ntohs (1188   )



                72.4.25          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 (1186   ), StrToNetAddr (1190   ), StrToHostAddr (1190   )



                72.4.26          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 (1187   ), but with the bytes in correct order.

    See also:    NetAddrToStr (1187   ), StrToHostAddr (1190   ), StrToNetAddr (1190   ), StrToHostAddr6 (1190   )



                72.4.27          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 (1186   ), NToHS (1188   ), HToNS (1187   ), ShortHostToNet (1188   ), ShortNetToHost
                (1188   )



                                                                                1187

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                72.4.28          NToHl

    Synopsis:    Convert long integer from network ordered to host ordered

Declaration:     function  NToHl(Net:  Cardinal)  :  Cardinal;    Overload

    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 (1186   ), htons (1187   ), ntohs (1188   )



                72.4.29          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 (1186   ), htons (1187   ), ntohl (1188   )



                72.4.30          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 (1188   ), HostToNet (1186   ), NToHS (1188   ), HToNS (1187   )



                72.4.31          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 (1188   ), HostToNet (1186   ), NToHS (1188   ), HToNS (1187   )



                                                                                1188

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                72.4.32          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:    FPSocket (1185   ), Sock2Text (1189   )



                72.4.33          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:    FPSocket (1185   ), Sock2File (1189   )



                72.4.34          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.



                72.4.35          Str2UnixSockAddr

    Synopsis:    Convert path to TUnixSockAddr (1173   )

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 (1174   ) call.

       Errors:   None.

    See also:    FPSocket (1185   ), FPBind (1178   )



                                                                                1189

                ________________________________________________________CHAPTER_72.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                72.4.36          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 (1187   ), HostAddrToStr (1186   ), StrToNetAddr (1190   )



                72.4.37          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 (1187   ), HostAddrToStr6 (1186   ), StrToHostAddr (1190   )



                72.4.38          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 (1187   ), HostAddrToStr (1186   ), StrToHostAddr (1190   )



                72.4.39          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 (1187   ), HostAddrToStr6 (1186   ), StrToHostAddr6 (1190   )



                                                                                1190




                Chapter   73



                Reference   for   unit   'strings'



                73.1          Overview


                This chapter describes the STRINGS unit for Free Pascal.  This unit is system independent,
                and therefore works on all supported platforms.



                73.2          Procedures  and  functions



                73.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 (1200   ), StrPCopy (1201   )



                73.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 (1196   )


                Listing:  ./stringex/ex11.pp



                                                                            1191

                _________________________________________________________CHAPTER_73.___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___.____________________________________________________________________________________________________________*
 *___________



                73.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 SizeInt when S1<S2.

                      o0 when S1=S2.

                      oA positive SizeInt when S1>S2.


                For an example, see StrLComp (1197   ).

       Errors:   None.

    See also:    StrLComp (1197   ), StrIComp (1195   ), StrLIComp (1198   )



                73.2.4         strcopy

    Synopsis:    Copy a null-terminated string

Declaration:     function  strcopy(dest:  pchar;source:  pchar)  :  pchar;    Overload

    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 (1201   ), StrLCopy (1197   ), StrECopy (1193   )


                Listing:  ./stringex/ex4.pp



                                                                                1192

                _________________________________________________________CHAPTER_73.___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___.____________________________________________________________________________________________________________*
 *___________



                73.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 (1200   )


                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___.____________________________________________________________________________________________________________*
 *___________



                73.2.6         strecopy

    Synopsis:    Copy a null-terminated string, return a pointer to the end.



                                                                                1193

                _________________________________________________________CHAPTER_73.___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 (1197   ), StrCopy (1192   )


                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___.____________________________________________________________________________________________________________*
 *___________



                73.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 (1198   )


                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  ! ' )



                                                                                1194

                _________________________________________________________CHAPTER_73.___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___.____________________________________________________________________________________________________________*
 *___________



                73.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 SizeInt when S1<S2.

                      o0 when S1=S2.

                      oA positive SizeInt when S1>S2.


       Errors:   None.

    See also:    StrLComp (1197   ), StrComp (1192   ), StrLIComp (1198   )


                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___.____________________________________________________________________________________________________________*
 *___________



                73.2.9         stripos

    Synopsis:    Return the position of a substring in a string, case insensitive.

Declaration:     function  stripos(str1:  pchar;str2:  pchar)  :  pchar

    Visibility:   default

Description:     stripos returns the position of str2 in str1.  It searches in a case-insensitive manner, and
                if it finds a match, it returns a pointer to the location of the match.  If no match is found,
                Nil is returned.



                                                                                1195

                _________________________________________________________CHAPTER_73.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



       Errors:   No checks are done on the validity of the pointers, and the pointers are assumed to point to
                a properly null-terminated string.  If either of these conditions are not met, a run-time error
                may follow.

    See also:    striscan (1196   ), strpos (1202   )



                73.2.10          striscan

    Synopsis:    Scan a string for a character, case-insensitive

Declaration:     function  striscan(p:  pchar;c:  Char)  :  pchar

    Visibility:   default

Description:     striscan does the same as strscan (1203   ) but compares the characters case-insensitively.
                It returns a pointer to the first occurrence of the character c in the null-terminated string p,
                or Nil if  c is not present in the string.

    See also:    strscan (1203   ), strriscan (1202   )



                73.2.11          strlcat

    Synopsis:    Concatenate 2 null-terminated strings, with length boundary.

Declaration:     function  strlcat(dest:  pchar;source:  pchar;l:  SizeInt)  :  pchar

    Visibility:   default

Description:     Adds  L  characters  from  Source  to  Dest,  and  adds  a  terminating  null-character.  Returns
                Dest.

       Errors:   None.

    See also:    StrCat (1191   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1196

                _________________________________________________________CHAPTER_73.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                73.2.12          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 SizeInt when S1<S2.

                      o0 when S1=S2.

                      oA positive SizeInt when S1>S2.


       Errors:   None.

    See also:    StrComp (1192   ), StrIComp (1195   ), StrLIComp (1198   )


                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___.____________________________________________________________________________________________________________*
 *___________



                73.2.13          strlcopy

    Synopsis:    Copy a null-terminated string, limited in length.

Declaration:     function  strlcopy(dest:  pchar;source:  pchar;maxlen:  SizeInt)  :  pchar
                                            ;    Overload

    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 (1192   ), StrECopy (1193   )


                Listing:  ./stringex/ex5.pp



                                                                                1197

                _________________________________________________________CHAPTER_73.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                73.2.14          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. If P equals Nil, then zero (0) is returned.

       Errors:   None.

    See also:    StrNew (1200   )


                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___.____________________________________________________________________________________________________________*
 *___________



                73.2.15          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



                                                                                1198

                _________________________________________________________CHAPTER_73.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                      oA negative SizeInt when S1<S2.

                      o0 when S1=S2.

                      oA positive SizeInt when S1>S2.


                For an example, see StrIComp (1195   )

       Errors:   None.

    See also:    StrLComp (1197   ), StrComp (1192   ), StrIComp (1195   )



                73.2.16          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 (1203   )


                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___.____________________________________________________________________________________________________________*
 *___________



                73.2.17          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 (1197   ), StrCopy (1192   )



                                                                                1199

                _________________________________________________________CHAPTER_73.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                73.2.18          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 (1192   ), StrDispose (1193   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1200

                _________________________________________________________CHAPTER_73.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                73.2.19          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 (1201   )


                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___.____________________________________________________________________________________________________________*
 *___________



                73.2.20          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  Se  to  a  Null-terminated  string,  and  copies  it  to  D.  D  needs
                enough room to contain the string Source, i.e.  Length(S)+1 bytes.

       Errors:   No length checking is performed.

    See also:    StrPas (1201   )


                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;



                                                                                1201

                _________________________________________________________CHAPTER_73.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                73.2.21          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 (1203   ), StrRScan (1203   )


                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   :   ' , s i z e i n(tS t r P o s(P , S)) -  s i z e *
 *i n t(P ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                73.2.22          strriscan

    Synopsis:    Scan a string reversely for a character, case-insensitive

Declaration:     function  strriscan(p:  pchar;c:  Char)  :  pchar

    Visibility:   default

Description:     strriscan does the same as strrscan (1203   ) but compares the characters case-insensitively.
                It returns a pointer to the last occurrence of the character c in the null-terminated string p,
                or Nil if  c is not present in the string.

    See also:    strrscan (1203   ), striscan (1196   )



                                                                                1202

                _________________________________________________________CHAPTER_73.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                73.2.23          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 (1203   ).

       Errors:   None.

    See also:    StrScan (1203   ), StrPos (1202   )



                73.2.24          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 (1203   ), StrPos (1202   )


                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___.____________________________________________________________________________________________________________*
 *___________



                73.2.25          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 (1199   )

       Errors:   None.

    See also:    StrLower (1199   )



                                                                                1203




Chapter   74



Reference   for   unit   'strutils'



74.1          Used  units



                                    Table 74.1:  Used units by unit 'strutils'


                                                   __Name__________Page_____
                                                     System        1235
                                                     sysutils      1489



74.2          Constants,  types  and  variables



74.2.1         Resource  strings

SErrAmountStrings  =  'Amount  of  search  and  replace  strings  don''t  match'


Error message used in stringsreplace function


SInvalidRomanNumeral  =  '%s  is  not  a  valid  Roman  numeral'


Error string shown in exception raised when invalid roman numeral is encountered



74.2.2         Constants

AnsiResemblesProc  :  TCompareTextProc  =  @SoundexProc


This procedural variable is standard set to SoundexProc (1229   ) 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']



                                                            1204

_______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________________________*
 *___



Set of digit characters


StdSwitchChars  =  ['-',  '/']


Standard characters for the SwitchChars argument of GetCmdLineArg (1217   ).


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 (1227   ) call.



74.2.3         Types

TCompareTextProc  =  function(const  AText:  string;const  AOther:  string)
                                                :  Boolean


Function prototype for comparing two string in AnsiResemblesText (1210   )


TRomanConversionStrictness  =  (rcsStrict,rcsRelaxed,rcsDontCare)



              Table 74.2:  Enumeration values for type TRomanConversionStrictness


    __Value________________Explanation____________________________________________________________________________________
      rcsDontCare          Do not check correctness
      rcsRelaxed           Like rcsStrict but allow more than 3 consecutive identical letters.
      rcsStrict            Only accept correct roman numerals.



TRomanConversionStrictness  is  an  enumerated  type  that  can  be  used  to  decide  how  to
react to invalid roman numerals.


rcsStrict      Strict  adherance  to  roman  numerals.  Up  to  3  consecutive  identical  letters.  No
        negative numbers.  Ordering must be correct.

rcsRelaxed         Same as rcsStrict but allow more than 3 consecutive identical letters.

rcsDontCare           Do not check validity at all


TSoundexIntLength  =  1..8


Range of allowed integer soundex lengths.


TSoundexLength  =  1..MaxInt


Range of allowed soundex lengths.


TStringSeachOption  =  TStringSearchOption



                                                                1205

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                There  is  an  typo  error  in  the  original  Borland  StrUtils  unit.  This  type  just  refers  to  the
                correct TStringSearchOption (1206   ) and is provided for compatibility only.


                TStringSearchOption  =  (soDown,soMatchCase,soWholeWord)



                                    Table 74.3:  Enumeration values for type TStringSearchOption


                                                __Value__________________Explanation__________________________
                                                  soDown                 Search in down direction.
                                                  soMatchCase            Match case
                                                  soWholeWord            Search whole words only.



                Possible options for SearchBuf (1227   ) call.


                TStringSearchOptions  =  Set  of  TStringSearchOption


                Set of options for SearchBuf (1227   ) call.



                74.3          Procedures  and  functions



                74.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 (1206   ), PadLeft (1222   ), PadRight (1223   ), PadCenter (1222   )



                74.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 (1206   )



                                                                                1206

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1207   ), AnsiEndsStr (1207   ), AnsiIndexStr (1208   ), AnsiStartsStr (1211   )



                74.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.

    See also:    AnsiContainsStr (1207   ), AnsiEndsText (1207   ), AnsiIndexText (1208   ), AnsiStartsText (1211   )



                74.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 (1207   ), AnsiStartsStr (1211   ), AnsiIndexStr (1208   ), AnsiContainsStr (1207   )



                74.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.



                                                                                1207

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



       Errors:   None

    See also:    AnsiStartsText (1211   ), AnsiEndsStr (1207   ), AnsiIndexText (1208   ), AnsiContainsText (1207   )



                74.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

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 (1208   ), AnsiMatchStr (1209   ), AnsiMatchText (1209   )



                74.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 (1208   ), AnsiMatchStr (1209   ), AnsiMatchText (1209   )



                74.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  (1209   ),  AnsiRightStr  (1211   ),  LeftStr  (1220   ),  RightStr  (1226   ),  MidStr  (1221   ),
                LeftBStr (1220   ), RightBStr (1226   ), MidBStr (1221   )



                                                                                1208

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1208   ) and checks whether it returns -1 or not.



                74.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 (1208   ) and checks whether it returns -1 or not.



                74.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  (1208   ),  AnsiRightStr  (1211   ),  LeftStr  (1220   ),  RightStr  (1226   ),  MidStr  (1221   ),
                LeftBStr (1220   ), RightBStr (1226   ), MidBStr (1221   )



                74.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 (1205   ) can be used for this.



                                                                                1209

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1210   ), SearchBuf (1227   )



                74.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 (1210   ), SearchBuf (1227   )



                74.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 (1204   ) 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 (1204   ), SoundexProc (1229   )



                74.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.



                                                                                1210

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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  (1208   ),  AnsiMidStr  (1209   ),  LeftStr  (1220   ),  RightStr  (1226   ),  MidStr  (1221   ),
                LeftBStr (1220   ), RightBStr (1226   ), MidBStr (1221   )



                74.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.

    See also:    AnsiEndsStr (1207   ), AnsiStartsStr (1211   ), AnsiIndexStr (1208   ), AnsiContainsStr (1207   )



                74.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 (1207   ), AnsiStartsStr (1211   ), AnsiIndexText (1208   ), AnsiContainsText (1207   )



                                                                                1211

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1218   )



                74.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 (1213   ) with the space (ASCII code 32) as the symbol
                argument.

       Errors:   None.

    See also:    Copy2Symb (1213   ), Copy2SpaceDel (1212   )



                74.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  (1213   )  with  the  space  (ASCII  code  32)  as  the
                symbol argument.

       Errors:   None.

    See also:    Copy2SymbDel (1213   ), Copy2Space (1212   )



                                                                                1212

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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:     Copy2Symb 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 (1212   ), Copy2SymbDel (1213   )



                74.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 and 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 (1212   ), Copy2Symb (1213   )



                74.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.  N  must  be  a  positive  integer.
                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 (1218   ), IntToBin (1218   ), intToRoman (1219   ), RomanToInt (1226   )



                74.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



                                                                                1213

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



Description:     DecodeSoundexInt  converts  the  integer  value  AValue  to  a  soundex  string.   It  performs
                the reverse operation of the SoundexInt (1229   ) function.  The result is the soundex string
                corresponding to AValue.  .

       Errors:   None.

    See also:    SoundexInt (1229   ), DecodeSoundexWord (1214   ), Soundex (1228   )



                74.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 (1230   ) function.  The result is the soundex string
                corresponding to AValue .

       Errors:   None.

    See also:    SoundexInt (1229   ), DecodeSoundexInt (1213   ), Soundex (1228   )



                74.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 (1214   ), DelSpace1 (1215   )



                74.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 (1214   ), DelSpace1 (1215   )



                                                                                1214

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1214   ), DelSpace (1214   )



                74.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.



                74.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 (1216   ), an empty string is a valid return value, i.e.  a part can
                be empty.

                The pre-defined constant StdWordDelims (1205   ) can be used for the Delims argument.  The
                pre-defined  constant  Brackets  (1204   )  would  be  better  suited  the  Delims  argument  e.g.  in
                case factors in a mathematical expression are searched.

       Errors:   None.

    See also:    ExtractSubStr (1216   ), ExtractWord (1216   ), ExtractWordPos (1216   )



                                                                                1215

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1205   ) can be used for the Delims argument.

       Errors:   None.

    See also:    ExtractDelimited (1215   ), ExtractWord (1216   ), ExtractWordPos (1216   )



                74.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  (1215   ),  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 (1205   ) can be used for the WordDelims argument.

       Errors:   None.

    See also:    ExtractWordPos  (1216   ),  ExtractSubStr  (1216   ),  ExtractDelimited  (1215   ),  IsWordPresent
                (1220   ), WordCount (1232   ), WordPosition (1232   )



                74.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.



                                                                                1216

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                Unlike  ExtractDelimited  (1215   ),  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 (1205   ) can be used for the WordDelims argument.

       Errors:   None.

    See also:    ExtractWord  (1216   ),  ExtractSubStr  (1216   ),  IsWordPresent  (1220   ),  WordCount  (1232   ),
                WordPosition (1232   )



                74.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 (1227   )



                74.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 (1205   ) 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 "-option2" as the result of the GetCmdLineArg call for option1.

    See also:    StdSwitchChars (1205   )



                                                                                1217

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1213   ), IntToBin (1218   ), intToRoman (1219   ), RomanToInt (1226   )



                74.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 (1212   )



                74.3.41          IfThen

    Synopsis:    Returns one of two strings, depending on a boolean expression

Declaration:     function  IfThen(AValue:  Boolean;const  ATrue:  string;
                                         const  AFalse:  string)  :  string;    Overload

    Visibility:   default

Description:     IfThen returns ATrue if  AValue is True, and returns AFalse if  AValue is false.

       Errors:   None.

    See also:    AnsiMatchStr (1209   ), AnsiMatchText (1209   )



                74.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

    Visibility:   default



                                                                                1218

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



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 (1218   ), IntToRoman (1219   )



                74.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 (1226   ), Hex2Dec (1218   ), IntToBin (1218   )



                74.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 (1219   ), FindPart (1217   ), IsWordPresent (1220   )



                74.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 (1227   ), FindPart (1217   )



                                                                                1219

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1227   ) function with the soWholeWords option
                specified.

       Errors:   None.

    See also:    SearchBuf (1227   )



                74.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 (1220   ), AnsiLeftStr (1208   ), RightBStr (1226   ), MidBStr (1221   )



                74.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 (1220   ), AnsiLeftStr (1208   ), RightStr (1226   ), MidStr (1221   )



                                                                                1220

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1220   ), AnsiMidStr (1209   ), RightBStr (1226   ), MidStr (1221   )



                74.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 (1220   ), AnsiMidStr (1209   ), RightStr (1226   ), MidBStr (1221   )



                74.3.51          NPos

    Synopsis:    Returns the position of the N-th occurrence 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 (1232   ), FindPart (1217   )



                                                                                1221

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1218   ), Numb2USA (1222   )



                74.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.



                74.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 (1222   ), PadRight (1223   ), AddChar (1206   ), AddCharR (1206   )



                74.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 (1222   ), PadCenter (1222   ), AddChar (1206   ), AddCharR (1206   )



                                                                                1222

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.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 (1222   ), PadCenter (1222   ), AddChar (1206   ), AddCharR (1206   )



                74.3.57          PosEx

    Synopsis:    Search for the occurrence 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 (1221   ), AnsiContainsText (1207   ), AnsiContainsStr (1207   )



                74.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 (1223   ), PosSetEx (1223   ), #rtl.system.pos (1407   ), RPosEx (1227   )



                74.3.59          PosSetEx

    Synopsis:    Return  the  position  in  a  string  of  any  character  out  of  a  set  of  characters,  starting  at  a
                certain position



                                                                                1223

                _______________________________________________________CHAPTER_74.___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 (1223   ), PosSet (1223   ), #rtl.system.pos (1407   ), RPosEx (1227   )



                74.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 (1209   ), AnsiMatchText (1209   )



                74.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 (1642   ) which used whitespace as the set.

       Errors:   None.

    See also:    TrimLeft (1642   ), RemoveTrailingChars (1225   ), RemovePadChars (1224   ), TrimLeftSet (1231   )



                74.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 (1641   ) which used whitespace as the set.



                                                                                1224

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    Trim  (1641   ),  RemoveLeadingChars  (1224   ),  RemoveTrailingChars  (1225   ),  TrimSet  (1232   ),
                TrimLeftSet (1231   ), TrimRightSet (1231   )



                74.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 (1642   ) which used whitespace as the set.

    See also:    TrimRight (1642   ), RemoveLeadingChars (1224   ), TrimRightSet (1231   )



                74.3.64          ReplaceStr

    Synopsis:    Replace strings case-sensitively

Declaration:     function  ReplaceStr(const  AText:  string;const  AFromText:  string;
                                                const  AToText:  string)  :  string

    Visibility:   default

Description:     ReplaceStr is a utility function that scans AText and replaces all occurrences of AFromText
                with AToText and returns the resulting string.  It simply calls StringReplace (1619   ) with the
                appropriate options.

    See also:    StringReplace (1619   ), ReplaceText (1225   )



                74.3.65          ReplaceText

    Synopsis:    Replace strings case-insensitively

Declaration:     function  ReplaceText(const  AText:  string;const  AFromText:  string;
                                                 const  AToText:  string)  :  string

    Visibility:   default

Description:     ReplaceText is a utility function that scans AText and replaces all occurrences of AFromText
                (case insensitive) with AToTextand returns the resulting string.  It simply calls StringReplace
                (1619   ) with the appropriate options.

    See also:    StringReplace (1619   ), ReplaceText (1225   )



                74.3.66          ReverseString

    Synopsis:    Reverse characters in a string

Declaration:     function  ReverseString(const  AText:  string)  :  string

    Visibility:   default



                                                                                1225

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



Description:     ReverseString returns a string, made up of the characters in string AText, in reverse order.

       Errors:   None.

    See also:    RandomFrom (1224   )



                74.3.67          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 (1220   ), AnsiRightStr (1211   ), RightStr (1226   ), MidBStr (1221   )



                74.3.68          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 (1220   ), AnsiRightStr (1211   ), RightBStr (1226   ), MidStr (1221   )



                74.3.69          RomanToInt

    Synopsis:    Convert a string with a Roman number to it's decimal value.

Declaration:     function  RomanToInt(const  S:  string;
                                                Strictness:  TRomanConversionStrictness)  :  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.  The level of error
                checking is determined by the strictness parameter, the values are described in the type
                TRomanConversionStrictness (1205   ).

       Errors:   On error, a EConvertError (1204   ) exception is raised.

    See also:    TRomanConversionStrictness  (1205   ),  IntToRoman  (1219   ),  Hex2Dec  (1218   ),  Numb2Dec
                (1222   )



                                                                                1226

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.3.70          RomanToIntDef

    Synopsis:    Convert a roman numeral to an integer value

Declaration:     function  RomanToIntDef(const  S:  string;const  ADefault:  LongInt;
                                                     Strictness:  TRomanConversionStrictness)  :  LongInt

    Visibility:   default

Description:     RomanToInt converts the roman numeral in S to an integer and returns the integer value.
                The strictness of the conversion algorithm is determined by Strictness.  If the conversion
                fails, ADefault is returned.

    See also:    TRomanConversionStrictness  (1205   ),  TryRomanToInt  (1232   ),  RomanToInt  (1226   ),  Int-
                ToRoman (1219   )



                74.3.71          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 (1227   )



                74.3.72          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

    Visibility:   default

Description:     RPos looks in S for the character C or the string SubStr.  It starts looking at position Offs
                (counted from the start 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:    RPos (1227   )



                74.3.73          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



                                                                                1227

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



    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  (1206   )
                specifies how the search is conducted.  It is a set of the following options:



                                                                       Table 74.4:



                __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 (1205   ) 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 (1217   ), ExtractWord (1216   ), ExtractWordPos (1216   ), ExtractSubStr (1216   ), Is-
                WordPresent (1220   )



                74.3.74          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.

                Note that AText may not contain null characters.

       Errors:   None.

    See also:    SoundexCompare  (1228   ),  SoundexInt  (1229   ),  SoundexProc  (1229   ),  SoundexWord  (1230   ),
                SoundexSimilar (1229   )



                74.3.75          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



                                                                                1228

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



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 (1228   ), SoundexInt (1229   ), SoundexProc (1229   ), SoundexWord (1230   ), SoundexSim-
                ilar (1229   )



                74.3.76          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 (1228   ) code (with length ALength, default 4) of AText,
                and converts the code to an integer value.

       Errors:   None.

    See also:    Soundex (1228   ), SoundexCompare (1228   ), SoundexProc (1229   ), SoundexWord (1230   ), SoundexSim-
                ilar (1229   )



                74.3.77          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 (1210   ) 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 (1228   ), SoundexCompare (1228   ), SoundexInt (1229   ), SoundexWord (1230   ), SoundexSim-
                ilar (1229   )



                74.3.78          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.



                                                                                1229

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    Soundex (1228   ), SoundexCompare (1228   ), SoundexInt (1229   ), SoundexProc (1229   ), Soundex-
                Word (1230   ), Soundex (1228   )



                74.3.79          SoundexWord

    Synopsis:    Calculate a word-sized soundex value

Declaration:     function  SoundexWord(const  AText:  string)  :  Word

    Visibility:   default

Description:     SoundexInt computes the Soundex (1228   ) code (with length 4) of  AText, and converts the
                code to a word-sized value.

                AText may not contain null characters.

       Errors:   None.

    See also:    Soundex (1228   ), SoundexCompare (1228   ), SoundexInt (1229   ), SoundexProc (1229   ), SoundexSim-
                ilar (1229   )



                74.3.80          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 (1619   ).

                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:    StringReplace (1619   ), TReplaceFlags (1511   )



                74.3.81          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.



                                                                                1230

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



       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  (1217   ),  DelChars  (1214   ),  DelSpace  (1214   ),  ExtractSubStr  (1216   ),  DupeString
                (1215   )



                74.3.82          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 (1230   ), FindPart (1217   ), ExtractWord (1216   ), DelChars (1214   ), DelSpace (1214   ),
                DelSpace1 (1215   ), DupeString (1215   )



                74.3.83          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  (1224   ),  but  returns  the
                resulting string.

       Errors:   None.

    See also:    TrimLeft (1642   ), RemoveLeadingChars (1224   ), RemoveTrailingChars (1225   ), RemovePad-
                Chars (1224   ), TrimSet (1232   ), TrimRightSet (1231   )



                74.3.84          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

Description:     TrimLeftSet  performs  the  same  action  as  RemoveTrailingChars  (1225   ),  but  returns  the
                resulting string.

       Errors:   None.

    See also:    TrimRight (1642   ), RemoveLeadingChars (1224   ), RemoveTrailingChars (1225   ), RemovePad-
                Chars (1224   ), TrimSet (1232   ), TrimLeftSet (1231   )



                                                                                1231

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                74.3.85          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  (1224   ),  but  returns  the  resulting
                string.

       Errors:   None.

    See also:    Trim (1641   ), RemoveLeadingChars (1224   ), RemoveTrailingChars (1225   ), RemovePadChars
                (1224   ), TrimRightSet (1231   ), TrimLeftSet (1231   )



                74.3.86          TryRomanToInt

    Synopsis:    Try to convert a roman numeral to an integer value.

Declaration:     function  TryRomanToInt(S:  string;out  N:  LongInt;
                                                     Strictness:  TRomanConversionStrictness)  :  Boolean

    Visibility:   default

Description:     TryRomanToInt will try to convert the roman numeral in S to an integer and returns the
                integer value in N. The strictness of the conversion algorithm is determined by Strictness.
                If the conversion succeeds, then True is returned, or else False.

    See also:    TRomanConversionStrictness (1205   ), RomanToIntDef (1227   ), RomanToInt (1226   ), IntToRo-
                man (1219   )



                74.3.87          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 (1205   ) constant can be used for the WordDelims argument.

       Errors:   None.

    See also:    WordPosition (1232   ), StdWordDelims (1205   ), ExtractWord (1216   ), ExtractWordPos (1216   )



                74.3.88          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



                                                                                1232

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



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 (1205   ) constant can be used for the WordDelims argument.

       Errors:   None

    See also:    WordCount (1232   ), StdWordDelims (1205   ), ExtractWord (1216   ), ExtractWordPos (1216   )



                74.3.89          XorDecode

    Synopsis:    Decode a string encoded with XorEncode (1233   )

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 (1233   ) 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 (1233   ), XorString (1233   )



                74.3.90          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 (1233   ) 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 (1233   ), XorString (1233   ), Hex2Dec (1218   )



                74.3.91          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



                                                                                1233

                _______________________________________________________CHAPTER_74.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



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 (1233   ) 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 (1233   ), XorDecode (1233   )



                                                                                1234




Chapter   75



Reference   for   unit   'System'



75.1          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
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.



75.2          Unicode  and  codepage  support


The system unit works with Short-, Ansi-, and UnicodeString routines for all string related
operations.

Ansistrings are code-page aware, which means that code page information is associated with
them.  For most routines, the support for converting these code pages is natural.  For some
routines, care must be taken when converting from codepage-aware strings to widestring.

The codepage conversion support is influenced by the following variables:



                                                       Table 75.1:



__Name_______________________________________________________Description___________________________________________________________*
 *__________________________________________
  DefaultSystemCodePage (1300   )                            Actual code page to use when CP_ACP (1241   ) is encountered
  DefaultUnicodeCodePage (1300   )                           Code page for new unicode strings
  DefaultFileSystemCodePage (1299   )                        Codepage to use when sending strings to single-byte OS filesystem rout*
 *ines.
  DefaultRTLFileSystemCodePage (1299   )                     Codepage to use when receiving strings from single-byte OS filesystem *
 *routines.



The windows code page identifiers are used.  There are 3 special codepage identifiers:



                                                            1235

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                                                       Table 75.2:



__Name_______________________________________________________Description___________________________________________________________*
 *_______
  CP_ACP (1241   )                                           Currently set default syststem cpdepage
  CP_OEMCP (1242   )                                         OEM (console) code page (only on windows)
  CP_NONE (1241   )                                          Indicates absence of code page information for a string
  DefaultRTLFileSystemCodePage (1299   )



The following routines may perform code page conversions:



                                                       Table 75.3:

           __Name________________________Description________________________________________________________________
             LowerCase (1398   )         Return lowercase version of a string.
             UpCase (1455   )            Convert a string to all uppercase.
             GetDir (1369   )            Return the current directory
             MkDir (1399   )             Create a new directory.
             ChDir (1334   )             Change current working directory.
             RmDir (1418   )             Remove directory when empty.
             Assign (1307   )            Assign a name to a file
             Erase (1355   )             Delete a file from disk
             Rename (1415   )            Rename file on disk
             Read (1411   )              Read from a text file into variable
             ReadLn (1413   )            Read from a text file into variable and goto next line
             Write (1461   )             Write variable to a text file
             WriteLn (1462   )           Write variable to a text file and append newline
             ReadStr (1413   )           Read variables from a string
             WriteStr (1463   )          Write variables to a string
             Insert (1386   )            Insert one string in another.
             Copy (1342   )              Copy part of a string.
             Delete (1346   )            Delete part of a string.
             SetString (1432   )         Set length of a string and copy buffer.



All these routines exist also in Unicode versions.

Note  that  for  conversion  of  codepages  and  unicode  strings,  a  unicode  manager  must  be
present.   On  windows,  the  system  is  used  for  this.   On  unix,  one  of  the  fpwidestring  or
cwstring units must be used.



75.3          Miscellaneous  functions


Functions that do not belong in one of the other categories.



                                                                1236

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                                                       Table 75.4:

                    __Name______________________Description________________________________________________
                      Assert (1307   )          Conditionally abort program with error
                      Break (1330   )           Abort current loop
                      Continue (1341   )        Next cycle in current loop
                      Exclude (1355   )         Exclude an element from a set
                      Exit (1357   )            Exit current function or procedure
                      Include (1379   )         Include an element into a set
                      LongJmp (1397   )         Jump to execution point
                      Ord (1404   )             Return ordinal value of enumerated type
                      Pred (1409   )            Return previous value of ordinal type
                      SetJmp (1429   )          Mark execution point for jump
                      SizeOf (1436   )          Return size of variable or type
                      Succ (1444   )            Return next value of ordinal type



75.4          Operating  System  functions


Functions that are connected to the operating system.



                                                       Table 75.5:

         __Name__________________________Description__________________________________________________________________
           Chdir (1334   )               Change working directory
           Getdir (1369   )              Return current working directory
           Halt (1375   )                Halt program execution
           Paramcount (1405   )          Number of parameters with which program was called
           Paramstr (1406   )            Retrieve parameters with which program was called
           Mkdir (1399   )               Make a directory
           Rmdir (1418   )               Remove a directory
           Runerror (1423   )            Abort program execution with error condition



75.5          String  handling


All things connected to string handling.



                                                                1237

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                                                       Table 75.6:

           __Name____________________________Description____________________________________________________________
             BinStr (1328   )                Construct binary representation of integer
             Chr (1334   )                   Convert ASCII code to character
             Concat (1340   )                Concatenate two strings
             Copy (1342   )                  Copy part of a string
             Delete (1346   )                Delete part of a string
             HexStr (1375   )                Construct hexadecimal representation of integer
             Insert (1386   )                Insert one string in another
             Length (1392   )                Return length of string
             Lowercase (1398   )             Convert string to all-lowercase
             OctStr (1402   )                Construct octal representation of integer
             Pos (1407   )                   Calculate position of one string in another
             SetLength (1430   )             Set length of a string
             SetString (1432   )             Set contents and length of a string
             Str (1440   )                   Convert number to string representation
             StringOfChar (1441   )          Create string consisting of a number of characters
             Upcase (1455   )                Convert string to all-uppercase
             Val (1458   )                   Convert string to number



75.6          Mathematical  routines


Functions connected to calculating and coverting numbers.



                                                       Table 75.7:

          __Name_________________________Description________________________________________________________________
            Abs (1303   )                Calculate absolute value
            Arctan (1306   )             Calculate inverse tangent
            Cos (1343   )                Calculate cosine of angle
            Dec (1344   )                Decrease value of variable
            Exp (1358   )                Exponentiate
            Frac (1367   )               Return fractional part of floating point value
            Hi (1376   )                 Return high byte/word of value
            Inc (1378   )                Increase value of variable
            Int (1387   )                Calculate integer part of floating point value
            Ln (1394   )                 Calculate logarithm
            Lo (1394   )                 Return low byte/word of value
            Odd (1403   )                Is a value odd or even ?
            Pi (1406   )                 Return the value of pi
            Random (1410   )             Generate random number
            Randomize (1411   )          Initialize random number generator
            Round (1421   )              Round floating point value to nearest integer number
            Sin (1436   )                Calculate sine of angle
            Sqr (1438   )                Calculate the square of a value
            Sqrt (1439   )               Calculate the square root of a value
            Swap (1444   )               Swap high and low bytes/words of a variable
            Trunc (1450   )              Truncate a floating point value



                                                                1238

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



75.7          Memory  management  functions


Functions concerning memory issues.



                                                       Table 75.8:

    __Name_______________________________________Description_______________________________________________________________
      Addr (1304   )                              Return address of variable
      Assigned (1326   )                          Check if a pointer is valid
      CompareByte (1335   )                       Compare 2 memory buffers byte per byte
      CompareChar (1337   )                       Compare 2 memory buffers byte per byte
      CompareDWord (1338   )                      Compare 2 memory buffers byte per byte
      CompareWord (1339   )                       Compare 2 memory buffers byte per byte
      CSeg (1343   )                              Return code segment
      Dispose (1346   )                           Free dynamically allocated memory
      DSeg (1348   )                              Return data segment
      FillByte (1361   )                          Fill memory region with 8-bit pattern
      FillChar (1361   )                          Fill memory region with certain character
      FillDWord (1362   )                         Fill memory region with 32-bit pattern
      FillQWord (1362   )                         Fill memory region with 64-bit pattern
      FillWord (1363   )                          Fill memory region with 16-bit pattern
      Freemem (1367   )                           Release allocated memory
      Getmem (1370   )                            Allocate new memory
      GetMemoryManager (1371   )                  Return current memory manager
      High (1377   )                              Return highest index of open array or enumerated
      IndexByte (1379   )                         Find byte-sized value in a memory range
      IndexChar (1380   )                         Find char-sized value in a memory range
      IndexDWord (1381   )                        Find DWord-sized (32-bit) value in a memory range
      IndexQWord (1382   )                        Find QWord-sized value in a memory range
      IndexWord (1382   )                         Find word-sized value in a memory range
      IsMemoryManagerSet (1391   )                Is the memory manager set
      Low (1397   )                               Return lowest index of open array or enumerated
      Move (1399   )                              Move data from one location in memory to another
      MoveChar0 (1400   )                         Move data till first zero character
      New (1401   )                               Dynamically allocate memory for variable
      Ofs (1403   )                               Return offset of variable
      Ptr (1409   )                               Combine segment and offset to pointer
      ReAllocMem (1415   )                        Resize a memory block on the heap
      Seg (1427   )                               Return segment
      SetMemoryManager (1430   )                  Set a memory manager
      Sptr (1438   )                              Return current stack pointer
      SSeg (1439   )                              Return stack segment register value



75.8          File  handling  functions


Functions concerning input and output from and to file.



                                                                1239

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                                                       Table 75.9:

               __Name_________________________Description_______________________________________________________
                 Append (1306   )             Open a file in append mode
                 Assign (1307   )             Assign a name to a file
                 Blockread (1329   )          Read data from a file into memory
                 Blockwrite (1330   )         Write data from memory to a file
                 Close (1335   )              Close a file
                 Eof (1353   )                Check for end of file
                 Eoln (1354   )               Check for end of line
                 Erase (1355   )              Delete file from disk
                 Filepos (1359   )            Position in file
                 Filesize (1360   )           Size of file
                 Flush (1365   )              Write file buffers to disk
                 IOresult (1389   )           Return result of last file IO operation
                 Read (1411   )               Read from file into variable
                 Readln (1413   )             Read from file into variable and goto next line
                 Rename (1415   )             Rename file on disk
                 Reset (1416   )              Open file for reading
                 Rewrite (1417   )            Open file for writing
                 Seek (1425   )               Set file position
                 SeekEof (1425   )            Set file position to end of file
                 SeekEoln (1426   )           Set file position to end of line
                 SetTextBuf (1432   )         Set size of file buffer
                 Truncate (1451   )           Truncate the file at position
                 Write (1461   )              Write variable to file
                 WriteLn (1462   )            Write variable to file and append newline



75.9          Run-Time  Error  behaviour


The  sytem  unit  handles  errors  by  default  by  generating  a  run-time  error,  and  halting  the
program with an exit code equal to the run-time error number.

This  behaviour  changes  when  the  SysUtils  (1489   )  unit  is  used.  In  that  case,  all  run-time
errors are converted to exceptions:  most run-time errors have their own exception class.

If these exceptions are caught, the program code decides what to do with it.  If the exception
is not caught, the program will exit through the default exception handler.

When the system unit documentation refers to run-time errors, the above should be kept in
mind.



75.10            Constants,  types  and  variables



75.10.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.



                                                                1240

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



AllFilesMask  =  '*'


AllFilesMask is the wildcard that can be used to return all files in a directory.  Do not assume
that this is '*' or '*.*' based on the platform only.  The actual value on DOS/Windows based
systems can be influenced by e.g.  LFNSupport (1254   ).


AllowDirectorySeparators  :  Set  of  Char  =  ['\',  '/']


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.


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.


CP_ACP  =  0


CP_ACP is the default Windows codepage identifier.


CP_ASCII  =  20127


CP_ASCII is the Windows ASCII encoding codepage identifier.


CP_NONE  =  $FFFF


CP_NONE is used when no code page information is available.



                                                                1241

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



CP_OEMCP  =  1


CP_ACP is the default Windows OEM (MS-DOS) codepage identifier.


CP_UTF16  =  1200


CP_UTF16 is the default Windows unicode codepage identifier (little endian).


CP_UTF16BE  =  1201


CP_UTF16BE is the Windows unicode codepage identifier (big endian).


CP_UTF7  =  65000


CP_UTF7 is the Windows unicode 7-Bit encoding codepage identifier.


CP_UTF8  =  65001


CP_UTF8 is the Windows unicode 8-Bit encoding codepage identifier.


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 apart from DOS and Windows.

To get DOS/Windows-compatible behaviour, this constant can be set to True


DefaultStackSize  =  4  *  1024  *  1024


Default size for a new thread's stack (4MiB by default).


DefaultTextLineBreakStyle  :  TTextLineBreakStyle  =  tlbsLF


DefaultTextLineBreakStyle contains the default OS setting for the TTextLineBreakStyle
(1289   ) 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.



                                                                1242

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Erroraddr  :  CodePointer  =  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.


ExceptClsProc  :  Pointer  =  Nil


ExceptClsProc  is  used  in  SEH  (Structured  Exception  Support)  to  convert  OS  exception
information to FPC exception classes when filtering exceptions.  It is set e.g.  by the sysutils
unit.  If it is not set, the exception is not handled.


ExceptObjProc  :  Pointer  =  Nil


ExceptObjProc  is  used  in  SEH  (Structured  Exception  Support)  to  convert  OS  exception
information to FPC exceptions.  It is set e.g.  by the sysutils unit.  If it is not set, a run-time
error results when OS exceptions are intercepted.


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 (1489   ) unit.


ExitProc  :  CodePointer  =  Nil


Exit procedure pointer.


ExtensionSeparator  =  '.'


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  =  ($80004002)


Interface call result:  Error:  not an interface


E_NOTIMPL  =  ($80004001)



                                                                1243

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Interface call result:  Interface not implemented


E_UNEXPECTED  =  ($8000FFFF)


Interface call result:  Unexpected error


Filemode  :  Byte  =  2


Default file mode for untyped files.


FileNameCasePreserving  :  Boolean  =  True


FileNameCasePreserving is True if case of letters in file and directory entries is preserved
and  may  be  later  retrieved  exactly  as  supplied  when  creating  or  renaming  these  entries.
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,
all letters may be automatically converted to uppercase.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


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.


filerecnamelength  =  255


filerecnamelength is the maximum filename size for untyped files.


float_flag_denormal  =  exDenormalized


IEC/IEEE floating-point exception flag:  ?


float_flag_divbyzero  =  exZeroDivide


IEC/IEEE floating-point exception flag:  Division by zero error


float_flag_inexact  =  exPrecision


IEC/IEEE floating-point exception flag:  ?


float_flag_invalid  =  exInvalidOp


IEC/IEEE floating-point exception flag:  Invalid operation error


float_flag_overflow  =  exOverflow



                                                                1244

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



IEC/IEEE floating-point exception flag:  Overflow error


float_flag_underflow  =  exUnderflow


IEC/IEEE floating-point exception flag:  Underflow error


float_round_down  =  rmDown


Round down


float_round_nearest_even  =  rmNearest


Round to nearest even number


float_round_to_zero  =  rmTruncate


Round in the direction of zero (down for positive, up for negative)


float_round_up  =  rmUp


Round up


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_long  =  64


Internal ABS function


fpc_in_abs_real  =  127


FPC compiler internal procedure index:  abs (real)


fpc_in_addr_x  =  42



                                                                1245

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



FPC compiler internal procedure index:  addr


fpc_in_aligned_x  =  80


FPC compiler internal procedure index:  aligned


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_box_x  =  77


FPC compiler internal procedure index:  box


fpc_in_break  =  39


FPC compiler internal procedure index:  break


fpc_in_bsf_x  =  74


FPC compiler internal procedure index:  bsf_x


fpc_in_bsr_x  =  75


FPC compiler internal procedure index:  bsr_x


fpc_in_chr_byte  =  7


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



                                                                1246

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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


FPC compiler internal procedure index:  dec


fpc_in_default_x  =  76


FPC compiler internal procedure index:  default


fpc_in_dispose_x  =  47


FPC compiler internal procedure index:  dispose


fpc_in_exclude_x_y  =  38



                                                                1247

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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_fma_double  =  134


FPC compiler internal procedure index:  fma (double)


fpc_in_fma_extended  =  135


FPC compiler internal procedure index:  fma (extended)


fpc_in_fma_float128  =  136


FPC compiler internal procedure index:  fma (float 128)


fpc_in_fma_single  =  133


FPC compiler internal procedure index:  fma (single)


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



                                                                1248

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



FPC compiler internal procedure index:  high


fpc_in_hi_long  =  4


FPC compiler internal procedure index:  hi (long)


fpc_in_hi_qword  =  107


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



                                                                1249

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



FPC compiler internal procedure index:  lo (qword)


fpc_in_lo_word  =  1


FPC compiler internal procedure index:  lo (word)


fpc_in_mmx_pcmpeqb  =  200


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



                                                                1250

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



FPC internal compiler routine:  in_pi_real


fpc_in_popcnt_x  =  79


FPC compiler internal procedure index:  popcnt


fpc_in_pred_x  =  30


FPC compiler internal procedure index:  pred


fpc_in_prefetch_var  =  109


FPC compiler internal procedure index:  prefetch


fpc_in_readln_x  =  17


FPC compiler internal procedure index:  readln


fpc_in_readstr_x  =  63


Internal read string procedure


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_rol_x  =  67



fpc_in_rol_x_x  =  68



fpc_in_ror_x  =  65



fpc_in_ror_x_x  =  66



                                                                1251

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



fpc_in_round_real  =  121


FPC internal compiler routine:  in_round_real


fpc_in_sar_x  =  73


FPC compiler internal procedure index:  sar_x


fpc_in_sar_x_y  =  72


FPC compiler internal procedure index:  sar_x_y


fpc_in_seg_x  =  29


FPC compiler internal procedure index:  seg


fpc_in_setlength_x  =  44


FPC compiler internal procedure index:  setlength


fpc_in_setstring_x_y_z  =  81


FPC compiler internal procedure index:  setstring


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


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



                                                                1252

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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_unbox_x_y  =  78


FPC compiler internal procedure index:  unbox


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_writestr_x  =  62


Internal write string procedure


fpc_in_write_x  =  14


FPC compiler internal procedure index:  write


fpc_objc_encode_x  =  71


FPC compiler internal procedure index:  encode


fpc_objc_protocol_x  =  70


FPC compiler internal procedure index:  protocol


fpc_objc_selector_x  =  69



                                                                1253

               __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'_________________*
 *__________________



               growheapsize1  :  PtrUInt  =  256  *  1024


               Grow rate for block less than 256 Kb.


               growheapsize2  :  PtrUInt  =  1024  *  1024


               Grow rate for block larger than 256 Kb.


               growheapsizesmall  :  PtrUInt  =  32  *  1024


               Fixed size small blocks grow rate


               InitProc  :  CodePointer  =  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.


               IObjectInstance  :  TGuid  =  '{D91C9AF4-3C93-420F-A303-BF5BA82BFD23}'


               IObjectInstance  is  an  internal  GUID,  which  should  not  be  used  in  end-user  code.  It  is
               used in the as operator.


               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 (1375   ) call.


               maxint  =  maxsmallint


               Maximum integer value.



                                                                               1254

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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.


MaxPathLen  =  4096


This constant is system dependent.


MaxSIntValue  =  (ValSInt)


Maximum String-size value.


maxSmallint  =  32767


Maximum smallint value.


MaxUIntValue  =  (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.



                                                                1255

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



RaiseMaxFrameCount  :  LongInt  =  16


Maximum number of frames to include in TExceptObject (1280   )


RaiseProc  :  TExceptProc  =  Nil


Procedure to raise an exception.


RT_ACCELERATOR  =  (9)


Constant identifying an accelerator resouce


RT_ANICURSOR  =  (21)


This constant can be used to specify a resource of type "animated cursor".


RT_ANIICON  =  (22)


This constant can be used to specify a resource of type "animated icon".


RT_BITMAP  =  (2)


Constant identifying a bitmap resource


RT_CURSOR  =  (1)


Constant identifying a cursor resource


RT_DIALOG  =  (5)


Constant identifying a dialog resource


RT_FONT  =  (8)


Constant identifying a font resource


RT_FONTDIR  =  (7)


Constant identifying a font directory resource


RT_GROUP_CURSOR  =  (12)


Constant identifying a group cursor resource


RT_GROUP_ICON  =  (14)


Constant identifying a group icon resource


RT_HTML  =  (23)


This constant can be used to specify a resource of type "HTML data".



                                                                1256

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



RT_ICON  =  (3)


Constant identifying an icon resource


RT_MANIFEST  =  (24)


This constant can be used to specify a resource of type "Manifest".


RT_MENU  =  (4)


Constant identifying a menu resource


RT_MESSAGETABLE  =  (11)


Constant identifying a message data resource


RT_RCDATA  =  (10)


Constant identifying a binary data resource


RT_STRING  =  (6)


Constant identifying a string table resource


RT_VERSION  =  (16)


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 (1355   ) routine to convert a TRuntimeError (1287   ) enumer-
ation 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.


sLineBreak  =  LineEnding


sLineBreak is an alias for LineEnding (1254   ) 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



                                                                1257

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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


TextRecBufSize  =  256


TextRecBufSize  is  the  default  buffer  size  for  text  files.   The  actual  buffer  can  be  set  to
another size using SetTextBuf (1432   ).


TextRecNameLength  =  256


TextRecNameLength is the maximum filename size for text files.


ThreadingAlreadyUsed  :  Boolean  =  False


Internal constant for the threading system.  Don't use.


UnixGetModuleByAddrHook  :  procedure(addr:  pointer;var  baseaddr:  pointer;var  filename:  string)  =  Nil


UnixGetModuleByAddrHook  is  used  on  unix  systems  to  retrieve  a  module  name  based  on
an address.  It is used in the exeinfo (662  ) unit to map addresses to module (programs or
library) names.


UnusedHandle  =  -1


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



                                                                1258

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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


Variant type:  Double float


varempty  =  0


Variant type:  Empty variant


varerror  =  10


Variant type:  Error type


varint64  =  20



                                                                1259

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Variant type:  Integer (64-Bit)


varinteger  =  3


Variant type:  Integer (32-bit)


varlongword  =  19


Variant type:  Word (32 bit)


varnull  =  1


Variant type:  Null (1402   ) variant


varolestr  =  8


Variant type:  OLE string (widestring)


varqword  =  21


Variant type:  Word (64-bit)


varrecord  =  36


Record variant type


varshortint  =  16


Variant type:  Shortint (16 bit)


varsingle  =  4


Variant type:  Single float


varsmallint  =  2


Variant type:  smallint (8 bit)


varstrarg  =  $48


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



                                                                1260

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Callback to convert a variant to a widestring.


vartypemask  =  $fff


Variant type:  Mask to extract type


varuint64  =  varqword


varuint64 denotes an unsigned 64-bit value in a variant.  It is one of the values found in the
VType field of the variant record tvardata (1293   ).


varunknown  =  13


Variant type:  Unknown


varustrarg  =  $49


varustrarg denotes a unicode string argument in DispInvoke call.  It will be converted to
varustring in a variant.


varustring  =  $102


varustring denotes a unicode string value in a variant.  It is one of the values found in the
VType field of the variant record tvardata (1293   ).


varvariant  =  12


Variant type:  Variant (arrays only)


varword  =  18


Variant type:  Word (16 bit)


varword64  =  varqword


Variant type:  Word (64-bit)


vmtAfterConstruction  =  vmtMethodStart  +  ((codepointer)  *  5)


VMT Layout:  ?


vmtAutoTable  =  vmtParent  +  ((pointer)  *  7)


VMT layout:  ?


vmtBeforeDestruction  =  vmtMethodStart  +  ((codepointer)  *  6)


VMT Layout:  ?


vmtClassName  =  vmtParent  +  (pointer)



                                                                1261

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



VMT Layout:  location of class name.


vmtDefaultHandler  =  vmtMethodStart  +  ((codepointer)  *  4)


VMT Layout:  ?


vmtDefaultHandlerStr  =  vmtMethodStart  +  ((codepointer)  *  7)


VMT Layout:  ?


vmtDestroy  =  vmtMethodStart


VMT Layout:  Location of destructor pointer.


vmtDispatch  =  vmtMethodStart  +  ((codepointer)  *  8)


vmtDispatch is the offset from the VMT start, in bytes to the dispatch table for a class.The
dispatch table is used when dispatching messages in TObject.Dispatch (1485   )


vmtDispatchStr  =  vmtMethodStart  +  ((codepointer)  *  9)


vmtDispatchStr  is  the  offset  from  the  VMT  start,  in  bytes  to  the  dispatch  table  for  a
class.The dispatch table is used when dispatching messages in TObject.DispatchStr (1485   )


vmtDynamicTable  =  vmtParent  +  ((pointer)  *  2)


VMT Layout:  location of dynamic methods table.


vmtEquals  =  vmtMethodStart  +  ((codepointer)  *  10)


vmtEquals contains the offset from the VMT start,  of the location of the TObject.Equals
(1488   ) method pointer.


vmtFieldTable  =  vmtParent  +  ((pointer)  *  4)


VMT Layout:  Location of fields table.


vmtFreeInstance  =  vmtMethodStart  +  ((codepointer)  *  2)


VMT Layout:  location of FreeInstance method.


vmtGetHashCode  =  vmtMethodStart  +  ((codepointer)  *  11)


vmtGetHashCode  contains  the  offset  from  the  VMT  start,  of  the  location  of  the  TOb-
ject.GetHashCode (1488   ) method pointer.


vmtInitTable  =  vmtParent  +  ((pointer)  *  6)


VMT Layout:  ?


vmtInstanceSize  =  0



                                                                1262

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



VMT Layout:  Location of class instance size in VMT


vmtIntfTable  =  vmtParent  +  ((pointer)  *  8)


VMT layout:  Interface table


vmtMethodStart  =  vmtParent  +  ((pointer)  *  10)


VMT layout:  start of method table.


vmtMethodTable  =  vmtParent  +  ((pointer)  *  3)


VMT Layout:  Method table start.


vmtMsgStrPtr  =  vmtParent  +  ((pointer)  *  9)


VMT layout:  message strings table.


vmtNewInstance  =  vmtMethodStart  +  (codepointer)


VMT Layout:  location of NewInstance method.


vmtParent  =  (SizeInt)  *  2


VMT Layout:  location of pointer to parent VMT.


vmtSafeCallException  =  vmtMethodStart  +  ((codepointer)  *  3)


VMT Layout:  ?


vmtToString  =  vmtMethodStart  +  ((codepointer)  *  12)


vmtToString contains the offset from the VMT start, of the location of the TObject.ToString
(1488   ) method pointer.


vmtTypeInfo  =  vmtParent  +  ((pointer)  *  5)


VMT Layout:  Location of class type information.


vtAnsiString  =  11


TVarRec type:  Ansistring


vtBoolean  =  1


TVarRec type:  Boolean


vtChar  =  2


TVarRec type:  Char



                                                                1263

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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


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


vtUnicodeString  =  18



                                                                1264

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



vtUnicodeString denotes a unicode string argument in the array of const.  The TVarRec.VUnicodeString
field will contain the actual value.


vtVariant  =  13


TVarRec type:  Variant


vtWideChar  =  9


TVarRec type:  Widechar


vtWideString  =  15


TVarRec type:  WideString



75.10.2          Types

AnsiChar  =  Char


Alias for 1-byte sized char.


Byte  =  0..255


An unsigned 8-bits integer


Cardinal  =  LongWord


An unsigned 32-bits integer.


Char  =  #0..#255


Char is the basic ANSI character type, with a range of [#0..#255].


CodePointer  =  Pointer


CodePointer is used in 8/16-bit targets to indicate pointers to code segments.  On all other
platforms this equals Pointer.


CodePtrInt  =  PtrInt


CodePtrInt is a signed integer with the same size as CodePointer (1265   )


CodePtrUInt  =  PtrUInt


CodePtrUInt is an unsigned integer with the same size as CodePointer (1265   )


DWord  =  LongWord


An unsigned 32-bits integer



                                                                1265

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



EnumResLangProc  =  function(ModuleHandle:  TFPResourceHMODULE;
                                            ResourceType:  PChar;ResourceName:  PChar;
                                            IDLanguage:  Word;lParam:  PtrInt)  :  LongBool


EnumResNameProcs  used  in  the  EnumResourceLanguages  (1352   )  call.   It  is  called  for  all
languages for a resource of the specified type and name,  and is passed the ModuleHandle,
ResourceName, ResourceName and IDLanguage values for each language encountered for the
specified resource.  Additionally,  the lParam parameter from the EnumResourceLanguages
is passed unaltered.


EnumResNameProc  =  function(ModuleHandle:  TFPResourceHMODULE;
                                            ResourceType:  PChar;ResourceName:  PChar;
                                            lParam:  PtrInt)  :  LongBool


EnumResNameProcs used in the EnumResourceNames (1352   ) call.  It is called for all resources
of the specified type, and is passed the ModuleHandle, ResourceType, ResourceName values
for each resource encountered.  Additionally, the lParam parameter from the EnumResourceNames
is passed unaltered.


EnumResTypeProc  =  function(ModuleHandle:  TFPResourceHMODULE;
                                            ResourceType:  PChar;lParam:  PtrInt)
                                              :  LongBool


EnumResTypeProc is used in the EnumResourceTypes (1353   ) call.  It is called for all resources,
and is passed the ModuleHandle, ResourceType values for each resource encountered.  Ad-
ditionally, the lParam parameter from the EnumResourceTypes is passed unaltered.


FarPointer  =  Pointer


FarPointer is used in 8/16-bit targets to indicate far pointers (over segments).  On all other
platforms this equals Pointer.


FileRec  =  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  TFileTextRecChar;
end



FileRec is the underlying type used in untyped files.  It should be treated as opaque and
never manipulated directly.


HGLOBAL  =  PtrUInt


This is an opaque type.


HMODULE  =  PtrUInt


This is an opaque type.



                                                                1266

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



HRESULT  =  LongInt


32-Bit signed integer.


IInterface  =  IUnknown


IInterface is the basic interface from which all COM style interfaces descend.


Int16  =  SmallInt


A signed 16-bits integer


Int32  =  LongInt


A signed 32-bits integer


Int64  =  -9223372036854775808..9223372036854775807


Int64 is a 64-bit, signed integer type, with range [-9223372036854775808..9223372036854775807].


Int8  =  ShortInt


A signed 8-bits integer


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.


IntPtr  =  PtrInt


A signed integer with the same size in bytes as pointer


jmp_buf  =  packed  record
   ebx  :  LongInt;
   esi  :  LongInt;
   edi  :  LongInt;
   bp  :  Pointer;
   sp  :  Pointer;
   pc  :  Pointer;
end



Record type to store processor information.


Longint  =  -2147483648..2147483647



                                                                1267

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



A signed 32-bits integer


Longword  =  0..4294967295


The base 32-bit unsigned type.  See the reference manual for more details


MAKEINTRESOURCE  =  PChar


Alias for the PChar (1268   ) type.


NativeInt  =  PtrInt


NativeInt is defined for Delphi compatibility.  It is a signed integer with the size of a pointer,
so 32-bit on 32-bit platforms, 64-bit on 64-bit platforms.


NativeUInt  =  PtrUInt


NativeInt is defined for Delphi compatibility.  It is an unsigned integer with the size of a
pointer, so 32-bit on 32-bit platforms, 64-bit on 64-bit platforms.


PAnsiChar  =  PChar


Alias for PChar (1268   ) type.


PAnsiString  =  ^AnsiString


Pointer to an ansistring type.


PBoolean  =  ^Boolean


Pointer to a Boolean type.


PByte  =  ^Byte


Pointer to byte (1265   ) type


pcalldesc  =  ^tcalldesc


Pointer to TCallDesc (1278   ) record.


PCardinal  =  ^Cardinal


Pointer to Cardinal (1265   ) 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



                                                                1268

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Pointer to TClass (1278   )


PCodePointer  =  ^CodePointer


PCodePointer is a typed pointer to CodePointer (1265   ).


PComp  =  ^Comp


PComp is a pointer to a complex type.


PCurrency  =  ^Currency


Pointer to currency type.


PDate  =  ^TDateTime


Pointer to a TDateTime (1278   ) type.


PDateTime  =  ^TDateTime


Pointer to TDatetime


PDispatch  =  ^IDispatch


Pointer to IDispatch (1471   ) interface type


pdispdesc  =  ^tdispdesc


Pointer to tdispdesc (1278   ) record


PDouble  =  ^Double


Pointer to double-sized float value.


PDWord  =  ^DWord


Pointer to DWord (1265   ) type


pdynarrayindex  =  ^tdynarrayindex


Pointer to tdynarrayindex (1279   ) type.


pdynarraytypeinfo  =  ^tdynarraytypeinfo


Pointer to TDynArrayTypeInfo (1279   ) type.


PError  =  ^TError


Pointer to an Error (1355   ) type.


PEventState  =  pointer



                                                                1269

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Pointer to EventState, which is an opaque type.


PExceptObject  =  ^TExceptObject


Pointer to Exception handler procedural type TExceptProc (1280   )


PExtended  =  ^Extended


Pointer to extended-sized float value.


PFileTextRecChar  =  ^TFileTextRecChar


PFileTextRecChar is a typed pointer to TFileTextRecChar (1280   ).


PGuid  =  ^TGuid


Pointer to TGUID (1283   ) type.


pInt16  =  PSmallInt


Pointer to Int16 (1267   ) type


pInt32  =  PLongint


Pointer to Int32 (1267   ) type


PInt64  =  ^Int64


Pointer to Int64 type


pInt8  =  PShortInt


Pointer to Int8 (1267   ) type


PInteger  =  ^Integer


Pointer to integer (1267   ) type


PIntegerArray  =  ^IntegerArray


Pointer to IntegerArray (1267   ) type


PInterface  =  PUnknown


Pointer to IInterface (1267   ) interface


pinterfaceentry  =  ^tinterfaceentry


Pointer to tinterfaceentry (1284   ) record.


pinterfacetable  =  ^tinterfacetable



                                                                1270

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Pointer to tinterfacetable (1284   ) record.


PIntPtr  =  PPtrInt


Pointer to IntPtr (1267   ) type


PJmp_buf  =  ^jmp_buf


Pointer to jmp_buf (1267   ) record


PLongBool  =  ^LongBool


Pointer to a LongBool type.


PLongint  =  ^LongInt


Pointer to Longint (1268   ) type


PLongWord  =  ^LongWord


Pointer to LongWord type


PMemoryManager  =  ^TMemoryManager


Pointer to TMemoryManager (1285   ) record


PMsgStrTable  =  ^TMsgStrTable


Pointer to array of TMsgStrTable (1285   ) records.


PNativeInt  =  ^NativeInt


Pointer to NativeInt (1268   ) type


PNativeUInt  =  ^NativeUInt


Pointer to NativeInt (1268   ) type


PointerArray  =  Array[0..512*1024*1024-2]  of  Pointer


Generic pointer array.


POleVariant  =  ^OleVariant


Pointer to OleVariant type.


PPAnsiChar  =  PPChar


Alias for PPChar (1272   ) type.


PPByte  =  ^PByte



                                                                1271

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



PPByte is a pointer to a PByte (1268   ) type.


PPChar  =  ^PChar


Pointer to an array of pointers to null-terminated strings.


PPCharArray  =  ^TPCharArray


Pointer to TPCharArray (1285   ) type.


PPCodePointer  =  ^PCodePointer


PPCodePointer is a typed pointer to PCodePointer (1269   ).


PPDispatch  =  ^PDispatch


Pointer to PDispatch (1269   ) pointer type


PPDouble  =  ^PDouble


PPDouble is a pointer to a PDouble (1269   ) type.


PPLongint  =  ^PLongint


PPLongint is a pointer to a PLongint (1271   ) type.


PPointer  =  ^Pointer


Pointer to a pointer type.


PPointerArray  =  ^PointerArray


Pointer to PointerArray (1271   ) type


PPPAnsiChar  =  PPPChar


PPPAnsiChar is a typed pointer to PPAnsichar (1271   ).


PPPChar  =  ^PPChar


PPPChar is a pointer to a PPChar (1272   )


PPPointer  =  ^PPointer


Pointer to a PPointer (1272   ) type.


PPPWideChar  =  ^PPWideChar


PPPWideChar is a pointer to a PPWideChar (1273   ) type.


PPtrInt  =  ^PtrInt



                                                                1272

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Pointer to PtrInt (1274   ) 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 (1286   ) type.


PRTLEvent  =  pointer


Pointer to RTLEvent, which is an opaque type.


PShortInt  =  ^ShortInt


Pointer to shortint (1276   ) type


PShortString  =  ^ShortString


Pointer to a shortstring type.


PSingle  =  ^Single


Pointer to single-sized float value.


PSizeInt  =  ^SizeInt


Pointer to a SizeInt (1276   ) type


PSmallInt  =  ^SmallInt


Pointer to smallint (1277   ) type


pstringmessagetable  =  ^TStringMessageTable


Pointer to TStringMessageTable (1288   ) record.


PText  =  ^Text



                                                                1273

__________________________________________________________CHAPTER_75.___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 (1274   ) 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 (1297   ) character.


PUCS4Char  =  ^UCS4Char


Pointer to UCS4Char (1297   )


PUCS4CharArray  =  ^TUCS4CharArray


Pointer to array of UCS4Char (1297   ) characters.


pUInt16  =  PWord


Pointer to UInt16 (1298   ) type


pUInt32  =  PDWord


Pointer to UInt32 (1298   ) type


pUInt8  =  PByte


Pointer to UInt8 (1298   ) type


PUintPtr  =  PPtrUInt


Pointer to UIntPtr (1298   ) type



                                                                1274

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



PUnicodeChar  =  ^UnicodeChar


PUnicodeChar  is  a  pointer  to  a  unicode  character,  just  like  PChar  is  a  pointer  to  a  Char
ansistring character.


PUnicodeString  =  ^UnicodeString


PUnicodeString is a pointer to a UnicodeString string.


PUnknown  =  ^IUnknown


Untyped pointer


PUTF8String  =  ^UTF8String


Pointer to UTF8String (1298   )


pvararray  =  ^tvararray


Pointer to TVarArray (1291   ) type.


pvararraybound  =  ^tvararraybound


Pointer to tvararraybound (1292   ) type.


pvararrayboundarray  =  ^tvararrayboundarray


Pointer to tvararrayboundarray (1292   ) type.


pvararraycoorarray  =  ^tvararraycoorarray


Pointer to tvararraycoorarray (1292   ) type.


pvardata  =  ^tvardata


Pointer to TVarData (1293   ) record.


PVariant  =  ^Variant


Pointer to Variant type.


pvariantmanager  =  ^tvariantmanager


Pointer to TVariantManager (1295   ) record.


PVarRec  =  ^TVarRec


Pointer to TVarRec (1296   ) type.


PVmt  =  ^TVmt



                                                                1275

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Pointer to TVMT (1297   ) record


PWideChar  =  ^WideChar


Pointer to WChar (1298   ).


PWideString  =  ^WideString


Pointer to widestring type


PWord  =  ^Word


Pointer to word (1298   ) type


PWordBool  =  ^WordBool


Pointer to a WordBool type.


QWord  =  0..18446744073709551615


QWord is a 64-bit, unsigned integer type, with range [0..18446744073709551615].


RawByteString  =  ansistring


RawByteString is a single-byte character string which does not have any codepage assigned
it.  Assigning a single-byte character string to this kind of string will not change the codepage
of the string.


Real  =  Double


Alias for real type


real48  =  Array[0..5]  of  Byte


TP compatible real type (6 bytes) definition


Shortint  =  -128..127


A signed 8-bits integer


SizeInt  =  LongInt


SizeInt is used to describe sizes of structures in FPC using a signed integer.  The actual
type  of  this  type  depends  on  the  architecture:  its  size  reflects  the  maximum  addressable
memory on the current architecture,  thus it is 64-bit on 64-bit platforms,  32-bit on 32-bit
platforms, and 16 bit on 16 bit platforms.


SizeUInt  =  DWord


SizeUInt is used to describe sizes of structures in FPC using an unsigned integer.  The actual
type  of  this  type  depends  on  the  architecture:  its  size  reflects  the  maximum  addressable
memory on the current architecture,  thus it is 64-bit on 64-bit platforms,  32-bit on 32-bit
platforms, and 16 bit on 16 bit platforms.



                                                                1276

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Smallint  =  -32768..32767


A signed 16-bits integer


TAbstractErrorProc  =  procedure


Abstract error handler procedural type.


TAllocateThreadVarsHandler  =  procedure


Threadvar allocation callback type for TThreadManager (1290   ).


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:  CodePointer)  :  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 (1290   ).


TBasicEventHandler  =  procedure(state:  PEventState)


Generic callback type for handling eventstate in TThreadManager (1290   ).


TBasicEventWaitForHandler  =  function(timeout:  Cardinal;
                                                             state:  PEventState)  :  LongInt


Wait for basic event callback type for TThreadManager (1290   ).


TBeginThreadHandler  =  function(sa:  Pointer;stacksize:  PtrUInt;
                                                   ThreadFunction:  TThreadFunc;p:  pointer;
                                                   creationFlags:  DWord;
                                                   var  ThreadId:  TThreadID)  :  TThreadID


Callback for thread start in TThreadManager (1290   ).


TBoundArray  =  Array  of  SizeInt



                                                                1277

__________________________________________________________CHAPTER_75.___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 (1478   ).


TCriticalSectionHandler  =  procedure(var  cs)


Generic callback type for critical section handling in TThreadManager (1290   ).


TCriticalSectionHandlerTryEnter  =  function(var  cs)  :  LongInt


TCriticalSectionHandlerTryEnter is the function prototype for the TryEnterCriticalsec-
tion  (1451   )  function,  in  the  TThreadManager  (1290   )  record's  TryEnterCriticalSection
field.


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.


TDate  =  TDateTime


TDate is defined for Delphi compatibility.  This type is deprecated, use TDateTime (1278   )
instead.


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.



                                                                1278

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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



tdynarraytypeinfo  describes  the  structure  of  a  multi-dimensional  dynamical  array.  It  is
used in the DynArraySetLength (1350   ) call.


TEndThreadHandler  =  procedure(ExitCode:  DWord)


Callback for thread end in TThreadManager (1290   ).


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:  CodePointer;
                                     Frame:  Pointer)


Standard error handler procedural type.


TExceptObject  =  record
   FObject  :  TObject;
   Addr  :  CodePointer;
   Next  :  PExceptObject;
   refcount  :  LongInt;
   Framecount  :  LongInt;
   Frames  :  PCodePointer;
end



                                                                1279

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TExceptObject is the exception description record which is found on the exception stack.


TExceptProc  =  procedure(Obj:  TObject;Addr:  CodePointer;
                                       FrameCount:  LongInt;Frame:  PCodePointer)


Exception handler procedural type


TextBuf  =  Array[0..TextRecBufSize-1]  of  AnsiChar


TextBuf is a type for the default buffer used in TextRec (1280   ).


TextFile  =  Text


Alias for Text file type.


TextRec  =  record
   Handle  :  THandle;
   Mode  :  LongInt;
   bufsize  :  SizeInt;
   _private  :  SizeInt;
   bufpos  :  SizeInt;
   bufend  :  SizeInt;
   bufptr  :  ^TextBuf;
   openfunc  :  CodePointer;
   inoutfunc  :  CodePointer;
   flushfunc  :  CodePointer;
   closefunc  :  CodePointer;
   UserData  :  Array[1..32]  of  Byte;
   name  :  Array[0..textrecnamelength-1]  of  TFileTextRecChar;
   LineEnd  :  TLineEndStr;
   buffer  :  TextBuf;
end



TextRec is the underlying type used in text files.  It should be treated as opaque and never
manipulated directly.


TFileTextRecChar  =  UnicodeChar


TFileTextRecChar  is  the  type  of  character  used  in  TextRec  (1280   )  or  FileRec  (1266   )  file
types.  It is an alias type, depending on platform and RTL compilation flags.  No assumptions
should be made on the actual character type.


TFloatSpecial  =  (fsZero,fsNZero,fsDenormal,fsNDenormal,fsPositive,
                            fsNegative,fsInf,fsNInf,fsNaN,fsInvalidOp)



                                                                1280

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                        Table 75.10:  Enumeration values for type TFloatSpecial


                                  __Value_________________Explanation_______________________
                                    fsDenormal            Denormal value
                                    fsInf                 Infinity
                                    fsInvalidOp           Invalid operation
                                    fsNaN                 Not a number
                                    fsNDenormal           Negative enormal value
                                    fsNegative            Negative value
                                    fsNInf                Negative infinity
                                    fsNZero               Negative zero
                                    fsPositive            Positive value
                                    fsZero                Zero



TFloatSpecial enumerates a series of floating point value properties.


TFPCHeapStatus  =  record
   MaxHeapSize  :  PtrUInt;
   MaxHeapUsed  :  PtrUInt;
   CurrHeapSize  :  PtrUInt;
   CurrHeapUsed  :  PtrUInt;
   CurrHeapFree  :  PtrUInt;
end



TFPCHeapStatus describes the state of the FPC heap manager.  This is not equivalent to the
THeapStatus  (1283   )  record  defined  by  Delphi,  which  contains  information  not  meaningful
for  the  FPC  heap  manager.  The  heap  status  can  be  retrieved  by  the  GetFPCHeapStatus
(1370   ) call.


TFPResourceHandle  =  PtrUInt


TFPResourceHandle  represents  a  handle  to  a  binary  resource  and  is  used  in  the  various
resource calls.  Its actual type and size may differ accross platforms.


TFPResourceHGLOBAL  =  PtrUInt


TFPResourceHGLOBAL represents a handle to the global module containing a resource.  It is
used in the various resource calls.  It is an opaque type:  its actual type and size may differ
accross platforms.


TFPResourceHMODULE  =  PtrUInt


TFPResourceHMODULE represents a module (library, executable, other) in which a resource is
located.  It is used in the various resource calls.  It is an opaque type:  its actual type and
size may differ accross platforms.


TFPUException  =  (exInvalidOp,exDenormalized,exZeroDivide,exOverflow,
                            exUnderflow,exPrecision)



                                                                1281

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                      Table 75.11:  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.



TFPUException describes what floating point errors raise exceptions.  It has been moved here
from the Math unit.


TFPUExceptionMask  =  Set  of  TFPUException


TFPUExceptionMask is a set of  TFPUException constants


TFPUPrecisionMode  =  (pmSingle,pmReserved,pmDouble,pmExtended)



                   Table 75.12:  Enumeration values for type TFPUPrecisionMode


                                  __Value________________Explanation_________________________
                                    pmDouble             Double-type precision
                                    pmExtended           Extended-type precision
                                    pmReserved           ?
                                    pmSingle             Single-type precision



TFPUPrecisionMode describes the possible default precisions for the software Floating Point
math routines.  It has been moved here from the math unit.


TFPURoundingMode  =  (rmNearest,rmDown,rmUp,rmTruncate)



                   Table 75.13:  Enumeration values for type TFPURoundingMode


                     __Value______________Explanation_____________________________________________________
                       rmDown              Round to biggest integer smaller than value.
                       rmNearest           Round to nearest integer
                       rmTruncate          Cut off fractional part
                       rmUp                Round to smallest integer larger than value



TFPURoundingMode enumerates the possible values for software floating point math rounding.
It has been moved here from the math unit.


TGetCurrentThreadIdHandler  =  function  :  TThreadID


Callback type for retrieving thread ID in TThreadManager (1290   ).



                                                                1282

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TGuid  =  packed  record
case  Integer  of
1:  (
   Data1  :  DWord;
   Data2  :  Word;
   Data3  :  Word;
   Data4  :  Array[0..7]  of  Byte;
);
2:  (
   D1  :  DWord;
   D2  :  Word;
   D3  :  Word;
   D4  :  Array[0..7]  of  Byte;
);
3:  (
   time_low  :  DWord;
   time_mid  :  Word;
   time_hi_and_version  :  Word;
   clock_seq_hi_and_reserved  :  Byte;
   clock_seq_low  :  Byte;
   node  :  Array[0..5]  of  Byte;
);
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 (1370   ) call.


TInitThreadVarHandler  =  procedure(var  offset:  DWord;size:  DWord)


Threadvar initialization callback type for TThreadManager (1290   ).


TInterfacedClass  =  Class  of  TInterfacedObject



                                                                1283

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TInterfacedClass is a descendent of


tinterfaceentry  =  record
   IID  :  PGuid;
   VTable  :  Pointer;
   IOffset  :  SizeUInt;
   IIDStr  :  PShortString;
case  Boolean  of
True:  (
   IType  :  tinterfaceentrytype;
);
False:  (
   __pad_dummy  :  SizeInt;
);
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,
                                     etVirtualMethodClass,etStaticMethodClass,
                                     etFieldValueClass)



                    Table 75.14:  Enumeration values for type tinterfaceentrytype


             __Value_______________________________Explanation____________________________________________________
               etFieldValue                        Field value
               etFieldValueClass                   Interface provided by a class field
               etStandard                          Standard entry
               etStaticMethodClass                 Interface provided by a static class method
               etStaticMethodResult                Statis method
               etVirtualMethodClass                Interface provided by a virtual class method
               etVirtualMethodResult               Virtual method



This is an internal type for the compiler to encode calls to dispatch interfaces.


tinterfacetable  =  record
   EntryCount  :  SizeUInt;
   Entries  :  Array[0..0]  of  tinterfaceentry;
end



Record to store list of interfaces of a class.


TLineEndStr  =  string


TLineEndStr is an alias for the actual line ending string type, used in TextRec (1280   ).  It
should be treated as opaque.



                                                                1284

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TMemoryManager  =  record
   NeedLock  :  Boolean;
   Getmem  :  function(Size:  PtrUInt)  :  Pointer;
   Freemem  :  function(p:  pointer)  :  PtrUInt;
   FreememSize  :  function(p:  pointer;Size:  PtrUInt)  :  PtrUInt;
   AllocMem  :  function(Size:  PtrUInt)  :  Pointer;
   ReAllocMem  :  function(var  p:  pointer;Size:  PtrUInt)  :  Pointer;
   MemSize  :  function(p:  pointer)  :  PtrUInt;
   InitThread  :  procedure;
   DoneThread  :  procedure;
   RelocateHeap  :  procedure;
   GetHeapStatus  :  function  :  THeapStatus;
   GetFPCHeapStatus  :  function  :  TFPCHeapStatus;
end



TMemoryManager describes the memory manager.  For more information about the memory
manager, see the programmer's reference.


TMethod  =  record
   Code  :  CodePointer;
   Data  :  Pointer;
end



TMethod  describes  a  general  method  pointer,  and  is  used  in  Run-Time  Type  Information
handling.


TMsgStrTable  =  record
   name  :  PShortString;
   method  :  CodePointer;
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 (1290   ).


TRelocateThreadVarHandler  =  function(offset:  DWord)  :  pointer


Threadvar relocalization callback type for TThreadManager (1290   ).



                                                                1285

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TResourceHandle  =  PtrUInt


This is an opaque type.


TResourceManager  =  record
   HINSTANCEFunc  :  function  :  TFPResourceHMODULE;
   EnumResourceTypesFunc  :  function(ModuleHandle:  TFPResourceHMODULE;EnumFunc:  EnumResTypeProc;
                  lParam:  PtrInt)  :  LongBool;
   EnumResourceNamesFunc  :  function(ModuleHandle:  TFPResourceHMODULE;ResourceType:  PChar;
                  EnumFunc:  EnumResNameProc;lParam:  PtrInt)  :  LongBool;
   EnumResourceLanguagesFunc  :  function(ModuleHandle:  TFPResourceHMODULE;ResourceType:  PChar;
                  ResourceName:  PChar;EnumFunc:  EnumResLangProc;lParam:  PtrInt)
                   :  LongBool;
   FindResourceFunc  :  function(ModuleHandle:  TFPResourceHMODULE;ResourceName:  PChar;
                  ResourceType:  PChar)  :  TFPResourceHandle;
   FindResourceExFunc  :  function(ModuleHandle:  TFPResourceHMODULE;ResourceType:  PChar;
                  ResourceName:  PChar;Language:  Word)  :  TFPResourceHandle;
   LoadResourceFunc  :  function(ModuleHandle:  TFPResourceHMODULE;ResHandle:  TFPResourceHandle)
                   :  TFPResourceHGLOBAL;
   SizeofResourceFunc  :  function(ModuleHandle:  TFPResourceHMODULE;ResHandle:  TFPResourceHandle)
                   :  LongWord;
   LockResourceFunc  :  function(ResData:  TFPResourceHGLOBAL)  :  Pointer;
   UnlockResourceFunc  :  function(ResData:  TFPResourceHGLOBAL)  :  LongBool;
   FreeResourceFunc  :  function(ResData:  TFPResourceHGLOBAL)  :  LongBool;
end



TResourceManager is the record describing the resource manager.  Depending on the kind of
resources (internal, external), another resource managing handler is installed by the system.
The resource manager record is used by all resource handling functions to do the actual work:
for each function in the API, a handler function is available.  People wishing to implement
their own resource manager, must implement all handler functions in their implementation.

As soon as resources are used,  the compiler will install a resource manager,  depending on
the platform, this may be an internal or an external resource manager.


TRTLCreateEventHandler  =  function  :  PRTLEvent


Callback type for creating a TRTLEvent type in TThreadManager (1290   ).


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)


Generic TRTLEvent handling type for TThreadManager (1290   ).


TRTLEventHandlerTimeout  =  procedure(AEvent:  PRTLEvent;timeout:  LongInt)


TRTLEvent timeout handling type for TThreadManager (1290   ).



                                                                1286

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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)



                       Table 75.15:  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



TRuntimeError is used in the Error (1355   ) 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.



                                                                1287

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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


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.


TStandardCodePageEnum  =  (scpAnsi,scpConsoleInput,scpConsoleOutput,
                                         scpFileSystemSingleByte)



               Table 75.16:  Enumeration values for type TStandardCodePageEnum


                   __Value_________________________________Explanation_____________________________________
                     scpAnsi                               Ansi codepage (CP_ACP)
                     scpConsoleInput                       Console input codepage
                     scpConsoleOutput                      Console output codepage
                     scpFileSystemSingleByte               File system single byte codepage.



TStandardCodePageEnum describes several types of standard used codepages, which can be
queried by the unicode string manager TUnicodeStringManager (1291   ).


TStringMessageTable  =  record
   count  :  LongInt;
   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 (1285   ) records.


TSystemCodePage  =  Word


TSystemCodePage is a type used to indicate code pages.  It should be treated as an opaque
type.



                                                                1288

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TTextBuf  =  TextBuf


TTextBuf is an alias for TextBuf


TTextLineBreakStyle  =  (tlbsLF,tlbsCRLF,tlbsCR)



                   Table 75.17:  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)



Text line break style.  (end of line character)


TThreadFunc  =  function(parameter:  pointer)  :  PtrInt


Thread function prototype


TThreadGetPriorityHandler  =  function(threadHandle:  TThreadID)  :  LongInt


Callback type for thread priority getting in TThreadManager (1290   ).


TThreadHandler  =  function(threadHandle:  TThreadID)  :  DWord


Generic thread handler callback for TThreadManager (1290   ).


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;
   CloseThread  :  TThreadHandler;
   ThreadSwitch  :  TThreadSwitchHandler;
   WaitForThreadTerminate  :  TWaitForThreadTerminateHandler;
   ThreadSetPriority  :  TThreadSetPriorityHandler;
   ThreadGetPriority  :  TThreadGetPriorityHandler;
   GetCurrentThreadId  :  TGetCurrentThreadIdHandler;
   InitCriticalSection  :  TCriticalSectionHandler;
   DoneCriticalSection  :  TCriticalSectionHandler;
   EnterCriticalSection  :  TCriticalSectionHandler;
   TryEnterCriticalSection  :  TCriticalSectionHandlerTryEnter;
   LeaveCriticalSection  :  TCriticalSectionHandler;



                                                                1289

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



   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;
   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  (1434   )  procedure,  and  the  current  thread  manager  can  be  retrieved  with
the GetThreadManager (1372   ) 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 (1290   ).


TThreadSwitchHandler  =  procedure


Callback type for thread switch in TThreadManager (1290   ).


TTime  =  TDateTime


TTime is defined for Delphi compatibility.  This type is deprecated, use TDateTime (1278   )
instead.


TUCS4CharArray  =  Array[0..$effffff]  of  UCS4Char


Array of UCS4Char (1297   ) characters.


TUnicodeStringManager  =  record
   Wide2AnsiMoveProc  :  procedure(source:  PWideChar;var  dest:  RawByteString;cp:  TSystemCodePage;



                                                                1290

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                   len:  SizeInt);
   Ansi2WideMoveProc  :  procedure(source:  PChar;cp:  TSystemCodePage;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;
   CodePointLengthProc  :  function(const  Str:  PChar;MaxLookAead:  PtrInt)  :  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;
   Unicode2AnsiMoveProc  :  procedure(source:  PUnicodeChar;var  dest:  RawByteString;
                   cp:  TSystemCodePage;len:  SizeInt);
   Ansi2UnicodeMoveProc  :  procedure(source:  PChar;cp:  TSystemCodePage;var  dest:  unicodestring;
                   len:  SizeInt);
   UpperUnicodeStringProc  :  function(const  S:  UnicodeString)  :  UnicodeString;
   LowerUnicodeStringProc  :  function(const  S:  UnicodeString)  :  UnicodeString;
   CompareUnicodeStringProc  :  function(const  s1:  UnicodeString;const  s2:  UnicodeString)  :  PtrInt;
   CompareTextUnicodeStringProc  :  function(const  s1:  UnicodeString;const  s2:  UnicodeString)  :  PtrInt;
   GetStandardCodePageProc  :  function(const  stdcp:  TStandardCodePageEnum)  :  TSystemCodePage;
end



TUnicodeStringManager is currently the same as the TUnicodeStringManager (1291   ) man-
ager record.  It performs the same functions:  converting unicode strings to ansistrings and
vice-versa, performing uppercase to lowercase transformations and comparing strings.


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 (1292   ) records equal to the number of dimensions in the
array (dimcoun).


tvararraybound  =  record
   elementcount  :  LongInt;



                                                                1291

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



   lowbound  :  LongInt;
end



tvararraybound is used to describe one dimension in a variant array.


tvararrayboundarray  =  Array[0..0]  of  tvararraybound


array of tvararraybound (1292   ) records.


tvararraycoorarray  =  Array[0..0]  of  LongInt


Array of variant array coordinates


tvardata  =  packed  record
   vtype  :  tvartype;
case  Integer  of
0:  (
   res1  :  Word;
case  Integer  of
0:  (
   res2  :  Word;
   res3  :  Word;
case  Word  of
varsmallint:  (
   vsmallint  :  SmallInt;
);
varinteger:  (
   vinteger  :  LongInt;
);
varsingle:  (
   vsingle  :  single;
);
vardouble:  (
   vdouble  :  Double;
);
vardate:  (
   vdate  :  TDateTime;
);
varcurrency:  (
   vcurrency  :  currency;
);
varolestr:  (
   volestr  :  PWideChar;
);
vardispatch:  (
   vdispatch  :  pointer;
);
varerror:  (
   verror  :  HRESULT;
);
varboolean:  (
   vboolean  :  wordbool;



                                                                1292

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



);
varunknown:  (
   vunknown  :  pointer;
);
varshortint:  (
   vshortint  :  ShortInt;
);
varbyte:  (
   vbyte  :  Byte;
);
varword:  (
   vword  :  Word;
);
varlongword:  (
   vlongword  :  DWord;
);
varint64:  (
   vint64  :  Int64;
);
varqword:  (
   vqword  :  QWord;
);
varword64:  (
   vword64  :  QWord;
);
varstring:  (
   vstring  :  pointer;
);
varany:  (
   vany  :  pointer;
);
vararray:  (
   varray  :  pvararray;
);
varbyref:  (
   vpointer  :  pointer;
);
);
1:  (
   vlongs  :  Array[0..2]  of  LongInt;
);
);
1:  (
   vwords  :  Array[0..6]  of  Word;
);
2:  (
   vbytes  :  Array[0..13]  of  Byte;
);
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.



                                                                1293

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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);
   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;var  source:  tvardata;calldesc:  pcalldesc;
                   params:  pointer);
   vararrayredim  :  procedure(var  a:  variant;highbound:  SizeInt);
   vararrayget  :  function(const  a:  variant;indexcount:  SizeInt;indices:  PLongint)
                   :  variant;
   vararrayput  :  procedure(var  a:  variant;const  value:  variant;indexcount:  SizeInt;
                   indices:  PLongint);
   writevariant  :  function(var  t:  text;const  v:  variant;width:  LongInt)  :  Pointer;
   write0Variant  :  function(var  t:  text;const  v:  Variant)  :  Pointer;
end



                                                                1294

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TVariantManager  describes  the  variant  manager  as  expected  by  the  SetVariantManager
(1435   ) call.


tvarop  =  (opadd,opsubtract,opmultiply,opdivide,opintdivide,opmodulus,
                opshiftleft,opshiftright,opand,opor,opxor,opcompare,opnegate,
                opnot,opcmpeq,opcmpne,opcmplt,opcmple,opcmpgt,opcmpge,oppower)



                             Table 75.18:  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.


TVarRec  =  record
case  VType  :  SizeInt  of
vtInteger:  (
   VInteger  :  LongInt;
);
vtBoolean:  (
   VBoolean  :  Boolean;
);
vtChar:  (
   VChar  :  Char;
);
vtWideChar:  (
   VWideChar  :  WideChar;
);
vtExtended:  (
   VExtended  :  PExtended;



                                                                1295

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



);
vtString:  (
   VString  :  PShortString;
);
vtPointer:  (
   VPointer  :  Pointer;
);
vtPChar:  (
   VPChar  :  PAnsiChar;
);
vtObject:  (
   VObject  :  TObject;
);
vtClass:  (
   VClass  :  TClass;
);
vtPWideChar:  (
   VPWideChar  :  PWideChar;
);
vtAnsiString:  (
   VAnsiString  :  Pointer;
);
vtCurrency:  (
   VCurrency  :  PCurrency;
);
vtVariant:  (
   VVariant  :  PVariant;
);
vtInterface:  (
   VInterface  :  Pointer;
);
vtWideString:  (
   VWideString  :  Pointer;
);
vtInt64:  (
   VInt64  :  PInt64;
);
vtUnicodeString:  (
   VUnicodeString  :  Pointer;
);
vtQWord:  (
   VQWord  :  PQWord;
);
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.



                                                                1296

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TVmt  =  record
   vInstanceSize  :  SizeInt;
   vInstanceSize2  :  SizeInt;
   vParent  :  PVmt;
   vClassName  :  PShortString;
   vDynamicTable  :  Pointer;
   vMethodTable  :  Pointer;
   vFieldTable  :  Pointer;
   vTypeInfo  :  Pointer;
   vInitTable  :  Pointer;
   vAutoTable  :  Pointer;
   vIntfTable  :  pinterfacetable;
   vMsgStrPtr  :  pstringmessagetable;
   vDestroy  :  CodePointer;
   vNewInstance  :  CodePointer;
   vFreeInstance  :  CodePointer;
   vSafeCallException  :  CodePointer;
   vDefaultHandler  :  CodePointer;
   vAfterConstruction  :  CodePointer;
   vBeforeDestruction  :  CodePointer;
   vDefaultHandlerStr  :  CodePointer;
   vDispatch  :  CodePointer;
   vDispatchStr  :  CodePointer;
   vEquals  :  CodePointer;
   vGetHashCode  :  CodePointer;
   vToString  :  CodePointer;
end



TVMT  is  a  record  describing  the  VMT  of  a  class.  It's  various  fields  represent  the  available
information in the VMT, as far as it is common to all classes.


TWaitForThreadTerminateHandler  =  function(threadHandle:  TThreadID;
                                                                     TimeoutMs:  LongInt)  :  DWord


Callback type for thread termination in TThreadManager (1290   ).


TWideStringManager  =  TUnicodeStringManager


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


String of UCS4Char (1297   ) characters.



                                                                1297

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



UInt16  =  Word


An unsigned 16-bits integer


UInt32  =  Cardinal


An unsigned 32-bits integer


UInt64  =  QWord


Unsigned 64-bit integer


UInt8  =  Byte


An unsigned 8-bits integer


UIntPtr  =  PtrUInt


Alias for PtrUInt (1274   ) type for compatibility with later Delphi versions.


UnicodeChar  =  WideChar


UnicodeChar is a single character from a UnicodeString.  It equals WideChar in all respects.


UnicodeString  =  UnicodeString


UnicodeString  is  a  string  of  WideChars.   The  main  difference  with  WideString  is  that
unicodestring is reference counted, and WideString is not reference counted on Windows.


UTF8String  =  ansistring


UTF-8 unicode (ansi) string.


ValReal  =  Extended


ValReal  is  an  alias  for  the  largest  available  floating  point  type  on  the  architecture  the
program runs on.  On most processors, it should be one of  Double or Extended.


ValSInt  =  LongInt


Integer with the same size as the return code of the Val (1458   ) function.


ValUInt  =  Cardinal


Integer with the same size as the return code of the Val (1458   ) function.


WChar  =  WideChar


Wide char (16-bit sized char)


WideChar  =  #$0000..#$FFFF


This  type  is  the  base  unit  for  all  two  byte  character  types,  like  UnicodeString  (1298   )  and
WideString (1298   )


WideString  =  WideString


Word  =  0..65535


An unsigned 16-bits integer



                                                                1298

               __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'_________________*
 *__________________



               75.10.3          Variables

               DefaultFileSystemCodePage  :  TSystemCodePage


               DefaultFileSystemCodePage determines the code page to which file/path names are trans-
               lated before they are passed to OS API calls, if the RTL uses a single byte OS API for this
               purpose on the current platform.

               This code page is also used for intermediate operations on file paths inside the RTL before
               making OS API calls.

               This variable does not exist in Delphi, and has been introduced in FPC to make it possible
               to change the value of  DefaultSystemCodePage without breaking RTL interfaces with the
               OS file system API calls.

               The initiali value of this variable depends on the platform:


                    o  Windows:  UTF-8, because the RTL uses UTF-16 OS API calls (so no data is lost in
                       intermediate operations).

                    o  OS X and iOS: UTF-8 (as defined by Apple)

                    o  Unix (excluding OS X and iOS): equals DefaultSystemCodePage (1300   ).  This is be-
                       cause the encoding of file names is undefined on Unix platforms:  it is an untyped array
                       of  bytes  that  can  be  interpreted  in  any  way;  Specifically,  it  is  not  guaranteed  to  be
                       valid UTF-8.

                    o  Other platforms:  same as DefaultSystemCodePage (1300   ).


               The  value  of  this  variable  may  be  changed  using  the  SetMultiByteFileSystemCodePage
               (1431   ) procedure.

Remark:         The Unix/OS X/iOS settings only apply in case the cwstring widestring manager is installed,
               otherwise DefaultFileSystemCodePage will have the same value as DefaultSystemCodePage
               after program startup.


               DefaultRTLFileSystemCodePage  :  TSystemCodePage


               DefaultRTLFileSystemCodePage  determines  the  code  page  to  which  file/path  names  are
               translated before they are returned from RawByteString (1276   ) file/path RTL routines.

               Examples  include  the  file/path  names  returned  by  the  RawbyteString  versions  of  SysU-
               tils.FindFirst (1235   ) and GetDir (1369   ).

               The main reason for its existence is to enable the RTL to provide backward compatibility
               with earlier versions of FPC, as these always returned strings encoded in whatever the OS'
               single byte API used (normally DefaultSystemCodePage (1300   )).

               The initial value of this variable depends on the platform:


                    o  Windows:  DefaultSystemCodePage, for backward compatibility.

                    o  OS X and iOS: UTF-8, for backward compatibility.  It was already always UTF-8 in the
                       past, since that's what the OS file APIs returned, and the data was never converted.

                    o  Other  Unixes:  DefaultSystemCodePage,  for  the  same  reason  as  DefaultFileSystem-
                       CodePage (1299   ).  Setting this to a different value than DefaultFileSystemCodePage
                       is  a  bad  idea  on  these  platforms,  since  any  code  page  conversion  can  corrupt  these
                       strings as their initial encoding is unknown.



                                                                               1299

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



     o Other platforms:  same as DefaultSystemCodePage.


The value of this variable can be set using the SetMultiByteRTLFileSystemCodePage (1431   )
call.


DefaultSystemCodePage  :  TSystemCodePage


DefaultSystemCodePage  is  used  to  determine  how  CP_ACP  is  interpreted;  it  is  what  the
program considers to be the current system codepage.

It is initialized to the default system codepage.


     o On windows, this is the result of the GetACP operating call, which returns the Windows
       ANSI code page.

     o On iOS, this is UTF-8

     o on other unixes this will be based on the currently set LANG or LC_CTYPE environment
       variables.  Normally this is UTF-8, but that is not guaranteed to be the case.

     o For all other platforms it is set to CP_ACP, as these platforms currently do not support
       multiple code pages, and are hardcoded to use their OS-specific code page in all cases.


The  DefaultSystemCodePage  value  may  be  set  using  SetMultiByteConversionCodePage
(1430   ).  That  means  that  it  is  not  a  good  idea  to  use  its  value  to  determine  the  real  OS
"default system code page".


DefaultUnicodeCodePage  :  TSystemCodePage


DefaultUnicodeCodePage  is  the  unicode  code  page  for  a  new  unicode  string.   On  most
platforms, this is CP_UTF16 (1242   ).


DispCallByIDProc  :  CodePointer


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.


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.



                                                                1300

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



FirstDotAtFileNameStartIsExtension  :  Boolean  =  False


FirstDotAtFileNameStartIsExtension determines what happens if a filename starts with
a dot (.)  character.  If True, then the whole file name will be treated as extension.  If False,
then the extension is empty.


InOutRes  :  Word


Result of last I/O operation.  Read-Only.


Input  :  Text


Standard input text file.


IsConsole  :  Boolean;public  name  'operatingsystem_isconsole'  =  False


True for console applications, False for GUI applications.


IsLibrary  :  Boolean;public  name  'operatingsystem_islibrary'  =  False


True if the current module is a library.  Otherwise module is an excutable


mem  :  Array[0..$7fffffff-1]  of  Byte


mem is an array of bytes, representing the computer's memory.  This array is available only
when compiling for the Dos Go32V2 target.  It's use is not recommended, and it is not even
available on other platforms.


meml  :  Array[0..($7fffffffdivsizeof(longint))-1]  of  LongInt


memw is an array of longints, representing the computer's memory as 32-bit signed integers.
This  array  is  available  only  when  compiling  for  the  Dos  Go32V2  target.   It's  use  is  not
recommended, and it is not even available on other platforms.


memw  :  Array[0..($7fffffffdivsizeof(word))-1]  of  Word


memw is an array of words, representing the computer's memory as 2-byte words.  This array
is  available  only  when  compiling  for  the  Dos  Go32V2  target  It's  use  is  not  recommended,
and it is not even available on other platforms.


NoErrMsg  :  Boolean  =  Falseplatform


Unused, for Delphi compatibility


Output  :  Text


Standard output text file.


RandSeed  :  Cardinal


Seed for Random (1410   ) function.



                                                                1301

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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  :  TFPUExceptionMask


Current soft float exception flags


softfloat_exception_mask  :  TFPUExceptionMask


Current soft float exception mask


softfloat_rounding_mode  :  TFPURoundingMode


softfloat_rounding_mode  determines  how  the  software  floating-point  emulation  routines
do the rounding.  The value can be one of the following:


float__round__nearest__even             Round to nearest even number

float__round__down          Round down

float__round__up        Round up

float__round__to__zero         Round in the direction of zero (down for positive, up for negative)


StackBottom  :  Pointer


Current stack bottom.


StackLength  :  SizeUInt


Maximum stack length.


StdErr  :  Text


Standard diagnostic output text file.


StdOut  :  Text


Alias for Output (1301   ).


ThreadID  :  TThreadID


Current Thread ID.


UTF8CompareLocale  :  TSystemCodePage


UTF8CompareLocale is currently present for Delphi compatibility only, it is not used in FPC
code.


widestringmanager  :  TUnicodeStringManager


Contains the current widestring manager.  Do not use directly.


WriteErrorsToStdErr  :  Boolean  =  True



                                                                1302

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11            Procedures  and  functions



                75.11.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 (1421   )


                Listing:  ./refex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.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
                (1240   ) constant is set, it will be called instead.

       Errors:   This routine causes a run-time error 211.

    See also:    AbstractErrorProc (1240   )



                75.11.3          AcquireExceptionObject

    Synopsis:    Obtain a reference to the current exception object

Declaration:     function  AcquireExceptionObject  :  Pointer

    Visibility:   default



                                                                                1303

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1415   ) 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 (1415   )



                75.11.4          add(variant,variant):variant

    Synopsis:    Implement addition (+) operation on variants.

Declaration:     operator  +(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the addition + operation is delegated to the variant manager with
                operation opadd.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator -(variant, variant):  variant (1235   )



                75.11.5          AddExitProc

    Synopsis:    Add an exit procedure to the exit procedure chain.

Declaration:     procedure  AddExitProc(Proc:  TProcedure)

    Visibility:   default

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 (1243   )



                75.11.6          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 (see the programmer's guide).

       Errors:   None

    See also:    SizeOf (1436   )



                                                                                1304

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.7          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.



                75.11.8          AllocMem

    Synopsis:    Allocate and clear memory.

Declaration:     function  AllocMem(Size:  PtrUInt)  :  pointer

    Visibility:   default

Description:     AllocMem calls getmem GetMem (1370   ), and clears the allocated memory, i.e.  the allocated
                memory is filled with Size zero bytes.

    See also:    GetMem (1370   )



                75.11.9          AnsiToUtf8

    Synopsis:    Convert ansi string to UTF-8 string

Declaration:     function  AnsiToUtf8(const  s:  RawByteString)  :  RawByteString

    Visibility:   default

Description:     AnsiToUtf8 converts the ansistring S to a UTF-8 format, that is, it converts the string from
                whatever codepage is currently in use, to UTF-8.

                The current codepage is fetched from the system, if internationalization support is enabled.
                It can be UTF-8, in which case the function simply returns S.

       Errors:   None.

    See also:    Utf8toAnsi (1457   )



                                                                                1305

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.10           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 (1417   ), Close (1335   ), Reset (1416   )


                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.}
                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.11           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 (1436   ), Cos (1343   )


                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;



                                                                                1306

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                 b e g i n
                    R := ArcTan     ( 0 ) ;          {  R : = 0  }
                    R := ArcTan     ( 1 ) /p i;      {  R : = 0 . 2 5 }
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.12           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 (1442   )



                75.11.13           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 (1375   ), Runerror (1423   )



                75.11.14           Assign

    Synopsis:    Assign a name to a file

Declaration:     procedure  Assign(out  f:  File;const  Name:  ShortString)
                procedure  Assign(out  f:  File;const  p:  PAnsiChar)
                procedure  Assign(out  f:  File;const  c:  AnsiChar)



                                                                                1307

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                procedure  Assign(out  f:  File;const  Name:  UnicodeString)
                procedure  Assign(out  f:  File;const  Name:  RawByteString)
                procedure  Assign(out  f:  TypedFile;const  Name:  shortstring)
                procedure  Assign(out  f:  TypedFile;const  p:  PAnsiChar)
                procedure  Assign(out  f:  TypedFile;const  c:  AnsiChar)
                procedure  Assign(out  f:  TypedFile;const  Name:  unicodestring)
                procedure  Assign(out  f:  TypedFile;const  Name:  RawByteString)
                procedure  Assign(out  t:  Text;const  s:  shortstring)
                procedure  Assign(out  t:  Text;const  p:  PAnsiChar)
                procedure  Assign(out  t:  Text;const  c:  AnsiChar)
                procedure  Assign(out  t:  Text;const  s:  unicodestring)
                procedure  Assign(out  t:  Text;const  s:  RawByteString)

    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 (1416   ), Rewrite (1417   ), Append (1306   )


                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 !  ') ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.15           assign(ansistring):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  ansistring)  :  olevariant

    Visibility:   default

Description:



                75.11.16           assign(ansistring):variant

    Synopsis:



                                                                                1308

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Declaration:     operator  :=(const  source:  ansistring)  :  variant

    Visibility:  default

Description:



                75.11.17           assign(Boolean):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  Boolean)  :  olevariant

    Visibility:   default

Description:



                75.11.18           assign(Boolean):variant

    Synopsis:

Declaration:     operator  :=(const  source:  Boolean)  :  variant

    Visibility:   default

Description:



                75.11.19           assign(Byte):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  Byte)  :  olevariant

    Visibility:   default

Description:



                75.11.20           assign(Byte):variant

    Synopsis:

Declaration:     operator  :=(const  source:  Byte)  :  variant

    Visibility:   default

Description:



                75.11.21           assign(Char):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  Char)  :  olevariant

    Visibility:   default

Description:



                                                                                1309

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.22           assign(Char):variant

    Synopsis:

Declaration:     operator  :=(const  source:  Char)  :  variant

    Visibility:   default

Description:



                75.11.23           assign(comp):olevariant

Declaration:     operator  :=(const  source:  comp)  :  olevariant

    Visibility:   default



                75.11.24           assign(comp):variant

Declaration:     operator  :=(const  source:  comp)  :  variant

    Visibility:   default



                75.11.25           assign(currency):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  currency)  :  olevariant

    Visibility:   default

Description:



                75.11.26           assign(currency):variant

    Synopsis:

Declaration:     operator  :=(const  source:  currency)  :  variant

    Visibility:   default

Description:



                75.11.27           assign(Double):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  Double)  :  olevariant

    Visibility:   default

Description:



                                                                                1310

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.28           assign(Double):variant

    Synopsis:

Declaration:     operator  :=(const  source:  Double)  :  variant

    Visibility:   default

Description:



                75.11.29           assign(DWord):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  DWord)  :  olevariant

    Visibility:   default

Description:



                75.11.30           assign(DWord):variant

    Synopsis:

Declaration:     operator  :=(const  source:  DWord)  :  variant

    Visibility:   default

Description:



                75.11.31           assign(extended):olevariant

Declaration:     operator  :=(const  source:  extended)  :  olevariant

    Visibility:   default



                75.11.32           assign(extended):variant

Declaration:     operator  :=(const  source:  extended)  :  variant

    Visibility:   default



                75.11.33           assign(Int64):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  Int64)  :  olevariant

    Visibility:   default

Description:



                                                                                1311

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.34           assign(Int64):variant

    Synopsis:

Declaration:     operator  :=(const  source:  Int64)  :  variant

    Visibility:   default

Description:



                75.11.35           assign(longbool):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  longbool)  :  olevariant

    Visibility:   default

Description:



                75.11.36           assign(longbool):variant

    Synopsis:

Declaration:     operator  :=(const  source:  longbool)  :  variant

    Visibility:   default

Description:



                75.11.37           assign(LongInt):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  LongInt)  :  olevariant

    Visibility:   default

Description:



                75.11.38           assign(LongInt):variant

    Synopsis:

Declaration:     operator  :=(const  source:  LongInt)  :  variant

    Visibility:   default

Description:



                75.11.39           assign(olevariant):ansistring

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  ansistring

    Visibility:   default

Description:



                                                                                1312

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.40           assign(olevariant):Boolean

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  Boolean

    Visibility:   default

Description:



                75.11.41           assign(olevariant):Byte

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  Byte

    Visibility:   default

Description:



                75.11.42           assign(olevariant):Char

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  Char

    Visibility:   default

Description:



                75.11.43           assign(olevariant):comp

Declaration:     operator  :=(const  source:  olevariant)  :  comp

    Visibility:   default



                75.11.44           assign(olevariant):currency

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  currency

    Visibility:   default

Description:



                75.11.45           assign(olevariant):Double

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  Double

    Visibility:   default

Description:



                                                                                1313

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.46           assign(olevariant):DWord

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  DWord

    Visibility:   default

Description:



                75.11.47           assign(olevariant):extended

Declaration:     operator  :=(const  source:  olevariant)  :  extended

    Visibility:   default



                75.11.48           assign(olevariant):Int64

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  Int64

    Visibility:   default

Description:



                75.11.49           assign(olevariant):longbool

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  longbool

    Visibility:   default

Description:



                75.11.50           assign(olevariant):LongInt

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  LongInt

    Visibility:   default

Description:



                75.11.51           assign(olevariant):QWord

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  QWord

    Visibility:   default

Description:



                                                                                1314

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.52           assign(olevariant):Real

Declaration:     operator  :=(const  source:  olevariant)  :  Real

    Visibility:   default



                75.11.53           assign(olevariant):ShortInt

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  ShortInt

    Visibility:   default

Description:



                75.11.54           assign(olevariant):shortstring

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  shortstring

    Visibility:   default

Description:



                75.11.55           assign(olevariant):single

Declaration:     operator  :=(const  source:  olevariant)  :  single

    Visibility:   default



                75.11.56           assign(olevariant):SmallInt

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  SmallInt

    Visibility:   default

Description:



                75.11.57           assign(olevariant):TDateTime

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  TDateTime

    Visibility:   default

Description:



                                                                                1315

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.58           assign(olevariant):TError

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  TError

    Visibility:   default

Description:



                75.11.59           assign(olevariant):UnicodeString

Declaration:     operator  :=(const  source:  olevariant)  :  UnicodeString

    Visibility:   default



                75.11.60           assign(olevariant):variant

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  variant

    Visibility:   default

Description:



                75.11.61           assign(olevariant):WideChar

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  WideChar

    Visibility:   default

Description:



                75.11.62           assign(olevariant):widestring

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  widestring

    Visibility:   default

Description:



                75.11.63           assign(olevariant):Word

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  Word

    Visibility:   default

Description:



                                                                                1316

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.64           assign(olevariant):wordbool

    Synopsis:

Declaration:     operator  :=(const  source:  olevariant)  :  wordbool

    Visibility:   default

Description:



                75.11.65           assign(QWord):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  QWord)  :  olevariant

    Visibility:   default

Description:



                75.11.66           assign(QWord):variant

    Synopsis:

Declaration:     operator  :=(const  source:  QWord)  :  variant

    Visibility:   default

Description:



                75.11.67           assign(Real):olevariant

Declaration:     operator  :=(const  source:  Real)  :  olevariant

    Visibility:   default



                75.11.68           assign(Real):variant

Declaration:     operator  :=(const  source:  Real)  :  variant

    Visibility:   default



                75.11.69           assign(real48):Double

    Synopsis:

Declaration:     operator  :=(b:  real48)  :  Double

    Visibility:   default

Description:



                75.11.70           assign(real48):extended

Declaration:     operator  :=(b:  real48)  :  extended

    Visibility:   default



                                                                                1317

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.71           assign(ShortInt):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  ShortInt)  :  olevariant

    Visibility:   default

Description:



                75.11.72           assign(ShortInt):variant

    Synopsis:

Declaration:     operator  :=(const  source:  ShortInt)  :  variant

    Visibility:   default

Description:



                75.11.73           assign(shortstring):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  shortstring)  :  olevariant

    Visibility:   default

Description:



                75.11.74           assign(shortstring):variant

    Synopsis:

Declaration:     operator  :=(const  source:  shortstring)  :  variant

    Visibility:   default

Description:



                75.11.75           assign(single):olevariant

Declaration:     operator  :=(const  source:  single)  :  olevariant

    Visibility:   default



                75.11.76           assign(single):variant

Declaration:     operator  :=(const  source:  single)  :  variant

    Visibility:   default



                                                                                1318

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.77           assign(SmallInt):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  SmallInt)  :  olevariant

    Visibility:   default

Description:



                75.11.78           assign(SmallInt):variant

    Synopsis:

Declaration:     operator  :=(const  source:  SmallInt)  :  variant

    Visibility:   default

Description:



                75.11.79           assign(TDateTime):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  TDateTime)  :  olevariant

    Visibility:   default

Description:



                75.11.80           assign(TDateTime):variant

    Synopsis:

Declaration:     operator  :=(const  source:  TDateTime)  :  variant

    Visibility:   default

Description:



                75.11.81           assign(TError):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  TError)  :  olevariant

    Visibility:   default

Description:



                75.11.82           assign(TError):variant

    Synopsis:

Declaration:     operator  :=(const  source:  TError)  :  variant

    Visibility:   default

Description:



                                                                                1319

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.83           assign(UCS4String):variant

Declaration:     operator  :=(const  source:  UCS4String)  :  variant

    Visibility:   default



                75.11.84           assign(UnicodeString):olevariant

Declaration:     operator  :=(const  source:  UnicodeString)  :  olevariant

    Visibility:   default



                75.11.85           assign(UnicodeString):variant

Declaration:     operator  :=(const  source:  UnicodeString)  :  variant

    Visibility:   default



                75.11.86           assign(UTF8String):variant

Declaration:     operator  :=(const  source:  UTF8String)  :  variant

    Visibility:   default



                75.11.87           assign(variant):ansistring

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  ansistring

    Visibility:   default

Description:



                75.11.88           assign(variant):Boolean

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  Boolean

    Visibility:   default

Description:



                75.11.89           assign(variant):Byte

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  Byte

    Visibility:   default

Description:



                                                                                1320

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.90           assign(variant):Char

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  Char

    Visibility:   default

Description:



                75.11.91           assign(variant):comp

Declaration:     operator  :=(const  source:  variant)  :  comp

    Visibility:   default



                75.11.92           assign(variant):currency

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  currency

    Visibility:   default

Description:



                75.11.93           assign(variant):Double

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  Double

    Visibility:   default

Description:



                75.11.94           assign(variant):DWord

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  DWord

    Visibility:   default

Description:



                75.11.95           assign(variant):extended

Declaration:     operator  :=(const  source:  variant)  :  extended

    Visibility:   default



                                                                                1321

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.96           assign(variant):Int64

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  Int64

    Visibility:   default

Description:



                75.11.97           assign(variant):longbool

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  longbool

    Visibility:   default

Description:



                75.11.98           assign(variant):LongInt

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  LongInt

    Visibility:   default

Description:



                75.11.99           assign(variant):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  olevariant

    Visibility:   default

Description:



                75.11.100            assign(variant):QWord

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  QWord

    Visibility:   default

Description:



                75.11.101            assign(variant):Real

Declaration:     operator  :=(const  source:  variant)  :  Real

    Visibility:   default



                                                                                1322

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.102            assign(variant):ShortInt

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  ShortInt

    Visibility:   default

Description:



                75.11.103            assign(variant):shortstring

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  shortstring

    Visibility:   default

Description:



                75.11.104            assign(variant):single

Declaration:     operator  :=(const  source:  variant)  :  single

    Visibility:   default



                75.11.105            assign(variant):SmallInt

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  SmallInt

    Visibility:   default

Description:



                75.11.106            assign(variant):TDateTime

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  TDateTime

    Visibility:   default

Description:



                75.11.107            assign(variant):TError

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  TError

    Visibility:   default

Description:



                                                                                1323

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.108            assign(variant):unicodestring

Declaration:     operator  :=(const  source:  variant)  :  unicodestring

    Visibility:   default



                75.11.109            assign(variant):UTF8String

Declaration:     operator  :=(const  source:  variant)  :  UTF8String

    Visibility:   default



                75.11.110            assign(variant):WideChar

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  WideChar

    Visibility:   default

Description:



                75.11.111            assign(variant):widestring

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  widestring

    Visibility:   default

Description:



                75.11.112            assign(variant):Word

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  Word

    Visibility:   default

Description:



                75.11.113            assign(variant):wordbool

    Synopsis:

Declaration:     operator  :=(const  source:  variant)  :  wordbool

    Visibility:   default

Description:



                                                                                1324

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.114            assign(WideChar):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  WideChar)  :  olevariant

    Visibility:   default

Description:



                75.11.115            assign(WideChar):variant

    Synopsis:

Declaration:     operator  :=(const  source:  WideChar)  :  variant

    Visibility:   default

Description:



                75.11.116            assign(widestring):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  widestring)  :  olevariant

    Visibility:   default

Description:



                75.11.117            assign(widestring):variant

    Synopsis:

Declaration:     operator  :=(const  source:  widestring)  :  variant

    Visibility:   default

Description:



                75.11.118            assign(Word):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  Word)  :  olevariant

    Visibility:   default

Description:



                75.11.119            assign(Word):variant

    Synopsis:

Declaration:     operator  :=(const  source:  Word)  :  variant

    Visibility:   default

Description:



                                                                                1325

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.120            assign(wordbool):olevariant

    Synopsis:

Declaration:     operator  :=(const  source:  wordbool)  :  olevariant

    Visibility:   default

Description:



                75.11.121            assign(wordbool):variant

    Synopsis:

Declaration:     operator  :=(const  source:  wordbool)  :  variant

    Visibility:   default

Description:



                75.11.122            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 (1401   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1326

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.123            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 (1422   ) instead.

    See also:    RTLEventCreate (1422   )



                75.11.124            basiceventdestroy

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  basiceventdestroy(state:  PEventState)

    Visibility:   default

Description:     basiceventdestroy is obsolete.  Use RTLEventDestroy (1422   ) instead.

    See also:    RTLEventDestroy (1422   )



                75.11.125            basiceventResetEvent

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  basiceventResetEvent(state:  PEventState)

    Visibility:   default

Description:     basiceventResetEvent is obsolete.  Use RTLEventResetEvent (1422   ) instead.

    See also:    RTLEventResetEvent (1422   )



                75.11.126            basiceventSetEvent

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  basiceventSetEvent(state:  PEventState)

    Visibility:   default

Description:     basiceventSetEvent is obsolete.  Use RTLEventSetEvent (1423   ) instead.

    See also:    RTLEventSetEvent (1423   )



                75.11.127            basiceventWaitFor

    Synopsis:    Obsolete.  Don't use

Declaration:     function  basiceventWaitFor(Timeout:  Cardinal;state:  PEventState)
                                                             :  LongInt

    Visibility:   default

Description:     basiceventwaitfor is obsolete.  Use RTLEventWaitFor (1423   ) instead.

    See also:    RTLEventWaitFor (1423   )



                                                                                1327

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.128            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
                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 4MiB is used.

                The function returns the thread handle (or ID, on some other operating systems like Linux
                or \ostwo) on success, or 0 if an error occurred.  Note that the thread ID and handle are the
                same on unix processes, and that the thread ID and thread handle are different on windows
                systems.

       Errors:   On error, the value "0" is returned.

    See also:    EndThread (1351   )



                75.11.129            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 (1394   ), NtoBE (1402   ), NtoLE (1402   )



                75.11.130            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



                                                                                1328

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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 (1440   ), Val (1458   ), HexStr (1375   ), OctStr (1402   )


                Listing:  ./refex/ex82.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.131            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 (1417   ) or Reset (1416   ) 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 {$I} switch.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Blockwrite (1330   ), Close (1335   ), Reset (1416   ), Assign (1307   )


                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. }



                                                                                1329

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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 ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.132            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 (1417   ) or Reset (1416   ) statement.  If the records couldn't be
                written to disk, a run-time error is generated.  This behavior can be controlled by the {$I}
                switch.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Blockread (1329   ), Close (1335   ), Rewrite (1417   ), Assign (1307   )



                75.11.133            Break

    Synopsis:    Exit current loop construct.

Declaration:     procedure  Break



                                                                                1330

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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 (1341   ), Exit (1357   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.134            BsfByte

    Synopsis:    Return the position of the rightmost set bit in an 8-bit value

Declaration:     function  BsfByte(const  AValue:  Byte)  :  Byte

    Visibility:   default

Description:     BsfByte scans the byte AValue, starting at position 0 (rightmost position) and returns the
                index of the first set bit.  The position is measured from the 0-th, rightmost bit.

    See also:    BsrByte (1332   ), BsfWord (1332   ), BsfDWord (1332   ), BsfQWord (1332   )



                                                                                1331

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.135            BsfDWord

    Synopsis:    Return the position of the rightmost set bit in a 32-bit value

Declaration:     function  BsfDWord(const  AValue:  DWord)  :  Cardinal

    Visibility:   default

Description:     BsfDWord scans the DWord AValue, starting at position 0 (rightmost position) , and returns
                the index of the first set bit.  The position is measured from the 0-th, rightmost bit.

    See also:    BsfByte (1331   ), BsfWord (1332   ), BsrDWord (1333   ), BsfQWord (1332   )



                75.11.136            BsfQWord

    Synopsis:    Return the position of the rightmost set bit in a 64-bit value

Declaration:     function  BsfQWord(const  AValue:  QWord)  :  Cardinal

    Visibility:   default

Description:     BsfQWord scans the QWord AValue, starting at position 0 (rightmost position) , and returns
                the index of the first set bit.  The position is measured from the 0-th, rightmost bit.

    See also:    BsfByte (1331   ), BsfWord (1332   ), BsfDWord (1332   ), BsrQWord (1333   )



                75.11.137            BsfWord

    Synopsis:    Return the position of the rightmost set bit in a 16-bit value

Declaration:     function  BsfWord(const  AValue:  Word)  :  Cardinal

    Visibility:   default

Description:     BsfWord scans the word AValue,  starting at position 0 (rightmost position) ,  and returns
                the index of the first set bit.  The position is measured from the 0-th, rightmost bit.

    See also:    BsfByte (1331   ), BsrWord (1333   ), BsfDWord (1332   ), BsfQWord (1332   )



                75.11.138            BsrByte

    Synopsis:    Return the position of the leftmost set bit in an 8-bit value

Declaration:     function  BsrByte(const  AValue:  Byte)  :  Byte

    Visibility:   default

Description:     BsfByte  scans  the  byte  AValue,  starting  at  the  leftmost  position  and  working  towards
                position 0, and returns the index of the first set bit.  The position is measured from the 0-th,
                rightmost bit.

    See also:    BsfByte (1331   ), BsrWord (1333   ), BsrDWord (1333   ), BsrQWord (1333   )



                                                                                1332

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.139            BsrDWord

    Synopsis:    Return the position of the leftmost set bit in a 32-bit value

Declaration:     function  BsrDWord(const  AValue:  DWord)  :  Cardinal

    Visibility:   default

Description:     BsrDWord scans the DWord AValue, starting at the leftmost position and working towards
                position 0, and returns the index of the first set bit.  The position is measured from the 0-th,
                rightmost bit.

    See also:    BsrByte (1332   ), BsrWord (1333   ), BsfDWord (1332   ), BsrQWord (1333   )



                75.11.140            BsrQWord

    Synopsis:    Return the position of the leftmost set bit in a 64-bit value

Declaration:     function  BsrQWord(const  AValue:  QWord)  :  Cardinal

    Visibility:   default

Description:     BsfQWord scans the QWord AValue, starting at the leftmost position and working towards
                position 0, and returns the index of the first set bit.  The position is measured from the 0-th,
                rightmost bit.

    See also:    BsfByte (1331   ), BsfWord (1332   ), BsfDWord (1332   ), BsrQWord (1333   )



                75.11.141            BsrWord

    Synopsis:    Return the position of the leftmost set bit in a 16-bit value

Declaration:     function  BsrWord(const  AValue:  Word)  :  Cardinal

    Visibility:   default

Description:     BsrWord  scans  the  word  AValue,  starting  at  the  leftmost  position  and  working  towards
                position 0, and returns the index of the first set bit.  The position is measured from the 0-th,
                rightmost bit.

    See also:    BsrByte (1332   ), BsfWord (1332   ), BsrDWord (1333   ), BsrQWord (1333   )



                75.11.142            CaptureBacktrace

    Synopsis:    Return stack trace

Declaration:     function  CaptureBacktrace(skipframes:  SizeInt;count:  SizeInt;
                                                         frames:  PCodePointer)  :  SizeInt

    Visibility:   default

Description:     CaptureBacktrace will fill the array pointed to by frames with the addresses of a backtrace.
                It will skip skipframes frames, and will write at most count addresses.  Frames must point
                to enough memory to hold the stacktrace, which is count*sizeof(codepointer) bytes.

    See also:    Get_pc_addr (1374   ), get_caller_stackinfo (1373   ), get_caller_addr (1373   ), get_caller_frame (1373   )



                                                                                1333

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.143            chdir

    Synopsis:    Change current working directory.

Declaration:     procedure  chdir(const  s:  shortstring);    Overload
                procedure  chdir(const  s:  RawByteString);    Overload
                procedure  chdir(const  s:  unicodestring);    Overload

    Visibility:   default

Description:     Chdir changes the working directory of the process to S.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Mkdir (1399   ), Rmdir (1418   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.144            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 (1404   ), Str (1440   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1334

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.145            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 (1416   ) or Rewrite (1417   ) is sufficient.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Assign (1307   ), Reset (1416   ), Rewrite (1417   ), Flush (1365   )


                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 ) ;
                  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___.____________________________________________________________________________________________________________*
 *___________



                75.11.146            CloseThread

    Synopsis:    Close a thread and free up resources used by the thread

Declaration:     function  CloseThread(threadHandle:  TThreadID)  :  DWord

    Visibility:   default

Description:     CloseThread  must  be  called  on  any  thread  started  with  BeginThread  (1328   ).   It  must
                be called after the thread has ended (either by exiting the thread function or after calling
                EndThread (1351   )).

       Errors:   If no threadmanager is installed, an exception may be raised or runtime error 232 may occur
                if no exceptions are used.

    See also:    BeginThread (1328   ), EndThread (1351   )



                75.11.147            CompareByte

    Synopsis:    Compare 2 memory buffers byte per byte

Declaration:     function  CompareByte(const  buf1;const  buf2;len:  SizeInt)  :  SizeInt



                                                                                1335

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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.

                0if the first len bytes in buf1 and buf2 are equal.

                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 (1337   ), CompareChar0 (1338   ), CompareWord (1339   ), CompareDWord (1338   )


                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 ;
                        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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1336

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.148            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 (1335   ), CompareChar0 (1338   ), CompareWord (1339   ), CompareDWord (1338   )


                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  ;


                    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



                                                                                1337

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                       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___.____________________________________________________________________________________________________________*
 *___________



                75.11.149            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 (1335   ), CompareChar (1337   ), CompareDWord (1338   ), CompareWord (1339   )



                75.11.150            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.



                                                                                1338

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                0if the first len DWords in buf1 and buf2 are equal.

                1if  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 (1337   ), CompareByte (1335   ), CompareWord (1339   )


                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 ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.151            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:



                                                                                1339

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                -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.

                0if the first len Words in buf1 and buf2 are equal.

                1if  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 (1337   ), CompareByte (1335   ), CompareDWord (1338   )


                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;
                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.152            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



                                                                                1340

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1342   ), Delete (1346   ), Insert (1386   ), Pos (1407   ), Length (1392   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.153            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, 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 (1330   ), Exit (1357   )


                Listing:  ./refex/ex86.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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



                                                                                1341

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                        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___.____________________________________________________________________________________________________________*
 *___________



                75.11.154            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 (1346   ), Insert (1386   ), Pos (1407   )


                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;


                 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___.____________________________________________________________________________________________________________*
 *___________



                75.11.155            CopyArray

    Synopsis:    Copy managed-type elements in array

Declaration:     procedure  CopyArray(dest:  Pointer;source:  Pointer;typeInfo:  Pointer;
                                                count:  SizeInt)

    Visibility:   default



                                                                                1342

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     CopyArray copies count elements containing managed types from the array pointed to by
                source to the array pointed to by dest.  For this, it uses the type information of the elements
                as specified in typeinfo.

                Under normal circumstances,  this procedure should not be used,  it is called automatically
                by the compiler when an array-typed variables are assigned to each other.

    See also:    InitializeArray (1385   ), FinalizeArray (1364   ), DynArraySize (1351   ), DynArrayClear (1349   ),
                DynArrayDim (1350   ), DynArrayBounds (1349   )



                75.11.156            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 (1306   ), Sin (1436   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.157            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/64 bit compiler.

       Errors:   None.

    See also:    DSeg (1348   ), Seg (1427   ), Ofs (1403   ), Ptr (1409   )


                Listing:  ./refex/ex13.pp



                                                                                1343

                __________________________________________________________CHAPTER_75.___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___.____________________________________________________________________________________________________________*
 *___________



                75.11.158            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 is made to decrease X below
                its minimum value.

    See also:    Inc (1378   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1344

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.159            Default

    Synopsis:    Return Default initialized value

Declaration:     function  Default(const  T:  AnyType)  :  AnyType

    Visibility:   default

Description:     Default is a compiler intrinsic:  it returns for every type T a default value.  In essence, this
                is a block of memory that is zeroed out.  It can be used to correctly initialize any type, and
                more importantly, a managed type.  It also works using a generic type template.

                This function cannot be used on any of the file types or complex types that contain a file
                type.

    See also:    TypeInfo (1452   ), Initialize (1383   ), Finalize (1363   )



                75.11.160            DefaultAnsi2UnicodeMove

    Synopsis:    Standard widestring manager callback

Declaration:     procedure  DefaultAnsi2UnicodeMove(source:  PChar;cp:  TSystemCodePage;
                                                                       var  dest:  unicodestring;len:  SizeInt)

    Visibility:   default

Description:     DefaultAnsi2UnicodeMove is the standard callback used for the widestring manager when
                an ansistring must be converted to a unicodestring.  It simply copies over all characters from
                the ansistring to the unicodestring, no conversion whatsoever is performed.



                75.11.161            DefaultAnsi2WideMove

    Synopsis:    Standard implementation of Ansi to Widestring conversion routine

Declaration:     procedure  DefaultAnsi2WideMove(source:  PChar;cp:  TSystemCodePage;
                                                                  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:    DefaultUnicode2AnsiMove (1345   )



                75.11.162            DefaultUnicode2AnsiMove

    Synopsis:    Standard widestring manager callback

Declaration:     procedure  DefaultUnicode2AnsiMove(source:  PUnicodeChar;
                                                                       var  dest:  RawByteString;
                                                                       cp:  TSystemCodePage;len:  SizeInt)

    Visibility:   default

Description:     DefaultUnicode2AnsiMove is the standard callback used for the widestring manager when
                a unicode string must be converted to an ansistring.  It replaces all words with value < 256
                with their value as ASCII code.



                                                                                1345

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   None.

    See also:    WidestringManager (1302   )



                75.11.163            Delete

    Synopsis:    Delete part of a string.

Declaration:     procedure  Delete(var  s:  shortstring;index:  SizeInt;count:  SizeInt)
                procedure  Delete(var  S:  RawByteString;Index:  SizeInt;Size:  SizeInt)
                procedure  Delete(var  S:  UnicodeString;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  deleted  characters  are  shifted  Count  positions  to  the  left,  and  the  length  of  the
                string is adjusted.

       Errors:   Shortstring variant's third parameter is called Count, in other overloaded variants it is called
                Index

    See also:    Copy (1342   ), Pos (1407   ), Insert (1386   )


                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
                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.164            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  (1401   ).   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 (1401   ), Getmem (1370   ), Freemem (1367   )



                                                                                1346

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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
                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.165            divide(variant,variant):variant

    Synopsis:    Implement division (/) operation on variants.

Declaration:     operator  /(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the division / operation is delegated to the variant manager with
                operation opDivide.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator *(variant, variant):  variant (1235   )



                                                                                1347

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.166            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 (1351   ) or LeaveCritical-
                section (1392   ), unless it is again initialized with InitCriticalSection (1383   )

    See also:    InitCriticalsection (1383   ), EnterCriticalsection (1351   ), LeaveCriticalsection (1392   )



                75.11.167            DoneThread

    Synopsis:    End the current thread

Declaration:     procedure  DoneThread

    Visibility:   default

Description:     DoneThread should be used to end the current thread.  It performs the necessary housekeep-
                ing before actually ending the thread.  Using the operating system calls to end the thread
                may result in data corruption or memory leaks.

    See also:    BeginThread (1328   )



                75.11.168            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/64 bit compiler.

       Errors:   None.

    See also:    CSeg (1343   ), Seg (1427   ), Ofs (1403   ), Ptr (1409   )


                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 p i l e r.}
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1348

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.169            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 (1349   )



                75.11.170            Dump__Stack

    Synopsis:    Dump stack to the given text file.

Declaration:     procedure  Dump_Stack(var  f:  text;fp:  pointer;addr:  CodePointer)

    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 (1373   ), get_caller_frame (1373   ), get_frame (1374   )



                75.11.171            DynArrayBounds

    Synopsis:    Return the bounds of the dynamic array

Declaration:     function  DynArrayBounds(a:  Pointer;typeInfo:  Pointer)  :  TBoundArray

    Visibility:   default

Description:     DynArrayBounds returns the bounds of all the dimensions of the dynamic array a with type
                information typeInfo.

                The result is an array (zero-based) with the maximum valid index for each dimension in the
                array:  the lower bound is not present in the result, it is always zero.

    See also:    InitializeArray (1385   ), FinalizeArray (1364   ), CopyArray (1342   ), DynArraySize (1351   ), Dy-
                nArrayClear (1349   ), DynArrayDim (1350   )



                75.11.172            DynArrayClear

    Synopsis:    Clear dynamical array

Declaration:     procedure  DynArrayClear(var  a:  Pointer;typeInfo:  Pointer)

    Visibility:   default

Description:     DynArrayClear clears the array (a) using its type info (typeInfo).  It is equal to setting
                the length to zero.

    See also:    InitializeArray (1385   ), FinalizeArray (1364   ), CopyArray (1342   ), DynArraySize (1351   ), Dy-
                nArrayDim (1350   ), DynArrayBounds (1349   )



                                                                                1349

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.173            DynArrayDim

    Synopsis:    Return the number of dimensions in a dynamic array

Declaration:     function  DynArrayDim(typeInfo:  Pointer)  :  Integer

    Visibility:   default

Description:     DynArrayDim returns the number of dimensions in a dynamic array,  using the type infor-
                mation (typeInfo) of the array.

    See also:    InitializeArray (1385   ), FinalizeArray (1364   ), CopyArray (1342   ), DynArraySize (1351   ), Dy-
                nArrayClear (1349   ), DynArrayBounds (1349   )



                75.11.174            DynArrayIndex

    Synopsis:    Return pointer to indicated element

Declaration:     function  DynArrayIndex(a:  Pointer;const  indices:  Array  of  SizeInt;
                                                     typeInfo:  Pointer)  :  Pointer

    Visibility:   default

Description:     DynArrayIndex returns a pointer to the element indicated by indices in dynamic array a
                with type information typinfo.  The length of indices must equal the number of dimensions
                of the array (as returned by DynArrayDim (1350   )).

       Errors:   No bounds checking is performed, it is therefor possible to get an access violation if one of
                the indexes is out of range.

    See also:    InitializeArray (1385   ), FinalizeArray (1364   ), CopyArray (1342   ), DynArraySize (1351   ), Dy-
                nArrayClear (1349   ), DynArrayBounds (1349   ), DynArrayDim (1350   ), IsDynArrayRectangu-
                lar (1391   )



                75.11.175            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 (1279   )

                It  should  never  be  necessary  to  call  this  function  directly,  the  standard  SetLength  (1430   )
                function should be used instead.

       Errors:   If an invalid pointer is specified, an error may occur.

    See also:    SetLength (1430   ), tdynarraytypeinfo (1279   )



                                                                                1350

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.176            DynArraySize

    Synopsis:    Return length of dynamic array

Declaration:     function  DynArraySize(a:  pointer)  :  tdynarrayindex

    Visibility:   default

Description:     DynArraySize gets the number of elements in the array (a) the result is equal to Length
                (1392   ) for dynamic arrays.

    See also:    InitializeArray (1385   ), FinalizeArray (1364   ), CopyArray (1342   ), DynArrayClear (1349   ), Dy-
                nArrayDim (1350   ), DynArrayBounds (1349   )



                75.11.177            EmptyMethod

    Synopsis:    Empty method alias

Declaration:     procedure  EmptyMethod

    Visibility:   default

Description:     Emptymethod is meant for the compiler only.  It should not be used directly.



                75.11.178            EndThread

    Synopsis:    End the current thread.

Declaration:     procedure  EndThread(ExitCode:  DWord)
                procedure  EndThread

    Visibility:   default

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
                (1460   )).  If it is omitted, zero is used.

                This function does not return.

    See also:    WaitForThreadTerminate (1460   ), BeginThread (1328   )



                75.11.179            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 (1392   )), 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 (1383   ) prior to a call
                to EnterCriticalsection.

                A call to EnterCriticalsection must always be matched by a call to LeaveCriticalSection
                (1392   ).  To avoid problems, it is best to include the code to be execute in a try...finally
                block, as follows:



                                                                                1351

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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 (1383   ), DoneCriticalsection (1348   ), LeaveCriticalsection (1392   )



                75.11.180            EnumResourceLanguages

    Synopsis:    Enumerate available languages for a resource of given type and name

Declaration:     function  EnumResourceLanguages(ModuleHandle:  TFPResourceHMODULE;
                                                                  ResourceType:  PChar;ResourceName:  PChar;
                                                                  EnumFunc:  EnumResLangProc;lParam:  PtrInt)
                                                                   :  LongBool

    Visibility:   default

Description:     EnumResourceLanguages enumerates the available languages for a resource of given ResourceName
                and type ResourceType in the module ModuleHandle.  For each language availanle, it calls
                EnumFunc and passes it ModuleHandle, the type of the resource ResourceType, the name of
                the resource ResourceName, the language ID, and lParam.  It returns False if no resources
                are available for the specified resource type and module, or True if there are resources avail-
                able.

       Errors:   None.

    See also:    EnumResourceTypes (1353   ), EnumResourceNames (1352   ), EnumResourceLanguages (1352   )



                75.11.181            EnumResourceNames

    Synopsis:    Enumerate available resource names for a specified resource type

Declaration:     function  EnumResourceNames(ModuleHandle:  TFPResourceHMODULE;
                                                           ResourceType:  PChar;EnumFunc:  EnumResNameProc;
                                                           lParam:  PtrInt)  :  LongBool

    Visibility:   default

Description:     EnumResourceNames  enumerates  the  names  of  all  resources  of  type  ResourceType  in  the
                module ModuleHandle.  For each resource available it calls EnumFunc and passes it ModuleHandle,
                the type of the resource ResourceType,  the name of the resource,  and lParam.  It returns
                False  if  no  resources  are  available  for  the  specified  resource  type  and  module,  or  True  if
                there are resources available.

       Errors:   None.

    See also:    EnumResourceTypes (1353   ), EnumResourceLanguages (1352   )



                                                                                1352

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.182            EnumResourceTypes

    Synopsis:    Enumerate available resource types

Declaration:     function  EnumResourceTypes(ModuleHandle:  TFPResourceHMODULE;
                                                           EnumFunc:  EnumResTypeProc;lParam:  PtrInt)
                                                             :  LongBool

    Visibility:   default

Description:     EnumResourceTypes  enumerates  the  types  of  all  resources  in  the  module  ModuleHandle.
                For each resource available it calls EnumFunc and passes it ModuleHandle,  the type of the
                resource, and lParam.  It returns False if no resources are available for the specified module,
                or True if there are resources available.

       Errors:   None.

    See also:    EnumResourceNames (1352   ), EnumResourceLanguages (1352   )



                75.11.183            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.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Eoln (1354   ), Assign (1307   ), Reset (1416   ), Rewrite (1417   )


                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



                                                                                1353

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                        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___.____________________________________________________________________________________________________________*
 *___________



                75.11.184            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 (1353   ), Assign (1307   ), Reset (1416   ), Rewrite (1417   )


                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.
                        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___.____________________________________________________________________________________________________________*
 *___________



                75.11.185            equal(variant,variant):Boolean

    Synopsis:    Implement = (equality) operation on variants.

Declaration:     operator  =(const  op1:  variant;const  op2:  variant)  :  Boolean

    Visibility:   default

Description:     The implementation of the equality (=) operation is delegated to the variant manager with
                operation opcmpeq.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator <(variant, variant):  boolean (1235   )



                                                                                1354

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.186            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 {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Assign (1307   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.187            Error

    Synopsis:    Generate run-time error

Declaration:     procedure  Error(RunTimeError:  TRuntimeError)

    Visibility:   default

Description:     Error generates a run-time error with an exit code corresponding to RunTimeError.  This
                function is implemented for Delphi compatibility, and is not used by the Free Pascal Run-
                Time Library.

    See also:    RunError (1423   ), Halt (1375   )



                75.11.188            Exclude

    Synopsis:    Exlude element from a set if it is present.

Declaration:     procedure  Exclude(var  S:  TSetType;E:  TSetElement)

    Visibility:   default



                                                                                1355

                __________________________________________________________CHAPTER_75.___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 (1379   )


                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   ) ;



                                                                                1356

                __________________________________________________________CHAPTER_75.___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___.____________________________________________________________________________________________________________*
 *___________



                75.11.189            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.

                In Object Pascal or Delphi modes, if the Exit statement is surrounded by one or more Try
                ..    Finally constructs, the Finally blocks are executed, which means that if the finally
                blocks are used to free resources, then these resources will also be freed when Exit is called.

       Errors:   None.

    See also:    Halt (1375   )


                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



                                                                                1357

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                        e x i t ( F a l s e) ;
                end   ;


                 b e g i n
                    {   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___.____________________________________________________________________________________________________________*
 *___________



                75.11.190            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 (1394   ), Power (1408   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.191            Fail

    Synopsis:    Fail a constructor

Declaration:     procedure  Fail

    Visibility:   default

Description:     Fail can be used in a constructor for an object or class.  It will exit the constructor at once,
                and the memory allocated for the constructor is freed.  This mean that for objects allocated
                with New (1401   ), the resulting pointer is Nil and for classes, the object instance will be Nil.

    See also:    TypeOf (1452   ), New (1401   ), Initialize (1383   ), Finalize (1363   )


                Listing:  ./refex/ex116.pp



                                                                                1358

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                program        t e s t f a i l;


                { $mode      o b j f p c}


                Type
                    TMyClass       =   C l a s s
                        C o n s t r u c t o rC r e a t e;
                    end  ;



                 C o n s t r u c t o rTMyClass      .C r e a t e;


                 b e g i n
                    F a i l;
                end   ;


                 v a r
                   M    :  TMyClass      ;


                 b e g i n
                   M  := TMyClass      . C r e a t e;
                    W r i t e l n('M   i s   n i l  :  ' ,Not    A s s i g n e d(M ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.192            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.  Untyped
                files have a default record size of 128, if the second parameter to Reset (1416   ) isn't specified.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Filesize (1360   )


                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;
                       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



                                                                                1359

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                       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___.____________________________________________________________________________________________________________*
 *___________



                75.11.193            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.  Untyped files have a default record size of 128, if the second parameter
                to Reset (1416   ) isn't specified.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Filepos (1359   )


                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 ) ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1360

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.194            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  (1363   ),  and  if  it  is*
 *  a
                multiple  of  4  bytes  it  is  better  to  use  FillDWord  (1362   ),  these  routines  are  optimized  for
                their respective sizes.

       Errors:   No checking on the size of  X is done.

    See also:    Fillchar (1361   ), FillDWord (1362   ), Fillword (1363   ), Move (1399   )


                Listing:  ./refex/ex103.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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 B y t e( 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___.____________________________________________________________________________________________________________*
 *___________



                75.11.195            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 (1363   ), Move (1399   ), FillByte (1361   ), FillDWord (1362   )


                Listing:  ./refex/ex25.pp



                                                                                1361

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.196            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 (1361   ), Fillchar (1361   ), Fillword (1363   ), Move (1399   )


                Listing:  ./refex/ex104.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 4;


                {   Program       t o  d e m o n s t r a t et h e  F i l l D W o r d f u n c t i o n. }


                Const
                    A r r a y S i z e=  1 0 0 0 ;


                Var
                    S   :  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;


                 b e g i n
                    F i l l D W o r d(S, A r r a y S i z e, 0 ) ;
                    For    I : = 1  t o  A r r a y S i z edo
                        I f  S [i ]<>0     then
                           W r i t e l n(' P o s i t i o n ', i , '  n o t  z e r o e d o u t ') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.197            FillQWord

    Synopsis:    Fill memory range with QWord (64-bit) values



                                                                                1362

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Declaration:     procedure  FillQWord(var  x;count:  SizeInt;value:  QWord)

    Visibility:  default

Description:     FillQWord  fills  the  memory  location  of  x  with  Count  times  value.  The  size  of  the  filled
                memory location is therefor 8*count bytes.

       Errors:   No checks are made to see if X actually has a minimum size of (Count*8) bytes.  Therefor,
                other variables can be overwritten or the memory may be out of the accessible memory for
                the program.  In the latter case a run-error or exception may be triggered.

    See also:    FillChar (1361   ), FillWord (1363   )



                75.11.198            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 (1361   ), Move (1399   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.199            Finalize

    Synopsis:    Finalize (clean up) memory block using RTTI

Declaration:     procedure  Finalize(var  T:  TAnyType;ACount:  Integer)

    Visibility:   default

Description:     Finalize  is  a  compiler  intrinsic:  it  cleans  up  (finalizes)  a  memory  area  T  for  any  kind
                of  managed  variable.   Finalizing  means  decreasing  reference  counts  where  necessaru  and
                generally  zeroeing  out  the  memory  area.   It  performs  the  opposite  operation  of  initialize
                (1383   ).

                The optional ACount parameter can be used to initialize an array.

                For examples, see initialize (1383   ).

    See also:    initialize (1383   ), Default (1345   ), TypeInfo (1452   )



                                                                                1363

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.200            FinalizeArray

    Synopsis:    Finalize managed-type elements in array

Declaration:     procedure  FinalizeArray(p:  Pointer;typeInfo:  Pointer;count:  SizeInt)

    Visibility:   default

Description:     FinalizeArray dereferences and clears managed types in the array pointed to by  p.  For
                this, it uses the type information of the elements as specified in typeinfo.

                Under normal circumstances,  this procedure should not be used,  it is called automatically
                by the compiler when an array-typed variable containing managed types goes out of scope.

    See also:    InitializeArray  (1385   ),  CopyArray  (1342   ),  DynArraySize  (1351   ),  DynArrayClear  (1349   ),
                DynArrayDim (1350   ), DynArrayBounds (1349   )



                75.11.201            FindResource

    Synopsis:    Locate a resource and return a handle to it.

Declaration:     function  FindResource(ModuleHandle:  TFPResourceHMODULE;
                                                   ResourceName:  PChar;ResourceType:  PChar)
                                                     :  TFPResourceHandle
                function  FindResource(ModuleHandle:  TFPResourceHMODULE;
                                                   ResourceName:  AnsiString;ResourceType:  AnsiString)
                                                     :  TFPResourceHandle

    Visibility:   default

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 (1395   ).

       Errors:   None.  In case the resource was not found, 0 is returned.

    See also:    FreeResource  (1368   ),  LoadResource  (1395   ),  SizeofResource  (1437   ),  LockResource  (1395   ),
                UnlockResource (1455   ), FreeResource (1368   )



                75.11.202            FindResourceEx

    Synopsis:    Find a resource based on type, name, language

Declaration:     function  FindResourceEx(ModuleHandle:  TFPResourceHMODULE;
                                                      ResourceType:  PChar;ResourceName:  PChar;
                                                      Language:  Word)  :  TFPResourceHandle
                function  FindResourceEx(ModuleHandle:  TFPResourceHMODULE;
                                                      ResourceType:  AnsiString;
                                                      ResourceName:  AnsiString;Language:  Word)
                                                        :  TFPResourceHandle

    Visibility:   default

Description:     FindResourceEx looks in module ModuleHandle for a resource of type ResourceType and
                name ResourceName with languague ID Language.  Both Resourcename and ResourceName
                can be specified as a null-terminated array of characters, or as an AnsiString.

                If the requested language/sublanguage is not found, then the search is conducted



                                                                                1364

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                     1.with only primary language.

                     2.with the neutral language (LANG_NEUTRAL)

                     3.with the english language


                If none of these has returned a match, then the first available language is returned.

                If a match is found, a handle to the resource is returned.  If none is found, an empty handle
                (nil or 0) is returned.

       Errors:   None.



                75.11.203            float__raise

    Synopsis:    Raise floating point exception

Declaration:     procedure  float_raise(i:  TFPUException)
                procedure  float_raise(i:  TFPUExceptionMask)

    Visibility:   default

Description:     float_raise raises the floating point exceptions specified by softfloat_exception_flags (1302   ).

    See also:    softfloat_exception_flags (1302   ), softfloat_exception_mask (1302   )



                75.11.204            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 {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Close (1335   )


                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 }



                                                                                1365

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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 }
                    W r i t e l n ( ' o f f. ') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.205            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 (1351   )



                75.11.206            FMADouble

    Synopsis:    Internal function, do not use

Declaration:     function  FMADouble(d1:  Double;d2:  Double;d3:  Double)  :  Double

    Visibility:   default



                75.11.207            FMAExtended

    Synopsis:    Internal function, do not use

Declaration:     function  FMAExtended(e1:  extended;e2:  extended;e3:  extended)  :  extended

    Visibility:   default



                75.11.208            FMASingle

    Synopsis:    Internal function, do not use

Declaration:     function  FMASingle(s1:  single;s2:  single;s3:  single)  :  single

    Visibility:   default



                75.11.209            fpc__dynarray__rangecheck

    Synopsis:    Auxiliary compiler routine

Declaration:     procedure  fpc_dynarray_rangecheck(p:  pointer;i:  tdynarrayindex)

    Visibility:   default

Description:     fpc_dynarray_rangecheck is an auxiliary routine for checking whether an array index is in
                range for the array.



                                                                                1366

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.210            fpc__SarInt64

    Synopsis:    SAR (int64)

Declaration:     function  fpc_SarInt64(const  AValue:  Int64;const  Shift:  Byte)  :  Int64

    Visibility:   default

Description:     fpc_SarInt64 is a FPC helper function which should not be used directly.



                75.11.211            FPower10

    Synopsis:    Fast multiply with a power of 10

Declaration:     function  FPower10(val:  Extended;Power:  LongInt)  :  Extended

    Visibility:   default

Description:     FPower10 multplies val with 10 to the power Power.  It uses a fast algorithm to calculate
                the result.



                75.11.212            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 (1421   ), Int (1387   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.213            Freemem

    Synopsis:    Release allocated memory

Declaration:     procedure  Freemem(p:  pointer;Size:  PtrUInt)
                function  Freemem(p:  pointer)  :  PtrUInt

    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.



                                                                                1367

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   An error will occur when P doesn't point to the heap.

    See also:    Getmem (1370   ), New (1401   ), Dispose (1346   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.214            Freememory

    Synopsis:    Alias for FreeMem (1367   )

Declaration:     procedure  Freememory(p:  pointer;Size:  PtrUInt)
                function  Freememory(p:  pointer)  :  PtrUInt

    Visibility:   default

Description:     FreeMemory is an alias for FreeMem (1367   ).

    See also:    FreeMem (1367   )



                75.11.215            FreeResource

    Synopsis:    Free a loaded resource

Declaration:     function  FreeResource(ResData:  TFPResourceHGLOBAL)  :  LongBool

    Visibility:   default

Description:     FreeResource unloads the resource identified by ResData from memory.  The resource must
                have been loaded by LoadResource (1395   ).  It returns True if the operation was succesful,
                False otherwise.

       Errors:   On error, False is returned.

    See also:    FindResource  (1364   ),  LoadResource  (1395   ),  SizeofResource  (1437   ),  LockResource  (1395   ),
                UnlockResource (1455   ), FreeResource (1368   )



                75.11.216            GetCPUCount

    Synopsis:    Return the number of cores on the system

Declaration:     function  GetCPUCount  :  LongWord

    Visibility:   default



                                                                                1368

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     GetCPUCount returns the number of CPU cores on the system.  Whether these are physically
                separate CPUs or cores on a single CPU is deliberately undefined.

    See also:    CPUCount (1235   )



                75.11.217            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 (1391   ) or ThreadSetPriority (1449   )

       Errors:   None.

    See also:    KillThread (1391   ), ThreadSetPriority (1449   )



                75.11.218            getdir

    Synopsis:    Return the current directory

Declaration:     procedure  getdir(drivenr:  Byte;var  dir:  shortstring);    Overload
                procedure  getdir(drivenr:  Byte;var  dir:  RawByteString);    Overload
                procedure  getdir(drivenr:  Byte;var  dir:  unicodestring);    Overload

    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 (1334   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1369

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.219            GetFPCHeapStatus

    Synopsis:    Return FPC heap manager status information

Declaration:     function  GetFPCHeapStatus  :  TFPCHeapStatus

    Visibility:   default

Description:     Return FPC heap manager status information



                75.11.220            GetHeapStatus

    Synopsis:    Return the memory manager heap status.

Declaration:     function  GetHeapStatus  :  THeapStatus

    Visibility:   default



                75.11.221            GetMem

    Synopsis:    Allocate new memory on the heap

Declaration:     procedure  Getmem(out  p:  pointer;Size:  PtrUInt)
                function  GetMem(size:  PtrUInt)  :  pointer

    Visibility:   default

Description:     Getmem  reserves  Size  bytes  memory  on  the  heap,  and  returns  a  pointer  to  this  memory
                in p.  What happens if no more memory is available,  depends on the value of the variable
                ReturnNilIfGrowHeapfails (1302   ):  if the variable is True then Nil is returned.  If the variable
                is False, a run-time error is generated.  The default value is False, so by default an error is
                generated.

                The newly allocated memory is not initialized in any way, and may contain garbage data.  It
                must be cleared with a call to FillChar (1361   ) or FillWord (1363   ).

                For an example, see Freemem (1367   ).

       Errors:   None.

    See also:    Freemem (1367   ), Dispose (1346   ), New (1401   ), returnnilifgrowheapfails (1302   )



                75.11.222            GetMemory

    Synopsis:    Alias for GetMem (1370   )

Declaration:     procedure  Getmemory(out  p:  pointer;Size:  PtrUInt)
                function  GetMemory(size:  PtrUInt)  :  pointer

    Visibility:   default

Description:     Getmemory is an alias for GetMem (1370   ).

    See also:    GetMem (1370   )



                                                                                1370

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.223            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 the programmer's guide.

       Errors:   None.

    See also:    SetMemoryManager (1430   ), IsMemoryManagerSet (1391   )



                75.11.224            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 (1372   )



                75.11.225            GetResourceManager

    Synopsis:    Return the currently active resource manager

Declaration:     procedure  GetResourceManager(var  Manager:  TResourceManager)

    Visibility:   default

Description:     GetResourceManager  returns  the  currently  active  resource  manager  record  in  Manager.
                There is always an active resource manager record.

       Errors:   None.

    See also:    TResourceManager (1286   ), SetResourceManager (1432   )



                75.11.226            GetTextCodePage

    Synopsis:    Get the codepage used in a text file.

Declaration:     function  GetTextCodePage(var  T:  Text)  :  TSystemCodePage

    Visibility:   default

Description:     GetTextCodePage returns the codepage that the text file T uses.  All strings written to the
                file will be converted to the indicated codepage.  By default, the codepage is set to CP_ACP.

       Errors:   None.

    See also:    TextRec (1280   ), SetTextCodePage (1433   )



                                                                                1371

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.227            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 (1371   )



                75.11.228            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 (1434   ), TThreadManager (1290   )



                75.11.229            GetUnicodeStringManager

    Synopsis:    Return a copy of the currently active unicodetring manager.

Declaration:     procedure  GetUnicodeStringManager(var  Manager:  TUnicodeStringManager)

    Visibility:   default

Description:     GetUnicodeStringManager returns a copy of the currently active unicode string manager
                in Old

                UnicodeStrings  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 UnicodeStringManager 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 cwstring).

                It is possible to implement a custom unicodestring manager, optimized for the current ap-
                plication, without having to recompile the complete Run-Time Library.

    See also:    SetUnicodeStringManager (1434   ), TUnicodeStringManager (1291   )



                75.11.230            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:    SetVariantManager (1435   )



                                                                                1372

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.231            GetWideStringManager

    Synopsis:    Return a copy of the currently active widestring manager.

Declaration:     procedure  GetWideStringManager(var  Manager:  TUnicodeStringManager)

    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
                cwstring).

                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 (1435   ), TWideStringManager (1297   )



                75.11.232            get__caller__addr

    Synopsis:    Return the address of the caller.

Declaration:     function  get_caller_addr(framebp:  pointer;addr:  CodePointer)
                                                         :  CodePointer

    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 (1374   ), get_caller_frame (1373   ), Dump_Stack (1349   )



                75.11.233            get__caller__frame

    Synopsis:    Return the frame pointer of the caller

Declaration:     function  get_caller_frame(framebp:  pointer;addr:  CodePointer)  :  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 (1373   ), get_frame (1374   ), Dump_Stack (1349   )



                75.11.234            get__caller__stackinfo

    Synopsis:    Return caller stack infomation

Declaration:     procedure  get_caller_stackinfo(var  framebp:  pointer;
                                                                  var  addr:  CodePointer)

    Visibility:   default

Description:     get_caller_stackinfo returns caller address in addr and frame base pointer in framebp.

    See also:    CaptureBacktrace (1333   ), Get_pc_addr (1374   ), get_caller_addr (1373   ), get_caller_frame (1373   )



                                                                                1373

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.235            get__cmdline

    Synopsis:    Return the command-line as a null-terminated string

Declaration:     function  get_cmdline  :  PChar

    Visibility:   default

Description:     get_cmdline  returns  the  complete  command-line  as  a  null-terminated  string.   It  is  not
                recommended to use this function, since it builds a complete value from the actual command-
                line arguments.  Instead, ParamCount (1405   ) and ParamStr (1406   ) should be used.

    See also:    ParamCount (1405   ), ParamStr (1406   )



                75.11.236            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 (1373   ), get_caller_frame (1373   )



                75.11.237            Get__pc__addr

    Synopsis:    Get Program Counter address

Declaration:     function  Get_pc_addr  :  CodePointer

    Visibility:   default

Description:     Get_pc_addr returns the program counter address (current execution address).

    See also:    CaptureBacktrace (1333   ), get_caller_stackinfo (1373   ), get_caller_addr (1373   ), get_caller_frame
                (1373   )



                75.11.238            greaterthan(variant,variant):Boolean

    Synopsis:    Implement > (greater than) operation on variants.

Declaration:     operator  >(const  op1:  variant;const  op2:  variant)  :  Boolean

    Visibility:   default

Description:     The  implementation  of  the  "greater  than"  comparison  (>)  operation  is  delegated  to  the
                variant manager with operation opcmpgt.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator <(variant, variant):  boolean (1235   )



                                                                                1374

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.239            greaterthanorequal(variant,variant):Boolean

    Synopsis:    Implement >= (greater than or equal) operation on variants.

Declaration:     operator  >=(const  op1:  variant;const  op2:  variant)  :  Boolean

    Visibility:   default

Description:     The implementation of the "greater than or equal" comparison (>=) operation is delegated
                to the variant manager with operation opcmpge.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator <(variant, variant):  boolean (1235   )



                75.11.240            halt

    Synopsis:    Stop program execution.

Declaration:     procedure  halt(errnum:  LongInt)
                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 (1357   )


                Listing:  ./refex/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  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___.____________________________________________________________________________________________________________*
 *___________



                75.11.241            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.



                                                                                1375

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   None.

    See also:    Str (1440   ), Val (1458   ), BinStr (1328   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.242            hi

    Synopsis:    Return high byte/word/nibble 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

    Visibility:   default

Description:     Hi returns the high nibble, 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.  If the
                size is 1, the high nibble is returned.

       Errors:   None

    See also:    Lo (1394   )


                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   :  B y t e;


                 b e g i n
                    L : = 1  S h l  1 6 ;         {  =   $10000      }
                   W  : = 1  S h l  8 ;           {  =   $100    }
                    B : = 1  S h l  4 ;           {  =   $10     }
                    W r i t e l n ( Hi ( L ) ) ;  {  P r i n t s 1   }



                                                                                1376

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    W r i t e l n ( Hi (W  ) ) ;  {  P r i n t s 1   }
                    W r i t e l n ( Hi ( B ) ) ;  {  P r i n t s 1   }
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.243            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.   For  dynamic  arrays,  it  returns  the  same  as  Length  -1,
                       meaning that it reports -1 for empty arrays.

                     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.  If the array is
                       empty, then -1 is returned.

                     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 (1397   ), Ord (1404   ), Pred (1409   ), Succ (1444   )


                Listing:  ./refex/ex80.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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    ;



                                                                                1377

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                       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___.____________________________________________________________________________________________________________*
 *___________



                75.11.244            HINSTANCE

    Synopsis:    Windows compatibility type for use in resources

Declaration:     function  HINSTANCE  :  TFPResourceHMODULE

    Visibility:   default

Description:     This is an opaque type.



                75.11.245            Inc

    Synopsis:    Increase value of integer variable

Declaration:     procedure  Inc(var  X:  TOrdinal)
                procedure  Inc(var  X:  TOrdinal;Increment:  TOrdinal)

    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 (1344   )


                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 ;



                                                                                1378

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.246            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 (1355   )

       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 (1355   )



                75.11.247            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 (1380   ), IndexDWord (1381   ), IndexWord (1382   ), CompareByte (1335   )


                Listing:  ./refex/ex105.pp



                                                                                1379

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.248            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.

       Errors:   Buf and Len are not checked to see if they are valid values.

    See also:    IndexByte (1379   ), IndexDWord (1381   ), IndexWord (1382   ), CompareChar (1337   )


                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   ;



                                                                                1380

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.249            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, -1 is returned.

       Errors:   On error, -1 is returned.

    See also:    IndexByte (1379   ), IndexChar (1380   ), IndexWord (1382   ), IndexDWord (1381   ), CompareChar0
                (1338   )



                75.11.250            IndexDWord

    Synopsis:    Search for a DWord value in a memory range.

Declaration:     function  IndexDWord(const  buf;len:  SizeInt;b:  DWord)  :  SizeInt

    Visibility:   default

Description:     IndexDWord 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 (1379   ), IndexChar (1380   ), IndexWord (1382   ), CompareDWord (1338   )


                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



                                                                                1381

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.251            IndexQWord

    Synopsis:    Return the position of a QWord in a memory range

Declaration:     function  IndexQWord(const  buf;len:  SizeInt;b:  QWord)  :  SizeInt

    Visibility:   default

Description:     IndexQWord  checks  the  first  len  qwords  starting  at  Buf,  and  returns  the  position  (zero-
                based) of  b.  If  b does not appear in the first len qwords, then -1 is returned.

                Note that the search is done on QWord boundaries, but that the address of buf need not be
                on a QWord boundary.

       Errors:   No check is done to see whether the indicated memory range is valid.  If it is not, a run-error
                or exception may be triggered.

    See also:    IndexDWord (1381   )



                75.11.252            Indexword

    Synopsis:    Search for a WORD value in a memory range.

Declaration:     function  Indexword(const  buf;len:  SizeInt;b:  Word)  :  SizeInt

    Visibility:   default

Description:     IndexWord  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 (1379   ), IndexDWord (1381   ), IndexChar (1380   ), CompareWord (1339   )


                Listing:  ./refex/ex107.pp



                                                                                1382

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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. }


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.253            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 (1351   ) or LeaveCriticalsection (1392   ) the critical section should be
                initialized with InitCriticalSection.

                When a critical section is no longer used, it should be disposed of with DoneCriticalsection
                (1348   )

    See also:    DoneCriticalsection (1348   ), EnterCriticalsection (1351   ), LeaveCriticalsection (1392   )



                75.11.254            Initialize

    Synopsis:    Initialize memory block using RTTI

Declaration:     procedure  Initialize(var  T:  TAnyType;ACount:  Integer)

    Visibility:   default

Description:     Initialize is a compiler intrinsic:  it initializes a memory area T for any kind of managed
                variable.   Initializing  means  zeroeing  out  the  memory  area.   In  this  sense  it  is  close  in
                functionality  to  Default  (1345   ),  but  Default  requires  an  already  initialized  variable.   It



                                                                                1383

            __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'____________________*
 *_______________



            performs  the  opposite  operation  of  finalize  (1363   ),  which  should  be  used  to  clean  up  the
            memory block when it is no longer needed.

            The  optional  ACount  parameter  can  be  used  to  initialize  an  array.   It  then  specifies  the
            number of elements in the array.

See also:    finalize (1363   ), Default (1345   ), TypeInfo (1452   )


            Listing:  ./refex/ex117.pp
            _______________________________________________________________________________________________________________________*
 *_______
            {
                T h i s  e x a m p l e d e m o n s t r a t e st h e u s e  o f   t h e  I n i t i a l i z eand    F i n a l i z ef *
 *u n c t i o n s
                u s e d  t o  i n i t i a l i z e( and    c l e a n up  )  any    RTTI   - e n a b l e d d a t a  n o t  a l l o c *
 *a t e dw i t h
                New    o r  C r e a t e.
            }


            { $mode      o b j f p c}
            { $h + }   //   u s e  a n s i s t r i n g s, t h e y  n e e d t o  be    i n i t i a l i z e.d
            Type
                PData     =  ^  TData    ;
                TData     =   r e c o r d
                    S t r e e t,C i t y,Z i p ,C o u n t r y,  T e l :  S t r i n g;
                    S t r e e t N u m b e r:  I n t e g e r;
                end  ;


             v a r
                Data   :  PData    ;


             b e g i n
                //   Do   n o t  u s e  New   .
                GetMem    ( Data   , S i z e O f(TData    ) ) ;
                Try
                   {   I n i t i a l i z et h e  s t r u c t u r e i n  memory     ,  u s i n g Run  - Time     Type     I n f o r *
 *m a t i o}n
                    I n i t i a l i z(eData   ^ ) ;
                   {   A s s i g n some     s t r i n g d a t a  t o  t h e  a n s i s t r i n gc o n t e n t s.
                       Note     t h a t  t h i s o n l y  w o r k s b e c a u s e t h e  r e c o r d was    z e r o e d  o u t by  *
 *  I n i t i a l i z}e
                   Data    ^ .S t r e e t:= ' Sesame      S t r e e t';
                   Data    ^ .C i t y:=  'Heaven     ' ;
                   Data    ^ .Z i p:=  '7 7 7 7 7 7 7' ;
                   Data    ^ .C o u n t r y:= 'S p a i n' ;
                   Data    ^ .S t r e e t N u m b e:r= 3 ;
                F i n a l l y
                   {   C l e a n up    t h e  r e c o r d c o n t e n t s.
                       Again    ,  t h e  s t r u c t u r e o f  t h e  r e c o r d i s  d e t e c t e d t h r o u g h
                       Run  - t i m e  Type     I n f o r m a t i o n}
                    F i n a l i z(eData   ^ ) ;
                   FreeMem      (Data    ) ;
                end  ;
            end___.________________________________________________________________________________________________________________*
 *_______


            Listing:  ./refex/ex118.pp
            _______________________________________________________________________________________________________________________*
 *_______
            {
                T h i s  e x a m p l e d e m o n s t r a t e st h e u s e  o f   t h e  I n i t i a l i z eand    F i n a l i z ef *
 *u n c t i o n s
                u s e d  t o  i n i t i a l i z e( and    c l e a n up  )  any    RTTI   - e n a b l e d d a t a  n o t  a l l o c *
 *a t e dw i t h
                New    o r  C r e a t e.
            }


            { $mode      o b j f p c}



                                                                            1384

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                { $h + }   //   u s e  a n s i s t r i n g s, t h e y  n e e d t o  be    i n i t i a l i z e.d
                Type
                    PData     =  ^  TData    ;
                    TData     =   r e c o r d
                        S t r e e t,C i t y,Z i p ,C o u n t r y,  T e l :  S t r i n g;
                        S t r e e t N u m b e r:  I n t e g e r;
                    end  ;


                 v a r
                    Data   :  PData    ;


                 b e g i n
                    //   We    u s e  t h e  f a c t t h a t  a   p o i n t e r i s  a l s o u s a b l e a s   an   a r r a y.
                    GetMem    ( Data   , S i z e O f(TData    ) * 2 ) ;
                    Try
                       {   I n i t i a l i z et h e  s t r u c t u r e i n  memory     ,  u s i n g Run  - Time     Type     I n f *
 *o r m a t i o}n
                        I n i t i a l i z(eData   ^ , 2 ) ;
                       {   A s s i g n some     s t r i n g d a t a  t o  t h e  a n s i s t r i n gc o n t e n t s.
                           Note     t h a t  t h i s o n l y  w o r k s b e c a u s e t h e  r e c o r d was    z e r o e d  o u t *
 *by    I n i t i a l i z}e
                       Data    [ 0 ] .S t r e e t:= 'Sesame       S t r e e t';
                       Data    [ 0 ] .C i t y:= ' Heaven    ' ;
                       Data    [ 0 ] .Z i p:=  '7 7 7 7 7 7 7';
                       Data    [ 0 ] .C o u n t r y:=' S p a i n' ;
                       Data    [ 0 ] .S t r e e t N u m b e:r= 3 ;
                       //    Second    ,   w e l l known      s t r e e t
                       Data    [ 1 ] .S t r e e t:= 'W a l l  S t r e e t';
                       Data    [ 1 ] .C i t y:= 'New     York   ' ;
                       Data    [ 1 ] .Z i p:=  '10005    ' ;
                       Data    [ 1 ] .C o u n t r y:=' USA  ' ;
                       Data    [ 1 ] .S t r e e t N u m b e:r= 1 1 ;
                    F i n a l l y
                       {   C l e a n up    t h e  r e c o r d c o n t e n t s.
                           Again    ,  t h e  s t r u c t u r e o f  t h e  r e c o r d i s  d e t e c t e d t h r o u g h
                           Run  - t i m e  Type     I n f o r m a t i o n}
                        F i n a l i z(eData   ^ ) ;
                       FreeMem      (Data    ) ;
                    end  ;
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.255            InitializeArray

    Synopsis:    Initialize managed-type elements in array

Declaration:     procedure  InitializeArray(p:  Pointer;typeInfo:  Pointer;count:  SizeInt)

    Visibility:   default

Description:     InitializeArray initializes managed types in the array pointed to by p.  For this, it uses
                the type information of the elements as specified in typeinfo.

                Under normal circumstances,  this procedure should not be used,  it is called automatically
                by the compiler when an array-typed variable is declared and the array contains elements
                with managed types.

    See also:    FinalizeArray (1364   ), CopyArray (1342   )



                                                                                1385

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.256            InitThread

    Synopsis:    Initialize a thread

Declaration:     procedure  InitThread(stklen:  SizeUInt)

    Visibility:   default

Description:     Do not use, this is used internally by the thread manager.



                75.11.257            InitThreadVars

    Synopsis:    Initialize threadvars

Declaration:     procedure  InitThreadVars(RelocProc:  TRelocateThreadVarHandler)

    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 (1290   )



                75.11.258            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:  RawByteString;var  S:  RawByteString;
                                           Index:  SizeInt)
                procedure  Insert(const  Source:  UnicodeString;var  S:  UnicodeString;
                                           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 (1346   ), Copy (1342   ), Pos (1407   )


                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  ! ';



                                                                                1386

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.259            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 (1367   ), Round (1421   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.260            intdivide(variant,variant):variant

    Synopsis:    Implement div (integer division) operation on variants.

Declaration:     operator  div(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the integer division Div operation is delegated to the variant manager
                with operation opintdivide.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator mod(variant, variant):  variant (1235   )



                75.11.261            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
                function  InterlockedCompareExchange(var  Target:  Cardinal;
                                                                          NewValue:  Cardinal;
                                                                          Comperand:  Cardinal)  :  Cardinal



                                                                                1387

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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 (1388   ), InterLockedIncrement (1389   ), InterLockedExchange (1388   ),
                InterLockedExchangeAdd (1389   )



                75.11.262            InterLockedDecrement

    Synopsis:    Thread-safe decrement

Declaration:     function  InterLockedDecrement(var  Target:  LongInt)  :  LongInt
                function  InterLockedDecrement(var  Target:  Pointer)  :  Pointer
                function  InterLockedDecrement(var  Target:  Cardinal)  :  Cardinal

    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 (1389   ), InterLockedExchange (1388   ), InterLockedExchangeAdd (1389   ),
                InterlockedCompareExchange (1387   )



                75.11.263            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
                function  InterLockedExchange(var  Target:  Cardinal;Source:  Cardinal)
                                                                :  Cardinal

    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 (1388   ), InterLockedIncrement (1389   ), InterLockedExchangeAdd (1389   ),
                InterlockedCompareExchange (1387   )



                                                                                1388

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.264            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
                function  InterLockedExchangeAdd(var  Target:  Cardinal;Source:  Cardinal)
                                                                     :  Cardinal

    Visibility:   default

Description:     InterLockedExchangeAdd 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 (1388   ), InterLockedIncrement (1389   ), InterLockedExchange (1388   ),
                InterlockedCompareExchange (1387   )



                75.11.265            InterLockedIncrement

    Synopsis:    Thread-safe increment

Declaration:     function  InterLockedIncrement(var  Target:  LongInt)  :  LongInt
                function  InterLockedIncrement(var  Target:  Pointer)  :  Pointer
                function  InterLockedIncrement(var  Target:  Cardinal)  :  Cardinal

    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 (1388   ), InterLockedExchange (1388   ), InterLockedExchangeAdd (1389   ),
                InterlockedCompareExchange (1387   )



                75.11.266            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.



                                                                                1389

         __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'_______________________*
 *____________



         5Access denied.

         6Invalid 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.

         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___.___________________________________________________________________________________________________________________*
 *____



                                                                         1390

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.267            IsDynArrayRectangular

    Synopsis:    Check whether all dimensions have the same size

Declaration:     function  IsDynArrayRectangular(a:  Pointer;typeInfo:  Pointer)  :  Boolean

    Visibility:   default

Description:     IsDynArrayRectangular returns True if all dimensions of the dynamic array a with type
                information typinfo have the same bounds.  It returns True if the array is empty.

    See also:    InitializeArray (1385   ), FinalizeArray (1364   ), CopyArray (1342   ), DynArraySize (1351   ), Dy-
                nArrayClear (1349   ), DynArrayBounds (1349   ), DynArrayDim (1350   )



                75.11.268            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 (1430   ), GetMemoryManager (1371   )



                75.11.269            Is__IntResource

    Synopsis:    Check whether a resource is an internal resource

Declaration:     function  Is_IntResource(aStr:  PChar)  :  Boolean

    Visibility:   default

Description:     Is_IntResource returns True if the resource type is internal (system predefined) resource
                or false if it is a user-defined resource type.

       Errors:   None.



                75.11.270            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 (1460   ), EndThread (1351   ), SuspendThread (1444   )



                                                                                1391

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.271            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 (1351   ).

                The critical section must have been initialized with InitCriticalSection (1383   ) prior to a call
                to EnterCriticalsection and LeaveCriticalSection.

    See also:    InitCriticalsection (1383   ), DoneCriticalsection (1348   ), EnterCriticalsection (1351   )



                75.11.272            leftshift(variant,variant):variant

    Synopsis:    Implement binary shl operation on variants.

Declaration:     operator  shl(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the shl operation is delegated to the variant manager with operation
                opshiftleft.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator shr(variant, variant):  variant (1235   )



                75.11.273            Length

    Synopsis:    Returns length of a string or array.

Declaration:     function  Length(S:  AStringType)  :  Integer
                function  Length(A:  DynArrayType)  :  Integer

    Visibility:   default

Description:     Length returns the length of the string or array S, which is limited to 255 for shortstrings.
                If the string S is empty, 0 is returned.

                Note:  The length of the string S is stored in S[0] for shortstrings only.  The Length function
                should always be used on ansistrings and widestrings.

                For dynamical or statical arrays, the function returns the number of elements in the array.

                Length also supports arguments of type PCharand PWideChar, in which case it is identical to
                the StrLen and WStrLen functions, respectively.  In this case, the function actually calculates
                the length of the null-terminated string, and its execution time is proportional to the string
                length because the terminating null character is searched through a linear scan.

       Errors:   None.

    See also:    Pos (1407   ), SetLength (1430   )


                Listing:  ./refex/ex36.pp



                                                                                1392

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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.  }


                 t y p e
                    s o m e b y t e s=   a r r a y  [ 6 . . 1 0 ]o f   b y t e;
                    somewords        =   a r r a y  [ 3 . . 1 0 ]o f  word    ;



                Var
                    S   :  S t r i n g;
                    I   :  I n t e g e r;
                    b y t e s  :  s o m e b y t e s;
                    w o r d s  :  somewords       ;


                 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   ;
                    W r i t e l n(' B y t e s :   ' ,l e n g t h(b y t e s) ) ;
                    W r i t e l n(' Words     :   ' ,l e n g t h(w o r d s) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.274            lessthan(variant,variant):Boolean

    Synopsis:    Implement < (less than) operation on variants.

Declaration:     operator  <(const  op1:  variant;const  op2:  variant)  :  Boolean

    Visibility:   default

Description:     The implementation of the "less than" comparison (<) operation is delegated to the variant
                manager with operation opcmplt.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator >(variant, variant):  boolean (1235   )



                75.11.275            lessthanorequal(variant,variant):Boolean

    Synopsis:    Implement <= (less than or equal) operation on variants.

Declaration:     operator  <=(const  op1:  variant;const  op2:  variant)  :  Boolean

    Visibility:   default

Description:     The implementation of the "less than or equal" comparison (<=) operation is delegated to
                the variant manager with operation opcmple.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator <(variant, variant):  boolean (1235   )



                                                                                1393

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.276            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 (1328   ), NtoBE (1402   ), NtoLE (1402   )



                75.11.277            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 (1358   ), Power (1408   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.278            lo

    Synopsis:    Return low nibble/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



                                                                                1394

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     Lo returns the low byte of its argument if this is of size 2 (such as Word or SmallInt), or
                the low nibble if the size is 1 (such as byte).  It returns the low word of its argument if this
                is of type Longint or Cardinal.

       Errors:   None.

    See also:    Ord (1404   ), Chr (1334   ), Hi (1376   )


                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   :  B y t e ;
                 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   }
                    B := $EF   ;
                    W r i t e l n ( Lo ( B ) ) ;                     {  P r i n t s 1 5   }
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.279            LoadResource

    Synopsis:    Load a resource for use

Declaration:     function  LoadResource(ModuleHandle:  TFPResourceHMODULE;
                                                   ResHandle:  TFPResourceHandle)  :  TFPResourceHGLOBAL

    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 (1368   ) function.

       Errors:   On error, 0 is returned.

    See also:    FindResource  (1364   ),  FreeResource  (1368   ),  SizeofResource  (1437   ),  LockResource  (1395   ),
                UnlockResource (1455   ), FreeResource (1368   )



                75.11.280            LockResource

    Synopsis:    Lock a resource

Declaration:     function  LockResource(ResData:  TFPResourceHGLOBAL)  :  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 (1455   ) function.



                                                                                1395

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   if the function fails, Nil is returned.

    See also:    FindResource  (1364   ),  FreeResource  (1368   ),  SizeofResource  (1437   ),  LoadResource  (1395   ),
                UnlockResource (1455   ), FreeResource (1368   )



                75.11.281            logicaland(variant,variant):variant

    Synopsis:    Implement logical/binary and operation on variants

Declaration:     operator  and(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the and operation is delegated to the variant manager with operation
                opand.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator or(variant, variant):  variant (1235   ), operator xor(variant, variant):  variant (1235   ),
                operator not(variant):  variant (1235   )



                75.11.282            logicalnot(variant):variant

    Synopsis:    Implement logical/binary not operation on variants

Declaration:     operator  not(const  op:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the not operation is delegated to the variant manager with operation
                opnot.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator and(variant, variant):  variant (1235   ), operator or(variant, variant):  variant (1235   ),
                operator xor(variant, variant):  variant (1235   )



                75.11.283            logicalor(variant,variant):variant

    Synopsis:    Implement logical/binary or operation on variants

Declaration:     operator  or(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the or operation is delegated to the variant manager with operation
                opor.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator and(variant, variant): variant (1235   ), operator xor(variant, variant): variant (1235   ),
                operator not(variant):  variant (1235   )



                                                                                1396

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.284            logicalxor(variant,variant):variant

    Synopsis:    Implement logical/binary xor operation on variants

Declaration:     operator  xor(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the xor operation is delegated to the variant manager with operation
                opxor.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator or(variant, variant):  variant (1235   ), operator and(variant, variant):  variant (1235   ),
                operator not(variant):  variant (1235   )



                75.11.285            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 (1429   ) 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 (1429   )

       Errors:   None.

    See also:    SetJmp (1429   )



                75.11.286            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.



                                                                                1397

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                The return type is always the same type as the type of the argument.

                for an example, see High (1377   ).

       Errors:   None.

    See also:    High (1377   ), Ord (1404   ), Pred (1409   ), Succ (1444   )



                75.11.287            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
                function  LowerCase(const  s:  UnicodeString)  :  UnicodeString
                function  LowerCase(c:  UnicodeChar)  :  UnicodeChar

    Visibility:   default

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.

                Lowercase does not change the number of characters (or bytes) in an ansistring.

       Errors:   None.

    See also:    Upcase (1455   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.288            MakeLangID

    Synopsis:    Create a langauge ID

Declaration:     function  MakeLangID(primary:  Word;sub:  Word)  :  Word

    Visibility:   default

Description:     MakeLangID creates a language ID from the primary and sub language IDS.



                                                                                1398

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.289            MemSize

    Synopsis:    Return the size of a memory block.

Declaration:     function  MemSize(p:  pointer)  :  PtrUInt

    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 (1370   ), FreeMem (1367   )



                75.11.290            mkdir

    Synopsis:    Create a new directory.

Declaration:     procedure  mkdir(const  s:  shortstring);    Overload
                procedure  mkdir(const  s:  RawByteString);    Overload
                procedure  mkdir(const  s:  unicodestring);    Overload

    Visibility:   default

Description:     Mkdir creates a new directory S.

                For an example, see Rmdir (1418   ).

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Chdir (1334   ), Rmdir (1418   )



                75.11.291            modulus(variant,variant):variant

    Synopsis:    Implement mod (modulo) operation on variants.

Declaration:     operator  mod(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the modulo Mod operation is delegated to the variant manager with
                operation opModulus.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator div(variant, variant):  variant (1235   )



                75.11.292            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.



                                                                                1399

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    See also:    Fillword (1363   ), Fillchar (1361   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.293            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 buf1 to buf2, 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 (1399   )


                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 ' ) ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1400

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.294            multiply(variant,variant):variant

    Synopsis:    Implement multiplication (*) operation on variants.

Declaration:     operator  *(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the multiplication * operation is delegated to the variant manager
                with operation opMultiply.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator /(variant, variant):  variant (1235   )



                75.11.295            negative(variant):variant

    Synopsis:    Implement - (unary minus, negation) operation on variants.

Declaration:     operator  -(const  op:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the unary minus (-) operation is delegated to the variant manager
                with operation varNeg.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator -(variant, variant):  variant (1235   )



                75.11.296            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.

                The newly allocated memory is not initialized in any way, and may contain garbage data.  It
                must be cleared with a call to FillChar (1361   ) or FillWord (1363   ).

                For an example, see Dispose (1346   ).

       Errors:   What  happens  if  no  more  memory  is  available,  depends  on  the  value  of  the  variable  Re-
                turnNilIfGrowHeapfails (1302   ):  if the variable is True then Nil is returned.  If the variable
                is False, a run-time error is generated.

    See also:    Dispose (1346   ), Freemem (1367   ), Getmem (1370   ), ReturnNilIfGrowHeapfails (1302   )



                                                                                1401

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.297            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 (1328   ), LEtoN (1394   ), NtoLE (1402   )



                75.11.298            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

    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 (1328   ), LEtoN (1394   ), NtoBE (1402   )



                75.11.299            Null

    Synopsis:    Null variant

Declaration:     function  Null  :  Variant

    Visibility:   default



                75.11.300            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.



                                                                                1402

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   None.

    See also:    Str (1440   ), Val (1458   ), BinStr (1328   ), HexStr (1375   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.301            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

    Visibility:   default

Description:     Odd returns True if  X is odd, or False otherwise.

       Errors:   None.

    See also:    Abs (1303   ), Ord (1404   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.302            Ofs

    Synopsis:    Return offset of a variable.

Declaration:     function  Ofs(var  X)  :  LongInt



                                                                                1403

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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/64 bit compiler.

       Errors:   None.

    See also:    DSeg (1348   ), CSeg (1343   ), Seg (1427   ), Ptr (1409   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.303            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 (1334   ), Succ (1444   ), Pred (1409   ), High (1377   ), Low (1397   )


                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 ;



                                                                                1404

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.304            Pack

    Synopsis:    Create packed array from normal array

Declaration:     procedure  Pack(const  A:  UnpackedArrayType;StartIndex:  TIndexType;
                                       out  Z:  PackedArrayType)

    Visibility:   default

Description:     Pack will copy the elements of an unpacked array (A) to a packed array (Z). It will start the
                copy at the index denoted by StartIndex.  The type of the index variable StartIndex must
                match the type of the index of  A. The elements are always transferred to the beginning of
                the packed array Z. (i.e.  it starts at Low(Z)).

                Obviously, the type of the elements of the arrays A and Z must match.

    See also:    unpack (1455   )



                75.11.305            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 (1406   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1405

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.306            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 (1405   ).

       Errors:   None.

    See also:    Paramcount (1405   )



                75.11.307            pi

    Synopsis:    Return the value of PI.

Declaration:     function  pi  :  ValReal

    Visibility:   default

Description:     Pi returns the value of Pi (3.1415926535897932385).

       Errors:   None.

    See also:    Cos (1343   ), Sin (1436   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1406

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.308            PopCnt

    Synopsis:    Count number of set bits

Declaration:     function  PopCnt(const  AValue:  Byte)  :  Byte
                function  PopCnt(const  AValue:  Word)  :  Word
                function  PopCnt(const  AValue:  DWord)  :  DWord
                function  PopCnt(const  AValue:  QWord)  :  QWord

    Visibility:   default

Description:     PopCnt (population count) counts the number of set bits in AValue.



                75.11.309            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:  RawByteString)
                                      :  SizeInt
                function  pos(const  substr:  shortstring;c:  Char)  :  SizeInt
                function  Pos(const  Substr:  RawByteString;const  Source:  RawByteString)
                                      :  SizeInt
                function  Pos(c:  AnsiChar;const  s:  RawByteString)  :  SizeInt
                function  Pos(const  Substr:  UnicodeString;const  Source:  UnicodeString)
                                      :  SizeInt
                function  Pos(c:  Char;const  s:  UnicodeString)  :  SizeInt
                function  Pos(c:  UnicodeChar;const  s:  UnicodeString)  :  SizeInt
                function  Pos(const  c:  RawByteString;const  s:  UnicodeString)  :  SizeInt
                function  Pos(const  c:  UnicodeString;const  s:  RawByteString)  :  SizeInt
                function  Pos(const  c:  ShortString;const  s:  UnicodeString)  :  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:  RawByteString)  :  SizeInt
                function  Pos(const  c:  RawByteString;const  s:  WideString)  :  SizeInt
                function  Pos(const  c:  WideString;const  s:  RawByteString)  :  SizeInt
                function  Pos(const  c:  ShortString;const  s:  WideString)  :  SizeInt
                function  Pos(c:  Char;const  v:  Variant)  :  SizeInt
                function  Pos(s:  ShortString;const  v:  Variant)  :  SizeInt
                function  Pos(const  a:  AnsiString;const  v:  Variant)  :  SizeInt
                function  Pos(const  w:  WideString;const  v:  Variant)  :  SizeInt
                function  Pos(const  w:  UnicodeString;const  v:  Variant)  :  SizeInt
                function  Pos(const  v:  Variant;const  c:  Char)  :  SizeInt
                function  Pos(const  v:  Variant;const  s:  ShortString)  :  SizeInt
                function  Pos(const  v:  Variant;const  a:  AnsiString)  :  SizeInt
                function  Pos(const  v:  Variant;const  w:  WideString)  :  SizeInt
                function  Pos(const  v:  Variant;const  w:  UnicodeString)  :  SizeInt
                function  Pos(const  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.



                                                                                1407

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   None

    See also:    Length (1392   ), Copy (1342   ), Delete (1346   ), Insert (1386   )


                Listing:  ./refex/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  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___.____________________________________________________________________________________________________________*
 *___________



                75.11.310            Power

    Synopsis:    Raise float to integer power

Declaration:     function  Power(Base:  Double;expon:  Double)  :  Double
                function  Power(Base:  LongInt;expon:  LongInt)  :  LongInt

    Visibility:   default

Description:     Power returns the value of base to the power expon.  Base and expon can be of type Longint,
                in which case the result will also be a Longint.

                The function actually returns Exp(expon*Ln(base))

       Errors:   None.

    See also:    Exp (1358   ), Ln (1394   )


                Listing:  ./refex/ex78.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 8;


                {   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. }


                 b e g i n
                    W r i t e l n ( Power   ( exp   ( 1 . 0 ) , 1 . 0 ) : 8 : 2 ){;  S h o u l d p r i n t 2 . 7 2  }
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.311            power(variant,variant):variant

    Synopsis:    Implement power (**) operation on variants.

Declaration:     operator  **(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default



                                                                                1408

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     The  implementation  of  the  power  **  operation  is  delegated  to  the  variant  manager  with
                operation opPower.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator *(variant, variant):  variant (1235   )



                75.11.312            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
                ({$R+}), then a run-time error will be generated.

                For an example, see Ord (1404   )

       Errors:   Run-time error 201 is generated when the result is out of range.

    See also:    Ord (1404   ), Succ (1444   ), High (1377   ), Low (1397   )



                75.11.313            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.



                75.11.314            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:

                     1.In the 32/64-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 (1304   )


                Listing:  ./refex/ex59.pp



                                                                                1409

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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 t i 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___.____________________________________________________________________________________________________________*
 *___________



                75.11.315            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.



                75.11.316            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).

 Remark:         The Free Pascal implementation of the Random routine uses the Mersenne Twister to simulate
                randomness.  This  implementation  has  a  better  statistical  distribution  than  for  example  a
                Linear Congruential generator algorithm, but is considerably slower than the latter.  If speed
                is an issue, then alternate random number generators should be considered.

       Errors:   None.

    See also:    Randomize (1411   )


                Listing:  ./refex/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  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;



                                                                                1410

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                75.11.317            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 (1410   ).

       Errors:   None.

    See also:    Random (1410   )



                75.11.318            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.

       Errors:   If no data is available,  empty values are returned (0 for ordinal values,  empty strings for
                string values)

    See also:    Readln (1413   ), Blockread (1329   ), Write (1461   ), Blockwrite (1330   )



                                                                                1411

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.319            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 (1412   ), ReadWriteBarrier (1414   ), WriteBarrier (1462   )



                75.11.320            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.

    See also:    ReadBarrier (1412   ), ReadWriteBarrier (1414   ), WriteBarrier (1462   )



                                                                                1412

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.321            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 any of the supported
                line ending styles, independent of the platform on which the code is running (supported line
                ending  styles  are  CRLF,  LF  or  CR).  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 (1411   ).

       Errors:   If no data is available,  empty values are returned (0 for ordinal values,  empty strings for
                string values)

    See also:    Read (1411   ), Blockread (1329   ), Write (1461   ), Blockwrite (1330   )



                75.11.322            ReadStr

    Synopsis:    Read variables from a string

Declaration:     procedure  ReadStr(const  S:  string;Args:  Arguments)

    Visibility:   default

Description:     ReadStr behaves like Read (1411   ), except that it reads its input from the string variable S
                instead of a file.  Semantically, the ReadStr call is equivalent to writing the string to a file
                using the Write call, and then reading them into the various arguments Arg using the Read
                call from the same file:


                var
                    F  :  Text;
                begin
                    Rewrite(F);
                    Write(F,S);
                    Close(F);
                    Reset(F);
                    Read(F,Args);
                    Close(F);
                end;


                Obviously, the ReadStr call does not use a temporary file.

                ReadStr is defined in the ISO Extended Pascal standard.  More information on the allowed
                arguments  and  the  behaviour  of  the  arguments  can  be  found  in  the  description  of  Read
                (1411   ).

    See also:    Read (1411   ), WriteStr (1463   ), Write (1461   )



                                                                                1413

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.323            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 (1412   ), ReadDependencyBarrier (1412   ), WriteBarrier (1462   )



                75.11.324            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
                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1414

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.325            ReAllocMem

    Synopsis:    Re-allocate memory on the heap

Declaration:     function  ReAllocMem(var  p:  pointer;Size:  PtrUInt)  :  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 (1370   ), FreeMem (1367   )



                75.11.326            ReAllocMemory

    Synopsis:    Alias for ReAllocMem (1415   )

Declaration:     function  ReAllocMemory(p:  pointer;Size:  PtrUInt)  :  pointer

    Visibility:   default

Description:     ReAllocMemory is an alias for ReAllocMem (1415   ).

    See also:    ReAllocMem (1415   )



                75.11.327            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 (1303   ) 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 (1303   )



                75.11.328            Rename

    Synopsis:    Rename file on disk

Declaration:     procedure  Rename(var  f:  File;const  s:  ShortString)
                procedure  Rename(var  f:  File;const  p:  PAnsiChar)
                procedure  Rename(var  f:  File;const  c:  AnsiChar)
                procedure  Rename(var  f:  File;const  s:  UnicodeString)
                procedure  Rename(var  f:  File;const  s:  RawByteString)
                procedure  Rename(var  t:  Text;const  s:  shortstring)
                procedure  Rename(var  t:  Text;const  p:  PAnsiChar)



                                                                                1415

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                procedure  Rename(var  t:  Text;const  c:  AnsiChar)
                procedure  Rename(var  t:  Text;const  s:  unicodestring)
                procedure  Rename(var  t:  Text;const  s:  RawByteString)

    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 {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Erase (1355   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.329            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)

    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 {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Rewrite (1417   ), Assign (1307   ), Close (1335   ), Append (1306   )


                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



                                                                                1416

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    { $ 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___.____________________________________________________________________________________________________________*
 *___________



                75.11.330            ResumeThread

    Synopsis:    Resume a suspended thread.

Declaration:     function  ResumeThread(threadHandle:  TThreadID)  :  DWord

    Visibility:   default

Description:     ResumeThread  causes  a  suspended  thread  (using  SuspendThread  (1444   ))  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 (1444   ), KillThread (1391   )



                75.11.331            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 (1416   ) is needed.
                File sharing is not taken into account when calling Rewrite.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Reset (1416   ), Assign (1307   ), Close (1335   ), Flush (1365   ), Append (1306   )


                Listing:  ./refex/ex52.pp



                                                                                1417

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.332            rightshift(variant,variant):variant

    Synopsis:    Implement binary shr operation on variants.

Declaration:     operator  shr(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the shr operation is delegated to the variant manager with operation
                opshiftright.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator shl(variant, variant):  variant (1235   )



                75.11.333            rmdir

    Synopsis:    Remove directory when empty.

Declaration:     procedure  rmdir(const  s:  shortstring);    Overload
                procedure  rmdir(const  s:  RawByteString);    Overload
                procedure  rmdir(const  s:  unicodestring);    Overload

    Visibility:   default

Description:     Rmdir removes the directory S.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Chdir (1334   ), Mkdir (1399   )


                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. }



                                                                                1418

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.334            RolByte

    Synopsis:    Rotate bits of a byte value to the left

Declaration:     function  RolByte(const  AValue:  Byte)  :  Byte
                function  RolByte(const  AValue:  Byte;const  Dist:  Byte)  :  Byte

    Visibility:   default

Description:     RolByte rotates the bits of the byte AValue with Dist positions to the left.  If  Dist is not
                specified, then 1 is assumed.

       Errors:   None.

    See also:    RorByte (1420   ), RolWord (1420   ), RolDWord (1419   ), RolQWord (1419   )



                75.11.335            RolDWord

    Synopsis:    Rotate bits of a DWord (cardinal) value to the left

Declaration:     function  RolDWord(const  AValue:  DWord)  :  DWord
                function  RolDWord(const  AValue:  DWord;const  Dist:  Byte)  :  DWord

    Visibility:   default

Description:     RolDWord rotates the bits of the DWord (cardinal) AValue with Dist positions to the left.
                If  Dist is not specified, then 1 is assumed.

       Errors:   None.

    See also:    RolByte (1419   ), RolWord (1420   ), RorDWord (1420   ), RolQWord (1419   )



                75.11.336            RolQWord

    Synopsis:    Rotate bits of a QWord (64-bit) value to the left

Declaration:     function  RolQWord(const  AValue:  QWord)  :  QWord
                function  RolQWord(const  AValue:  QWord;const  Dist:  Byte)  :  QWord

    Visibility:   default



                                                                                1419

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     RorQWord rotates the bits of the QWord (64-bit) AValue with Dist positions to the left.  If
                Dist is not specified, then 1 is assumed.

       Errors:   None.

    See also:    RolByte (1419   ), RolWord (1420   ), RolDWord (1419   ), RorQWord (1421   )



                75.11.337            RolWord

    Synopsis:    Rotate bits of a word value to the left

Declaration:     function  RolWord(const  AValue:  Word)  :  Word
                function  RolWord(const  AValue:  Word;const  Dist:  Byte)  :  Word

    Visibility:   default

Description:     RolWord rotates the bits of the word AValue with Dist positions to the right.  If  Dist is
                not specified, then 1 is assumed.

       Errors:   None.

    See also:    RolByte (1419   ), RorWord (1421   ), RolDWord (1419   ), RolQWord (1419   )



                75.11.338            RorByte

    Synopsis:    Rotate bits of a byte value to the right

Declaration:     function  RorByte(const  AValue:  Byte)  :  Byte
                function  RorByte(const  AValue:  Byte;const  Dist:  Byte)  :  Byte

    Visibility:   default

Description:     RorByte rotates the bits of the byte AValue with Dist positions to the right.  If Dist is not
                specified, then 1 is assumed.

       Errors:   None.

    See also:    RolByte (1419   ), RorWord (1421   ), RorDWord (1420   ), RorQWord (1421   )



                75.11.339            RorDWord

    Synopsis:    Rotate bits of a DWord (cardinal) value to the right

Declaration:     function  RorDWord(const  AValue:  DWord)  :  DWord
                function  RorDWord(const  AValue:  DWord;const  Dist:  Byte)  :  DWord

    Visibility:   default

Description:     RorDWord rotates the bits of the DWord (cardinal) AValue with Dist positions to the right.
                If  Dist is not specified, then 1 is assumed.

       Errors:   None.

    See also:    RorByte (1420   ), RolDWord (1419   ), RorWord (1421   ), RorQWord (1421   )



                                                                                1420

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.340            RorQWord

    Synopsis:    Rotate bits of a QWord (64-bit) value to the right

Declaration:     function  RorQWord(const  AValue:  QWord)  :  QWord
                function  RorQWord(const  AValue:  QWord;const  Dist:  Byte)  :  QWord

    Visibility:   default

Description:     RorQWord rotates the bits of the QWord (64-bit) AValue with Dist positions to the right.
                If  Dist is not specified, then 1 is assumed.

       Errors:   None.

    See also:    RorByte (1420   ), RorWord (1421   ), RorDWord (1420   ), RolQWord (1419   )



                75.11.341            RorWord

    Synopsis:    Rotate bits of a word value to the right

Declaration:     function  RorWord(const  AValue:  Word)  :  Word
                function  RorWord(const  AValue:  Word;const  Dist:  Byte)  :  Word

    Visibility:   default

Description:     RorWord rotates the bits of the word AValue with Dist positions to the right.  If  Dist is
                not specified, then 1 is assumed.

       Errors:   None.

    See also:    RorByte (1420   ), RolWord (1420   ), RorDWord (1420   ), RorQWord (1421   )



                75.11.342            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  "banker's  rounding":  .5  values  are  always  rounded
                towards the even number.

       Errors:   None.

    See also:    Frac (1367   ), Int (1387   ), Trunc (1450   )


                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             }



                                                                                1421

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.343            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 (1422   )

                RTLEvent is used mainly for the synchronize method.

    See also:    RTLEventDestroy (1422   ), RTLEventSetEvent (1423   ), RTLEventReSetEvent (1422   ), RTLEvent-
                WaitFor (1423   )



                75.11.344            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 (1422   ), RTLEventResetEvent (1422   ), RTLEventSetEvent (1423   )



                75.11.345            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 (1422   ), RTLEventDestroy (1422   ), RTLEventSetEvent (1423   ), RTLEvent-
                WaitFor (1423   )



                                                                                1422

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.346            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 (1422   ), RTLEventResetEvent (1422   ), RTLEventDestroy (1422   ), RTLEvent-
                WaitFor (1423   )



                75.11.347            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 (1423   ) 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 (1422   ), RTLEventDestroy (1422   ), RTLEventSetEvent (1423   ), RTLEvent-
                WaitFor (1423   )



                75.11.348            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 (1357   ), Halt (1375   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1423

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.349            SarInt64

    Synopsis:    64-bit Shift Arithmetic Right

Declaration:     function  SarInt64(const  AValue:  Int64)  :  Int64
                function  SarInt64(const  AValue:  Int64;Shift:  Byte)  :  Int64

    Visibility:   default

Description:     SarInt64 performs an arithmetic right shift for Shift positions on a 64-bit integer AValue
                and returns the result.  Shift is optional, and is 1 by default.  The difference with the regular
                Shr shift operation is that the leftmost bit is preserved during the shift operation.

    See also:    SarShortInt (1424   ), SarSmallInt (1424   ), SarLongInt (1424   )



                75.11.350            SarLongint

    Synopsis:    32-bit Shift Arithmetic Right

Declaration:     function  SarLongint(const  AValue:  LongInt;const  Shift:  Byte)  :  LongInt

    Visibility:   default

Description:     SarLongint performs an arithmetic right shift for Shift positions on a 32-bit integer AValue
                and returns the result.  Shift is optional, and is 1 by default.  The difference with the regular
                Shr shift operation is that the leftmost bit is preserved during the shift operation.

    See also:    SarShortInt (1424   ), SarSmallInt (1424   ), SarInt64 (1424   )



                75.11.351            SarShortint

    Synopsis:    8-bit Shift Arithmetic Right

Declaration:     function  SarShortint(const  AValue:  ShortInt;const  Shift:  Byte)
                                                   :  ShortInt

    Visibility:   default

Description:     SarShortint  performs  an  arithmetic  right  shift  for  Shift  positions  on  an  8-bit  integer
                AValue and returns the result.  Shift is optional, and is 1 by default.  The difference with
                the regular Shr shift operation is that the leftmost bit is preserved during the shift operation.

    See also:    SarSmallint (1424   ), SarLongint (1424   ), SarInt64 (1424   )



                75.11.352            SarSmallint

    Synopsis:    16-bit Shift Arithmetic Right

Declaration:     function  SarSmallint(const  AValue:  SmallInt;const  Shift:  Byte)
                                                   :  SmallInt

    Visibility:   default

Description:     SarSmallint  performs  an  arithmetic  right  shift  for  Shift  positions  on  an  16-bit  integer
                AValue and returns the result.  Shift is optional, and is 1 by default.  The difference with
                the regular Shr shift operation is that the leftmost bit is preserved during the shift operation.

    See also:    SarShortint (1424   ), SarLongint (1424   ), SarInt64 (1424   )



                                                                                1424

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.353            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 (1416   ) or Rewrite (1417   ), 128 is assumed.

       Errors:   Depending on the state of the {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Eof (1353   ), SeekEof (1425   ), SeekEoln (1426   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.354            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.



                                                                                1425

                __________________________________________________________CHAPTER_75.___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 (1353   ), SeekEoln (1426   ), Seek (1425   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.355            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 (1353   ), SeekEof (1425   ), Seek (1425   )


                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. }



                                                                                1426

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    While     not    SeekEoln        do
                       Begin
                       Read     ( c ) ;
                       Write      ( c ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.356            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 (1348   ), CSeg (1343   ), Ofs (1403   ), Ptr (1409   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.357            SemaphoreDestroy

    Synopsis:    Destroy a semaphore

Declaration:     procedure  SemaphoreDestroy(const  sem:  Pointer)

    Visibility:   default

Description:     SemaphoreDestroy destroys a semaphore, created with SemaphoreInit (1428   ).

                The use of semaphores requires thread support (use #rtl.cthreads (523  ) unit on unices).

       Errors:   If no thread support is compiled in, then calling this function will result in a run-time error
                232.

    See also:    #rtl.cthreads (523  ), SemaphoreWait (1428   ), SemaphorePost (1428   ), SemaphoreInit (1428   )



                                                                                1427

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.358            SemaphoreInit

    Synopsis:    Create a new semaphore

Declaration:     function  SemaphoreInit  :  Pointer

    Visibility:   default

Description:     SemaphoreInit  creates  a  new  semaphore,  which  can  be  used  in  thread  synchronization.
                The  semaphore  can  be  used  with  SemaphoreWait  (1428   )  and  SemaphorePost  (1428   ),  and
                must be destroyed with SemaphoreDestroy (1427   ).

                The result is an untyped pointer (thread support is platform dependent).

                The use of semaphores requires thread support (use #rtl.cthreads (523  ) unit on unices).

       Errors:   On error, Pointer(-1) is returned.  If no thread support is compiled in, then calling this
                function will result in a run-time error 232.

    See also:    #rtl.cthreads  (523  ),  SemaphoreWait  (1428   ),  SemaphorePost  (1428   ),  SemaphoreDestroy
                (1427   )



                75.11.359            SemaphorePost

    Synopsis:    Make semaphore available

Declaration:     procedure  SemaphorePost(const  sem:  Pointer)

    Visibility:   default

Description:     SemaphorePost  makes  the  semaphore  FSem  to  available.   Any  threads  that  were  waiting
                for the semaphore FSem to become available (using SemaphoreWait (1428   ), will continue to
                execute.

                The use of semaphores requires thread support (use #rtl.cthreads (523  ) unit on unices).

       Errors:   If no thread support is compiled in, then calling this function will result in a run-time error
                232.

    See also:    #rtl.cthreads (523  ), SemaphoreInit (1428   ), SemaphoreWait (1428   ), SemaphoreDestroy (1427   )



                75.11.360            SemaphoreWait

    Synopsis:    Wait for semaphore to become available

Declaration:     procedure  SemaphoreWait(const  sem:  Pointer)

    Visibility:   default

Description:     SemaphoreWait waits (indefinitely) for the semaphore FSem to become available.

                The use of semaphores requires thread support (use #rtl.cthreads (523  ) unit on unices).

       Errors:   If no thread support is compiled in, then calling this function will result in a run-time error
                232.

    See also:    #rtl.cthreads (523  ), SemaphoreInit (1428   ), SemaphorePost (1428   ), SemaphoreDestroy (1427   )



                                                                                1428

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.361            SetCodePage

    Synopsis:    Set the codepage of a string

Declaration:     procedure  SetCodePage(var  s:  RawByteString;CodePage:  TSystemCodePage;
                                                   Convert:  Boolean)

    Visibility:   default

Description:     SetCodePage  sets  the  codepage  of  a  string  S  to  CodePage.   If  Convert  is  True  then  the
                string will be transcoded to the new codepage.  The resulting string will have reference count
                1.

    See also:    StringCodePage (1440   )



                75.11.362            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 (1397   ) with env as an argument was made somewhere in the program.

       Errors:   None.

    See also:    LongJmp (1397   )


                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}


                 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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1429

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.363            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 \emph{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 (1392   )


                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
                    S e t l e n g t h(S, 1 0 0 ) ;
                    F i l l C h a r(S [ 1 ] , 1 0 0 , # 3 2 ) ;
                    W r i t e l n ( '"  ',S  , '" ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.364            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 the programmer's guide.

       Errors:   None.

    See also:    GetMemoryManager (1371   ), IsMemoryManagerSet (1391   )



                75.11.365            SetMultiByteConversionCodePage

    Synopsis:    Set codepage for conversions from multi-byte strings to single-byte strings

Declaration:     procedure  SetMultiByteConversionCodePage(CodePage:  TSystemCodePage)

    Visibility:   default



                                                                                1430

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     SetMultiByteConversionCodePage sets DefaultSystemCodePage (1300   ) to CodePage.  The
                effect  of  this  change  is  that  the  default  codepage  used  to  translate  multi-byte  (UTF-16)
                strings  to  single-byte  codepage-aware  strings  changes,  and  code  page  conversions  will  be
                done to the new codepage.

                Do  not  set  DefaultSystemCodePage  directly,  as  additional  actions  may  need  to  be  done
                when changing the code page.

    See also:    DefaultSystemCodePage (1300   ), SetMultiByteFileSystemCodePage (1431   ), SetMultiByteRTL-
                FileSystemCodePage (1431   )



                75.11.366            SetMultiByteFileSystemCodePage

    Synopsis:    Set codepage used when passing strings to OS single-byte filesystem APIs

Declaration:     procedure  SetMultiByteFileSystemCodePage(CodePage:  TSystemCodePage)

    Visibility:   default

Description:     SetMultiByteFileSystemCodePage  sets  the  codepage  used  in  single-byte  OS  filesystem
                APIs to CodePage.  The effect of this change is that the default codepage used to translate
                multi-byte (UTF-16) strings to single-byte codepage-aware strings used in Filesystem APIs
                changes, and strings passed to the codepage-aware filesystem APIs will be passed using the
                new codepage.

                This constant is not used if the filesystem API of the OS is multi-byte (such as on Windows).

                Do not set DefaultFileSystemCodePage directly, as additional actions may need to be done
                when changing the code page.

    See also:    DefaultFileSystemCodePage  (1299   ),  SetMultiByteConversionCodePage  (1430   ),  SetMulti-
                ByteRTLFileSystemCodePage (1431   )



                75.11.367            SetMultiByteRTLFileSystemCodePage

    Synopsis:    Set codepage used when interpreting strings from OS single-byte filesystem APIs

Declaration:     procedure  SetMultiByteRTLFileSystemCodePage(CodePage:  TSystemCodePage)

    Visibility:   default

Description:     SetMultiByteRTLFileSystemCodePage  sets  the  codepage  used  to  interprete  strings  re-
                turned by single-byte OS filesystem APIs to CodePage.

                The effect of this change is that the default codepage used to translate single byte strings
                obtained from the OS to single-byte codepage-aware strings or multi-byte strings changes,
                and strings obtained from the codepage-aware filesystem APIs will be interpreted using the
                new codepage.

                his constant is not used if the filesystem API of the OS is multi-byte (such as on Windows).

                Do not set DefaultRTLFileSystemCodePage directly, as additional actions may need to be
                done when changing the code page.

    See also:    SetMultiByteFileSystemCodePage  (1431   ),  SetMultiByteConversionCodePage  (1430   ),  Set-
                MultiByteRTLFileSystemCodePage (1431   )



                                                                                1431

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.368            SetResourceManager

    Synopsis:    Set the resource manager

Declaration:     procedure  SetResourceManager(const  New:  TResourceManager)

    Visibility:   default

Description:     SetResourceManager sets the active resource manager to Manager.  After a call to SetResourceManager,
                the functions in the Manager record will be used to handle resources.

                Note that it is not supported to change resource managers on-the-fly:  any resources or infor-
                mation about resources obtained should be discareded prior to a call to SetResourceManager.
                Typically, SetResourceManager should be called once, at program startup.

       Errors:   None.

    See also:    TResourceManager (1286   ), GetResourceManager (1371   )



                75.11.369            SetString

    Synopsis:    Set length of a string and copy buffer.

Declaration:     procedure  SetString(out  S:  AnsiString;Buf:  PAnsiChar;Len:  SizeInt)
                procedure  SetString(out  S:  AnsiString;Buf:  PWideChar;Len:  SizeInt)
                procedure  SetString(out  S:  Shortstring;Buf:  PChar;Len:  SizeInt)
                procedure  SetString(out  S:  UnicodeString;Buf:  PUnicodeChar;Len:  SizeInt)
                procedure  SetString(out  S:  UnicodeString;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 (1430   )



                75.11.370            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

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:



                                                                                1432

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                      oNever assign a new buffer to an opened file.  A new buffer can be assigned immediately
                      after a call to Rewrite (1417   ), Reset (1416   ) 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 (1307   ), Reset (1416   ), Rewrite (1417   ), Append (1306   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.371            SetTextCodePage

    Synopsis:    Set the codepage used in a text file.

Declaration:     procedure  SetTextCodePage(var  T:  Text;CodePage:  TSystemCodePage)

    Visibility:   default

Description:     GetTextCodePage sets the codepage that the text file T uses.  All strings written to the file
                will be converted to the indicated codepage.  By default, the codepage is set to CP_ACP.

       Errors:   None.

    See also:    TextRec (1280   ), GetTextCodePage (1371   )



                                                                                1433

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.372            SetTextLineEnding

    Synopsis:    Set the end-of-line character for the given text file.

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 (1242   ).

       Errors:   None.

    See also:    DefaultTextLineBreakStyle (1242   ), TTextLineBreakStyle (1289   )



                75.11.373            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 (1372   ), TThreadManager (1290   )



                75.11.374            SetUnicodeStringManager

    Synopsis:    Set the unicodestring manager

Declaration:     procedure  SetUnicodeStringManager(const  New:  TUnicodeStringManager)
                procedure  SetUnicodeStringManager(const  New:  TUnicodeStringManager;
                                                                       var  Old:  TUnicodeStringManager)

    Visibility:   default

Description:     SetUnicodeStringManager sets the current unicodestring manager to New.  Optionally, it
                returns the currently active widestring manager in Old.

                UnicodeStrings  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 UnicodeString 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 cwstring).

                It is possible to implement a custom unicodestring manager, optimized for the current ap-
                plication, without having to recompile the complete Run-Time Library.

    See also:    TUnicodeStringManager (1291   )



                                                                                1434

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.375            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:    GetVariantManager (1372   )



                75.11.376            SetWideStringManager

    Synopsis:    Set the widestring manager

Declaration:     procedure  SetWideStringManager(const  New:  TUnicodeStringManager)
                procedure  SetWideStringManager(const  New:  TUnicodeStringManager;
                                                                  var  Old:  TUnicodeStringManager)

    Visibility:   default

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
                cwstring).

                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:    TWideStringManager (1297   )



                75.11.377            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:    CompareText (1540   )



                                                                                1435

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.378            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 (1343   ), Pi (1406   ), Exp (1358   ), Ln (1394   )


                Listing:  ./refex/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  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___.____________________________________________________________________________________________________________*
 *___________



                75.11.379            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 (1304   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1436

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.380            SizeofResource

    Synopsis:    Return the size of a particular resource

Declaration:     function  SizeofResource(ModuleHandle:  TFPResourceHMODULE;
                                                      ResHandle:  TFPResourceHandle)  :  LongWord

    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 (1395   )

       Errors:   In case of an error, 0 is returned.

    See also:    FindResource (1364   ), FreeResource (1368   ), LoadResource (1395   ), LockResource (1395   ), Un-
                lockResource (1455   ), FreeResource (1368   )



                75.11.381            Slice

    Synopsis:    Return part of an array

Declaration:     function  Slice(const  A:  ArrayType;ACount:  Integer)  :  ArrayType2

    Visibility:   default

Description:     Slice returns the first ACount elements from the array A. It returns an array with the same
                element type as A, but this array is not assignment compatible to any other array, and can
                therefor only be used in open array arguments to functions.

    See also:    Length (1392   ), SetLength (1430   )


                Listing:__./refex/ex113.pp_________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 1 3;


                {   Program       t o  d e m o n s t r a t et h e  S l i c e  f u n c t i o n. }


                 p r o c e d u r eShowArray       (c o n s t A  :  a r r a y  o f  I n t e g e r) ;
                 v a r
                    I :  I n t e g e r;
                 b e g i n
                    f o r  I  : =  Low   (A  )  t o  High   (A  )  do
                       WriteLn      (I ,   '  :   ' , A  [ I] ) ;
                end   ;


                 b e g i n
                    ShowArray       ( S l i c e( [ 1 , 2 , 3 , 4 ] , 2 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.382            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 (1441   )



                                                                                1437

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.383            Sptr

    Synopsis:    Return current stack pointer

Declaration:     function  Sptr  :  Pointer

    Visibility:   default

Description:     Sptr returns the current stack pointer.

       Errors:   None.

    See also:    SSeg (1439   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.384            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 (1439   ), Ln (1394   ), Exp (1358   )


                Listing:  ./refex/ex65.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1438

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.385            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 (1438   ), Ln (1394   ), Exp (1358   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.386            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 (1438   )


                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;


                 b e g i n
                   W  := SSeg   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                75.11.387            StackTop

    Synopsis:    Top location of the stack.

Declaration:     function  StackTop  :  Pointer

    Visibility:   default



                                                                                1439

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     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.

    See also:    StackBottom (1302   ), StackLength (1302   )



                75.11.388            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 (1458   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.389            StringCodePage

    Synopsis:    Get the code page of a string

Declaration:     function  StringCodePage(const  S:  RawByteString)  :  TSystemCodePage
                                                      ;    Overload
                function  StringCodePage(const  S:  UnicodeString)  :  TSystemCodePage
                                                      ;    Overload



                                                                                1440

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    Visibility:  default

Description:     StringCodePage  returns  the  code  page  of  a  string  (S),  regardless  of  the  string  type.   It
                accesses  the  internal  structures  of  the  string  to  retrieve  this  information.   For  an  empty
                string, DefaultSystemCodePage (1300   ) is returned.

    See also:    DefaultSystemCodePage  (1300   ),  StringElementSize  (1441   ),  StringRefCount  (1442   ),  Set-
                CodePage (1429   )



                75.11.390            StringElementSize

    Synopsis:    Get the character size of a string.

Declaration:     function  StringElementSize(const  S:  RawByteString)  :  Word;    Overload
                function  StringElementSize(const  S:  UnicodeString)  :  Word;    Overload

    Visibility:   default

Description:     StringCodePage  returns  the  character  size  of  a  string  (S),  regardless  of  the  string  type.
                It accesses the internal structures of the string to retrieve this information.  For an empty
                string, SizeOf(AnsiChar) (normally 1) is returned.

    See also:    StringCodePage (1440   ), StringRefCount (1442   )



                75.11.391            StringOfChar

    Synopsis:    Return a string consisting of 1 character repeated N times.

Declaration:     function  StringOfChar(c:  AnsiChar;l:  SizeInt)  :  AnsiString

    Visibility:   default

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 (1430   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1441

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.392            StringRefCount

    Synopsis:    Get the reference count of a string

Declaration:     function  StringRefCount(const  S:  RawByteString)  :  SizeInt;    Overload
                function  StringRefCount(const  S:  UnicodeString)  :  SizeInt;    Overload

    Visibility:   default

Description:     StringRefCount returns the reference count of a string (S), regardless of the string type.
                It accesses the internal structures of the string to retrieve this information.  For an empty
                string, 0 is returned.

    See also:    StringCodePage (1440   ), StringElementSize (1441   )



                75.11.393            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 (1307   )



                75.11.394            StringToUnicodeChar

    Synopsis:    Convert an ansistring to a null-terminated array of unicode characters.

Declaration:     function  StringToUnicodeChar(const  Src:  RawByteString;
                                                              Dest:  PUnicodeChar;DestSize:  SizeInt)
                                                                :  PUnicodeChar

    Visibility:   default

Description:     StringToUnicodeChar converts the ansistring S to a unicodestring and places the result in
                Dest.  The size of the memory location pointed to by Dest must be given in DestSize.  If
                the result string is longer than the available size, the result string will be truncated.

                The function always returns Dest.

       Errors:   No check is performed to see whether Dest points to a valid memory location.

    See also:    UnicodeCharToString (1453   ), UnicodeCharLenToString (1453   )



                                                                                1442

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.395            StringToWideChar

    Synopsis:    Convert a string to an array of widechars.

Declaration:     function  StringToWideChar(const  Src:  RawByteString;Dest:  PWideChar;
                                                         DestSize:  SizeInt)  :  PWideChar

    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 (1461   ), WideCharToStrVar (1461   ), WideCharLenToStrVar (1460   ), WideCharLen-
                ToString (1460   )



                75.11.396            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.



                75.11.397            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.



                75.11.398            subtract(variant,variant):variant

    Synopsis:    Implement subtraction (-) operation on variants.

Declaration:     operator  -(const  op1:  variant;const  op2:  variant)  :  variant

    Visibility:   default

Description:     The implementation of the subtraction - operation is delegated to the variant manager with
                operation opSubtract.

       Errors:   Execution of this operator may result in an exception if no variant manager is installed or
                if the types of the operand are not suitable for the operation.

    See also:    operator -(variant, variant):  variant (1235   )



                                                                                1443

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.399            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
                ({$R+}), then a run-time error will be generated.

                for an example, see Ord (1404   ).

       Errors:   Run-time error 201 is generated when the result is out of range.

    See also:    Ord (1404   ), Pred (1409   ), High (1377   ), Low (1397   )



                75.11.400            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 (1417   ), KillThread (1391   )



                75.11.401            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 (1394   ), Hi (1376   )


                Listing:  ./refex/ex69.pp



                                                                                1444

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.402            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 (1376   ), lo (1394   ), swap (1444   ), BEToN (1328   ), NToBE (1402   ), NToLE (1402   ), LEToN
                (1394   )



                75.11.403            SysAllocMem

    Synopsis:    System memory manager:  Allocate memory

Declaration:     function  SysAllocMem(size:  PtrUInt)  :  Pointer

    Visibility:   default

Description:     SysFreemSize is the system memory manager implementation for AllocMem (1305   )

    See also:    AllocMem (1305   )



                75.11.404            SysAssert

    Synopsis:    Standard Assert failure implementation

Declaration:     procedure  SysAssert(const  Msg:  ShortString;const  FName:  ShortString;
                                                LineNo:  LongInt;ErrorAddr:  Pointer)



                                                                                1445

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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 (1241   )



                75.11.405            SysBackTraceStr

    Synopsis:    Format an address suitable for inclusion in a backtrace

Declaration:     function  SysBackTraceStr(Addr:  CodePointer)  :  ShortString

    Visibility:   default

Description:     SysBackTraceStr will create a string representation of the address Addr, suitable for inclu-
                sion in a stack backtrace.

       Errors:   None.



                75.11.406            SysFlushStdIO

    Synopsis:

Declaration:     procedure  SysFlushStdIO

    Visibility:   default

Description:



                75.11.407            SysFreemem

    Synopsis:    System memory manager free routine.

Declaration:     function  SysFreemem(p:  pointer)  :  PtrUInt

    Visibility:   default

Description:     SysFreeem is the system memory manager implementation for FreeMem (1367   )

    See also:    FreeMem (1367   )



                75.11.408            SysFreememSize

    Synopsis:    System memory manager free routine.

Declaration:     function  SysFreememSize(p:  pointer;Size:  PtrUInt)  :  PtrUInt

    Visibility:   default

Description:     SysFreemSize is the system memory manager implementation for FreeMem (1367   )

    See also:    MemSize (1399   )



                                                                                1446

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.409            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 (1370   ) function.

       Errors:   None.  The result of this function is bogus information if the current heapmanager is not
                the standard FPC heapmanager.

    See also:    GetFPCHeapStatus (1370   )



                75.11.410            SysGetHeapStatus

    Synopsis:    System implementation of GetHeapStatus (1370   )

Declaration:     function  SysGetHeapStatus  :  THeapStatus

    Visibility:   default

Description:     SysGetHeapStatus is the system implementation of the GetHeapStatus (1370   ) call.

    See also:    GetHeapStatus (1370   )



                75.11.411            SysGetmem

    Synopsis:    System memory manager memory allocator.

Declaration:     function  SysGetmem(Size:  PtrUInt)  :  Pointer

    Visibility:   default

Description:     SysGetmem is the system memory manager implementation for GetMem (1370   )

    See also:    GetMem (1370   ), GetMemory (1370   )



                75.11.412            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.



                                                                                1447

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.413            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 (1328   )



                75.11.414            SysInitStdIO

    Synopsis:    Initialize standard input and output.

Declaration:     procedure  SysInitStdIO

    Visibility:   default

Description:     SysInitStdIO initializes the standard input and output files:  Output (1301   ), Input (1301   )
                and StdErr (1302   ).  This routine is called by the initialization code of the system unit, there
                should be no need to call it directly.



                75.11.415            SysMemSize

    Synopsis:    System memory manager:  free size.

Declaration:     function  SysMemSize(p:  pointer)  :  PtrUInt

    Visibility:   default

Description:     SysFreemSize is the system memory manager implementation for MemSize (1399   )

    See also:    MemSize (1399   )



                75.11.416            SysReAllocMem

    Synopsis:    System memory manager:  Reallocate memory

Declaration:     function  SysReAllocMem(var  p:  pointer;size:  PtrUInt)  :  Pointer

    Visibility:   default

Description:     SysReallocMem is a help routine for the system memory manager implementation for Re-
                AllocMem (1415   ).

    See also:    ReAllocMem (1415   )



                75.11.417            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.



                                                                                1448

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.418            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 (1278   )



                75.11.419            SysTryResizeMem

    Synopsis:    System memory manager:  attempt to resize memory.

Declaration:     function  SysTryResizeMem(var  p:  pointer;size:  PtrUInt)  :  Boolean

    Visibility:   default

Description:     SysTryResizeMem  is  a  help  routine  for  the  system  memory  manager  implementation  for
                ReAllocMem (1415   ), SysReAllocMem (1448   )

    See also:    SysReAllocMem (1448   ), ReAllocMem (1415   )



                75.11.420            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 (1449   )



                75.11.421            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 (1449   )



                                                                                1449

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.422            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 (1444   ), ResumeThread (1417   ), KillThread (1391   )



                75.11.423            ToSingleByteFileSystemEncodedFileName

    Synopsis:    Convert string to encoding for use in single-byte filesystem API

Declaration:     function  ToSingleByteFileSystemEncodedFileName(const  Str:  UnicodeString)
                                                                                              :  RawByteString
                function  ToSingleByteFileSystemEncodedFileName
                                                                                            (const  arr:  Array  of  WideChar)
                                                                                              :  RawByteString
                function  ToSingleByteFileSystemEncodedFileName(const  Str:  RawByteString)
                                                                                              :  RawByteString

    Visibility:   default

Description:     ToSingleByteFileSystemEncodedFileName converts the argument (Str or Arr) to a single-
                byte string, encoded using the codepage used by the single-byte filesystem API.

                This  routine  is  simply  an  auxiliary  routine,  which  converts  the  argument  to  a  single-byte
                string using DefaultFileSystemCodePage (1299   ) as a codepage.

    See also:    DefaultFileSystemCodePage (1299   )



                75.11.424            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 (1367   ), Int (1387   ), Round (1421   )


                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   }



                                                                                1450

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.425            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 {$I} switch, a runtime error can be generated if there is an
                error.  In the {$I-} state, use IOResult to check for errors.

    See also:    Append (1306   ), Filepos (1359   ), Seek (1425   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.426            TryEnterCriticalsection

    Synopsis:    Try entering a critical section

Declaration:     function  TryEnterCriticalsection(var  cs:  TRTLCriticalSection)  :  LongInt

    Visibility:   default

Description:     TryEnterCriticalsection attempts to enter critical section cs.  It returns at once.  The
                return  value  is  zero  if  another  thread  owns  the  critical  section,  or  nonzero  if  the  current
                thread already owns or succesfully obtained the critical section.



                                                                                1451

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.427            TypeInfo

    Synopsis:    Return pointer to type information for type

Declaration:     function  TypeInfo(const  T:  AnyType)  :  Pointer

    Visibility:   default

Description:     TypeInfo  is  a  compiler  intrinsic:  it  returns  a  pointer  to  the  generated  type  information
                (RTTI) for the type T. If no type information was yet generated for the type, this statement
                will ensure that type information is available, i.e.  the result is always non-nil.

    See also:    Default (1345   ), TypeOf (1452   ), Initialize (1383   ), Finalize (1363   )



                75.11.428            TypeOf

    Synopsis:    Return pointer to VMT of an object

Declaration:     function  TypeOf(T:  TObjectType)  :  Pointer

    Visibility:   default

Description:     TypeOf is a compiler intrinsic:  it returns a pointer to the VMT of the object type T.

    See also:    Default (1345   ), TypeInfo (1452   )



                75.11.429            UCS4StringToUnicodeString

    Synopsis:    Convert a UCS-4 encoded string to a unicode string

Declaration:     function  UCS4StringToUnicodeString(const  s:  UCS4String)  :  UnicodeString

    Visibility:   default

Description:     UCS4StringToUnicodeString converts the UCS-4 encoded string S to a unicode string and
                returns the resulting string.

                This function requires the widestring manager.

    See also:    UnicodeStringToUCS4String (1454   )



                75.11.430            UCS4StringToWideString

    Synopsis:

Declaration:     function  UCS4StringToWideString(const  s:  UCS4String)  :  WideString

    Visibility:   default

Description:



                75.11.431            Unassigned

    Synopsis:    Unassigned variant.

Declaration:     function  Unassigned  :  Variant

    Visibility:   default



                                                                                1452

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.432            UnicodeCharLenToString

    Synopsis:    Convert a memory buffer with unicode characters to an ansistring

Declaration:     function  UnicodeCharLenToString(S:  PUnicodeChar;Len:  SizeInt)
                                                                     :  UnicodeString

    Visibility:   default

Description:     UnicodeCharLenToString  converts  the  unicode  characters  in  buffer  S  with  at  most  len
                bytes length, to an ansistring and returns the result.

                This function requires the use of a widestring manager.

       Errors:   No checking is done to see if the pointer S or length len are valid.

    See also:    StringToUnicodeChar (1442   ), UnicodeCharToString (1453   )



                75.11.433            UnicodeCharLenToStrVar

    Synopsis:    Convert a memory buffer with unicode characters to an ansistring

Declaration:     procedure  UnicodeCharLenToStrVar(Src:  PUnicodeChar;Len:  SizeInt;
                                                                     out  Dest:  UnicodeString)
                procedure  UnicodeCharLenToStrVar(Src:  PUnicodeChar;Len:  SizeInt;
                                                                     out  Dest:  AnsiString)

    Visibility:   default

Description:     UnicodeCharLenToString  converts  the  unicode  characters  in  buffer  S  with  at  most  len
                bytes length, to an ansistring and returns the result in Dest

                This function does the same as UnicodeCharLenToString (1453   ).

       Errors:   No checking is done to see if the pointer S or length len are valid.

    See also:    StringToUnicodeChar (1442   ), UnicodeCharToString (1453   ), UnicodeCharLenToString (1453   ),
                UnicodeCharToStrVar (1454   )



                75.11.434            UnicodeCharToString

    Synopsis:    Convert unicode character to string

Declaration:     function  UnicodeCharToString(S:  PUnicodeChar)  :  UnicodeString

    Visibility:   default

Description:     UnicodeCharToString converts a null-word-terminated array of unicode characters in S to
                an AnsiString value.  It simply calls UnicodeCharLenToString (1453   ) with the length of the
                string S.

                This function requires the use of a widestring manager.

       Errors:   No checking is done to see if the pointer S is valid.

    See also:    StringToUnicodeChar (1442   ), UnicodeCharLenToString (1453   ), WidestringManager (1302   )



                                                                                1453

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.435            UnicodeCharToStrVar

    Synopsis:    Convert a null-terminated memory buffer with unicode characters to an ansistring

Declaration:     procedure  UnicodeCharToStrVar(S:  PUnicodeChar;out  Dest:  AnsiString)

    Visibility:   default

Description:     UnicodeCharLenToString converts the unicode characters in buffer S up to the first null
                word, to an ansistring and returns the result in Dest

                This function does the same as UnicodeCharToString (1453   ).

       Errors:   No checking is done to see if the pointer S is valid.

    See also:    StringToUnicodeChar (1442   ), UnicodeCharToString (1453   ), UnicodeCharLenToString (1453   ),
                UnicodeCharToString (1453   )



                75.11.436            UnicodeStringToUCS4String

    Synopsis:    Convert a unicode string to a UCS-4 string.

Declaration:     function  UnicodeStringToUCS4String(const  s:  UnicodeString)  :  UCS4String

    Visibility:   default

Description:     UnicodeStringToUCS4String converts a unicode string S to a UCS-4 encoded string, and
                returns the resulting string.

                This function requires the widestring manager.

    See also:    UCS4StringToUnicodeString (1452   )



                75.11.437            UnicodeToUtf8

    Synopsis:

Declaration:     function  UnicodeToUtf8(Dest:  PChar;Source:  PUnicodeChar;
                                                     MaxBytes:  SizeInt)  :  SizeInt
                function  UnicodeToUtf8(Dest:  PChar;MaxDestBytes:  SizeUInt;
                                                     Source:  PUnicodeChar;SourceChars:  SizeUInt)
                                                      :  SizeUInt

    Visibility:   default

Description:



                75.11.438            UniqueString

    Synopsis:    Make sure reference count of string is 1

Declaration:     procedure  UniqueString(var  S:  RawByteString)
                procedure  UniqueString(var  S:  UnicodeString)
                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.



                                                                                1454

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.439            UnlockResource

    Synopsis:    Unlock a previously locked resource

Declaration:     function  UnlockResource(ResData:  TFPResourceHGLOBAL)  :  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  (1364   ),  FreeResource  (1368   ),  SizeofResource  (1437   ),  LoadResource  (1395   ),
                lockResource (1395   ), FreeResource (1368   )



                75.11.440            UnPack

    Synopsis:    Create unpacked array from packed array

Declaration:     procedure  UnPack(const  Z:  PackedArrayType;out  A:  UnpackedArrayType;
                                           StartIndex:  TIndexType)

    Visibility:   default

Description:     UnPack will copy the elements of a packed array (Z) to an unpacked array (A). All elements
                in  Z  are  copied  to  A,  starting  at  index  StartIndex  in  A.  The  type  of  the  index  variable
                StartIndex must match the type of the index of  A.

                Obviously, the type of the elements of the arrays A and Z must match.

    See also:    Pack (1405   )



                75.11.441            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:  UnicodeString)  :  UnicodeString
                function  UpCase(c:  UnicodeChar)  :  UnicodeChar
                function  UpCase(const  s:  WideString)  :  WideString

    Visibility:   default

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.

                UpCase does not change the number of characters in the string.

       Errors:   None.

    See also:    Lowercase (1398   )


                Listing:  ./refex/ex72.pp



                                                                                1455

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.442            Utf8CodePointLen

    Synopsis:    Length of an UTF-8 codepoint.

Declaration:     function  Utf8CodePointLen(P:  PAnsiChar;MaxLookAhead:  SizeInt;
                                                         IncludeCombiningDiacriticalMarks:  Boolean)
                                                           :  SizeInt

    Visibility:   default

Description:     Utf8CodePointLen returns the length of the UTF-8 codepoint starting at the beginning of P.
                It will look at at most MaxLookAhead bytes to do create this codepoint.  If IncludeCombiningDiacriticalMarks
                is true, combining diacritical marks trailing the first codepoint (which itself can also be such
                a mark) will be considered to be part of the codepoint.

                If the function returns a value > 0, then this is the number of bytes occupied by the codepoint
                and, if requested, the trailing combining diacritical marks.  If the result = 0, this means that
                all bytes within the requested MaxLookAhead could be part of a single valid codepoint and, if
                requested, its trailing diacritical marks, but that the codepoint is incomplete and more bytes
                need to be looked at.  If the result is < 0, then the function determined that the codepoint
                was invalid after processing the number of bytes equal to the absolute value of the function
                result.

                If  IncludeCombiningDiacriticalMarks is True, then


                      oIf the function processes all MaxLookAhead bytes, it will return the value MaxLookAhead
                       rather  than  0,  even  though  in  theory  more  combining  diacritical  marks  might  follow
                       if more bytes would be looked at.  Therefore, in order to ascertain that all combining
                       diacritical marks are processed, pass all bytes at once to this function.

                      oIf  an  invalid  sequence  is  detected  while  processing  a  potential  combining  diacritical
                       mark after a valid codepoint has been found already, the function will return the length
                       of this valid codepoint (plus that of any preceding valid combining diacritical marks)
                       as a positive value.  The idea is that this invalid sequence at the end is by definition not
                       a combining diacritical mark (since all of those are valid sequences) and hence should
                       not render the preceding codepoint invalid.


       Errors:   None.



                75.11.443            UTF8Decode

    Synopsis:    Convert an UTF-8 encoded ansistring to a unicodestring



                                                                                1456

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Declaration:     function  UTF8Decode(const  s:  RawByteString)  :  UnicodeString

    Visibility:  default

Description:     UTF8Decode  converts  the  UTF-8  encoded  ansistring  S  to  a  unicodestring  and  returns  the
                resulting string.  It calls the low-level Utf8ToUnicode (1457   ) function to do the actual work.

    See also:    UTF8Encode  (1457   ),  Utf8ToAnsi  (1457   ),  SetWideStringManager  (1435   ),  Utf8ToUnicode
                (1457   )



                75.11.444            UTF8Encode

    Synopsis:    Convert a widestring or unicodestring to an UTF-8 encoded ansistring

Declaration:     function  UTF8Encode(const  s:  RawByteString)  :  RawByteString
                function  UTF8Encode(const  s:  UnicodeString)  :  RawByteString
                function  UTF8Encode(const  s:  WideString)  :  RawByteString

    Visibility:   default

Description:     UTF8Encode converts an ansistring or widestring S to the equivalent UTF-8 encoded unicode
                string and returns this resulting string.  It calls the low-level UnicodeToUTF8 (1454   ) function
                to do the actual work.

                The resulting string has code page CP_UTF8.

    See also:    UTF8Decode  (1456   ),  Utf8ToAnsi  (1457   ),  UnicodeToUtf8  (1454   ),  SetWideStringManager
                (1435   )



                75.11.445            Utf8ToAnsi

    Synopsis:    Convert a UTF-8 encoded unicode string to an ansistring

Declaration:     function  Utf8ToAnsi(const  s:  RawByteString)  :  RawByteString

    Visibility:   default

Description:     Utf8ToAnsi converts an utf8-encode unicode string to an ansistring.  It converts the string
                to a widestring and then converts the widestring to an ansistring.

                For this function to work, a widestring manager must be installed.

    See also:    UTF8Encode (1457   ), UTF8Decode (1456   ), SetWideStringManager (1435   )



                75.11.446            Utf8ToUnicode

    Synopsis:    Convert a buffer with UTF-8 characters to widestring characters

Declaration:     function  Utf8ToUnicode(Dest:  PUnicodeChar;Source:  PChar;
                                                     MaxChars:  SizeInt)  :  SizeInt
                function  Utf8ToUnicode(Dest:  PUnicodeChar;MaxDestChars:  SizeUInt;
                                                     Source:  PChar;SourceBytes:  SizeUInt)  :  SizeUInt

    Visibility:   default

Description:     Utf8ToUnicode converts the buffer in Source with a length of  SourceBytes or for a maxi-
                mum length of  MaxChars (or MaxDestChars) widestring characters to the buffer pointed to
                by Dest.

                The function returns the number of copied widestring characters.

                For this function to work, a widestring manager must be installed.



                                                                                1457

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   On error, -1 is returned.

    See also:    UTF8Encode (1457   ), UTF8Decode (1456   ), Utf8ToAnsi (1457   ), SetWideStringManager (1435   )



                75.11.447            Val

    Synopsis:    Calculate numerical/enumerated 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 or an enumerated
                value, and stores this value in the variable V, which can be of type Longint, Real and Byte
                or any enumerated type.  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.  For enumerated values, the string must be the name of
                the enumerated value.  The name is searched case insensitively.

                For hexadecimal values, the prefix '0x' or 'x' (case insensitive) may be used as well.

                The conversion to enumerated exists only as of version 2.3.1 (or later) of the compiler.

       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 (1440   )


                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___.____________________________________________________________________________________________________________*
 *___________



                75.11.448            VarArrayGet

    Synopsis:

Declaration:     function  VarArrayGet(const  A:  Variant;const  Indices:  Array  of  LongInt)
                                                   :  Variant

    Visibility:   default

Description:



                                                                                1458

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.449            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  LongInt)

    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 (1458   )



                75.11.450            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.



                75.11.451            VarCast

    Synopsis:    Cast a variant to a certain type

Declaration:     procedure  VarCast(var  dest:  variant;const  source:  variant;
                                            vartype:  LongInt)

    Visibility:   default

Description:     VarCast converts the variant in Source to the type indicated in VarType and returns the
                result in dest.  The VarType must be one of the pre-defined VarNNN constants.

       Errors:   If the conversion is not possible because the value cannot be correctly casted, then a run-time
                error or an exception may occur.



                                                                                1459

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.452            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.

                Not all platforms support the timeout parameter:  the unix platforms (with threads support
                based on pthreads) do not support timeout, and will wait indefinitely for the thread to exit.

    See also:    EndThread (1351   ), KillThread (1391   )



                75.11.453            WideCharLenToString

    Synopsis:    Convert a length-limited array of widechar to an ansistring

Declaration:     function  WideCharLenToString(S:  PWideChar;Len:  SizeInt)  :  UnicodeString

    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 (1443   ), WideCharToString (1461   ), WideCharToStrVar (1461   ), WideCharLen-
                ToStrVar (1460   )



                75.11.454            WideCharLenToStrVar

    Synopsis:    Convert a length-limited array of widechar to an ansistring

Declaration:     procedure  WideCharLenToStrVar(Src:  PWideChar;Len:  SizeInt;
                                                                out  Dest:  UnicodeString)
                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 (1443   ), WideCharToString (1461   ), WideCharToStrVar (1461   ), WideCharLen-
                ToString (1460   )



                                                                                1460

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.11.455            WideCharToString

    Synopsis:    Convert a null-terminated array of widechar to an ansistring

Declaration:     function  WideCharToString(S:  PWideChar)  :  UnicodeString

    Visibility:   default

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 (1443   ), WideCharToStrVar (1461   ), WideCharLenToStrVar (1460   ), WideCharLen-
                ToString (1460   )



                75.11.456            WideCharToStrVar

    Synopsis:    Convert a null-terminated array of widechar to an ansistring

Declaration:     procedure  WideCharToStrVar(S:  PWideChar;out  Dest:  UnicodeString)
                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 (1443   ), WideCharToString (1461   ), WideCharToStrVar (1461   ), WideCharLen-
                ToString (1460   )



                75.11.457            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.



                75.11.458            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.



                                                                                1461

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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, 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.

 Remark:         When writing string variables, no codepage conversions are done.  The string is copied as-is
                to the file descriptor.  In particular, for console output, it is the programmer's responsibility
                to make sure that the codepage of the string matches the codepage of the console.

       Errors:   If an error occurs, a run-time error is generated.  This behavior can be controlled with the
                {$I} switch.

    See also:    WriteLn (1462   ), Read (1411   ), Readln (1413   ), Blockwrite (1330   )



                75.11.459            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 (1412   ), ReadDependencyBarrier (1412   ), ReadWriteBarrier (1414   )



                75.11.460            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 (1461   ) 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 newline character sequence is emitted, resulting in a new line in the
                file F.

 Remark:         The newline character is determined by the slinebreak (1257   ) constant.

 Remark:         When writing string variables, no codepage conversions are done.  The string is copied as-is
                to the file descriptor.  In particular, for console output, it is the programmer's responsibility
                to make sure that the codepage of the string matches the codepage of the console.

       Errors:   If an error occurs, a run-time error is generated.  This behavior can be controlled with the
                {$I} switch.



                                                                                1462

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    See also:    Write (1461   ), Read (1411   ), Readln (1413   ), Blockwrite (1330   ), slinebreak (1257   )


                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!  }
                    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___.____________________________________________________________________________________________________________*
 *___________



                75.11.461            WriteStr

    Synopsis:    Write variables to a string

Declaration:     procedure  WriteStr(out  S:  string;Args:  Arguments)

    Visibility:   default

Description:     WriteStr behaves like Write (1461   ), except that it stores its output in the string variable S
                instead of a file.  Semantically, the WriteStr call is equivalent to writing the arguments to
                a file using the Write call, and then reading them into S using the Read call from the same
                file:


                var
                    F  :  Text;
                begin
                    Rewrite(F);
                    Write(F,Args);
                    Close(F);
                    Reset(F);
                    Read(F,S);
                    Close(F);
                end;


                Obviously, the WriteStr call does not use a temporary file.

                WriteStr is defined in the ISO Extended Pascal standard.  More information on the allowed
                arguments and the possible formatting can be found in the description of Write (1461   ).

    See also:    Write (1461   ), ReadStr (1413   ), Read (1411   )



                                                                                1463

__________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



75.12            TDoubleRec


TDoubleRec  =  packed  record
private
    function  GetExp  :  QWord;
    procedure  SetExp(e:  QWord);
    function  GetSign  :  Boolean;
    procedure  SetSign(s:  Boolean);
    function  GetFrac  :  QWord;
    procedure  SetFrac(e:  QWord);
public
    function  Mantissa  :  QWord;
    function  Fraction  :  ValReal;
    function  Exponent  :  LongInt;
    property  Sign  :  Boolean;
    property  Exp  :  QWord;
    property  Frac  :  QWord;
    function  SpecialType  :  TFloatSpecial;
case  Byte  of
0:  (
    Bytes  :  Array[0..7]  of  Byte;
);
1:  (
    Words  :  Array[0..3]  of  Word;
);
2:  (
    Data  :  QWord;
);
3:  (
    Value  :  Double;
);
end



TDoubleRec models the memory layout of a double value when using software floating point
math.



75.12.1          Method  overview

__Page______Method_______________Description__________________________________________________________________________________
  1465      Exponent             Exponent of the floating point value
  1465      Fraction             Fraction of the floating point value
  1465      Mantissa             Mantissa of the floating point value
__1465______SpecialType__________Is_the_floating_point_value_special_?________________________________________________________



75.12.2          Property  overview

__Page______Properties________Access_______Description________________________________________________________________________
  1466      Exp               rw           Exponent
  1466      Frac              rw
__1465______Sign______________rw___________Sign_of_the_floating_point_value___________________________________________________



                                                                1464

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.12.3          TDoubleRec.Mantissa

    Synopsis:    Mantissa of the floating point value

Declaration:     function  Mantissa  :  QWord

    Visibility:   public

Description:     Mantissa returns the Mantissa part (before decimal) of the floating point value.

    See also:    TDoubleRec.Fraction (1465   ), TDoubleRec.Exponent (1465   ), TDoubleRec.SpecialType (1465   )



                75.12.4          TDoubleRec.Fraction

    Synopsis:    Fraction of the floating point value

Declaration:     function  Fraction  :  ValReal

    Visibility:   public

Description:     Fraction returns the fraction (after decimal) of the floating point value.

    See also:    TDoubleRec.Mantissa (1465   ), TDoubleRec.Exponent (1465   ), TDoubleRec.SpecialType (1465   )



                75.12.5          TDoubleRec.Exponent

    Synopsis:    Exponent of the floating point value

Declaration:     function  Exponent  :  LongInt

    Visibility:   public

Description:     Exponent returns the fraction (after decimal) of the floating point value.

    See also:    TDoubleRec.Fraction (1465   ), TDoubleRec.Mantissa (1465   ), TDoubleRec.SpecialType (1465   )



                75.12.6          TDoubleRec.SpecialType

    Synopsis:    Is the floating point value special ?

Declaration:     function  SpecialType  :  TFloatSpecial

    Visibility:   public

Description:     SpecialType returns special characteristics of the floating point value, if any.

    See also:    TDoubleRec.Fraction (1465   ), TDoubleRec.Mantissa (1465   ), TDoubleRec.Exponent (1465   )



                75.12.7          TDoubleRec.Sign

    Synopsis:    Sign of the floating point value

Declaration:     Property  Sign  :  Boolean

    Visibility:   public

      Access:    Read,Write



                                                                                1465

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.12.8          TDoubleRec.Exp

    Synopsis:    Exponent

Declaration:     Property  Exp  :  QWord

    Visibility:   public

      Access:    Read,Write

Description:     ?

    See also:    TDoubleRec.Sign (1465   ), TDoubleRec.Exponent (1465   )



                75.12.9          TDoubleRec.Frac

Declaration:     Property  Frac  :  QWord

    Visibility:   public

      Access:    Read,Write



                75.13            TExtended80Rec


                TExtended80Rec  =  packed  record
                private
                    function  GetExp  :  QWord;
                    procedure  SetExp(e:  QWord);
                    function  GetSign  :  Boolean;
                    procedure  SetSign(s:  Boolean);
                public
                    function  Mantissa  :  QWord;
                    function  Fraction  :  Extended;
                    function  Exponent  :  LongInt;
                    property  Sign  :  Boolean;
                    property  Exp  :  QWord;
                    function  SpecialType  :  TFloatSpecial;
                case  Byte  of
                0:  (
                    Bytes  :  Array[0..9]  of  Byte;
                );
                1:  (
                    Words  :  Array[0..4]  of  Word;
                );
                2:  (
                    _Exp  :  Word;
                    Frac  :  QWord;
                );
                3:  (
                    Value  :  Extended;
                );
                end



                TExtended80Rec models the memory layout of an extended value when using software float-
                ing point math.



                                                                                1466

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.13.1          Method  overview

                __Page______Method_______________Description_______________________________________________________________________*
 *___________
                  1467      Exponent             Exponent of the floating point value
                  1467      Fraction             Fraction of the floating point value
                  1467      Mantissa             Mantissa of the floating point value
                __1468______SpecialType__________Is_the_floating_point_value_special_?_____________________________________________*
 *___________



                75.13.2          Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  1468      Exp               rw           Exponent
                __1468______Sign______________rw___________Sign_of_the_floating_point_value________________________________________*
 *___________



                75.13.3          TExtended80Rec.Mantissa

    Synopsis:    Mantissa of the floating point value

Declaration:     function  Mantissa  :  QWord

    Visibility:   public

Description:     Mantissa returns the Mantissa part (before decimal) of the floating point value.

    See also:    TExtended80Rec.Fraction (1467   ), TExtended80Rec.Exponent (1467   ), TExtended80Rec.SpecialType
                (1468   )



                75.13.4          TExtended80Rec.Fraction

    Synopsis:    Fraction of the floating point value

Declaration:     function  Fraction  :  Extended

    Visibility:   public

Description:     Fraction returns the fraction (after decimal) of the floating point value.

    See also:    TExtended80Rec.Mantissa (1467   ), TExtended80Rec.Exponent (1467   ), TExtended80Rec.SpecialType
                (1468   )



                75.13.5          TExtended80Rec.Exponent

    Synopsis:    Exponent of the floating point value

Declaration:     function  Exponent  :  LongInt

    Visibility:   public

Description:     Exponent returns the fraction (after decimal) of the floating point value.

    See also:    TExtended80Rec.Fraction (1467   ), TExtended80Rec.Mantissa (1467   ), TExtended80Rec.SpecialType
                (1468   )



                                                                                1467

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.13.6          TExtended80Rec.SpecialType

    Synopsis:    Is the floating point value special ?

Declaration:     function  SpecialType  :  TFloatSpecial

    Visibility:   public

Description:     SpecialType returns special characteristics of the floating point value, if any.

    See also:    TExtended80Rec.Fraction (1467   ), TExtended80Rec.Mantissa (1467   ), TExtended80Rec.Exponent
                (1467   )



                75.13.7          TExtended80Rec.Sign

    Synopsis:    Sign of the floating point value

Declaration:     Property  Sign  :  Boolean

    Visibility:   public

      Access:    Read,Write



                75.13.8          TExtended80Rec.Exp

    Synopsis:    Exponent

Declaration:     Property  Exp  :  QWord

    Visibility:   public

      Access:    Read,Write

Description:     ?

    See also:    TExtended80Rec.Sign (1468   ), TExtended80Rec.Exponent (1467   )



                75.14            TSingleRec


                TSingleRec  =  packed  record
                private
                    function  GetExp  :  QWord;
                    procedure  SetExp(e:  QWord);
                    function  GetSign  :  Boolean;
                    procedure  SetSign(s:  Boolean);
                    function  GetFrac  :  QWord;
                    procedure  SetFrac(e:  QWord);
                public
                    function  Mantissa  :  QWord;
                    function  Fraction  :  ValReal;
                    function  Exponent  :  LongInt;
                    property  Sign  :  Boolean;
                    property  Exp  :  QWord;
                    property  Frac  :  QWord;
                    function  SpecialType  :  TFloatSpecial;
                case  Byte  of



                                                                                1468

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                0:  (
                   Bytes  :  Array[0..3]  of  Byte;
                );
                1:  (
                   Words  :  Array[0..1]  of  Word;
                );
                2:  (
                   Data  :  DWord;
                );
                3:  (
                   Value  :  Single;
                );
                end



                TsingleRec models the memory layout of a double value when using software floating point
                math.



                75.14.1          Method  overview

                __Page______Method_______________Description_______________________________________________________________________*
 *___________
                  1470      Exponent             Exponent of the floating point value
                  1469      Fraction             Fraction of the floating point value
                  1469      Mantissa             Mantissa of the floating point value
                __1470______SpecialType__________Is_the_floating_point_value_special_?_____________________________________________*
 *___________



                75.14.2          Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                  1470      Exp               rw           Exponent
                  1470      Frac              rw
                __1470______Sign______________rw___________Sign_of_the_floating_point_value________________________________________*
 *___________



                75.14.3          TSingleRec.Mantissa

    Synopsis:    Mantissa of the floating point value

Declaration:     function  Mantissa  :  QWord

    Visibility:   public

Description:     Mantissa returns the Mantissa part (before decimal) of the floating point value.

    See also:    TsingleRec.Fraction (1469   ), TsingleRec.Exponent (1470   ), TsingleRec.SpecialType (1470   )



                75.14.4          TSingleRec.Fraction

    Synopsis:    Fraction of the floating point value

Declaration:     function  Fraction  :  ValReal

    Visibility:   public

Description:     Fraction returns the fraction (after decimal) of the floating point value.

    See also:    TsingleRec.Mantissa (1469   ), TsingleRec.Exponent (1470   ), TsingleRec.SpecialType (1470   )



                                                                                1469

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.14.5          TSingleRec.Exponent

    Synopsis:    Exponent of the floating point value

Declaration:     function  Exponent  :  LongInt

    Visibility:   public

Description:     Exponent returns the fraction (after decimal) of the floating point value.

    See also:    TsingleRec.Fraction (1469   ), TsingleRec.Mantissa (1469   ), TsingleRec.SpecialType (1470   )



                75.14.6          TSingleRec.SpecialType

    Synopsis:    Is the floating point value special ?

Declaration:     function  SpecialType  :  TFloatSpecial

    Visibility:   public

Description:     SpecialType returns special characteristics of the floating point value, if any.

    See also:    TsingleRec.Fraction (1469   ), TsingleRec.Mantissa (1469   ), TsingleRec.Exponent (1470   )



                75.14.7          TSingleRec.Sign

    Synopsis:    Sign of the floating point value

Declaration:     Property  Sign  :  Boolean

    Visibility:   public

      Access:    Read,Write



                75.14.8          TSingleRec.Exp

    Synopsis:    Exponent

Declaration:     Property  Exp  :  QWord

    Visibility:   public

      Access:    Read,Write

Description:     ?

    See also:    TsingleRec.Sign (1470   ), TsingleRec.Exponent (1470   )



                75.14.9          TSingleRec.Frac

Declaration:     Property  Frac  :  QWord

    Visibility:   public

      Access:    Read,Write



                                                                                1470

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.15            IDispatch



                75.15.1          Description

                IDispatch is the pascal definition of the Windows Dispatch interface definition.


    See also:    IUnknown (1474   )



                75.15.2          Method  overview

                __Page______Method________________________Description______________________________________________________________*
 *___________
                  1471      GetIDsOfNames                 Return IDs of named procedures
                  1471      GetTypeInfo                   Return type information about properties
                  1471      GetTypeInfoCount              Return number of properties.
                __1471______Invoke________________________Invoke_a_dispatch_method_________________________________________________*
 *___________



                75.15.3          IDispatch.GetTypeInfoCount

    Synopsis:    Return number of properties.

Declaration:     function  GetTypeInfoCount(out  count:  LongInt)  :  HRESULT

    Visibility:   default



                75.15.4          IDispatch.GetTypeInfo

    Synopsis:    Return type information about properties

Declaration:     function  GetTypeInfo(Index:  LongInt;LocaleID:  LongInt;out  TypeInfo)
                                                   :  HRESULT

    Visibility:   default



                75.15.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.



                75.15.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



                                                                                1471

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.16            IEnumerable



                75.16.1          Description

                IEnumerable can be used to get an enumerator from a class.  If a class implements IEnumerable,
                it can return an enumerator interface IEnumerator (1472   ).


    See also:    IEnumerator (1472   )



                75.16.2          Method  overview

                __Page______Method____________________Description__________________________________________________________________*
 *___________
                __1472______GetEnumerator_____________Return_an_enumerator_interface_for_this_class________________________________*
 *___________



                75.16.3          IEnumerable.GetEnumerator

    Synopsis:    Return an enumerator interface for this class

Declaration:     function  GetEnumerator  :  IEnumerator

    Visibility:   default

Description:     GetEnumerator  returns  a  new  IEnumerator  (1472   )  interface  for  this  class.  This  is  called
                by the compiler whenever a for  in loop is encountered in the source code to retrieve the
                enumerator instance.

    See also:    IEnumerator (1472   )



                75.17            IEnumerator



                75.17.1          Description

                IEnumerator  is  the  interface  needed  by  the  For  ...    in  ...   language  construct,  when
                operating on classes.  It contains all methods that the compiler needs to implement a loop.

                A for  in loop like the following:


                For  O  in  MyObject  do
                    begin
                    //  do  things
                    end;


                is treated by the compiler as equivalent to the following code:


                Var
                    I  :  IEnumerator;
                    O  :  TObject;


                begin
                    I:=MyObject.GetEnumerator;
                    While  I.MoveNext  do
                       begin
                       O:=I.GetCurrent;
                       //  Do  things
                       end;
                end.



                                                                                1472

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                Any class that implements the IEnumerable interface must be able to return an IEnumerator
                instance for the compiler to use in a For  in loop.


    See also:    IEnumerable (1472   )



                75.17.2          Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                  1473      GetCurrent          Returns the current element in the iteration cycle
                  1473      MoveNext            Move to the next value
                __1474______Reset_______________Reset_the_pointer__________________________________________________________________*
 *___________



                75.17.3          Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __1474______Current___________r____________Return_the_current_item_________________________________________________*
 *___________



                75.17.4          IEnumerator.GetCurrent

    Synopsis:    Returns the current element in the iteration cycle

Declaration:     function  GetCurrent  :  TObject

    Visibility:   default

Description:     getCurrent should return the object instance representing the current value in the for  in
                loop.   GetCurrent  will  always  be  called  immediately  after  IEnumerator.MoveNext  (1473   )
                returned True.

 Remark:          The  actual  return  type  of  the  interface  should  not  necessarily  be  TObject,  it  can  be  any
                type.  The compiler will check the actual return type with the type of the loop variable, and
                they should match.

    See also:    IEnumerator.MoveNext (1473   ), IEnumerator.Reset (1474   )



                75.17.5          IEnumerator.MoveNext

    Synopsis:    Move to the next value

Declaration:     function  MoveNext  :  Boolean

    Visibility:   default

Description:     MoveNext should move the current item pointer to the next available item.  It should return
                True if an item is available, False if no more items are available.  The first time it is called
                It  will  be  called  at  the  beginning  of  the  for  loop,  so  it  should  position  the  enumerator  on
                the first value (if there is one).  After MoveNext has returned True, IEnumerator.GetCurrent
                (1473   ) will be called to retrieve the item.

    See also:    IEnumerator.Reset (1474   ), IEnumerator.GetCurrent (1473   )



                                                                                1473

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.17.6          IEnumerator.Reset

    Synopsis:    Reset the pointer

Declaration:     procedure  Reset

    Visibility:   default

Description:     Reset can be implemented to put the pointer at the start of the list.  It is not mandatory
                to implement this method, the compiler does not use it.

    See also:    IEnumerator.GetCurrent (1473   ), IEnumerator.MoveNext (1473   )



                75.17.7          IEnumerator.Current

    Synopsis:    Return the current item

Declaration:     Property  Current  :  TObject

    Visibility:   default

      Access:    Read

Description:     Current simply is the redefinition of IEnumerator.GetCurrent (1473   ) as a property.  It is
                read-only.

    See also:    IEnumerator.GetCurrent (1473   ), IEnumerator.MoveNext (1473   )



                75.18            IInvokable



                75.18.1          Description

                IInvokable is a descendent of IInterface (1267   ), compiled in the {$M+} state, so Run-Time
                Type Information (RTTI) is generated for it.


    See also:    IDispatch (1471   ), IInterface (1267   )



                75.19            IUnknown



                75.19.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.


    See also:    IInterface (1267   ), IDispatch (1471   ), IInvokable (1474   )



                75.19.2          Method  overview

                __Page______Method___________________Description___________________________________________________________________*
 *___________
                  1475      \_AddRef                 Increase reference count of the interface
                  1475      QueryInterface           Return pointer to VMT table of interface
                __1475______\_Release________________Decrease_reference_count_of_the_interface_____________________________________*
 *___________



                                                                                1474

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.19.3          IUnknown.QueryInterface

    Synopsis:    Return pointer to VMT table of interface

Declaration:     function  QueryInterface(const  iid:  TGuid;out  obj)  :  LongInt

    Visibility:   default



                75.19.4          IUnknown.__AddRef

    Synopsis:    Increase reference count of the interface

Declaration:     function  _AddRef  :  LongInt

    Visibility:   default

    See also:    IUnknown._Release (1475   )



                75.19.5          IUnknown.__Release

    Synopsis:    Decrease reference count of the interface

Declaration:     function  _Release  :  LongInt

    Visibility:   default

    See also:    IUnknown._AddRef (1475   )



                75.20            TAggregatedOb ject



                75.20.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 (1476   ) 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.


    See also:    Create (1476   ), Controller (1476   )



                75.20.2          Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                __1476______Create_________Create_a_new_instance_of__TAggregatedObject_____________________________________________*
 *___________



                75.20.3          Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __1476______Controller________r____________Controlling_instance____________________________________________________*
 *___________



                                                                                1475

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.20.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 (1476   ) 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:    Controller (1476   )



                75.20.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 (1476   )



                75.21            TContainedOb ject



                75.21.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.


    See also:    IInterface (1267   )



                75.21.2          Interfaces  overview

                __Page______Interfaces_______Description___________________________________________________________________________*
 *___________
                __1267______IInterface_______Basic_interface_for_all_COM_based_interfaces__________________________________________*
 *___________



                75.22            TInterfacedOb ject



                75.22.1          Description

                TInterfacedObject  is  a  descendent  of  TObject  (1478   )  which  implements  the  IUnknown
                (1474   ) interface.  It can be used as a base class for all classes which need reference counting.


    See also:    IUnknown (1474   ), TObject (1478   )



                                                                                1476

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.22.2          Interfaces  overview

                __Page______Interfaces________Description__________________________________________________________________________*
 *___________
                __1474______IUnknown__________Basic_interface_for_all_COM-based_interfaces_________________________________________*
 *___________



                75.22.3          Method  overview

                __Page______Method_______________________Description_______________________________________________________________*
 *___________
                  1477      AfterConstruction            Handle reference count properly.
                  1477      BeforeDestruction            Check reference count.
                __1477______NewInstance__________________Create_a_new_instance_____________________________________________________*
 *___________



                75.22.4          Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __1478______RefCount__________r____________Return_the_current_reference_count______________________________________*
 *___________



                75.22.5          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.

       Errors:   None.

    See also:    BeforeDestruction (1477   )



                75.22.6          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:    AfterConstruction (1477   )



                75.22.7          TInterfacedObject.NewInstance

    Synopsis:    Create a new instance

Declaration:     class  function  NewInstance;    Override

    Visibility:   public

Description:     NewInstance initializes a new instance of TInterfacedObject (1476   )

       Errors:   None.



                                                                                1477

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.22.8          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 (1474   ).  When it reaches zero, the class instance
                is destroyed.

    See also:    IUnknown (1474   )



                75.23            TOb ject



                75.23.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).


    See also:    TClass (1278   )



                                                                                1478

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.23.2          Method  overview

                __Page______Method_______________________________Description_______________________________________________________*
 *___________
                  1484      AfterConstruction                    Method called after the constructor was called.
                  1485      BeforeDestruction                    Method called before the destructor is called.
                  1482      ClassInfo                            Return a pointer to the type information for this class.
                  1482      ClassName                            Return the current class name.
                  1482      ClassNameIs                          Check whether the class name equals the given name.
                  1483      ClassParent                          Return the parent class.
                  1482      ClassType                            Return a "class of" pointer for the current class
                  1481      CleanupInstance                      Finalize the class instance.
                  1479      Create                               TObject Constructor
                  1481      DefaultHandler                       Default handler for integer message handlers.
                  1485      DefaultHandlerStr                    Default handler for string messages.
                  1480      Destroy                              TObject destructor.
                  1485      Dispatch                             Dispatch an integer message
                  1485      DispatchStr                          Dispatch a string message.
                  1488      Equals                               Check if two objects are equal.
                  1484      FieldAddress                         Return the address of a field.
                  1481      Free                                 Check for Nil and call destructor.
                  1480      FreeInstance                         Clean up instance and free the memory reserved for the
                                                                 instance.
                  1488      GetHashCode                          Return a hash code for the object
                  1486      GetInterface                         Return a reference to an interface
                  1486      GetInterfaceByStr                    Return an interface based on its GUID
                  1487      GetInterfaceEntry                    Return the interface table entry by GUID
                  1487      GetInterfaceEntryByStr               Return the interface table entry by string
                  1487      GetInterfaceTable                    Return a pointer to the table of implemented interfaces
                                                                 for a class
                  1486      GetInterfaceWeak                     Get a reference to an interface, not increasing the ref-
                                                                 erence count
                  1483      InheritsFrom                         Check whether class is an ancestor.
                  1481      InitInstance                         Initialize a new class instance.
                  1483      InstanceSize                         Return the size of an instance.
                  1484      MethodAddress                        Return the address of a method
                  1484      MethodName                           Return the name of a method.
                  1480      newinstance                          Allocate memory on the heap for a new instance
                  1480      SafeCallException                    Handle exception object
                  1483      StringMessageTable                   Return a pointer to the string message table.
                  1488      ToString                             Return a string representation for the object
                __1487______UnitName_____________________________Unit_name_________________________________________________________*
 *___________



                75.23.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:    Destroy (1480   )



                                                                                1479

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.23.4          TObject.Destroy

    Synopsis:    TObject destructor.

Declaration:     destructor  Destroy;    Virtual

    Visibility:   public

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 (1481   )
                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
                (1591   ) function.

    See also:    Create (1479   ), Free (1481   )



                75.23.5          TObject.newinstance

    Synopsis:    Allocate memory on the heap for a new instance

Declaration:     class  function  newinstance;    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  (1481   ).   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:    Create (1479   ), InitInstance (1481   ), InstanceSize (1483   ), FreeInstance (1480   )



                75.23.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:    Destroy (1480   ), InitInstance (1481   ), NewInstance (1480   )



                75.23.7          TObject.SafeCallException

    Synopsis:    Handle exception object

Declaration:     function  SafeCallException(exceptobject:  TObject;
                                                           exceptaddr:  CodePointer)  :  HRESULT;    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.



                                                                                1480

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.23.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 (1485   ) method.

    See also:    Dispatch (1485   ), DefaultHandlerStr (1485   )



                75.23.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 (1480   ) 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 (1591   ) should be called.

       Errors:   None.

    See also:    Destroy (1480   ), FreeAndNil (1591   )



                75.23.10           TObject.InitInstance

    Synopsis:    Initialize a new class instance.

Declaration:     class  function  InitInstance(instance:  pointer)

    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:    NewInstance (1480   ), Create (1479   )



                75.23.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:    Destroy (1480   ), Free (1481   ), InitInstance (1481   )



                                                                                1481

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.23.12           TObject.ClassType

    Synopsis:    Return a "class of" pointer for the current class

Declaration:     class  function  ClassType

    Visibility:   public

Description:     ClassType returns a TClass (1278   ) class type reference for the current class.

    See also:    TClass (1278   ), ClassInfo (1482   ), ClassName (1482   )



                75.23.13           TObject.ClassInfo

    Synopsis:    Return a pointer to the type information for this class.

Declaration:     class  function  ClassInfo

    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.



                75.23.14           TObject.ClassName

    Synopsis:    Return the current class name.

Declaration:     class  function  ClassName

    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 (1482   ) class method.

       Errors:   None.

    See also:    ClassInfo (1482   ), ClassType (1482   ), ClassNameIs (1482   )



                75.23.15           TObject.ClassNameIs

    Synopsis:    Check whether the class name equals the given name.

Declaration:     class  function  ClassNameIs(const  name:  string)

    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:    ClassInfo (1482   ), ClassType (1482   ), ClassName (1482   )



                                                                                1482

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.23.16           TObject.ClassParent

    Synopsis:    Return the parent class.

Declaration:     class  function  ClassParent

    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:    ClassInfo (1482   ), ClassType (1482   ), ClassNameIs (1482   )



                75.23.17           TObject.InstanceSize

    Synopsis:    Return the size of an instance.

Declaration:     class  function  InstanceSize

    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:    InitInstance (1481   ), ClassName (1482   ), ClassInfo (1482   ), ClassType (1482   )



                75.23.18           TObject.InheritsFrom

    Synopsis:    Check whether class is an ancestor.

Declaration:     class  function  InheritsFrom(aclass:  TClass)

    Visibility:   public

Description:     InheritsFrom returns True if AClass is an ancestor class from the current class, and returns
                false if it is not.

    See also:    ClassName (1482   ), ClassInfo (1482   ), ClassType (1482   ), TClass (1278   )



                75.23.19           TObject.StringMessageTable

    Synopsis:    Return a pointer to the string message table.

Declaration:     class  function  StringMessageTable

    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  (1485   )
                method.

       Errors:   If there are no string message handlers, nil is returned.

    See also:    DispatchStr (1485   ), Dispatch (1485   )



                                                                                1483

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.23.20           TObject.MethodAddress

    Synopsis:    Return the address of a method

Declaration:     class  function  MethodAddress(const  name:  shortstring)

    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:    MethodName (1484   ), FieldAddress (1484   )



                75.23.21           TObject.MethodName

    Synopsis:    Return the name of a method.

Declaration:     class  function  MethodName(address:  CodePointer)

    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:    MethodAddress (1484   ), FieldAddress (1484   )



                75.23.22           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:    MethodAddress (1484   ), MethodName (1484   )



                75.23.23           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:    BeforeDestruction (1485   ), Create (1479   )



                                                                                1484

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.23.24           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:    AfterConstruction (1484   ), Destroy (1480   ), Free (1481   )



                75.23.25           TObject.DefaultHandlerStr

    Synopsis:    Default handler for string messages.

Declaration:     procedure  DefaultHandlerStr(var  message);    Virtual

    Visibility:   public

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:    DispatchStr (1485   ), Dispatch (1485   ), DefaultHandler (1481   )



                75.23.26           TObject.Dispatch

    Synopsis:    Dispatch an integer message

Declaration:     procedure  Dispatch(var  message);    Virtual

    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 (1481   )
                method, which can be overridden by descendent classes to add custom handling of messages.

    See also:    DispatchStr (1485   ), DefaultHandler (1481   )



                75.23.27           TObject.DispatchStr

    Synopsis:    Dispatch a string message.

Declaration:     procedure  DispatchStr(var  message);    Virtual

    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 (1485   ) is called.



                                                                                1485

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   None.

    See also:    DefaultHandlerStr (1485   ), Dispatch (1485   ), DefaultHandler (1481   )



                75.23.28           TObject.GetInterface

    Synopsis:    Return a reference to an interface

Declaration:     function  GetInterface(const  iid:  TGuid;out  obj)  :  Boolean
                function  GetInterface(const  iidstr:  shortstring;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:    GetInterfaceByStr (1486   )



                75.23.29           TObject.GetInterfaceByStr

    Synopsis:    Return an interface based on its GUID

Declaration:     function  GetInterfaceByStr(const  iidstr:  shortstring;out  obj)  :  Boolean

    Visibility:   public

Description:     GetInterfaceByStr  returns  in  obj  a  pointer  to  the  interface  identified  by  iidstr.   The
                function returns True if the interface is indeed implemented by the class, or False otherwise.

                The iidstr is the unique GUID by which the interface was declared.

       Errors:   The function returns false if the requested interface is not implemented.

    See also:    TObject.GetInterfaceEntry (1487   ), TObject.GetInterfaceEntryByStr (1487   )



                75.23.30           TObject.GetInterfaceWeak

    Synopsis:    Get a reference to an interface, not increasing the reference count

Declaration:     function  GetInterfaceWeak(const  iid:  TGuid;out  obj)  :  Boolean

    Visibility:   public

Description:     GetInterfaceWeak performs the same function as Getinterface (1486   ), but unlike the latter,
                it will not increase the reference count of the interface.

    See also:    TObject.GetInterface (1486   )



                                                                                1486

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.23.31           TObject.GetInterfaceEntry

    Synopsis:    Return the interface table entry by GUID

Declaration:     class  function  GetInterfaceEntry(const  iid:  TGuid)

    Visibility:   public

Description:     GetInterfaceEntry returns the internal interface table entry for the interface identified by
                iid (the GUID used in the declaration of the interface).  If the interface is not implemented
                by the class, the function returns Nil.

    See also:    TObject.GetInterfaceByStr (1486   ), TObject.GetInterfaceEntryByStr (1487   )



                75.23.32           TObject.GetInterfaceEntryByStr

    Synopsis:    Return the interface table entry by string

Declaration:     class  function  GetInterfaceEntryByStr(const  iidstr:  shortstring)

    Visibility:   public

Description:     GetInterfaceEntryByStr returns the internal interface table entry for the interface identi-
                fied by iidstr (A string representation of the GUID used in the declaration of the interface).
                If the interface is not implemented by the class, the function returns Nil.

    See also:    TObject.GetInterfaceByStr (1486   ), TObject.GetInterfaceEntry (1487   )



                75.23.33           TObject.GetInterfaceTable

    Synopsis:    Return a pointer to the table of implemented interfaces for a class

Declaration:     class  function  GetInterfaceTable

    Visibility:   public

Description:     GetInterfaceTable returns a pointer to the internal table of implemented interfaces for a
                class.  The result will always point to a valid address, if the class implements no interfaces
                the EntryCount field of the interface table will be zero.

    See also:    TObject.GetInterfaceByStr (1486   ), TObject.GetInterfaceEntry (1487   )



                75.23.34           TObject.UnitName

    Synopsis:    Unit name

Declaration:     class  function  UnitName

    Visibility:   public

Description:     UnitName returns the unit name in which the class was defined.  The name is obtained from
                the class definition data the compiler generates for each class.



                                                                                1487

                __________________________________________________________CHAPTER_75.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                75.23.35           TObject.Equals

    Synopsis:    Check if two objects are equal.

Declaration:     function  Equals(Obj:  TObject)  :  Boolean;    Virtual

    Visibility:   public

Description:     Equals returns True if the object instance pointer (Self) equals the instance pointer Obj.

                Descendent  classes  can  override  to  check  properties  etc.  in  case  the  instance  pointers  are
                different.

    See also:    TObject.GetHashCode (1488   ), TObject.ToString (1488   )



                75.23.36           TObject.GetHashCode

    Synopsis:    Return a hash code for the object

Declaration:     function  GetHashCode  :  PtrInt;    Virtual

    Visibility:   public

Description:     GetHashCode should return a hash code for the object.  By default, the numerical (integer)
                address of  Self is returned.

                Descendent classes can use this to generate better suitable values to be used in a hash table.

    See also:    TObject.ToString (1488   ), TObject.Equals (1488   )



                75.23.37           TObject.ToString

    Synopsis:    Return a string representation for the object

Declaration:     function  ToString  :  ansistring;    Virtual

    Visibility:   public

Description:     ToString  returns  by  default  the  class  name  of  the  object.  It  is  useful  during  sending  of
                debug messages.

                Descendent classes can override this method to give a better description of the object than
                just the class name.

    See also:    TObject.GetHashCode (1488   ), TObject.Equals (1488   )



                                                                                1488




Chapter   76



Reference   for   unit   'sysutils'



76.1          Used  units



                                    Table 76.1:  Used units by unit 'sysutils'


                                                  __Name____________Page_____
                                                    errors            660
                                                    Linux             872
                                                    sysconst           ??
                                                    System          1235
                                                    Unix            1761
                                                    unixtype        1798



76.2          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.



76.3          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:  cwstring,  which loads the various
needed  functions  from  the  C  library.   It  should  be  added  manually  to  the  uses  clause  of
your  program.   No  internationalization  (or  localisation)  settings  are  applied  by  this  unit,
these must be initialized separately by including the clocale unit in the uses clause of your
program.



                                                            1489

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



76.4          Unicode  and  codepage  awareness


The many functions that deal with filenames in the sysutils routines have been changed from
AnsiString to RawByteString so they do not perform implict codepage conversions to the
ansi  code  page.  At  the  same  time,  overloaded  versions  that  accept  a  unicode  string  have
been created.

For routines that access actual OS functions using single-byte string APIS, the strings are
converted  to  ensure  that  the  OS  routine  receives  a  string  with  the  correct  encoding  when
using single-byte strings.  This encoding is normally the DefaultFileSystemCodePage (1299   )
encoding.

On systems with a unicode I/O API (2-byte strings), the native API is used, meaning that
unicode strings will be passed on as-is, but single-byte strings will be converted (implicitly)
to Unicode.

The following is a minimal list of functions that have been changed and duplicated:



                                                       Table 76.2:

     __Name_______________________________Description____________________________________________________________________
       FileCreate (1564   )               Create a new file and return a handle to it.
       FileOpen (1568   )                 Open an existing file and return a filehandle
       FileExists (1565   )               Check whether a particular file exists in the filesystem.
       DirectoryExists (1550   )          Check whether a directory exists in the file system.
       FileSetDate (1571   )              Set the date of a file.
       FileGetAttr (1566   )              Return attributes of a file.
       FileSetAttr (1571   )              Set the attributes of a file.
       DeleteFile (1550   )               Delete a file from the filesystem.
       RenameFile (1609   )               Rename a file.
       FileSearch (1569   )               Search for a file in a path.
       ExeSearch (1557   )                Search for an executable
       FindFirst (1573   )                Start a file search and return a findhandle
       FindNext (1575   )                 Find the next entry in a findhandle.
       FindClose (1573   )                Close a find handle
       FileIsReadOnly (1568   )           Check whether a file is read-only.
       GetCurrentDir (1593   )            Return the current working directory of the application.
       SetCurrentDir (1612   )            Set the current directory of the application.



The following functions do not interact with the OS, but may nevertheless change the code-
page of the strings involved in their operation:



                                                                1490

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                                                       Table 76.3:



__Name___________________________________________________Description_______________________________________________________________*
 *___________________________________________
  ChangeFileExt (1537   )                                Change the extension of a filename.
  ExtractFilePath (1561   )                              Extract the path from a filename.
  ExtractFileDrive (1560   )                             Extract the drive part from a filename.
  ExtractFileName (1561   )                              Extract the filename part from a full path filename.
  ExtractFileExt (1561   )                               Return the extension from a filename.
  ExtractFileDir (1560   )                               Extract the drive and directory part of a filename.
  ExtractShortPathName (1562   )                         Returns a 8.3 path name
  ExpandFileName (1558   )                               Expand a relative filename to an absolute filename.
  ExpandFileNameCase (1558   )                           Expand a filename entered as case insensitive to the full path as stored o*
 *n the disk.
  ExtractRelativepath (1562   )                          Extract a relative path from a filename, given a base directory.
  ExpandUNCFileName (1559   )                            Expand a relative filename to an absolute UNC filename.
  IncludeTrailingPathDelimiter (1600   )                 Add trailing directory separator to a pathname, if needed.
  IncludeTrailingBackslash (1600   )                     Add trailing directory separator to a pathname, if needed.
  ExcludeTrailingBackslash (1556   )                     Strip trailing directory separator from a pathname, if needed.
  ExcludeTrailingPathDelimiter (1556   )                 Strip trailing directory separator from a pathname, if needed.
  IncludeLeadingPathDelimiter (1599   )                  Prepend a path delimiter if there is not already one.
  ExcludeLeadingPathDelimiter (1556   )                  Strip the leading path delimiter of a path
  IsPathDelimiter (1604   )                              Is the character at the given position a pathdelimiter ?
  DoDirSeparators (1552   )                              Convert known directory separators to the current directory separator.
  SetDirSeparators (1612   )                             Set the directory separators to the known directory separators.
  GetDirs (1593   )                                      Return a list of directory names from a path.
  ConcatPaths (1541   )                                  Concatenate an array of paths to form a single path
  GetEnvironmentVariable (1595   )                       Return the value of an environment variable.



76.5          Miscellaneous  conversion  routines


Functions for various conversions.



                                                       Table 76.4:

              __Name_____________________________Description____________________________________________________
                BCDToInt (1534   )               Convert BCD number to integer
                CompareMem (1538   )             Compare two memory regions
                FloatToStrF (1577   )            Convert float to formatted string
                FloatToStr (1576   )             Convert float to string
                FloatToText (1579   )            Convert float to string
                FormatFloat (1590   )            Format a floating point value
                GetDirs (1593   )                Split string in list of directories
                IntToHex (1601   )               return hexadecimal representation of integer
                IntToStr (1602   )               return decumal representation of integer
                StrToIntDef (1634   )            Convert string to integer with default value
                StrToInt (1633   )               Convert string to integer
                StrToFloat (1631   )             Convert string to float
                TextToFloat (1638   )            Convert null-terminated string to float



                                                                1491

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



76.6          Date/time  routines


Functions for date and time handling.



                                                       Table 76.5:

    _Name____________________________________________Description____________________________________________________________
      DateTimeToFileDate (1544   )                    Convert DateTime type to file date
      DateTimeToStr (1544   )                         Construct string representation of DateTime
      DateTimeToString (1545   )                      Construct string representation of DateTime
      DateTimeToSystemTime (1546   )                  Convert DateTime to system time
      DateTimeToTimeStamp (1547   )                   Convert DateTime to timestamp
      DateToStr (1547   )                             Construct string representation of date
      Date (1543   )                                  Get current date
      DayOfWeek (1548   )                             Get day of week
      DecodeDate (1548   )                            Decode DateTime to year month and day
      DecodeTime (1549   )                            Decode DateTime to hours, minutes and seconds
      EncodeDate (1553   )                            Encode year, day and month to DateTime
      EncodeTime (1554   )                            Encode hours, minutes and seconds to DateTime
      FormatDateTime (1589   )                        Return string representation of DateTime
      IncMonth (1600   )                              Add 1 to month
      IsLeapYear (1603   )                            Determine if year is leap year
      MSecsToTimeStamp (1606   )                      Convert nr of milliseconds to timestamp
      Now (1607   )                                   Get current date and time
      StrToDateTime (1630   )                         Convert string to DateTime
      StrToDate (1629   )                             Convert string to date
      StrToTime (1635   )                             Convert string to time
      SystemTimeToDateTime (1637   )                  Convert system time to datetime
      TimeStampToDateTime (1640   )                   Convert time stamp to DateTime
      TimeStampToMSecs (1640   )                      Convert Timestamp to number of millicseconds
      TimeToStr (1641   )                             return string representation of Time
      Time (1639   )                                  Get current time



76.7          FileName  handling  routines


Functions for file manipulation.



                                                                1492

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                                                       Table 76.6:

       __Name____________________________________________Description____________________________________________________
         AnsiCompareFileName (1520   )                   Compare 2 filenames
         AnsiLowerCaseFileName (1524   )                 Create lowercase filename
         AnsiUpperCaseFileName (1532   )                 Create uppercase filename
         AddDisk (1519   )                               Add disk to list of disk drives
         ChangeFileExt (1537   )                         Change extension of file name
         CreateDir (1541   )                             Create a directory
         DeleteFile (1550   )                            Delete a file
         DiskFree (1551   )                              Free space on disk
         DiskSize (1551   )                              Total size of disk
         ExpandFileName (1558   )                        Create full file name
         ExpandFileNameCase (1558   )                    Create full file name case insensitively
         ExpandUNCFileName (1559   )                     Create full UNC file name
         ExtractFileDir (1560   )                        Extract drive and directory part of filename
         ExtractFileDrive (1560   )                      Extract drive part of filename
         ExtractFileExt (1561   )                        Extract extension part of filename
         ExtractFileName (1561   )                       Extract name part of filename
         ExtractFilePath (1561   )                       Extrct path part of filename
         ExtractRelativePath (1562   )                   Construct relative path between two files
         FileAge (1563   )                               Return file age
         FileDateToDateTime (1565   )                    Convert file date to system date
         FileExists (1565   )                            Determine whether a file exists on disk
         FileGetAttr (1566   )                           Get attributes of file
         FileGetDate (1567   )                           Get date of last file modification
         FileSearch (1569   )                            Search for file in path
         FileSetAttr (1571   )                           Get file attributes
         FileSetDate (1571   )                           Get file dates
         FindFirst (1573   )                             Start finding a file
         FindNext (1575   )                              Find next file
         GetCurrentDir (1593   )                         Return current working directory
         RemoveDir (1609   )                             Remove a directory from disk
         RenameFile (1609   )                            Rename a file on disk
         SameFileName (1611   )                          Check whether 2 filenames are the same
         SetCurrentDir (1612   )                         Set current working directory
         SetDirSeparators (1612   )                      Set directory separator characters
         FindClose (1573   )                             Stop searching a file
         DoDirSeparators (1552   )                       Replace directory separator characters



76.8          File  input/output  routines


Functions for reading/writing to file.



                                                                1493

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                                                       Table 76.7:

                        __Name___________________________Description__________________________________
                          FileCreate (1564   )           Create a file and return handle
                          FileOpen (1568   )             Open file end return handle
                          FileRead (1569   )             Read from file
                          FileSeek (1570   )             Set file position
                          FileTruncate (1572   )         Truncate file length
                          FileWrite (1572   )            Write to file
                          FileClose (1563   )            Close file handle



76.9          PChar  related  functions


Most PChar functions are the same as their counterparts in the STRINGS unit.  The following
functions are the same :


    1.  StrCat (1615   ) :  Concatenates two PChar strings.

    2.  StrComp (1616   ) :  Compares two PChar strings.

    3.  StrCopy (1616   ) :  Copies a PChar string.

    4.  StrECopy (1617   ) :  Copies a PChar string and returns a pointer to the terminating null
        byte.

    5.  StrEnd (1617   ) :  Returns a pointer to the terminating null byte.

    6.  StrIComp (1619   ) :  Case insensitive compare of 2 PChar strings.

    7.  StrLCat (1620   ) :  Appends at most L characters from one PChar to another PChar.

    8.  StrLComp (1621   ) :  Case sensitive compare of at most L characters of 2 PChar strings.

    9.  StrLCopy (1621   ) :  Copies at most L characters from one PChar to another.

   10.  StrLen (1622   ) :  Returns the length (exclusive terminating null byte) of a PChar string.

   11.  StrLIComp  (1623   )  :   Case  insensitive  compare  of  at  most  L  characters  of  2  PChar
        strings.

   12.  StrLower (1623   ) :  Converts a PChar to all lowercase letters.

   13.  StrMove (1624   ) :  Moves one PChar to another.

   14.  StrNew (1625   ) :  Makes a copy of a PChar on the heap, and returns a pointer to this
        copy.

   15.  StrPos (1626   ) :  Returns the position of one PChar string in another?

   16.  StrRScan (1627   ) :  returns a pointer to the last occurrence of on PChar string in another
        one.

   17.  StrScan (1627   ) :  returns a pointer to the first occurrence of on PChar string in another
        one.

   18.  StrUpper (1636   ) :  Converts a PChar to all uppercase letters.


The  subsequent  functions  are  different  from  their  counterparts  in  STRINGS,  although  the
same examples can be used.



                                                                1494

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



76.10            Date  and  time  formatting  characters


Various date and time formatting routines accept a format string to format the date and or
time.  The following characters can be used to control the date and time formatting:


c  Formats date using shortdateformat and formats time using longtimeformat if the time
        is not zero.

f  Same as c, but adds the time even if it is zero.

d   day of month

dd    day of month (leading zero)

ddd     day of week (abbreviation)

dddd      day of week (full)

ddddd       shortdateformat

dddddd        longdateformat

m    month

mm      month (leading zero)

mmm        month (abbreviation)

mmmm          month (full)

y   year (2 digits)

yy    year (two digits)

yyyy     year (with century)

h   hour

hh    hour (leading zero)

n   minute

nn    minute (leading zero)

s  second

ss   second (leading zero)

t  shorttimeformat

tt   longtimeformat

am/pm        use 12 hour clock and display am and pm accordingly

a/p    use 12 hour clock and display a and p accordingly

/   insert date seperator

:  insert time seperator

"xx"     literal text

'xx'    literal text



                                                                1495

            _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            z  milliseconds

            zzz   milliseconds(leading zero)


            The date and time separators are taken from the DefaultFormatSettings (1514   ) record, unless
            a TFormatSettings (1509   ) record is passed to the FormatDateTime (1589   ) function.

            Note that to include any of the above characters literally in the result string, they must be
            enclosed in double quotes.


See also:    DefaultFormatSettings (1514   ), TFormatSettings (1509   ), FormatDateTime (1589   )



            76.11            Formatting  strings


            Functions for formatting strings.



                                                                   Table 76.8:

                       __Name__________________________________Description_____________________________________________________
                         AdjustLineBreaks (1519   )            Convert line breaks to line breaks for system
                         FormatBuf (1588   )                   Format a buffer
                         Format (1581   )                      Format arguments in string
                         FmtStr (1580   )                      Format buffer
                         QuotedStr (1608   )                   Quote a string
                         StrFmt (1618   )                      Format arguments in a string
                         StrLFmt (1622   )                     Format maximum L characters in a string
                         TrimLeft (1642   )                    Remove whitespace at the left of a string
                         TrimRight (1642   )                   Remove whitespace at the right of a string
                         Trim (1641   )                        Remove whitespace at both ends of a string



            76.12            String  functions


            Functions for handling strings.



                                                                            1496

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                                                       Table 76.9:

      __Name________________________________________Description__________________________________________________________
        AnsiCompareStr (1520   )                     Compare two strings
        AnsiCompareText (1521   )                    Compare two strings, case insensitive
        AnsiExtractQuotedStr (1522   )               Removes quotes from string
        AnsiLastChar (1523   )                       Get last character of string
        AnsiLowerCase (1524   )                      Convert string to all-lowercase
        AnsiQuotedStr (1525   )                      Qoutes a string
        AnsiStrComp (1526   )                        Compare strings case-sensitive
        AnsiStrIComp (1526   )                       Compare strings case-insensitive
        AnsiStrLComp (1528   )                       Compare L characters of strings case sensitive
        AnsiStrLIComp (1529   )                      Compare L characters of strings case insensitive
        AnsiStrLastChar (1527   )                    Get last character of string
        AnsiStrLower (1530   )                       Convert string to all-lowercase
        AnsiStrUpper (1531   )                       Convert string to all-uppercase
        AnsiUpperCase (1532   )                      Convert string to all-uppercase
        AppendStr (1533   )                          Append 2 strings
        AssignStr (1534   )                          Assign value of strings on heap
        CompareStr (1539   )                         Compare two strings case sensitive
        CompareText (1540   )                        Compare two strings case insensitive
        DisposeStr (1552   )                         Remove string from heap
        IsValidIdent (1604   )                       Is string a valid pascal identifier
        LastDelimiter (1605   )                      Last occurance of character in a string
        LeftStr (1605   )                            Get first N characters of a string
        LoadStr (1606   )                            Load string from resources
        LowerCase (1606   )                          Convert string to all-lowercase
        NewStr (1607   )                             Allocate new string on heap
        RightStr (1610   )                           Get last N characters of a string
        StrAlloc (1614   )                           Allocate memory for string
        StrBufSize (1614   )                         Reserve memory for a string
        StrDispose (1617   )                         Remove string from heap
        StrPas (1625   )                             Convert PChar to pascal string
        StrPCopy (1626   )                           Copy pascal string
        StrPLCopy (1626   )                          Copy N bytes of pascal string
        UpperCase (1648   )                          Convert string to all-uppercase



76.13            Constants,  types  and  variables



76.13.1          Constants

ConfigExtension  :  string  =  '.cfg'


ConfigExtension is the default extension used by the GetAppConfigFile (1592   ) 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



                                                                1497

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



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 (1573   ) call to find all matching files.


faArchive  =  $00000020


Attribute of a file, meaning the file has the archive bit set.  Used in TSearchRec (1511   ) and
FindFirst (1573   )


faDirectory  =  $00000010


Attribute of a file, meaning the file is a directory.  Used in TSearchRec (1511   ) and FindFirst
(1573   )


faHidden  =  $00000002


Attribute of a file, meaning the file is read-only.  Used in TSearchRec (1511   ) and FindFirst
(1573   )


faReadOnly  =  $00000001


Attribute of a file, meaning the file is read-only.  Used in TSearchRec (1511   ) and FindFirst
(1573   )


faSymLink  =  $00000040


faSymLink  means  the  file  (as  returned  e.g.   by  FindFirst  (1573   )/FindNext  (1575   )),  is  a
symlink.  It's ignored under Windows.


faSysFile  =  $00000004


Attribute of a file, meaning the file is a system file.  Used in TSearchRec (1511   ) and FindFirst
(1573   )


faVolumeId  =  $00000008


Attribute of a file, meaning the entry contains the volume ID. Used in TSearchRec (1511   )
and FindFirst (1573   )


feInvalidHandle  :  THandle  =  (-1)



                                                                1498

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



feInvalidHandle is the return value of FileOpen (1568   ) in case of an error.


fmOpenRead  =  $0000


fmOpenRead is used in the FileOpen (1568   ) call to open a file in read-only mode.


fmOpenReadWrite  =  $0002


fmOpenReadWrite is used in the FileOpen (1568   ) call to open a file in read-write mode.


fmOpenWrite  =  $0001


fmOpenWrite is used in the FileOpen (1568   ) call to open a file in write-only mode.


fmShareCompat  =  $0000


fmOpenShareCompat is used in the FileOpen (1568   ) call OR-ed together with one of fmOpen-
ReadWrite (1499   ), fmOpenRead (1499   ) or fmOpenWrite (1499   ),to open a file in a sharing
modus that is equivalent to sharing implemented in MS-DOS.


fmShareDenyNone  =  $0040


fmShareDenyNone is used in the FileOpen (1568   ) call OR-ed together with one of fmOpen-
ReadWrite  (1499   ),  fmOpenRead  (1499   )  or  fmOpenWrite  (1499   ),  to  open  a  file  so  other
processes can read/write the file as well.


fmShareDenyRead  =  $0030


fmOpenShareRead is used in the FileOpen (1568   ) call OR-ed together with one of fmOpen-
ReadWrite  (1499   ),  fmOpenRead  (1499   )  or  fmOpenWrite  (1499   ),  to  open  a  file  so  other
processes cannot read from it.

This constant only works on Windows, because other operating systems do not support this
constants.


fmShareDenyWrite  =  $0020


fmOpenShareWrite is used in the FileOpen (1568   ) call OR-ed together with one of fmOpen-
ReadWrite  (1499   ),  fmOpenRead  (1499   )  or  fmOpenWrite  (1499   ),  to  open  a  file  so  other
processes cannot write to it, they can only read.


fmShareExclusive  =  $0010


fmOpenShareExclusive  is  used  in  the  FileOpen  (1568   )  call  OR-ed  together  with  one  of
fmOpenReadWrite (1499   ),  fmOpenRead (1499   ) or fmOpenWrite (1499   ),  to open a file ex-
clusively.


fsFromBeginning  =  0


fsFromBeginning is used to indicate in the FileSeek (1570   ) call that a seek operation should
be started at the start of the file.



                                                                1499

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



fsFromCurrent  =  1


fsFromBeginning is used to indicate in the FileSeek (1570   ) 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 (1570   ) call that a seek operation should
be started at the last position in the file.


GUID_NULL  :  TGuid  =  '{00000000-0000-0000-0000-000000000000}'


NULL GUID constant


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  =  (-2415018.5)


Starting point of the Julian calendar


LeadBytes  :  Set  of  Char  =  []


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.



                                                                1500

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



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,  30,  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.


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



                                                                1501

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



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


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



                                                                1502

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



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  (1573   )  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.


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 (1592   ) call on some systems.


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



                                                                1503

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



Weak (original or not) packaged unit


ufWeakUnit  =  $04


Unit is a weak packaged unit


UnixDateDelta  =  (UnixEpoch)


Number of days between 1.1.1900 and 1.1.1970


UnixEpoch  =  JulianEpoch  +  (2440587.5)


Starting point of the unix calendar (1/1/1970)



76.13.2          Types

EHeapException  =  EHeapMemoryError


EHeapMemoryError is raised when an error occurs in the heap management routines.


ExceptClass  =  Class  of  Exception


ExceptClass is a Exception (1659   ) class reference.


Int128Rec  =  packed  record
case  Integer  of
0:  (
    Hi  :  QWord;
    Lo  :  QWord;
);
1:  (
    DWords  :  Array[0..3]  of  DWord;
);
2:  (
    Words  :  Array[0..7]  of  Word;
);
3:  (
    Bytes  :  Array[0..15]  of  Byte;
);
end



Int128Rec is a record defining a 128-bit integer.  It is made up of 2 QWords or 4 DWords
or 8 words or 16 bytes.


Int64Rec  =  packed  record
case  Integer  of
0:  (
    Hi  :  Cardinal;
    Lo  :  Cardinal;
);
1:  (



                                                                1504

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



   Words  :  Array[0..3]  of  Word;
);
2:  (
   Bytes  :  Array[0..7]  of  Byte;
);
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
case  Integer  of
0:  (
   Hi  :  Word;
   Lo  :  Word;
);
1:  (
   Bytes  :  Array[0..3]  of  Byte;
);
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.


OWordRec  =  packed  record
case  Integer  of
0:  (
   Hi  :  QWord;
   Lo  :  QWord;
);
1:  (
   DWords  :  Array[0..3]  of  DWord;
);
2:  (
   Words  :  Array[0..7]  of  Word;
);
3:  (
   Bytes  :  Array[0..15]  of  Byte;
);
end



OWordRec is a record defining a 128-bit integer.  It is made up of 2 QWords or 4 DWords or
8 words or 16 bytes.


PByteArray  =  ^TByteArray


Generic pointer to TByteArray (1506   ).  Use to access memory regions as a byte array.



                                                                1505

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



PDayTable  =  ^TDayTable


Pointer to TDayTable type.


PString  =  ^string


Pointer to a ansistring


PSysCharSet  =  ^TSysCharSet


Pointer to TSysCharSet (1511   ) type.


PWordarray  =  ^TWordArray


Generic pointer to TWordArray (1513   ).  Use to access memory regions as a word array.


TBeepHandler  =  procedure


TBeepHandler is the prototype used by the OnBeep (1516   ) handler.  This in turn is called
by  the  Beep  (1535   )  call  to  actually  implement  the  beep  functionality.   The  call  takes  no
arguments.


TByteArray  =  Array[0..32767]  of  Byte


TByteArray is a generic array definition, mostly for use as a base type of the PByteArray
(1505   ) type.


TBytes  =  Array  of  Byte


TBytes  defines  a  dynamic  array  of  bytes.   This  can  be  used  to  typecast  e.g.   strings  to
manipulate them byte for byte.


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.


TEventType  =  (etCustom,etInfo,etWarning,etError,etDebug)



                         Table 76.10:  Enumeration values for type TEventType


                __Value_____________Explanation_______________________________________________________________
                  etCustom          Custom log event, with application-specific meaning
                  etDebug           Debug message.
                  etError           Error condition message
                  etInfo            General information event message
                  etWarning         Warning message



                                                                1506

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



TEventType is a type to be used by logging mechanisms (in particular, the TCustomApplication
and TEventLog classes.  It can be used to filter events, and write only certain types of event
to the event log.


TEventTypes  =  Set  of  TEventType


TEventTypes is a set type of  TEventType, defined for convenience.  It is used in the custom
application classes for logging purposes.


TExecuteFlags=  Set  of  (ExecInheritsHandles)



                                  Table 76.11:  Enumeration values for type



__Value___________________________Explanation______________________________________________________________________________________*
 *____
  ExecInheritsHandles             The new process inherits all (file) handles owned by the current process



TExecuteFlags is a set of flags to influence the behaviour of the ExecuteProcess (1557   ) call.


TFilename  =  String


TFileName is used in the TSearchRec (1511   ) definition.


TFileRec  =  FileRec


Alias for FileRec (1489   ) for Delphi compatibility.


TFileSearchOption  =  (sfoImplicitCurrentDir,sfoStripQuotes)



                     Table 76.12:  Enumeration values for type TFileSearchOption



__Value_____________________________Explanation___________________________________________________________________________________
  sfoImplicitCurrentDir             Always search the current directory first, even if it is not specified.
  sfoStripQuotes                    Strip quotes from the components in the search path.



TFileSearchOption  enumerates  the  options  that  can  be  used  in  the  FileSearch  call  to
control the behaviour of the search mechanism


TFileSearchOptions  =  Set  of  TFileSearchOption


TFileSearchOptions  is  a  set  of  TFileSearchOption  (1507   )  values,  used  in  the  FileSearch
(1569   ) call when searching for files.


TFloatFormat  =  (ffGeneral,ffExponent,ffFixed,ffNumber,ffCurrency)



                                                                1507

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                        Table 76.13:  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
(1579   ) 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 (1576   ) function.


TFloatValue  =  (fvExtended,fvCurrency,fvSingle,fvReal,fvDouble,fvComp)



                         Table 76.14:  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 (1638   ) function.


TFormatDateTimeOption  =  (fdoInterval)



                Table 76.15:  Enumeration values for type TFormatDateTimeOption


        __Value______________Explanation______________________________________________________________________________
          fdoInterval        Format the time as an interval, 24+hours are presented as such



TFormatDateTimeOption enumerates possible options to the FormatDateTime (1589   ) rou-
tine.



                                                                1508

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



TFormatDateTimeOptions  =  Set  of  TFormatDateTimeOption


TFormatDateTimeOptions is a set of TFormatDateTimeOptions (1509   ), and is used in the
last argument of FormatDateTime (1589   )


TFormatSettings  =  record
   CurrencyFormat  :  Byte;
   NegCurrFormat  :  Byte;
   ThousandSeparator  :  Char;
   DecimalSeparator  :  Char;
   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  (1516   )  to  return  an  alternative
application name.


TGetTempDirEvent  =  function(Global:  Boolean)  :  string


Function prototype for OnGetTempDir (1516   ) handler.


TGetTempFileEvent  =  function(const  Dir:  string;const  Prefix:  string)
                                                 :  string


Function prototype for OnGetTempFile (1516   ) handler.


TGetVendorNameEvent  =  function  :  string


TGetVendorNameEvent is the function prototype for the OnGetVendorName (1516   ) callback,
used by the VendorName (1648   ) function.


THandle  =  System.THandle



                                                                1509

               _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'__________________*
 *__________________



               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.


               TMbcsByteType  =  (mbSingleByte,mbLeadByte,mbTrailByte)



                                     Table 76.16:  Enumeration values for type TMbcsByteType


                                                     __Value_________________Explanation________________
                                                       mbLeadByte             Uses lead-byte
                                                       mbSingleByte           Single bytes
                                                       mbTrailByte            Uses trailing byte



               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.


               TRawbyteSearchRec  =  record
                  Time  :  LongInt;
                  Size  :  Int64;
                  Attr  :  LongInt;
                  Name  :  RawByteString;
                  ExcludeAttr  :  LongInt;
                  FindHandle  :  THandle;
                  Mode  :  TMode;
               end



               TRawbyteSearchRec  is  a  search  handle  description  record  using  single-byte  strings.   It  is
               initialized by a call to FindFirst (1573   ) and can be used to do subsequent calls to FindNext
               (1575   ).  It  contains  the  result  of  these  function  calls.  It  must  be  used  to  close  the  search
               sequence with a call to FindClose (1573   ).

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)

Remark:        Note that for files with unicode filenames this is a converted value from the unicode filename.
               Depending on the codepage, this may or may not be a correct rendering of the correct unicode
               filename.


               TReplaceFlags=  Set  of  (rfReplaceAll,rfIgnoreCase)



                                                                               1510

               _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'__________________*
 *__________________



                                                 Table 76.17:  Enumeration values for type


                __Value________________Explanation_________________________________________________________________________________*
 *__________
                  rfIgnoreCase         Search case insensitive.
                  rfReplaceAll         Replace all occurrences of the search string with the replacement string.



               TReplaceFlags determines the behaviour of the StringReplace (1619   ) function.


               TSearchRec  =  TRawbyteSearchRec


               TSearchRec  is  a  search  handle  description  record.   It  is  initialized  by  a  call  to  FindFirst
               (1573   ) and can be used to do subsequent calls to FindNext (1575   ).  It contains the result of
               these function calls.  It must be used to close the search sequence with a call to FindClose
               (1573   ).

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)



                                        Table 76.18:  Enumeration values for type TSignalState


                         __Value________________Explanation_________________________________________________________________________
                           ssHooked              A signal handler is set by the RTL code for the signal.
                           ssNotHooked           No signal handler is set for the signal.
                           ssOverridden          A signal handler was set for the signal by third-party code.



               TSignalState indicates the state of a signal handler in a unix system for a particular signal.


               TSysCharSet  =  Set  of  AnsiChar


               Generic set of characters type.


               TSysLocale  =  record
                  DefaultLCID  :  Integer;
                  PriLangID  :  Integer;
                  SubLangID  :  Integer;
               case  Byte  of
               1:  (
                  FarEast  :  Boolean;
                  MiddleEast  :  Boolean;
               );
               2:  (
                  MBCS  :  Boolean;
                  RightToLeft  :  Boolean;
               );
               end



                                                                               1511

               _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'__________________*
 *__________________



               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.


               TSystemTime  =  record
                  Year  :  Word;
                  Month  :  Word;
                  Day  :  Word;
                  DayOfWeek  :  Word;
                  Hour  :  Word;
                  Minute  :  Word;
                  Second  :  Word;
                  MilliSecond  :  Word;
               end



               The System time structure contains the date/time in a human-understandable format.


               TTerminateProc  =  function  :  Boolean


               TTerminateProc is the procedural type which should be used when adding exit procedures.


               TTextRec  =  TextRec


               Alias for TextRec (1489   ) for Delphi compatibility.


               TTimeStamp  =  record
                  Time  :  LongInt;
                  Date  :  LongInt;
               end



               TTimeStamp contains a timestamp, with the date and time parts specified as separate TDateTime
               values.


               TUnicodeSearchRec  =  record
                  Time  :  LongInt;
                  Size  :  Int64;
                  Attr  :  LongInt;
                  Name  :  UnicodeString;
                  ExcludeAttr  :  LongInt;
                  FindHandle  :  THandle;
                  Mode  :  TMode;
               end



               TRawbyteSearchRec  is  a  search  handle  description  record  using  multi-byte  strings.   It  is
               initialized by a call to FindFirst (1573   ) and can be used to do subsequent calls to FindNext
               (1575   ).  It  contains  the  result  of  these  function  calls.  It  must  be  used  to  close  the  search
               sequence with a call to FindClose (1573   ).

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)



                                                                               1512

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



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
(1506   ) type.


WordRec  =  packed  record
   Hi  :  Byte;
   Lo  :  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.



76.13.3          Variables

CurrencyDecimals  :  Bytedeprecated


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.

This constant is deprecated.  You should use DefaultFormatSettings.CurrencyFormat (1514   )
instead.


CurrencyFormat  :  Bytedeprecated


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.

This constant is deprecated.  You should use DefaultFormatSettings.CurrencyFormat (1514   )
instead.


CurrencyString  :  stringdeprecated


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.

This constant is deprecated.  You should use DefaultFormatSettings.CurrencyString (1514   )
instead.


DateSeparator  :  Chardeprecated


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.

This  constant  is  deprecated.  You  should  use  DefaultFormatSettings.DateSeparator  (1514   )
instead.



                                                                1513

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



DecimalSeparator  :  Chardeprecated


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.

This constant is deprecated.  You should use DefaultFormatSettings.DecimalSeparator (1514   )
instead.


DefaultFormatSettings  :  TFormatSettings  =  (CurrencyFormat:  1;  NegCurrFormat:  5;  ThousandSeparator:  ',';  DecimalSeparator:*
 *  '.';  CurrencyDecimals:  2;  DateSeparator:  '-';  TimeSeparator:  ':';  ListSeparator:  ',';  CurrencyString:  '$';  ShortDate*
 *Format:  'd/m/y';  LongDateFormat:  'dd"  "mmmm"  "yyyy';  TimeAMString:  'AM';  Time@


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
(1627   ).


FormatSettings  :  TFormatSettings


FormatSettings is provided for Delphi compatibility, and refers to the DefaultFormatSet-
tings (1514   ) variable.


ListSeparator  :  Chardeprecated


ListSeparator is the character used in lists of values.  It is locale dependent.


LongDateFormat  :  stringdeprecated


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.

This constant is deprecated.  You should use DefaultFormatSettings.LongDateFormat (1514   )
instead.


LongDayNames  :  TWeekNameArraydeprecated


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.

The array is indexed by values as returned by the DayOfWeek function.

This constant is deprecated.  You should use DefaultFormatSettings.LongDayNames (1514   )
instead.


LongMonthNames  :  TMonthNameArraydeprecated



                                                                1514

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



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.

This constant is deprecated.  You should use DefaultFormatSettings.LongMonthNames (1514   )
instead.


LongTimeFormat  :  stringdeprecated


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.

This constant is deprecated.  You should use DefaultFormatSettings.LongTimeFormat (1514   )
instead.


NegCurrFormat  :  Bytedeprecated


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:


0  Left parenthesis, currency symbol, amount, right parenthesis.  Ex:  ($1.2)

1  Negative sign, currency symbol, amount.  Ex:  -$1.2

2  Monetary symbol, negative sign, amount.  Ex:  $-1.2

3  Monetary symbol, amount, negative sign.  Ex:  $1.2-

4  Left parenthesis, amount, currency symbol, right parenthesis.  Ex:  (1.2$)

5  Negative sign, amount, currency symbol.  Ex:  -1.2$

5  6Amount, negative sign, currency symbol.  Ex:  1.2-$

5  7Amount, currency symbol, negative sign.  Ex:  1.2$-

5  8Negative sign, amount, space, currency symbol (as #5, adding a space before the currency
       symbol).  Ex:  -1.2 $

9  Negative sign, currency symbol, space, amount (as #1, adding a space after the currency
       symbol).  Ex:  -$ 1.2

10   Amount, space, currency symbol, negative sign (as #7, adding a space before the currency
       symbol).  Ex:  1.2 $-

11   Monetary symbol, space, amount, negative sign (as #3, adding a space after the currency
       symbol).  Ex:  $ 1.2-

12   Monetary symbol, space, negative sign, amount (as #2, adding a space after the currency
       symbol).  Ex:  $ -1.2

13   Amount, negative sign, space, currency symbol (as #6, adding a space before the currency
       symbol).  Ex:  1.2- $

14   Left  parenthesis,  currency  symbol,  space,  amount,  right  parenthesis  (as  #0,  adding  a
       space after the currency symbol).  Ex:  ($ 1.2)



                                                                1515

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



15   Left parenthesis, amount, space, currency symbol, right parenthesis (as ##4, adding a
       space before the currency symbol).  Ex:  (1.2 $)


OnBeep  :  TBeepHandler  =  Nil


OnBeep  is  calles  whenever  Beep  is  called.   Beep  contains  no  implementation  to  actually
produce a beep, since there is no way to implement beep in a meaningful way for all possible
implementations.


OnCreateGUID  :  TCreateGUIDFunc  =  Nil


OnCreateGUID can be set to point to a custom routine that creates GUID values.  If set, the
CreateGUID (1542   ) 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 (1592   ) and GetAppConfigFile
(1592   )  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 (1597   ) function.
Note that the returned name should have a trailing directory delimiter character.


OnGetTempFile  :  TGetTempFileEvent


OnGetTempDir can be used to provide custom behaviour for the GetTempFileName (1597   )
function.  Note that the values for Prefix and Dir should be observed.


OnGetVendorName  :  TGetVendorNameEvent


OnGetVendorName  must  be  set  in  order  for  VendorName  (1648   )  to  return  a  value.  It  will
then  be  used  in  GetAppConfigDir  (1592   )  and  GetAppConfigFile  (1592   )  to  determine  the
configuration  directory.   Set  it  to  a  callback  that  returns  the  actual  vendor  name  for  the
application.


OnShowException  :  procedure(Msg:  ShortString)


OnShowException is the callback that ShowException (1612   ) 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  :  stringdeprecated



                                                                1516

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



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.

This constant is deprecated.  You should use DefaultFormatSettings.ShortDateFormat (1514   )
instead.


ShortDayNames  :  TWeekNameArraydeprecated


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.

The array is indexed by values as returned by the DayOfWeek function.

This constant is deprecated.  You should use DefaultFormatSettings.ShortDayNames (1514   )
instead.


ShortMonthNames  :  TMonthNameArraydeprecated


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.

This constant is deprecated.  You should use DefaultFormatSettings.ShortMonthNames (1514   )
instead.


ShortTimeFormat  :  stringdeprecated


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.

This constant is deprecated.  You should use DefaultFormatSettings.ShortTimeFormat (1514   )
instead.


SysLocale  :  TSysLocale


SysLocale is initialized by the initialization code of the SysUtils unit.  For an explanation of
the fields, see TSysLocale (1512   )


ThousandSeparator  :  Chardeprecated


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.

This  constant  is  deprecated.   You  should  use  DefaultFormatSettings.ThousandSeparator
(1514   ) instead.


TimeAMString  :  stringdeprecated


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.

This constant is deprecated.  You should use DefaultFormatSettings.TimeAMString (1514   )
instead.



                                                                1517

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                TimePMString  :  stringdeprecated


                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.

                This constant is deprecated.  You should use DefaultFormatSettings.TimePMString (1514   )
                instead.


                TimeSeparator  :  Chardeprecated


                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
                (1627   ).


                TwoDigitYearCenturyWindow  :  Word


                Window to determine what century 2 digit years are in.



                76.14            Procedures  and  functions



                76.14.1          AbandonSignalHandler

    Synopsis:    Abandon the signal handler

Declaration:     procedure  AbandonSignalHandler(RtlSigNum:  Integer)

    Visibility:   default

Description:     AbandonSignalHandler tells the system routines that they should not re-install the signal
                handler for signal RtlSigNum under any circumstances.  Normally, signal handlers are re-set
                when they are called.  If AbandonSignalHandler has been called for a signal that is handled
                by the system code, the signal will not be re-set again.



                76.14.2          Abort

    Synopsis:    Abort program execution.

Declaration:     procedure  Abort

    Visibility:   default

Description:     Abort raises an EAbort (1652   ) exception.

    See also:    EAbort (1652   )



                                                                                1518

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.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 (1551   ) and DiskSize (1551   ) 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 (1551   ), DiskSize (1551   )



                76.14.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 (1512   ), CallTerminateProcs (1536   )



                76.14.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 occurrences of  #13 and #10 characters with the correct
                line-ending characters for the current platform.  This is #13#10 on Windows and Dos.  On
                Unix-like platforms, this is #10 and for Mac OS X it is #13.

       Errors:   None.



                                                                                1519

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    AnsiCompareStr (1520   ), AnsiCompareText (1521   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.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 (1520   ) or AnsiCompareText (1521   ) depending on whether FileNameCaseSensitive
                is True or False

       Errors:   None.

    See also:    AnsiCompareStr (1520   ), AnsiCompareText (1521   ), AnsiLowerCaseFileName (1524   )



                76.14.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.



                                                                                1520

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                The  comparision  takes  into  account  Ansi  characters,  i.e.  it  takes  care  of  strange  accented
                characters.  Contrary to AnsiCompareText (1521   ), 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 (1519   ), AnsiCompareText (1521   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.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.



                                                                                1521

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                the  comparision  takes  into  account  Ansi  characters,  i.e.  it  takes  care  of  strange  accented
                characters.  Contrary to AnsiCompareStr (1520   ), 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 (1519   ), AnsiCompareText (1521   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.9          AnsiDequotedStr

    Synopsis:

Declaration:     function  AnsiDequotedStr(const  S:  string;AQuote:  Char)  :  string

    Visibility:   default

Description:



                76.14.10           AnsiExtractQuotedStr

    Synopsis:    Removes the first quoted string from a string.

Declaration:     function  AnsiExtractQuotedStr(var  Src:  PChar;Quote:  Char)  :  string



                                                                                1522

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    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 (1525   ).

       Errors:   None.

    See also:    AnsiQuotedStr (1525   )


                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;
                    P   :  PChar    ;


                Begin
                  S :=  'He    s a i d " H e l l o"  and    w a l k e d on  ' ;
                  P :=  P c h a r(S ) ;
                  S :=  A n s i Q u o t e d S t(rP, '" ' ) ;
                  W r i t e l n ( S ) ;
                  P :=  P c h a r(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(tPr, '" ' ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                76.14.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 (1527   )


                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



                                                                                1523

                _______________________________________________________CHAPTER_76.___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___.____________________________________________________________________________________________________________*
 *___________



                76.14.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  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 (1532   ), AnsiStrLower (1530   ), AnsiStrUpper (1531   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.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 (1524   ), AnsiCompareFileName (1520   ), AnsiUpperCaseFileName (1532   )



                                                                                1524

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.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 (1530   ), AnsiStrScan (1531   ), AnsiStrRScan (1531   )



                76.14.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 (1522   ).

                For an example, see AnsiExtractQuotedStr (1522   )

       Errors:   None.

    See also:    AnsiExtractQuotedStr (1522   )



                76.14.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 (1520   ) 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 (1520   ), SameText (1611   ), AnsiSameText (1525   )



                76.14.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 (1521   ) with S1 and S2 as parameters and returns True if
                the result of that call is zero, or False otherwise.

    See also:    AnsiCompareText (1521   ), SameText (1611   ), AnsiSameStr (1525   )



                                                                                1525

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.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 (1521   ), AnsiCompareStr (1520   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.19           AnsiStrIComp

    Synopsis:    Compare two null-terminated strings.  Case insensitive.



                                                                                1526

                _______________________________________________________CHAPTER_76.___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 (1521   ), AnsiCompareStr (1520   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.20           AnsiStrLastChar

    Synopsis:    Return a pointer to the last character of a string.

Declaration:     function  AnsiStrLastChar(Str:  PChar)  :  PChar

    Visibility:   default



                                                                                1527

                _______________________________________________________CHAPTER_76.___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 (1521   ), AnsiCompareStr (1520   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.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 (1526   ),  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 (1526   ), AnsiStrIComp (1526   ), AnsiStrLIComp (1529   )



                                                                                1528

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.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 (1521   ), AnsiCompareStr (1520   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1529

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.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 (1524   ).
                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 (1531   ), AnsiLowerCase (1524   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.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 (1525   ), AnsiStrScan (1531   ), AnsiStrRScan (1531   )



                                                                                1530

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.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 (1525   ), AnsiStrScan (1531   ), AnsiStrPos (1530   )



                76.14.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 (1525   ), AnsiStrScan (1531   ), AnsiStrPos (1530   )



                76.14.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 (1532   ).
                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 (1532   ), AnsiStrLower (1530   ), AnsiLowerCase (1524   )


                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) ;



                                                                                1531

                _______________________________________________________CHAPTER_76.___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___.____________________________________________________________________________________________________________*
 *___________



                76.14.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 (1531   ), AnsiStrLower (1530   ), AnsiLowerCase (1524   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.29           AnsiUpperCaseFileName

    Synopsis:    Convert filename to uppercase.

Declaration:     function  AnsiUpperCaseFileName(const  s:  string)  :  string

    Visibility:   default



                                                                                1532

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Description:     AnsiUpperCaseFileName simply returns the result of


                AnsiUpperCase(S);


    See also:    AnsiUpperCase (1532   ), AnsiCompareFileName (1520   ), AnsiLowerCaseFileName (1524   )



                76.14.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 (1534   ), NewStr (1607   ), DisposeStr (1552   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.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 filename part minus extension of  ParamStr(0), but it can be customized by setting the
                OnGetApplicationName (1516   ) callback.

                Note that the returned value is only the name portion.  It does not contain any path or file
                extension.

       Errors:   None.

    See also:    GetAppConfigDir (1592   ), OnGetApplicationName (1516   ), GetAppConfigFile (1592   ), Con-
                figExtension (1497   )



                                                                                1533

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.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 (1607   ), AppendStr (1533   ), DisposeStr (1552   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.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 (1633   ), IntToStr (1602   )


                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



                                                                                1534

                _______________________________________________________CHAPTER_76.___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( 2 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                76.14.34           Beep

    Synopsis:    Sound the system bell.

Declaration:     procedure  Beep

    Visibility:   default

Description:     Beep sounds the system bell, if one is available.  The actual beep is produced by the OnBeep
                (1516   ) callback.  The Sysutils unit itself contains no implementation of this call.



                76.14.35           BoolToStr

    Synopsis:    Convert a boolean value to a string.

Declaration:     function  BoolToStr(B:  Boolean;UseBoolStrs:  Boolean)  :  string
                function  BoolToStr(B:  Boolean;const  TrueS:  string;const  FalseS:  string)
                                                :  string

    Visibility:   default

Description:     BoolToStr converts the boolean B to one of the strings 'TRUE' or 'FALSE'

       Errors:   None.

    See also:    StrToBool (1627   )



                76.14.36           BytesOf

    Synopsis:    Return the bytes in a string

Declaration:     function  BytesOf(const  Val:  RawByteString)  :  TBytes
                function  BytesOf(const  Val:  AnsiChar)  :  TBytes

    Visibility:   default

Description:     BytesOf returns a copy of the string's content as an array of bytes.  For an empty string,
                zero bytes are returned (i.e.  length(BytesOf(S))=0).

    See also:    TBytes (1506   )



                76.14.37           ByteToCharIndex

    Synopsis:    Convert a character index in Bytes to an Index in characters

Declaration:     function  ByteToCharIndex(const  S:  string;Index:  Integer)  :  Integer

    Visibility:   default



                                                                                1535

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1537   ), ByteToCharLen (1536   )



                76.14.38           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

       Errors:   This function does not take into account MBCS yet.

    See also:    CharToByteLen (1537   ), ByteToCharIndex (1535   )



                76.14.39           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 (1510   ), StrByteType (1615   )



                76.14.40           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 (1519   ), 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 (1512   ), AddTerminateProc (1519   )



                                                                                1536

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.41           ChangeFileExt

    Synopsis:    Change the extension of a filename.

Declaration:     function  ChangeFileExt(const  FileName:  UnicodeString;
                                                     const  Extension:  UnicodeString)  :  UnicodeString
                function  ChangeFileExt(const  FileName:  RawByteString;
                                                     const  Extension:  RawByteString)  :  RawByteString

    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:    ExtractFileExt (1561   ), ExtractFileName (1561   ), ExtractFilePath (1561   ), ExpandFileName
                (1558   )



                76.14.42           CharInSet

    Synopsis:    Check whether a char is in a set of characters

Declaration:     function  CharInSet(Ch:  AnsiChar;const  CSet:  TSysCharSet)  :  Boolean
                function  CharInSet(Ch:  WideChar;const  CSet:  TSysCharSet)  :  Boolean

    Visibility:   default

Description:     CharInSet  returns  True  if  Ch  matches  one  of  the  characters  in  CSet,  it  returns  False
                otherwise.  It is equivalent to


                Ch  in  CSet


                Later versions of this function may take WideChar into account.



                76.14.43           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 (1536   ), ByteToCharIndex (1535   )



                                                                                1537

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.44           CodePageNameToCodePage

    Synopsis:    Return a numeric identifier for the codepage.

Declaration:     function  CodePageNameToCodePage(const  cpname:  AnsiString)
                                                                     :  TSystemCodePage

    Visibility:   default

Description:     CodePageNameToCodePage returns the code page number for the specified codepage cpname.

       Errors:   If the code page is not found in the list of code pages, $FFFF is returned.

    See also:    CodePageToCodePageName (1538   )



                76.14.45           CodePageToCodePageName

    Synopsis:    Convert a numeric codepage identifier to a codepage name

Declaration:     function  CodePageToCodePageName(cp:  TSystemCodePage)  :  AnsiString

    Visibility:   default

Description:     CodePageToCodePageName returns the name of the codepage cp.

       Errors:   If no matching codepage is found in the list of codepages, an empty string is returned.

    See also:    CodePageNameToCodePage (1538   )



                76.14.46           CompareMem

    Synopsis:    Compare two memory areas.

Declaration:     function  CompareMem(P1:  Pointer;P2:  Pointer;Length:  PtrUInt)  :  Boolean

    Visibility:   default

Description:     CompareMem compares, byte by byte, 2 memory areas pointed to by P1 and P2, for a length
                of  L bytes.

                The function returns True if all L bytes are the same, and False otherwise.



                76.14.47           CompareMemRange

    Synopsis:    Compare 2 memory locations

Declaration:     function  CompareMemRange(P1:  Pointer;P2:  Pointer;Length:  PtrUInt)
                                                         :  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 (1611   )



                                                                                1538

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.48           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 (1521   ), AnsiCompareStr (1520   ), CompareText (1540   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1539

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.49           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 (1521   ), AnsiCompareStr (1520   ), CompareStr (1539   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.50           ComposeDateTime

    Synopsis:    Add a date and time

Declaration:     function  ComposeDateTime(Date:  TDateTime;Time:  TDateTime)  :  TDateTime



                                                                                1540

                _______________________________________________________CHAPTER_76.___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:    #rtl.dateutils.EncodeDateTime (551  )



                76.14.51           ConcatPaths

    Synopsis:    Concatenate an array of paths to form a single path

Declaration:     function  ConcatPaths(const  Paths:  Array  of  UnicodeString)
                                                   :  UnicodeString
                function  ConcatPaths(const  Paths:  Array  of  RawByteString)
                                                   :  RawByteString

    Visibility:   default

Description:     ConcatPaths will concatenate the different path components in Paths to a single path.  It
                will insert directory separators between the various components of the path as needed.  No
                directory separators will be added to the beginning or the end of the path, and none will be
                taken away.

    See also:    IncludeTrailingPathDelimiter  (1600   ),  IncludeLeadingPathDelimiter  (1599   ),  ExcludeTrail-
                ingPathDelimiter (1556   ), IncludeTrailingPathDelimiter (1600   )


                Listing:  ./sysutex/ex96.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x 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 C o n c a t p a t h sf 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 i l l w r i t e / t h i s/ p a t h/more   /  l e v e l s/
                    W r i t e l n(C o n c a t P a t h(s[ '/ t h i s/ ' , 'p a t h' , 'more   / l e v e l s/ '] ) ) ;
                    //    w i l l w r i t e  t h i s/p a t h/ more   / l e v e l s/
                    W r i t e l n(C o n c a t P a t h(s[ ' t h i s/' , 'p a t h ', 'more   /  l e v e l s/'] ) ) ;
                    //    w i l l w r i t e  t h i s/p a t h/ more   / l e v e l s
                    W r i t e l n(C o n c a t P a t h(s[ ' t h i s/' , 'p a t h ', 'more   /  l e v e l s'] ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                76.14.52           CreateDir

    Synopsis:    Create a new directory

Declaration:     function  CreateDir(const  NewDir:  RawByteString)  :  Boolean
                function  CreateDir(const  NewDir:  UnicodeString)  :  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.



                                                                                1541

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   In case of an error, the function returns False.

    See also:    RemoveDir (1609   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.53           CreateGUID

    Synopsis:    Create a new GUID

Declaration:     function  CreateGUID(out  GUID:  TGuid)  :  Integer

    Visibility:   default

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:    GUIDCase (1598   ), IsEqualGUID (1603   ), StringToGUID (1620   ), TryStringToGUID (1644   ),
                GUIDToString (1598   )



                76.14.54           CurrentYear

    Synopsis:    Return the current year

Declaration:     function  CurrentYear  :  Word

    Visibility:   default

Description:     CurrentYear returns the current year as a 4-digit number.



                                                                                1542

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    Date (1543   ), Time (1639   ), Now (1607   )



                76.14.55           CurrToStr

    Synopsis:    Convert a currency value to a string.

Declaration:     function  CurrToStr(Value:  Currency)  :  string
                function  CurrToStr(Value:  Currency;
                                              const  FormatSettings:  TFormatSettings)  :  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 (1577   ):


                FloatToStrF(Value,ffNumber,15,2);


       Errors:   None.

    See also:    FloatToStrF (1577   ), StrToCurr (1628   )



                76.14.56           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

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
                (1577   ).

    See also:    FloatToStrF (1577   )



                76.14.57           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 (1639   ), Now (1607   )


                Listing:  ./sysutex/ex1.pp



                                                                                1543

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.58           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 (1563   ) function.

       Errors:   None.

    See also:    Time  (1639   ),  Date  (1543   ),  FileDateToDateTime  (1565   ),  DateTimeToSystemTime  (1546   ),
                DateTimeToTimeStamp (1547   )


                Listing:  ./sysutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.59           DateTimeToStr

    Synopsis:    Converts a TDateTime value to a string using a predefined format.

Declaration:     function  DateTimeToStr(DateTime:  TDateTime;ForceTimeIfZero:  Boolean)
                                                      :  string
                function  DateTimeToStr(DateTime:  TDateTime;
                                                     const  FormatSettings:  TFormatSettings;
                                                     ForceTimeIfZero:  Boolean)  :  string

    Visibility:   default



                                                                                1544

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1495   )).

                Note that if the time part is 0 (i.e.  midnight), no time is appended.

       Errors:   None.

    See also:    FormatDateTime (1589   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.60           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;
                                                           Options:  TFormatDateTimeOptions)
                procedure  DateTimeToString(out  Result:  string;const  FormatStr:  string;
                                                           const  DateTime:  TDateTime;
                                                           const  FormatSettings:  TFormatSettings;
                                                           Options:  TFormatDateTimeOptions)

    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
                (1495   ).

                Note that for 'c', if the time part is 0 (i.e.  midnight), no time is appended.

       Errors:   In case a wrong formatting character is found, an EConvertError is raised.

    See also:    FormatDateTime (1589   ), formatchars (1495   )


                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) ;



                                                                                1545

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.61           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 (1544   ), SystemTimeToDateTime (1637   ), DateTimeToTimeStamp (1547   )


                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}


                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;



                                                                                1546

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________



                76.14.62           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 (1544   ), SystemTimeToDateTime (1637   ), DateTimeToSystemTime (1546   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.63           DateToStr

    Synopsis:    Converts a TDateTime value to a date string with a predefined format.

Declaration:     function  DateToStr(Date:  TDateTime)  :  string
                function  DateToStr(Date:  TDateTime;
                                              const  FormatSettings:  TFormatSettings)  :  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).

       Errors:   None.

    See also:    TimeToStr (1641   ), DateTimeToStr (1544   ), FormatDateTime (1589   ), StrToDate (1629   )


                Listing:  ./sysutex/ex7.pp



                                                                                1547

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.64           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 (1543   ), DateToStr (1547   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.65           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.

    See also:    EncodeDate (1553   ), DecodeTime (1549   )


                Listing:  ./sysutex/ex9.pp



                                                                                1548

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.66           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 (1548   ), 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 (1553   ), TryEncodeDate (1643   ), DecodeDate (1548   )



                76.14.67           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 (1554   ), DecodeDate (1548   )


                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


                Var    HH  ,MM  , SS  ,MS  :  Word   ;


                Begin



                                                                                1549

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                76.14.68           DeleteFile

    Synopsis:    Delete a file from the filesystem.

Declaration:     function  DeleteFile(const  FileName:  UnicodeString)  :  Boolean
                function  DeleteFile(const  FileName:  RawByteString)  :  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 (1564   ), FileExists (1565   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.69           DirectoryExists

    Synopsis:    Check whether a directory exists in the file system.

Declaration:     function  DirectoryExists(const  Directory:  UnicodeString)  :  Boolean
                function  DirectoryExists(const  Directory:  RawByteString)  :  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 (1565   )



                                                                                1550

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.70           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
                (1551   ) functions must be mimicked using filenames that reside on the partitions.  For more
                information, see AddDisk (1519   ).

       Errors:   On error, -1 is returned.

    See also:    DiskSize (1551   ), AddDisk (1519   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.71           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.



                                                                                1551

                _______________________________________________________CHAPTER_76.___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  (1551   )  and
                DiskSize  functions  must  be  mimicked  using  filenames  that  reside  on  the  partitions.   For
                more information, see AddDisk (1519   )

                For an example, see DiskFree (1551   ).

       Errors:   On error, -1 is returned.

    See also:    DiskFree (1551   ), AddDisk (1519   )



                76.14.72           DisposeStr

    Synopsis:    Dispose an ansistring from the heap.

Declaration:     procedure  DisposeStr(S:  PString);    Overload
                procedure  DisposeStr(S:  PShortString);    Overload

    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 (1552   ).

       Errors:   None.

    See also:    NewStr (1607   ), AppendStr (1533   ), AssignStr (1534   )



                76.14.73           DoDirSeparators

    Synopsis:    Convert known directory separators to the current directory separator.

Declaration:     procedure  DoDirSeparators(var  FileName:  UnicodeString)
                procedure  DoDirSeparators(var  FileName:  RawByteString)

    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
                AllowDirectorySeparators (1241   ) constant.

       Errors:   None.

    See also:    ExtractFileName (1561   ), ExtractFilePath (1561   )


                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



                                                                                1552

                _______________________________________________________CHAPTER_76.___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 ( ' 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.74           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 (1548   ) 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 (1653   ) exception
                is raised.

    See also:    EncodeTime (1554   ), DecodeDate (1548   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1553

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.75           EncodeTime

    Synopsis:    Encode a Hour,Min,Sec,millisec to a TDateTime value.

Declaration:     function  EncodeTime(Hour:  Word;Minute:  Word;Second:  Word;
                                                MilliSecond:  Word)  :  TDateTime

    Visibility:   default

Description:     EncodeTime  encodes  the  Hour,  Minute,  Second,  MilliSecond  variables  to  a  TDateTime
                format result.  It does the opposite of the DecodeTime (1549   ) 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 (1653   ) exception
                is raised.

    See also:    EncodeDate (1553   ), DecodeTime (1549   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.76           ExceptAddr

    Synopsis:    Current exception address.

Declaration:     function  ExceptAddr  :  CodePointer

    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 (1555   ), ExceptionErrorMessage (1555   ), ShowException (1612   )



                76.14.77           ExceptFrameCount

    Synopsis:    Number of frames included in an exception backtrace

Declaration:     function  ExceptFrameCount  :  LongInt

    Visibility:   default



                                                                                1554

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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  (1555   ),  ExceptAddr  (1554   ),  ExceptObject  (1555   ),  #rtl.system.ExceptProc
                (1243   )



                76.14.78           ExceptFrames

    Synopsis:

Declaration:     function  ExceptFrames  :  PCodePointer

    Visibility:   default

Description:

    See also:    ExceptFrameCount (1554   ), ExceptAddr (1554   ), ExceptObject (1555   ), #rtl.system.ExceptProc
                (1243   )



                76.14.79           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 (1659   ) object or not, and adapts
                the output accordingly.

    See also:    ExceptObject (1555   ), ExceptAddr (1554   ), ShowException (1612   )



                76.14.80           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 (1554   ), ExceptionErrorMessage (1555   ), ShowException (1612   )



                                                                                1555

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.81           ExcludeLeadingPathDelimiter

    Synopsis:    Strip the leading path delimiter of a path

Declaration:     function  ExcludeLeadingPathDelimiter(const  Path:  UnicodeString)
                                                                             :  UnicodeString
                function  ExcludeLeadingPathDelimiter(const  Path:  RawByteString)
                                                                             :  RawByteString

    Visibility:   default

Description:     ExcludeLeadingPathDelimiter will remove any path delimiter on the first position of Path
                if there is one.  if there is none (or the path is empty), it is left untouched.

    See also:    IncludeTrailingPathDelimiter  (1600   ),  IncludeLeadingPathDelimiter  (1599   ),  ExcludeTrail-
                ingPathDelimiter (1556   ), ConcatPaths (1541   )


                Listing:  ./sysutex/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 I n c l u d e L e a d i n g P a t h D e l i m i tfeurn c t *
 *i o n }


                Uses      s y s u t i l;s


                Begin
                    //   W i l l  p r i n t " / t h i s/ p a t h"
                    W r i t e l n(I n c l u d e L e a d i n g P a t h D e l i m i(t'etrh i s/p a t h ') ) ;
                    //   The    same     r e s u l t
                    W r i t e l n(I n c l u d e L e a d i n g P a t h D e l i m i(t'e/rt h i s/p a t h' ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                76.14.82           ExcludeTrailingBackslash

    Synopsis:    Strip trailing directory separator from a pathname, if needed.

Declaration:     function  ExcludeTrailingBackslash(const  Path:  UnicodeString)
                                                                        :  UnicodeString
                function  ExcludeTrailingBackslash(const  Path:  RawByteString)
                                                                        :  RawByteString

    Visibility:   default

Description:     ExcludeTrailingBackslash is provided for backwards compatibility with Delphi.  Use Ex-
                cludeTrailingPathDelimiter (1556   ) instead.

    See also:    IncludeTrailingPathDelimiter (1600   ), ExcludeTrailingPathDelimiter (1556   ), PathDelim (1501   ),
                IsPathDelimiter (1604   )



                76.14.83           ExcludeTrailingPathDelimiter

    Synopsis:    Strip trailing directory separator from a pathname, if needed.

Declaration:     function  ExcludeTrailingPathDelimiter(const  Path:  UnicodeString)
                                                                               :  UnicodeString
                function  ExcludeTrailingPathDelimiter(const  Path:  RawByteString)
                                                                               :  RawByteString



                                                                                1556

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    Visibility:  default

Description:     ExcludeTrailingPathDelimiter removes the trailing path delimiter character (PathDelim
                (1501   )) from Path if it is present, and returns the result.

    See also:    ExcludeTrailingBackslash (1556   ), IncludeTrailingPathDelimiter (1600   ), PathDelim (1501   ),
                IsPathDelimiter (1604   )



                76.14.84           ExecuteProcess

    Synopsis:    Execute another process (program).

Declaration:     function  ExecuteProcess(const  Path:  AnsiString;
                                                      const  ComLine:  AnsiString;Flags:  TExecuteFlags)
                                                        :  Integer
                function  ExecuteProcess(const  Path:  AnsiString;
                                                      const  ComLine:  Array  of  AnsiString;
                                                      Flags:  TExecuteFlags)  :  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.

                The program specified in Path is not searched in the searchpath specified in the PATH en-
                vironment variable, so the full path to the executable must be specified in Path, although
                some operating systems may perform this search anyway (notably, windows)

                Flags can be used to control the passing of file handles:  if ExecInheritsHandles is included,
                the file handles of the current process will be passed on to the newly executed process.

       Errors:   In case the program could not be executed or an other error occurs, an EOSError (1657   )
                exception will be raised.

    See also:    TExecuteFlags (1507   ), EOSError (1657   )



                76.14.85           ExeSearch

    Synopsis:    Search for an executable

Declaration:     function  ExeSearch(const  Name:  UnicodeString;
                                              const  DirList:  UnicodeString)  :  UnicodeString
                function  ExeSearch(const  Name:  RawByteString;
                                              const  DirList:  RawByteString)  :  RawByteString

    Visibility:   default

Description:     ExeSearch  searches  for  an  executable  Name  in  the  list  of  directories  DirList  (a  list  of
                directories, separator by PathSeparator (1255   ).  If the current OS also searches implicitly in
                the current working directory, the current directory is searched in the first place.

                If the executable is found, then the full path of the executable is returned.  If it is not found,
                an empty string is returned.

                No check is performed whether the found file is actually executable.

    See also:    FileSearch (1569   )



                                                                                1557

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.86           ExpandFileName

    Synopsis:    Expand a relative filename to an absolute filename.

Declaration:     function  ExpandFileName(const  FileName:  UnicodeString)  :  UnicodeString
                function  ExpandFileName(const  FileName:  RawByteString)  :  RawByteString

    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.

                If an empty filename is passed, it is expanded to the current directory.

       Errors:   None.

    See also:    ExpandFileNameCase  (1558   ),  ExtractFileName  (1561   ),  ExtractFilePath  (1561   ),  Extract-
                FileDir (1560   ), ExtractFileDrive (1560   ), ExtractFileExt (1561   ), ExtractRelativePath (1562   )


                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


                 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.87           ExpandFileNameCase

    Synopsis:    Expand a filename entered as case insensitive to the full path as stored on the disk.

Declaration:     function  ExpandFileNameCase(const  FileName:  UnicodeString;
                                                             out  MatchFound:  TFilenameCaseMatch)
                                                              :  UnicodeString
                function  ExpandFileNameCase(const  FileName:  RawByteString;
                                                             out  MatchFound:  TFilenameCaseMatch)
                                                              :  RawByteString

    Visibility:   default

Description:     On case insensitive platforms, ExpandFileNameCase behaves similarly to ExpandFileName
                (1558   )  except  for  the  fact  that  it  returns  the  final  part  of  the  path  with  the  same  case  of
                letters  as  found  on  the  disk  (if  it  exists  -  otherwise  the  case  equals  the  one  provided  on
                input).  On case sensitive platforms it also checks whether one or more full paths exist on



                                                                                1558

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                disk which would correspond to the provided input if treated case insensitively and returns
                the first such match found and information whether the match is unique or not.

                Note  that  the  behaviour  is  basically  undefined  if  the  input  includes  wildcards  characters.
                Normally,  wildcards  in  the  last  part  of  path  provided  on  input  are  resolved  to  the  first
                corresponding item found on the disk, but it is better not to rely on that and use other more
                suitable functions if working with wildcards like FindFirst (1573   )/FindNext (1575   ).

       Errors:   None.

    See also:    ExpandFileName (1558   ), ExtractFileName (1561   ), ExtractFilePath (1561   ), ExtractFileDir
                (1560   ), ExtractFileDrive (1560   ), ExtractFileExt (1561   ), ExtractRelativePath (1562   )


                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


                 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.88           ExpandUNCFileName

    Synopsis:    Expand a relative filename to an absolute UNC filename.

Declaration:     function  ExpandUNCFileName(const  FileName:  UnicodeString)
                                                             :  UnicodeString
                function  ExpandUNCFileName(const  FileName:  RawByteString)
                                                             :  RawByteString

    Visibility:   default

Description:     ExpandUNCFileName runs ExpandFileName (1558   ) on FileName and then attempts to re-
                place the drive letter by the name of a shared disk.

       Errors:   None.

    See also:    ExpandFileName (1558   ), ExtractFileName (1561   ), ExtractFilePath (1561   ), ExtractFileDir
                (1560   ), ExtractFileDrive (1560   ), ExtractFileExt (1561   ), ExtractRelativePath (1562   )



                                                                                1559

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.89           ExtractFileDir

    Synopsis:    Extract the drive and directory part of a filename.

Declaration:     function  ExtractFileDir(const  FileName:  UnicodeString)  :  UnicodeString
                function  ExtractFileDir(const  FileName:  RawByteString)  :  RawByteString

    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 (1561   ).

       Errors:   None.

    See also:    ExtractFileName (1561   ), ExtractFilePath (1561   ), ExtractFileDir (1560   ), ExtractFileDrive
                (1560   ), ExtractFileExt (1561   ), ExtractRelativePath (1562   )


                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 ) ;
                  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___.____________________________________________________________________________________________________________*
 *___________



                76.14.90           ExtractFileDrive

    Synopsis:    Extract the drive part from a filename.

Declaration:     function  ExtractFileDrive(const  FileName:  UnicodeString)  :  UnicodeString
                function  ExtractFileDrive(const  FileName:  RawByteString)  :  RawByteString

    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 (1560   ).

    See also:    ExtractFileName (1561   ), ExtractFilePath (1561   ), ExtractFileDir (1560   ), ExtractFileDrive
                (1560   ), ExtractFileExt (1561   ), ExtractRelativePath (1562   )



                                                                                1560

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.91           ExtractFileExt

    Synopsis:    Return the extension from a filename.

Declaration:     function  ExtractFileExt(const  FileName:  UnicodeString)  :  UnicodeString
                function  ExtractFileExt(const  FileName:  RawByteString)  :  RawByteString

    Visibility:   default

Description:     ExtractFileExt returns the extension (including the .(dot) character) of  FileName.

                For an example, see ExtractFileDir (1560   ).

       Errors:   None.

    See also:    ChangeFileExt  (1537   ),  ExtractFileName  (1561   ),  ExtractFilePath  (1561   ),  ExtractFileDir
                (1560   ), ExtractFileDrive (1560   ), ExtractFileExt (1561   ), ExtractRelativePath (1562   )



                76.14.92           ExtractFileName

    Synopsis:    Extract the filename part from a full path filename.

Declaration:     function  ExtractFileName(const  FileName:  UnicodeString)  :  UnicodeString
                function  ExtractFileName(const  FileName:  RawByteString)  :  RawByteString

    Visibility:   default

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
                (1561   ) and ExtractFileName.

                For an example, see ExtractFileDir (1560   ).

       Errors:   None.

    See also:    ExtractFileName (1561   ), ExtractFilePath (1561   ), ExtractFileDir (1560   ), ExtractFileDrive
                (1560   ), ExtractFileExt (1561   ), ExtractRelativePath (1562   )



                76.14.93           ExtractFilePath

    Synopsis:    Extract the path from a filename.

Declaration:     function  ExtractFilePath(const  FileName:  UnicodeString)  :  UnicodeString
                function  ExtractFilePath(const  FileName:  RawByteString)  :  RawByteString

    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 (1561   ).

                For an example, see ExtractFileDir (1560   ).

       Errors:   None.

    See also:    ExtractFileName (1561   ), ExtractFilePath (1561   ), ExtractFileDir (1560   ), ExtractFileDrive
                (1560   ), ExtractFileExt (1561   ), ExtractRelativePath (1562   )



                                                                                1561

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.94           ExtractRelativepath

    Synopsis:    Extract a relative path from a filename, given a base directory.

Declaration:     function  ExtractRelativepath(const  BaseName:  UnicodeString;
                                                              const  DestNAme:  UnicodeString)
                                                                :  UnicodeString
                function  ExtractRelativepath(const  BaseName:  RawByteString;
                                                              const  DestNAme:  RawByteString)
                                                                :  RawByteString

    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 (1561   ), ExtractFilePath (1561   ), ExtractFileDir (1560   ), ExtractFileDrive
                (1560   ), ExtractFileExt (1561   )


                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


                 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.95           ExtractShortPathName

    Synopsis:    Returns a 8.3 path name

Declaration:     function  ExtractShortPathName(const  FileName:  UnicodeString)
                                                                  :  UnicodeString
                function  ExtractShortPathName(const  FileName:  RawByteString)
                                                                  :  RawByteString

    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 (1561   ), ExtractFileName (1561   )



                                                                                1562

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.96           FileAge

    Synopsis:    Return the timestamp of a file.

Declaration:     function  FileAge(const  FileName:  UnicodeString)  :  LongInt
                function  FileAge(const  FileName:  UnicodeString;
                                           out  FileDateTime:  TDateTime;FollowLink:  Boolean)
                                            :  Boolean
                function  FileAge(const  FileName:  RawByteString;
                                           out  FileDateTime:  TDateTime;FollowLink:  Boolean)
                                            :  Boolean
                function  FileAge(const  FileName:  RawByteString)  :  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 (1565   ) function.

                Fileage cannot be used on directories, it will return -1 if  FileName indicates a directory.

       Errors:   In case of errors, -1 is returned.

    See also:    FileDateToDateTime (1565   ), FileExists (1565   ), FileGetAttr (1566   )


                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 ) ;
                        W r i t e l n(  'I ' 'm   f r o m  ', DateTimeToStr          (S ) )
                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________



                76.14.97           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 (1564   )

       Errors:   None.

    See also:    FileCreate (1564   ), FileWrite (1572   ), FileOpen (1568   ), FileRead (1569   ), FileTruncate (1572   ),
                FileSeek (1570   )



                                                                                1563

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.98           FileCreate

    Synopsis:    Create a new file and return a handle to it.

Declaration:     function  FileCreate(const  FileName:  UnicodeString)  :  THandle
                function  FileCreate(const  FileName:  UnicodeString;Rights:  Integer)
                                                 :  THandle
                function  FileCreate(const  FileName:  UnicodeString;ShareMode:  Integer;
                                                Rights:  Integer)  :  THandle
                function  FileCreate(const  FileName:  RawByteString)  :  THandle
                function  FileCreate(const  FileName:  RawByteString;Rights:  Integer)
                                                 :  THandle
                function  FileCreate(const  FileName:  RawByteString;ShareMode:  Integer;
                                                Rights:  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  (1569   )  and  FileWrite
                (1572   ) functions.

                If a file with name FileName already existed on the disk, it is overwritten.

                The  optional  Mode  parameter  only  has  an  effect  under  unix,  where  it  can  be  used  to  set
                the mode (read, write, execute, sticky bit, setgid and setuid flags) of the created file to the
                specified custom value.  On other platfors, the Mode parameter is ignored.

       Errors:   If an error occurs (e.g.  disk full or non-existent path), the function returns THandle(-1).

    See also:    FileClose (1563   ), FileWrite (1572   ), FileOpen (1568   ), FileRead (1569   ), FileTruncate (1572   ),
                FileSeek (1570   )


                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        ) ;
                    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



                                                                                1564

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                        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___.____________________________________________________________________________________________________________*
 *___________



                76.14.99           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 (1563   ) or FindFirst
                (1573   )/FindNext (1575   ) functions to TDateTime form.

       Errors:   None.

    See also:    DateTimeToFileDate (1544   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.100            FileExists

    Synopsis:    Check whether a particular file exists in the filesystem.

Declaration:     function  FileExists(const  FileName:  UnicodeString)  :  Boolean
                function  FileExists(const  FileName:  RawByteString)  :  Boolean

    Visibility:   default

Description:     FileExists returns True if a file with name FileName exists on the disk, False otherwise.
                On windows, this function will return False if a directory is passed as FileName.  On unices,
                passing a directory name will result in True.  The rationale is that on unix, a directory is a
                file as well.



                                                                                1565

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                Note  that  this  function  accepts  a  single  filename  as  an  argument,  without  wildcards.   To
                check for the existence of multiple files, see the FindFirst (1573   ) function.

       Errors:   None.

    See also:    FindFirst (1573   ), FileAge (1563   ), FileGetAttr (1566   ), FileSetAttr (1571   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.101            FileGetAttr

    Synopsis:    Return attributes of a file.

Declaration:     function  FileGetAttr(const  FileName:  UnicodeString)  :  LongInt
                function  FileGetAttr(const  FileName:  RawByteString)  :  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.  Only for DOS/Windows on a plain FAT (not VFAT or Fat32)
                       filesystem.

                faDirectory       File is a directory.

                faArchive      file should be archived.  Not possible on Unix


       Errors:   In case of error, -1 is returned.

    See also:    FileSetAttr (1571   ), FileAge (1563   ), FileGetDate (1567   )


                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


                 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;



                                                                                1566

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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 u 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.102            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 (1563   ),  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 (1563   )


                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


                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' ) ;



                                                                                1567

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                76.14.103            FileIsReadOnly

    Synopsis:    Check whether a file is read-only.

Declaration:     function  FileIsReadOnly(const  FileName:  UnicodeString)  :  Boolean
                function  FileIsReadOnly(const  FileName:  RawByteString)  :  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 (1565   )



                76.14.104            FileOpen

    Synopsis:    Open an existing file and return a filehandle

Declaration:     function  FileOpen(const  FileName:  UnicodeString;Mode:  Integer)  :  THandle
                function  FileOpen(const  FileName:  RawByteString;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           Open file in read-only mode

                fmOpenWrite           Open file in write-only mode

                fmOpenReadWrite               Open file in read/write mode.


                Under  Windows  and  Unix,  the  above  mode  can  be  or-ed  with  one  of  the  following  shar-
                ing/locking flags:


                fmShareCompat             Open file in DOS share-compatibility mode

                fmShareExclusive            Lock file for exclusive use

                fmShareDenyWrite              Lock file so other processes can only read.

                fmShareDenyRead               Lock file so other processes cannot read.

                fmShareDenyNone               Do not lock file.


                If the file has been successfully opened, it can be read from or written to (depending on the
                Mode parameter) with the FileRead (1569   ) 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 (1564   ) function.

                There are some limitations to the sharing modes.


                     1.Sharing modes are only available on Unix and Windows platforms.

                     2.Unix only support sharing modes as of 2.4.0.



                                                                                1568

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                     3.fmShareDenyRead only works under Windows at this time, and will always result in an
                       error on Unix platforms because its file locking APIs do not support this concept.

                     4.File locking is advisory on Unix platforms.  This means that the locks are only checked
                       when a file is opened using a file locking mode.  In other cases, existing locks are simply
                       ignored.   In  particular,  this  means  that  fmShareDenyNone  has  no  effect  under  Unix,
                       because  this  can  only  be  implemented  as  "use  no  locking"  on  those  platforms.  As  a
                       result,  opening  a  file  using  this  mode  will  always  succeed  under  Unix  as  far  as  the
                       locking is concerned, even if the file has already been opened using fmShareExclusive.

                     5.Under Solaris, closing a single file handle associated with a file will result in all locks on
                       that file (even via other handles) being destroyed due to the behaviour of the underlying
                       API (fcntl).  Because of the same reason, on Solaris you cannot use fmShareDenyWrite
                       in combination with fmOpenWrite, nor fmShareExclusive in combination with fmOpenRead
                       although both work with fmOpenReadWrite.


                For an example, see FileCreate (1564   )

       Errors:   On Error, THandle(-1) is returned.

    See also:    fmOpenRead (1499   ),  fmOpenWrite (1499   ),  fmOpenReadWrite (1499   ),  fmShareDenyWrite
                (1499   ), fmShareExclusive (1499   ), fmShareDenyRead (1499   ), fmShareDenyNone (1499   ), fmShare-
                Compat  (1499   ),  FileClose  (1563   ),  FileWrite  (1572   ),  FileCreate  (1564   ),  FileRead  (1569   ),
                FileTruncate (1572   ), FileSeek (1570   )



                76.14.105            FileRead

    Synopsis:    Read data from a filehandle in a buffer.

Declaration:     function  FileRead(Handle:  THandle;out  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 (1568   ) call.

                The function returns the number of bytes actually read, or -1 on error.

                For an example, see FileCreate (1564   )

       Errors:   On error, -1 is returned.

    See also:    FileClose (1563   ), FileWrite (1572   ), FileCreate (1564   ), FileOpen (1568   ), FileTruncate (1572   ),
                FileSeek (1570   )



                76.14.106            FileSearch

    Synopsis:    Search for a file in a path.

Declaration:     function  FileSearch(const  Name:  UnicodeString;
                                                const  DirList:  UnicodeString;
                                                Options:  TFileSearchOptions)  :  UnicodeString
                function  FileSearch(const  Name:  UnicodeString;
                                                const  DirList:  UnicodeString;
                                                ImplicitCurrentDir:  Boolean)  :  UnicodeString
                function  FileSearch(const  Name:  RawByteString;
                                                const  DirList:  RawByteString;



                                                                                1569

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                                               Options:  TFileSearchOptions)  :  RawByteString
                function  FileSearch(const  Name:  RawByteString;
                                               const  DirList:  RawByteString;
                                               ImplicitCurrentDir:  Boolean)  :  RawByteString

    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.  The optional
                Options parameter may be specified to influence the behaviour of the search algorithm.  It
                is a set of the following options:


                sfoImplicitCurrentDir             Always search the current directory first, even if it is not specified.

                sfoStripQuotes         Strip quotes from the components in the search path.


                A deprecated form of the function allowed to specify using the boolean ImplicitCurrentDir
                parameter  whether  the  current  directory  was  searched  implicitly  or  not.   By  default,  the
                current directory is searched.

       Errors:   On error, an empty string is returned.

    See also:    ExpandFileName (1558   ), FindFirst (1573   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.107            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:



                                                                                1570

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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  (1563   ),  FileWrite  (1572   ),  FileCreate  (1564   ),  FileOpen  (1568   ),  FileRead  (1569   ),
                FileTruncate (1572   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.108            FileSetAttr

    Synopsis:    Set the attributes of a file.

Declaration:     function  FileSetAttr(const  Filename:  UnicodeString;Attr:  LongInt)
                                                   :  LongInt
                function  FileSetAttr(const  Filename:  RawByteString;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 (1566   ), FileGetDate (1567   ), FileSetDate (1571   )



                76.14.109            FileSetDate

    Synopsis:    Set the date of a file.



                                                                                1571

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Declaration:     function  FileSetDate(const  FileName:  UnicodeString;Age:  LongInt)
                                                  :  LongInt
                function  FileSetDate(const  FileName:  RawByteString;Age:  LongInt)
                                                  :  LongInt
                function  FileSetDate(Handle:  THandle;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.



                76.14.110            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 (1564   ).

       Errors:   On error, the function returns False.

    See also:    FileClose  (1563   ),  FileWrite  (1572   ),  FileCreate  (1564   ),  FileOpen  (1568   ),  FileRead  (1569   ),
                FileSeek (1570   )



                76.14.111            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 (1564   ).

       Errors:   In case of error, -1 is returned.

    See also:    FileClose (1563   ), FileCreate (1564   ), FileOpen (1568   ), FileRead (1569   ), FileTruncate (1572   ),
                FileSeek (1570   )



                                                                                1572

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.112            FindClose

    Synopsis:    Close a find handle

Declaration:     procedure  FindClose(var  F:  TUnicodeSearchRec)
                procedure  FindClose(var  F:  TRawbyteSearchRec)

    Visibility:   default

Description:     FindClose ends a series of FindFirst (1573   )/FindNext (1575   ) 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 (1573   ).

       Errors:   None.

    See also:    FindFirst (1573   ), FindNext (1575   )



                76.14.113            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  (1503   ))  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 (1503   )



                76.14.114            FindFirst

    Synopsis:    Start a file search and return a findhandle

Declaration:     function  FindFirst(const  Path:  UnicodeString;Attr:  LongInt;
                                              out  Rslt:  TUnicodeSearchRec)  :  LongInt
                function  FindFirst(const  Path:  RawByteString;Attr:  LongInt;
                                              out  Rslt:  TRawbyteSearchRec)  :  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:



                                                                                1573

               _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'__________________*
 *__________________



               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        Drive volume Label.  Not possible under unix,  and on Windows-like systems,
                     this works only for plan FAT (not Fat32 of VFAT) filesystems.

               faDirectory       File is a directory.

               faArchive      file needs to be archived.  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 (1573   ) 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 (1573   ), FindNext (1575   )


               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___._____________________________________________________________________________________________________________*
 *__________



                                                                               1574

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.115            FindNext

    Synopsis:    Find the next entry in a findhandle.

Declaration:     function  FindNext(var  Rslt:  TUnicodeSearchRec)  :  LongInt
                function  FindNext(var  Rslt:  TRawbyteSearchRec)  :  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 (1573   )

       Errors:   On error (no more file is found), a nonzero constant is returned.

    See also:    FindFirst (1573   ), FindClose (1573   )



                76.14.116            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 (1500   ) and MaxCur-
                rency (1500   )).  If not, an EConvertError (1653   ) exception is raised.

       Errors:   If  Value is out of range, an EConvertError (1653   ) exception is raised.

    See also:    EConvertError (1653   ), TryFloatToCurr (1644   ), MinCurrency (1500   ), MaxCurrency (1500   )



                76.14.117            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 (1500   ) and Max-
                DateTime (1500   )).  If not, an EConvertError (1653   ) exception is raised.

       Errors:   If  Value is out of range, an EConvertError (1653   ) exception is raised.

    See also:    EConvertError (1653   ), MinDateTime (1500   ), MaxDateTime (1500   )



                                                                                1575

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.118            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)

    Visibility:   default

Description:     FloatToDecimal  converts  the  float  Value  to  a  float  description  in  the  ResultTFloatRec
                (1508   ) format.  It will store Precision digits in the Digits field, of which at most Decimal
                decimals.

       Errors:   None.

    See also:    TFloatRec (1508   )



                76.14.119            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  (1577   ).   FloatToStr  is
                completely equivalent to the following call:


                FloatToStrF(Value,  ffGeneral,15,  0);


       Errors:   None.

    See also:    FloatToStrF (1577   ), FormatFloat (1590   ), StrToFloat (1631   )



                                                                                1576

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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) ;


                 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.120            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



                                                                                1577

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    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:


                ffcurrency     Money format.  Value is converted to a string using the global variables CurrencyString,
                      CurrencyFormat and NegCurrFormat.  The Digits paramater specifies the number 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 re-
                      sulting string.


       Errors:   None.

    See also:    FloatToStr (1576   ), FloatToText (1579   )


                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] ,*
 * ' )  :   ') ;



                                                                                1578

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                               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  ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                76.14.121            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 (1577   ).  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 (1576   ), FloatToStrF (1577   )


                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



                                                                                1579

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                       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 ) ) ;
                               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___.____________________________________________________________________________________________________________*
 *___________



                76.14.122            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 (1590   )

       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 (1590   )



                76.14.123            FmtStr

    Synopsis:    Format a string with given arguments.



                                                                                1580

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1581   ) with Fmt and Args as arguments, and stores the result in Res.
                For more information on how the resulting string is composed, see Format (1581   ).

       Errors:   In case of error, a EConvertError exception is raised.

    See also:    Format (1581   ), FormatBuf (1588   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.124            ForceDirectories

    Synopsis:    Create a chain of directories

Declaration:     function  ForceDirectories(const  Dir:  RawByteString)  :  Boolean
                function  ForceDirectories(const  Dir:  UnicodeString)  :  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.



                76.14.125            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:



                                                                                1581

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



'%'  [[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 are 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.

'-'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 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 usage of 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  (1577   ),  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
      (1577   )).  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)



                                                                1582

            _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            M  Currency  format.  the  next  argument  in  the  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 (1577   )

                  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.

            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 (1588   )


            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;


            {   E x p e c t e d o u t p u t:
                          [%  d ]  = >  [ 1 0 ]
                          [%%]  = >  [%]
                       [%10   d ]  = >  [               1 0 ]
                       [ % . 4d ]  = >  [ 0 0 1 0 ]
                    [ % 1 0 . 4d]  = >  [            0 0 1 0 ]
                       [ % 0 :d ]  = >  [ 1 0 ]



                                                                            1583

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



        [ % 0 : 1 0d]  = >  [               1 0 ]
    [ % 0 : 1 0 . 4d]  = >  [            0 0 1 0 ]
      [%0: -10    d ]  = >  [ 1 0               ]
  [%0: -10.4      d ]  = >  [ 0 0 1 0           ]
       [% -*.*    d ]  = >  [ 0 0 0 1 0 ]
}
 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' ) ;
    r e a d l n;
end   ;


{   E x p e c t e d o u t p u t:
              [%  x ]  = >  [ A ]
           [%10   x ]  = >  [                A  ]
        [ % 1 0 . 4x]  = >  [            000 A  ]
           [ % 0 :x ]  = >  [ A ]
        [ % 0 : 1 0x]  = >  [                A  ]
    [ % 0 : 1 0 . 4x]  = >  [            000 A  ]
      [%0: -10    x ]  = >  [ A                 ]
  [%0: -10.4      x ]  = >  [ 0 0 0A            ]
       [% -*.*    x ]  = >  [ 0 0 0 0A ]
}
 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  ;



                                                                1584

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



    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   ;


{   E x p e c t e d o u t p u t:
           [ 0x % p ]  = >  [ 0 x0012D687       ]
        [ 0x%10   p ]  = >  [ 0 x    0012   D687   ]
    [ 0x %10.4    p ]  = >  [ 0 x    0012   D687   ]
        [ 0x %0:  p ]  = >  [ 0 x0012D687       ]
    [ 0x %0:10    p ]  = >  [ 0 x    0012   D687   ]
 [ 0x % 0 : 1 0 . 4p]  = >  [ 0 x    0012   D687   ]
  [ 0 x%0:-10     p ]  = >  [ 0 x0012D687          ]
 [ 0x %0: -10.4     p]  = >  [ 0  x0012D687          ]
       [% -*.*    p ]  = >  [ 0 0 1 2D687   ]
}
 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   ;


{   E x p e c t e d o u t p u t:
              [%  s ]= >  [ T h i s  i s  a   s t r i n g]
           [ % 0 :s ]= >  [ T h i s  i s  a   s t r i n g]
        [ % 0 : 1 8s] = >  [    T h i s  i s  a   s t r i n g]
      [%0: -18    s ]= >  [ T h i s  i s  a   s t r i n g   ]
  [ % 0 : 1 8 . 1 2s] = >  [           T h i s  i s  a  s t ]
       [% -*.*    s ]= >  [ T h i s  i s  a   s t           ]
}
 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) ;
       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



                                                                1585

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



           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   ;


{   E x p e c t e d o u t p u t:
              [%  e ]  = >  [ 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
           [%10   e ]  = >  [ 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
        [ % 1 0 . 4e]  = >  [ 1 . 2 3 4E +000]
           [ % 0 :e ]  = >  [ 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
        [ % 0 : 1 0e]  = >  [ 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
    [ % 0 : 1 0 . 4e]  = >  [ 1 . 2 3 4E +000]
      [%0: -10    e ]  = >  [ 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
  [%0: -10.4      e ]  = >  [ 1 . 2 3 4E +000]
       [% -*.*    e ]  = >  [ 1 . 2 3 4 0E+000]
}
 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   ;


{   E x p e c t e d o u t p u t:
              [%  e ]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
           [%10   e ]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
        [ % 1 0 . 4e]  = >  [ - 1 . 2 3 4E+000]
           [ % 0 :e ]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
        [ % 0 : 1 0e]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
    [ % 0 : 1 0 . 4e]  = >  [ - 1 . 2 3 4E+000]
      [%0: -10    e ]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0+0000]
  [%0: -10.4      e ]  = >  [ - 1 . 2 3 4E+000]
       [% -*.*    e ]  = >  [ - 1 . 2 3 4 0E+000]
}
 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 ) ;



                                                                1586

_______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



       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   ;


{   E x p e c t e d o u t p u t:
              [%  e ]  = >  [ 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0-0002]
           [%10   e ]  = >  [ 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0-0002]
        [ % 1 0 . 4e]  = >  [ 1 . 2 3 4E -002]
           [ % 0 :e ]  = >  [ 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0-0002]
        [ % 0 : 1 0e]  = >  [ 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0-0002]
    [ % 0 : 1 0 . 4e]  = >  [ 1 . 2 3 4E -002]
      [%0: -10    e ]  = >  [ 1 . 2 3 0 0 0 0 0 0 0 0 0 0 0 0E0-0002]
  [%0: -10.4      e ]  = >  [ 1 . 2 3 4E -002]
       [% -*.*    e ]  = >  [ 1 . 2 3 4 0E-002]
}
 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   ;


{   E x p e c t e d o u t p u t:
              [%  e ]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0-0002]
           [%10   e ]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0-0002]
        [ % 1 0 . 4e]  = >  [ - 1 . 2 3 4E-002]
           [ % 0 :e ]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0-0002]
        [ % 0 : 1 0e]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0-0002]
    [ % 0 : 1 0 . 4e]  = >  [ - 1 . 2 3 4E-002]
      [%0: -10    e ]  = >  [ - 1 . 2 3 4 0 0 0 0 0 0 0 0 0 0 0E0-0002]
  [%0: -10.4      e ]  = >  [ - 1 . 2 3 4E-002]



                                                                1587

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                       [% -*.*    e ]  = >  [ - 1 . 2 3 4 0E-002]
                }
                 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 s t r i n g;
                    T e s t E x p o n e n t i a;l
                    T e s t N e g a t i v e E x p o n e n t i;a l
                    T e s t S m a l l E x p o n e n t i;a l
                    T e s t S m a l l N e g E x p o n e n t i;a l
                end___.____________________________________________________________________________________________________________*
 *___________



                76.14.126            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 (1581   ) and stores the result in Buf.

    See also:    Format (1581   )


                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}



                                                                                1588

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.127            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  the  Format
                parameter, and returns the resulting string.

                For  an  explanation  of  the  formatting  characters  usable  in  the  Format  parameter,  see  For-
                matFloat (1590   ).

    See also:    FormatFloat (1590   ), FloatToText (1579   )



                76.14.128            FormatDateTime

    Synopsis:    Return a string representation of a TDateTime value with a given format.

Declaration:     function  FormatDateTime(const  FormatStr:  string;DateTime:  TDateTime;
                                                      Options:  TFormatDateTimeOptions)  :  string
                function  FormatDateTime(const  FormatStr:  string;DateTime:  TDateTime;
                                                      const  FormatSettings:  TFormatSettings;
                                                      Options:  TFormatDateTimeOptions)  :  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 (1495   ).

       Errors:   On error (such as an invalid character in the formatting string), and EConvertError excep-
                tion is raised.

    See also:    DateTimeToStr (1544   ), DateToStr (1547   ), TimeToStr (1641   ), StrToDateTime (1630   )


                Listing:  ./sysutex/ex14.pp



                                                                                1589

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.129            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 (1577   ) 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.

                .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 (1576   )



                                                                                1590

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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
                           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___.____________________________________________________________________________________________________________*
 *___________



                76.14.130            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



                                                                                1591

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                be Nil anyway.

       Errors:   Exceptions that occur during the destruction of  Obj are not caught.



                76.14.131            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.
                Also note that the returned name always contains an ending path delimiter.

                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 (1533   ) call,
                but can be configured by means of the OnGetApplicationName (1516   ) callback.

                If VendorName (1648   ) is not-empty, then VendorName will also be inserted before the application-
                specific directory.

       Errors:   None.

    See also:    GetAppConfigFile  (1592   ),  ApplicationName  (1533   ),  OnGetApplicationName  (1516   ),  Cre-
                ateDir (1541   ), SysConfigDir (1503   ), VendorName (1648   )



                76.14.132            GetAppConfigFile

    Synopsis:    Return an appropriate name for an application configuration file.

Declaration:     function  GetAppConfigFile(Global:  Boolean)  :  string
                function  GetAppConfigFile(Global:  Boolean;SubDir:  Boolean)  :  string

    Visibility:   default

Description:     GetAppConfigFile returns the name of a file in which the application can store its config-
                uration parameters.  The exact name and location of the file depends on the customs of the
                operating system.

                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.



                                                                                1592

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                Note that on Windows, even when Subdir is False, a subdirectory is created for the appli-
                cation configuration files,  as per the windows specifications.  Specifying  true will create a
                subdirectory of the application settings subdirectory.

                The default file extension of the returned file is:  .cfg

                No assumptions should be made about the existence or writeability of this file, or the direc-
                tory where the file should reside.  It is best to call ForceDirectories (1581   ) prior to opening
                a file with the resulting filename.

                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 (1533   ) call,
                but can be configured by means of the OnGetApplicationName (1516   ) callback.

                If VendorName (1648   ) is not-empty,  then VendorName will be inserted in the path for the
                config file directory.

       Errors:   None.

    See also:    GetAppConfigDir  (1592   ),  OnGetApplicationName  (1516   ),  ApplicationName  (1533   ),  Cre-
                ateDir (1541   ), ConfigExtension (1497   ), SysConfigDir (1503   ), VendorName (1648   )



                76.14.133            GetCurrentDir

    Synopsis:    Return the current working directory of the application.

Declaration:     function  GetCurrentDir  :  AnsiString

    Visibility:   default

Description:     GetCurrentDir returns the current working directory.

       Errors:   None.

    See also:    SetCurrentDir (1612   ), DiskFree (1551   ), DiskSize (1551   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.134            GetDirs

    Synopsis:    Return a list of directory names from a path.

Declaration:     function  GetDirs(var  DirName:  UnicodeString;
                                           var  Dirs:  Array  of  PWideChar)  :  LongInt
                function  GetDirs(var  DirName:  RawByteString;
                                           var  Dirs:  Array  of  PAnsiChar)  :  LongInt



                                                                                1593

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    Visibility:  default

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 (1562   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.135            GetEnvironmentString

    Synopsis:    Return an environment variable by index.

Declaration:     function  GetEnvironmentString(Index:  Integer)  :  AnsiString

    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 (1595   ).

                For an example, GetEnvironmentVariableCount (1595   ).

 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 (1595   ), GetEnvironmentVariableCount (1595   )



                                                                                1594

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.136            GetEnvironmentVariable

    Synopsis:    Return the value of an environment variable.

Declaration:     function  GetEnvironmentVariable(const  EnvVar:  AnsiString)  :  AnsiString
                function  GetEnvironmentVariable(const  EnvVar:  UnicodeString)
                                                                     :  UnicodeString

    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 (1594   ), GetEnvironmentVariableCount (1595   )



                76.14.137            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 (1594   ), GetEnvironmentVariable (1595   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.138            GetFileHandle

    Synopsis:    Extract OS handle from an untyped file or text file.

Declaration:     function  GetFileHandle(var  f:  File)  :  THandle
                function  GetFileHandle(var  f:  Text)  :  THandle

    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.



                                                                                1595

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.139            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 (1609   )



                76.14.140            GetLocalTime

    Synopsis:    Get the local time.

Declaration:     procedure  GetLocalTime(var  SystemTime:  TSystemTime)

    Visibility:   default

Description:     GetLocalTime returns the system time in a TSystemTime (1512   ) format.

       Errors:   None.

    See also:    Now (1607   ), Date (1543   ), Time (1639   ), TSystemTime (1512   )



                76.14.141            GetLocalTimeOffset

    Synopsis:    Return local timezone offset

Declaration:     function  GetLocalTimeOffset  :  Integer

    Visibility:   default

Description:     GetLocalTimeOffset  returns  the  local  timezone  offset  in  minutes.  This  is  the  difference
                between UTC time and local time:

                UTC  =  LocalTime  +  GetLocalTimeOffset

                Note that on Linux/Unix, this information may be inaccurate around the DST time changes
                (for  optimization).  In  that  case,  the  unix.ReReadLocalTime  (1791   )  unit  must  be  used  to
                re-initialize the timezone information.

    See also:    unix.ReReadLocalTime (1791   ), Date (1543   ), Time (1639   ), Now (1607   )



                76.14.142            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.



                                                                                1596

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.143            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.

                The  OnGetTempDir  (1516   )  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 (1516   ), GetTempFileName (1597   )



                76.14.144            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  (1516   )  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 (1597   ), OnGetTempFile (1516   )



                76.14.145            GetTickCount

    Synopsis:    Get tick count (32-bit, deprecated)

Declaration:     function  GetTickCount  :  LongWord

    Visibility:   default

Description:     GetTickCount returns an increasing clock tick count.  It is useful for time measurements,
                but  no  assumtions  should  be  made  as  to  the  interval  between  the  ticks.   This  function  is
                provided for Delphi compatibility, use GetTickCount64 (1598   ) instead.

    See also:    GetTickCount64 (1598   ), Now (1607   ), Time (1639   ), Sleep (1613   )



                                                                                1597

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.146            GetTickCount64

    Synopsis:    Get tick count (64-bit)

Declaration:     function  GetTickCount64  :  QWord

    Visibility:   default

Description:     GetTickCount64 returns an increasing clock tick count.  It is useful for time measurements,
                but no assumtions should be made as to the interval between the ticks.

    See also:    Now (1607   ), Time (1639   ), Sleep (1613   )



                76.14.147            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 (1592   )



                76.14.148            GuidCase

    Synopsis:    Return the index of a GUID in an array of GUID values

Declaration:     function  GuidCase(const  GUID:  TGuid;const  List:  Array  of  TGuid)
                                              :  Integer

    Visibility:   default

Description:     GuidCase returns the index of GUID in the array List, where 0 denotes the first element in
                the list.  If GUID is not present in the list, -1 is returned.

    See also:    IsEqualGUID (1603   )



                76.14.149            GUIDToString

    Synopsis:    Convert a TGUID to a string representation.

Declaration:     function  GUIDToString(const  GUID:  TGuid)  :  string

    Visibility:   default

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 (1636   ), #rtl.system.TGUID (1283   ), StringToGUID (1620   ), IsEqualGuid (1603   )



                                                                                1598

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.150            HashName

    Synopsis:    Calculate a hash from a null-terminated string

Declaration:     function  HashName(Name:  PAnsiChar)  :  LongWord

    Visibility:   default

Description:     HashName calculates a hash value from a null terminated string.  The hash value is calculated
                in such a way that it returns the same value for strings that only differ in case.



                76.14.151            HookSignal

    Synopsis:    Hook a specified signal

Declaration:     procedure  HookSignal(RtlSigNum:  Integer)

    Visibility:   default

Description:     HookSignal installs the RTL default signal handler for signal RtlSigNum.  It does not check
                whether the signal is already handled, and should therefor only be called if  InquireSignal
                returns ssNotHooked.



                76.14.152            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 (1600   ), but operates on an already decoded date.

    See also:    IncMonth (1600   )



                76.14.153            IncludeLeadingPathDelimiter

    Synopsis:    Prepend a path delimiter if there is not already one.

Declaration:     function  IncludeLeadingPathDelimiter(const  Path:  UnicodeString)
                                                                             :  UnicodeString
                function  IncludeLeadingPathDelimiter(const  Path:  RawByteString)
                                                                             :  RawByteString

    Visibility:   default

Description:     IncludeLeadingPathDelimiter will insert a path delimiter (#rtl.system.DirectorySeparator
                (1242   )) in the first position of Path, if there is not already a directory separator at that po-
                sition.   It  will  return  the  resulting  string.   If  the  path  is  empty,  a  DirectorySeparator
                character is returned.

    See also:    IncludeTrailingPathDelimiter  (1600   ),  ExcludeLeadingPathDelimiter  (1556   ),  ExcludeTrail-
                ingPathDelimiter (1556   ), ConcatPaths (1541   )


                Listing:  ./sysutex/ex94.pp



                                                                                1599

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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 I n c l u d e L e a d i n g P a t h D e l i m i tfeurn c t *
 *i o n }


                Uses      s y s u t i l;s


                Begin
                End___.____________________________________________________________________________________________________________*
 *___________



                76.14.154            IncludeTrailingBackslash

    Synopsis:    Add trailing directory separator to a pathname, if needed.

Declaration:     function  IncludeTrailingBackslash(const  Path:  UnicodeString)
                                                                        :  UnicodeString
                function  IncludeTrailingBackslash(const  Path:  RawByteString)
                                                                        :  RawByteString

    Visibility:   default

Description:     IncludeTrailingBackslash is provided for backwards compatibility with Delphi.  Use In-
                cludeTrailingPathDelimiter (1600   ) instead.

    See also:    IncludeTrailingPathDelimiter (1600   ), ExcludeTrailingPathDelimiter (1556   ), PathDelim (1501   ),
                IsPathDelimiter (1604   )



                76.14.155            IncludeTrailingPathDelimiter

    Synopsis:    Add trailing directory separator to a pathname, if needed.

Declaration:     function  IncludeTrailingPathDelimiter(const  Path:  UnicodeString)
                                                                               :  UnicodeString
                function  IncludeTrailingPathDelimiter(const  Path:  RawByteString)
                                                                               :  RawByteString

    Visibility:   default

Description:     IncludeTrailingPathDelimiter adds a trailing path delimiter character (PathDelim (1501   ))
                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 (1600   ), ExcludeTrailingPathDelimiter (1556   ), PathDelim (1501   ),
                IsPathDelimiter (1604   )



                76.14.156            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).



                                                                                1600

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    Date (1543   ), Time (1639   ), Now (1607   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.157            InquireSignal

    Synopsis:    Check whether a signal handler is set (unix only)

Declaration:     function  InquireSignal(RtlSigNum:  Integer)  :  TSignalState

    Visibility:   default

Description:     RtlSigNum  will  check  whether  the  signal  RtlSigNum  is  being  handled,  and  by  whom.   It
                returns  a  TSignalState  result  to  report  the  state  of  the  signal,  which  can  be  one  of  the
                following values:


                ssNotHooked          No signal handler is set for the signal.

                ssHooked       A signal handler is set by the RTL code for the signal.

                ssOverridden         A signal handler was set for the signal by third-party code.


                This routine works by resetting the signal handlers, so it is risky to call.



                76.14.158            IntToHex

    Synopsis:    Convert an integer value to a hexadecimal string.

Declaration:     function  IntToHex(Value:  LongInt;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.



                                                                                1601

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    IntToStr (1602   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.159            IntToStr

    Synopsis:    Convert an integer value to a decimal string.

Declaration:     function  IntToStr(Value:  LongInt)  :  string
                function  IntToStr(Value:  Int64)  :  string
                function  IntToStr(Value:  QWord)  :  string

    Visibility:   default

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 (1601   ), StrToInt (1633   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1602

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.160            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 (1605   )



                76.14.161            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.

    See also:    Supports (1636   ), #rtl.system.TGUID (1283   ), StringToGUID (1620   ), GuidToString (1598   )



                76.14.162            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 (1600   ), Date (1543   )


                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



                                                                                1603

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                76.14.163            IsPathDelimiter

    Synopsis:    Is the character at the given position a pathdelimiter ?

Declaration:     function  IsPathDelimiter(const  Path:  UnicodeString;Index:  Integer)
                                                         :  Boolean
                function  IsPathDelimiter(const  Path:  RawByteString;Index:  Integer)
                                                         :  Boolean

    Visibility:   default

Description:     IsPathDelimiter returns True if the character at position Index equals PathDelim (1501   ),
                i.e.  if it is a path delimiter character for the current platform.

       Errors:   IncludeTrailingPathDelimiter (1600   )ExcludeTrailingPathDelimiter (1556   )PathDelim (1501   )



                76.14.164            IsValidIdent

    Synopsis:    Check whether a string is a valid identifier name.

Declaration:     function  IsValidIdent(const  Ident:  string)  :  Boolean

    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



                                                                                1604

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                76.14.165            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.


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.166            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 (1610   ), TrimLeft (1642   ), TrimRight (1642   ), Trim (1641   )


                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 ) ) ;



                                                                                1605

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                76.14.167            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.



                76.14.168            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 compatibility only.

                Lowercase does not change the number of characters (or bytes) in an ansistring or short-
                string.

       Errors:   None.

    See also:    AnsiLowerCase (1524   ), UpperCase (1648   ), AnsiUpperCase (1532   )


                Listing:  ./sysutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.169            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.



                                                                                1606

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    TimeStampToMSecs (1640   ), DateTimeToTimeStamp (1547   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.170            NewStr

    Synopsis:    Allocate a new ansistring on the heap.

Declaration:     function  NewStr(const  S:  string)  :  PString;    Overload

    Visibility:   default

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 (1534   ).

       Errors:   If not enough memory is present, an EOutOfMemory exception will be raised.

    See also:    AssignStr (1534   ), DisposeStr (1552   )



                76.14.171            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.



                                                                                1607

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    Date (1543   ), Time (1639   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.172            OutOfMemoryError

    Synopsis:    Raise an EOutOfMemory exception

Declaration:     procedure  OutOfMemoryError

    Visibility:   default

Description:     OutOfMemoryError  raises  an  EOutOfMemory  (1657   )  exception,  with  an  exception  object
                that has been allocated on the heap at program startup.  The program should neved create
                an EOutOfMemory (1657   ) exception, but always call this routine.

    See also:    EOutOfMemory (1657   )



                76.14.173            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 (1525   ), AnsiExtractQuotedStr (1522   )


                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  ) ;



                                                                                1608

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                76.14.174            RaiseLastOSError

    Synopsis:    Raise an exception with the last Operating System error code.

Declaration:     procedure  RaiseLastOSError;    Overload
                procedure  RaiseLastOSError(LastError:  Integer);    Overload

    Visibility:   default

Description:     RaiseLastOSError raises an EOSError (1657   ) 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 (1659   ) will be raised.

    See also:    EOSError (1657   ), GetLastOSError (1596   ), Exception (1659   )



                76.14.175            RemoveDir

    Synopsis:    Remove a directory from the filesystem.

Declaration:     function  RemoveDir(const  Dir:  RawByteString)  :  Boolean
                function  RemoveDir(const  Dir:  UnicodeString)  :  Boolean

    Visibility:   default

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 (1541   ).

       Errors:   In case of error (e.g.  the directory isn't empty) the function returns False.  If successful,
                True is returned.



                76.14.176            RenameFile

    Synopsis:    Rename a file.

Declaration:     function  RenameFile(const  OldName:  UnicodeString;
                                                const  NewName:  UnicodeString)  :  Boolean
                function  RenameFile(const  OldName:  RawByteString;
                                                const  NewName:  RawByteString)  :  Boolean

    Visibility:   default

Description:     RenameFile renames a file from OldName to NewName.  The function returns True if success-
                ful, False otherwise.  For safety, the new name must be a full path specification, including
                the directory, otherwise it will be assumed to be a filename relative to the current working
                directory.  Remark:  The implementation of RenameFile relies on the undelying OS's support
                for renaming/moving a file.  Whether or not a file can be renamed accros disks or partitions
                depends  entirely  on  the  OS.  On  unix-like  OS-es,  the  rename  function  will  fail  when  used
                accross partitions.  On Windows, it will work.



                                                                                1609

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   On Error, False is returned.

    See also:    DeleteFile (1550   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.177            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 (1610   )



                76.14.178            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.



                76.14.179            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



                                                                                1610

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1605   ), Trim (1641   ), TrimLeft (1642   ), TrimRight (1642   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.180            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.



                76.14.181            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 (1520   ) with arguments S1 and
                S2 returns 0, and returns False otherwise.

       Errors:   None.

    See also:    AnsiCompareFileName (1520   )



                76.14.182            SameText

    Synopsis:    Checks whether 2 strings are the same (case insensitive)

Declaration:     function  SameText(const  s1:  string;const  s2:  string)  :  Boolean

    Visibility:   default



                                                                                1611

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Description:     SameText calls CompareText (1540   ) 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 (1540   ), AnsiSameText (1525   ), AnsiSameStr (1525   )



                76.14.183            SetCurrentDir

    Synopsis:    Set the current directory of the application.

Declaration:     function  SetCurrentDir(const  NewDir:  RawByteString)  :  Boolean
                function  SetCurrentDir(const  NewDir:  UnicodeString)  :  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 (1593   )



                76.14.184            SetDirSeparators

    Synopsis:    Set the directory separators to the known directory separators.

Declaration:     function  SetDirSeparators(const  FileName:  UnicodeString)  :  UnicodeString
                function  SetDirSeparators(const  FileName:  RawByteString)  :  RawByteString

    Visibility:   default

Description:     SetDirSeparators returns FileName with all possible DirSeparators replaced by OSDirSeparator.

       Errors:   None.

    See also:    ExpandFileName (1558   ), ExtractFilePath (1561   ), ExtractFileDir (1560   )


                Listing:  ./sysutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.185            ShowException

    Synopsis:    Show the current exception to the user.

Declaration:     procedure  ShowException(ExceptObject:  TObject;ExceptAddr:  Pointer)

    Visibility:   default



                                                                                1612

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Description:     ShowException shows a message stating that a ExceptObject was raised at address ExceptAddr.
                It uses ExceptionErrorMessage (1555   ) 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
                (1516   ) is executed.

       Errors:   If, for a GUI application, OnShowException (1516   ) 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 (1555   ), ExceptAddr (1554   ), ExceptionErrorMessage (1555   )



                76.14.186            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.



                76.14.187            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

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)

                s Placeholder for a string of arbitrary length.

                c Placeholder 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.

                s A pointer to an ansistring.

                c A pointer to a single character.

       Errors:   No error checking is performed on the type of the memory location.

    See also:    Format (1581   )



                                                                                1613

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.188            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 (1191   ) function of the Strings
                unit.

                For an example, see StrBufSize (1614   ).

       Errors:   None.

    See also:    StrBufSize (1614   ), StrDispose (1617   ), StrAlloc (1191   )



                76.14.189            StrBufSize

    Synopsis:    Return the size of a null-terminated string allocated on the heap.

Declaration:     function  StrBufSize(Str:  PChar)  :  Cardinal

    Visibility:   default

Description:     StrBufSize returns the memory allocated for Str.  This function ONLY gives the correct
                result if  Str was allocated using StrAlloc (1614   ).

       Errors:   If no more memory is available, a runtime error occurs.

    See also:    StrAlloc (1614   ), StrDispose (1617   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1614

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.190            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 (1510   ), ByteType (1536   )



                76.14.191            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 (1620   )


                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.  }


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.192            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.



                                                                                1615

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.193            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 (1621   ).

       Errors:   None.

    See also:    StrLComp (1621   ), StrIComp (1619   ), StrLIComp (1623   )



                76.14.194            StrCopy

    Synopsis:    Copy a null-terminated string

Declaration:     function  strcopy(dest:  PChar;source:  PChar)  :  PChar;    Overload
                function  StrCopy(Dest:  PWideChar;Source:  PWideChar)  :  PWideChar
                                           ;    Overload

    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 (1626   ), StrLCopy (1621   ), StrECopy (1617   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1616

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.195            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 (1614   ) from the SysUtils unit.

                For an example, see StrBufSize (1614   ).

       Errors:   If an invalid pointer is passed, or a pointer not allocated with StrAlloc, an error may occur.

    See also:    StrBufSize (1614   ), StrAlloc (1614   ), StrDispose (1617   )



                76.14.196            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 (1621   ), StrCopy (1616   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.197            strend

    Synopsis:    Return a pointer to the end of a null-terminated string

Declaration:     function  strend(p:  PChar)  :  PChar



                                                                                1617

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    Visibility:  default

Description:     Returns a pointer to the end of  P. (i.e.  to the terminating null-character.

       Errors:   None.

    See also:    StrLen (1622   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.198            StrFmt

    Synopsis:    Format a string with given arguments, store the result in a buffer.

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  (1581   )  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 (1581   ).

    See also:    StrLFmt (1622   ), FmtStr (1580   ), Format (1581   ), FormatBuf (1588   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1618

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.199            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 (1621   ), StrComp (1616   ), StrLIComp (1623   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.200            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 (1511   ).  Standard
                behaviour is to replace only the first occurrence of OldPattern, and to search case sensitively.

       Errors:   None.

    See also:    TReplaceFlags (1511   )



                                                                                1619

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.201            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  (1653   )  exception  is
                raised.

    See also:    Supports (1636   ), #rtl.system.TGUID (1283   ), GUIDToString (1598   ), IsEqualGuid (1603   )



                76.14.202            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 (1615   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1620

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.203            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 (1616   ), StrIComp (1619   ), StrLIComp (1623   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.204            StrLCopy

    Synopsis:    Copy a null-terminated string, limited in length.

Declaration:     function  strlcopy(dest:  PChar;source:  PChar;maxlen:  SizeInt)  :  PChar
                                            ;    Overload
                function  StrLCopy(Dest:  PWideChar;Source:  PWideChar;MaxLen:  SizeInt)
                                              :  PWideChar;    Overload

    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 (1616   ), StrECopy (1617   )



                                                                                1621

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.205            StrLen

    Synopsis:    Length of a null-terminated string.

Declaration:     function  strlen(p:  PChar)  :  SizeInt;    Overload
                function  StrLen(p:  PWideChar)  :  SizeInt;    Overload

    Visibility:   default

Description:     Returns the length of the null-terminated string P. If P equals Nil then zero (0) is returned.

       Errors:   None.

    See also:    StrNew (1625   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.206            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



                                                                                1622

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    Visibility:  default

Description:     StrLFmt will format fmt with Args, as the Format (1581   ) 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 (1581   ).

    See also:    StrFmt (1618   ), FmtStr (1580   ), Format (1581   ), FormatBuf (1588   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.207            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 (1619   )

       Errors:   None.

    See also:    StrLComp (1621   ), StrComp (1616   ), StrIComp (1619   )



                76.14.208            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.



                                                                                1623

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    StrUpper (1636   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.209            strmove

    Synopsis:    Move a null-terminated string to new location.

Declaration:     function  strmove(dest:  PChar;source:  PChar;l:  SizeInt)  :  PChar
                                           ;    Overload

    Visibility:   default

Description:     Copies  MaxLen  characters  from  Source  to  Dest.  No  terminating  null-character  is  copied.
                Returns Dest

       Errors:   None.

    See also:    StrLCopy (1621   ), StrCopy (1616   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1624

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.210            strnew

    Synopsis:    Allocate room for new null-terminated string.

Declaration:     function  strnew(p:  PChar)  :  PChar;    Overload

    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 (1616   ), StrDispose (1617   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.211            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.



                76.14.212            StrPas

    Synopsis:    Convert a null-terminated string to an ansistring.

Declaration:     function  StrPas(Str:  PChar)  :  string;    Overload

    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 system unit's version.

       Errors:   None.

    See also:    StrPCopy (1626   ), StrPLCopy (1626   )



                                                                                1625

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.213            StrPCopy

    Synopsis:    Copy an ansistring to a null-terminated string.

Declaration:     function  StrPCopy(Dest:  PChar;const  Source:  string)  :  PChar;    Overload

    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 (1626   ), StrPas (1625   )



                76.14.214            StrPLCopy

    Synopsis:    Copy a limited number of characters from an ansistring to a null-terminated string.

Declaration:     function  StrPLCopy(Dest:  PChar;const  Source:  string;MaxLen:  SizeUInt)
                                                :  PChar;    Overload

    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 (1626   )



                76.14.215            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 (1627   ), StrRScan (1627   )


                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   :   ' , s i z e i n(tS t r P o s(P , S)) -  s i z e *
 *i n t(P ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1626

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.216            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 (1627   ).

       Errors:   None.

    See also:    StrScan (1627   ), StrPos (1626   )



                76.14.217            strscan

    Synopsis:    Find first occurrence of a character in a null-terminated string.

Declaration:     function  strscan(p:  PChar;c:  Char)  :  PChar;    Overload

    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 (1627   ), StrPos (1626   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.218            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 (1653   ) exception is raised.



                                                                                1627

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   On error, an EConvertError (1653   ) exception is raised.

    See also:    BoolToStr (1535   )



                76.14.219            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 (1627   ), TryStrToBool (1644   )



                76.14.220            StrToCurr

    Synopsis:    Convert a string to a currency value

Declaration:     function  StrToCurr(const  S:  string)  :  Currency
                function  StrToCurr(const  S:  string;
                                              const  FormatSettings:  TFormatSettings)  :  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 (1653   ) exception is raised.

       Errors:   On error, an EConvertError (1653   ) exception is raised.

    See also:    CurrToStr (1543   ), StrToCurrDef (1628   )



                76.14.221            StrToCurrDef

    Synopsis:    Convert a string to a currency value, using a default value

Declaration:     function  StrToCurrDef(const  S:  string;Default:  Currency)  :  Currency
                function  StrToCurrDef(const  S:  string;Default:  Currency;
                                                   const  FormatSettings:  TFormatSettings)  :  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 (1543   ), StrToCurr (1628   )



                                                                                1628

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.222            StrToDate

    Synopsis:    Convert a date string to a TDateTime value.

Declaration:     function  StrToDate(const  S:  ShortString)  :  TDateTime
                function  StrToDate(const  S:  Ansistring)  :  TDateTime
                function  StrToDate(const  S:  ShortString;separator:  Char)  :  TDateTime
                function  StrToDate(const  S:  AnsiString;separator:  Char)  :  TDateTime
                function  StrToDate(const  S:  string;FormatSettings:  TFormatSettings)
                                                :  TDateTime
                function  StrToDate(const  S:  ShortString;const  useformat:  string;
                                              separator:  Char)  :  TDateTime
                function  StrToDate(const  S:  AnsiString;const  useformat:  string;
                                              separator:  Char)  :  TDateTime
                function  StrToDate(const  S:  PChar;Len:  Integer;const  useformat:  string;
                                              separator:  Char)  :  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 (1635   ), DateToStr (1547   ), TimeToStr (1641   )


                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


                 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(' 05  '+ D a t e S e p a r a t o+r'05  '+ D a t e S e p a r a t o+r'1999   ' ) ;
                    T e s t S t r(' 5 '+ D a t e S e p a r a t o+r'5 ' ) ;
                    T e s t S t r(' 5 ') ;
                End___.____________________________________________________________________________________________________________*
 *___________



                76.14.223            StrToDateDef

    Synopsis:    Convert string to date, returning a default value



                                                                                1629

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Declaration:     function  StrToDateDef(const  S:  ShortString;const  Defvalue:  TDateTime)
                                                    :  TDateTime
                function  StrToDateDef(const  S:  ShortString;const  Defvalue:  TDateTime;
                                                  separator:  Char)  :  TDateTime
                function  StrToDateDef(const  S:  AnsiString;const  Defvalue:  TDateTime)
                                                    :  TDateTime
                function  StrToDateDef(const  S:  AnsiString;const  Defvalue:  TDateTime;
                                                  separator:  Char)  :  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 (1629   ), TryStrToDate (1645   ), StrToTimeDef (1636   )



                76.14.224            StrToDateTime

    Synopsis:    Convert a date/time string to a TDateTime value.

Declaration:     function  StrToDateTime(const  S:  AnsiString)  :  TDateTime
                function  StrToDateTime(const  s:  ShortString;
                                                     const  FormatSettings:  TFormatSettings)  :  TDateTime
                function  StrToDateTime(const  s:  AnsiString;
                                                     const  FormatSettings:  TFormatSettings)  :  TDateTime

    Visibility:   default

Description:     StrToDateTime converts the string S to a TDateTime date and time value.  The date and
                time parts must be separated by a space.

                For  the  date  part,  the  same  restrictions  apply  as  for  the  StrToDate  (1629   )  function:  The
                Date must consist of 1 to three numbers, 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 3 numbers (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 (1629   ), StrToTime (1635   ), DateTimeToStr (1544   )


                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}


                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   ;



                                                                                1630

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.225            StrToDateTimeDef

    Synopsis:    Convert string to date/time, returning a default value

Declaration:     function  StrToDateTimeDef(const  S:  ShortString;
                                                         const  Defvalue:  TDateTime)  :  TDateTime
                function  StrToDateTimeDef(const  S:  AnsiString;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  (1636   ),  StrToDateDef  (1629   ),  TryStrToDateTime  (1645   ),  StrToDateTime
                (1630   )



                76.14.226            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 (1638   ), FloatToStr (1576   ), FormatFloat (1590   ), StrToInt (1633   )


                Listing:  ./sysutex/ex90.pp



                                                                                1631

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.227            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.



                                                                                1632

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.228            StrToInt

    Synopsis:    Convert a string to an integer value.

Declaration:     function  StrToInt(const  s:  string)  :  LongInt

    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.

                The  string  S  can  contain  a  number  in  decimal,  hexadecimal,  binary  or  octal  format,  as
                described in the language reference.  For enumerated values, the string must be the name of
                the enumerated value.  The name is searched case insensitively.

                For hexadecimal values, the prefix '0x' or 'x' (case insensitive) may be used as well.

       Errors:   In case of error, an EConvertError is raised.

    See also:    IntToStr (1602   ), StrToIntDef (1634   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.229            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 (1653   ) exception is raised.



                                                                                1633

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    TryStrToInt64  (1647   ),  StrToInt64Def  (1634   ),  StrToInt  (1633   ),  TryStrToInt  (1646   ),  Str-
                ToIntDef (1634   )



                76.14.230            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 (1633   ), TryStrToInt64 (1647   ), StrToInt (1633   ), TryStrToInt (1646   ), StrToIntDef
                (1634   )



                76.14.231            StrToIntDef

    Synopsis:    Convert a string to an integer value, with a default value.

Declaration:     function  StrToIntDef(const  S:  string;Default:  LongInt)  :  LongInt

    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 (1602   ), StrToInt (1633   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1634

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.232            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 (1653   ) exception is
                raised.

    See also:    TryStrToQWord (1647   ), StrToQWordDef (1635   ), StrToInt64 (1633   ), StrToInt (1633   )



                76.14.233            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 (1635   ), TryStrToQWord (1647   ), StrToInt64Def (1634   ), StrToIntDef (1634   )



                76.14.234            StrToTime

    Synopsis:    Convert a time string to a TDateTime value.

Declaration:     function  StrToTime(const  S:  Shortstring)  :  TDateTime
                function  StrToTime(const  S:  Ansistring)  :  TDateTime
                function  StrToTime(const  S:  ShortString;separator:  Char)  :  TDateTime
                function  StrToTime(const  S:  AnsiString;separator:  Char)  :  TDateTime
                function  StrToTime(const  S:  string;FormatSettings:  TFormatSettings)
                                                :  TDateTime
                function  StrToTime(const  S:  PChar;Len:  Integer;separator:  Char)
                                                :  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 (1629   ), StrToDateTime (1630   ), TimeToStr (1641   )


                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



                                                                                1635

                _______________________________________________________CHAPTER_76.___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  , '  :   ', TimeToStr      ( StrToTime       (S  ) ) ) ;
                end   ;


                Begin
                    t e s t s t r ( TimeToStr      ( Time   ) ) ;
                    t e s t s t r ( ' 1 2 : 0 0') ;
                    t e s t s t r ( ' 1 5 : 3 0') ;
                    t e s t s t r ( ' 3 : 3 0PM ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                76.14.235            StrToTimeDef

    Synopsis:    Convert string to time, returning a default value

Declaration:     function  StrToTimeDef(const  S:  ShortString;const  Defvalue:  TDateTime)
                                                     :  TDateTime
                function  StrToTimeDef(const  S:  ShortString;const  Defvalue:  TDateTime;
                                                   separator:  Char)  :  TDateTime
                function  StrToTimeDef(const  S:  AnsiString;const  Defvalue:  TDateTime)
                                                     :  TDateTime
                function  StrToTimeDef(const  S:  AnsiString;const  Defvalue:  TDateTime;
                                                   separator:  Char)  :  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 (1635   ), TryStrToTime (1647   ), StrToDateDef (1629   )



                76.14.236            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 (1623   )

       Errors:   None.

    See also:    StrLower (1623   )



                76.14.237            Supports

    Synopsis:    Check whether a class or given interface supports an interface



                                                                                1636

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Declaration:     function  Supports(const  Instance:  IInterface;const  AClass:  TClass;
                                            out  Obj)  :  Boolean;    Overload
                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:  TObject;const  IID:  Shortstring;
                                            out  Intf)  :  Boolean;    Overload
                function  Supports(const  Instance:  IInterface;const  AClass:  TClass)
                                             :  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  Instance:  TObject;const  IID:  Shortstring)
                                             :  Boolean;    Overload
                function  Supports(const  AClass:  TClass;const  IID:  TGuid)  :  Boolean
                                            ;    Overload
                function  Supports(const  AClass:  TClass;const  IID:  Shortstring)  :  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.

       Errors:   None.

    See also:    StringToGUID (1620   )



                76.14.238            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 (1657   )



                76.14.239            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 (1546   )



                                                                                1637

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.240            TextToFloat

    Synopsis:    Convert a buffer to a float value.

Declaration:     function  TextToFloat(Buffer:  PChar;out  Value:  Extended)  :  Boolean
                function  TextToFloat(Buffer:  PChar;out  Value:  Extended;
                                                 const  FormatSettings:  TFormatSettings)  :  Boolean
                function  TextToFloat(Buffer:  PChar;out  Value;ValueType:  TFloatValue)
                                                   :  Boolean
                function  TextToFloat(Buffer:  PChar;out  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 (1631   ), FloatToStr (1576   ), FormatFloat (1590   )


                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=



                                                                                1638

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                                    ( '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=', ' ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                76.14.241            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 (1607   ), Date (1543   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1639

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.242            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 (1547   ).

       Errors:   None.

    See also:    DateTimeToTimeStamp (1547   ), TimeStampToMSecs (1640   )


                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       ;


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.243            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 (1606   ).

       Errors:   None.

    See also:    MSecsToTimeStamp (1606   ), TimeStampToDateTime (1640   )



                                                                                1640

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.244            TimeToStr

    Synopsis:    Convert a TDateTime time to a string using a predefined format.

Declaration:     function  TimeToStr(Time:  TDateTime)  :  string
                function  TimeToStr(Time:  TDateTime;
                                              const  FormatSettings:  TFormatSettings)  :  string

    Visibility:   default

Description:     TimeToStr converts the time in Time to a string.  It uses the LongTimeFormat variable to see
                what formatting needs to be applied.  It is therefor entirely equivalent to a FormatDateTime('tt',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___.____________________________________________________________________________________________________________*
 *___________



                76.14.245            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 and control characters) at the beginning and end of  S
                and returns the resulting string.  All characters with ordinal values less than or equal to 32
                (a space) are stripped.

                If the string contains only spaces, an empty string is returned.

       Errors:   None.

    See also:    TrimLeft (1642   ), TrimRight (1642   )


                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



                                                                                1641

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                76.14.246            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:     Trim  strips  blank  characters  (spaces  and  control  characters)  at  the  beginning  of  S  and
                returns the resulting string.  All characters with ordinal values less than or equal to 32 (a
                space) are stripped.

                If the string contains only spaces, an empty string is returned.

       Errors:   None.

    See also:    Trim (1641   ), TrimRight (1642   )


                Listing:  ./sysutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                76.14.247            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



                                                                                1642

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Description:     Trim  strips  blank  characters  (spaces  and  control  characters)  at  the  end  of  S  and  returns
                the resulting string.  All characters with ordinal values less than or equal to 32 (a space) are
                stripped.

                If the string contains only spaces, an empty string is returned.

       Errors:   None.

    See also:    Trim (1641   ), TrimLeft (1642   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.248            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  Date.  The
                function will return True in this case.  If an invalid argument is passed, then False will be
                returned.

       Errors:   None.  If an error occurs during the encoding, False is returned.

    See also:    EncodeDate (1553   ), DecodeDateFully (1549   ), DecodeDate (1548   ), TryEncodeTime (1643   )



                76.14.249            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



                                                                                1643

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 Time.  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 (1554   ), DecodeTime (1549   ), TryEncodeDate (1643   )



                76.14.250            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 (1500   )
                and MaxCurrency (1500   )).  If not, False is returned.

       Errors:   If  Value is out of range, False is returned.

    See also:    FloatToCurr (1575   ), MinCurrency (1500   ), MaxCurrency (1500   )



                76.14.251            TryStringToGUID

    Synopsis:    Try to transform a string to a GUID

Declaration:     function  TryStringToGUID(const  S:  string;out  Guid:  TGuid)  :  Boolean

    Visibility:   default

Description:     TryStringToGUID  tries  to  convert  the  string  S  to  a  TGUID  value,  returned  in  GUID.  It
                returns True if the conversion succeeds, and False if the string S does not contain a valid
                GUID notation.  The string S must be 38 characters long, must start with { and end on },
                and contain a valid GUID string (hex number grouped using 8-4-4-4-12 digits).

       Errors:   In case S does not contain a valid GUID number, False is returned.

    See also:    StringToGUID (1620   )



                76.14.252            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 (1514   ) (for False values) and True-
                BoolStrs (1518   ) (for True values) variables.

    See also:    StrToBool (1627   ), StrToBoolDef (1628   )



                                                                                1644

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.253            TryStrToCurr

    Synopsis:    Try to convert a string to a currency

Declaration:     function  TryStrToCurr(const  S:  string;out  Value:  Currency)  :  Boolean
                function  TryStrToCurr(const  S:  string;out  Value:  Currency;
                                                   const  FormatSettings:  TFormatSettings)  :  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
                (1628   ), which raises an exception when the conversion fails.

                The function takes into account locale information.

    See also:    StrToCurr (1628   ), TextToFloat (1638   )



                76.14.254            TryStrToDate

    Synopsis:    Try to convert a string with a date indication to a TDateTime value

Declaration:     function  TryStrToDate(const  S:  ShortString;out  Value:  TDateTime)
                                                     :  Boolean
                function  TryStrToDate(const  S:  AnsiString;out  Value:  TDateTime)
                                                     :  Boolean
                function  TryStrToDate(const  S:  ShortString;out  Value:  TDateTime;
                                                   separator:  Char)  :  Boolean
                function  TryStrToDate(const  S:  AnsiString;out  Value:  TDateTime;
                                                   separator:  Char)  :  Boolean
                function  TryStrToDate(const  S:  ShortString;out  Value:  TDateTime;
                                                   const  useformat:  string;separator:  Char)  :  Boolean
                function  TryStrToDate(const  S:  AnsiString;out  Value:  TDateTime;
                                                   const  useformat:  string;separator:  Char)  :  Boolean
                function  TryStrToDate(const  S:  string;out  Value:  TDateTime;
                                                   const  FormatSettings:  TFormatSettings)  :  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  (1629   ),  StrToTime  (1635   ),  TryStrToTime  (1647   ),  TryStrToDateTime  (1645   ),
                DateToStr (1547   ), TimeToStr (1641   )



                76.14.255            TryStrToDateTime

    Synopsis:    Try to convert a string with date/time indication to a TDateTime value



                                                                                1645

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Declaration:     function  TryStrToDateTime(const  S:  ShortString;out  Value:  TDateTime)
                                                          :  Boolean
                function  TryStrToDateTime(const  S:  AnsiString;out  Value:  TDateTime)
                                                          :  Boolean
                function  TryStrToDateTime(const  S:  string;out  Value:  TDateTime;
                                                         const  FormatSettings:  TFormatSettings)
                                                          :  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  (1645   ),  TryStrToTime  (1647   ),  StrToDateTime  (1630   ),  StrToTime  (1635   ),
                DateToStr (1547   ), TimeToStr (1641   )



                76.14.256            TryStrToFloat

    Synopsis:    Try to convert a string to a float.

Declaration:     function  TryStrToFloat(const  S:  string;out  Value:  Single)  :  Boolean
                function  TryStrToFloat(const  S:  string;out  Value:  Single;
                                                     const  FormatSettings:  TFormatSettings)  :  Boolean
                function  TryStrToFloat(const  S:  string;out  Value:  Double)  :  Boolean
                function  TryStrToFloat(const  S:  string;out  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 (1631   )



                76.14.257            TryStrToInt

    Synopsis:    Try to convert a string to an integer, and report on success.

Declaration:     function  TryStrToInt(const  s:  string;out  i:  LongInt)  :  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.



                                                                                1646

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    StrToInt (1633   ), TryStrToInt64 (1647   ), StrToIntDef (1634   ), StrToInt64 (1633   ), StrToInt64Def
                (1634   )



                76.14.258            TryStrToInt64

    Synopsis:    Try to convert a string to an int64 value, and report on success.

Declaration:     function  TryStrToInt64(const  s:  string;out  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 (1633   ), StrToInt64Def (1634   ), StrToInt (1633   ), TryStrToInt (1646   ), StrToIntDef
                (1634   )



                76.14.259            TryStrToQWord

    Synopsis:    Try to convert a string to a QWord value, and report on success

Declaration:     function  TryStrToQWord(const  s:  string;out  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 (1635   ), StrToQWordDef (1635   ), TryStrToInt64 (1647   ), TryStrToInt (1646   )



                76.14.260            TryStrToTime

    Synopsis:    Try to convert a string with a time indication to a TDateTime value

Declaration:     function  TryStrToTime(const  S:  ShortString;out  Value:  TDateTime)
                                                     :  Boolean
                function  TryStrToTime(const  S:  AnsiString;out  Value:  TDateTime)
                                                     :  Boolean
                function  TryStrToTime(const  S:  ShortString;out  Value:  TDateTime;
                                                   separator:  Char)  :  Boolean
                function  TryStrToTime(const  S:  AnsiString;out  Value:  TDateTime;
                                                   separator:  Char)  :  Boolean
                function  TryStrToTime(const  S:  string;out  Value:  TDateTime;
                                                   const  FormatSettings:  TFormatSettings)  :  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.



                                                                                1647

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    TryStrToDate  (1645   ),  TryStrToDateTime  (1645   ),  StrToDate  (1629   ),  StrToTime  (1635   ),
                DateToStr (1547   ), TimeToStr (1641   )



                76.14.261            UnhookSignal

    Synopsis:    UnHook a specified signal

Declaration:     procedure  UnhookSignal(RtlSigNum:  Integer;OnlyIfHooked:  Boolean)

    Visibility:   default

Description:     UnHookSignal de-installs the RTL default signal handler for signal RtlSigNum.  If OnlyIfHooked
                is  True  then  UnhookSignal  will  first  check  if  the  signal  was  hooked  by  the  RTL  routines,
                and has not been overridden since.



                76.14.262            UpperCase

    Synopsis:    Return an uppercase version of a string.

Declaration:     function  UpperCase(const  s:  string)  :  string;    Overload

    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 (1524   ), LowerCase (1606   ), AnsiUpperCase (1532   )


                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___.____________________________________________________________________________________________________________*
 *___________



                76.14.263            VendorName

    Synopsis:    Return Application vendor Name

Declaration:     function  VendorName  :  string

    Visibility:   default

Description:     VendorName  returns  the  application  vendor  name.  In  order  to  set  the  application  vendor
                name,  the  OnGetVendorName  (1516   )  event  must  be  set,  and  an  appropriate  return  value
                must be returned.  The Vendor name is used in GetAppConfigDir (1592   ) and GetAppCon-
                figFile (1592   ) to determine the configuration directory.

       Errors:   If OnGetVendorName (1516   ) is not set, an empty string is returned.

    See also:    OnGetVendorName (1516   ), GetAppConfigDir (1592   ), GetAppConfigFile (1592   )



                                                                                1648

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.264            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.

                The comparision takes into account wide characters,  i.e.  it takes care of strange accented
                characters.  Contrary to WideCompareText (1649   ), the comparision is case sensitive.

       Errors:   None.

    See also:    WideCompareText (1649   ), WideSameStr (1651   ), WideSameText (1651   )



                76.14.265            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 (1649   ), the comparision is case insensitive.

       Errors:   None.

    See also:    WideCompareStr (1649   ), WideSameStr (1651   ), WideSameText (1651   )



                76.14.266            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 (1650   ), WideFormatBuf (1650   ), Format (1581   )



                                                                                1649

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.267            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

Description:     WideFormat does the same as Format (1581   ) 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 (1581   ) string.

    See also:    Format (1581   )



                76.14.268            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 (1650   ) 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 (1649   ), WideFormat (1650   ), Format (1581   ), FormatBuf (1588   )



                76.14.269            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  special
                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 (1651   )



                                                                                1650

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.14.270            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 (1649   ) returns 0 (zero), i.e.  when S1 and S2
                are the same string (taking into account case).

    See also:    WideSameText (1651   ),  WideCompareStr (1649   ),  WideCompareText (1649   ),  AnsiSameStr
                (1525   )



                76.14.271            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 (1649   ) returns 0 (zero), i.e.  when S1 and
                S2 are the same string (taking into account case).

    See also:    WideSameStr (1651   ),  WideCompareStr (1649   ),  WideCompareText (1649   ),  AnsiSameText
                (1525   )



                76.14.272            WideUpperCase

    Synopsis:    Change a widestring to all-uppercase.

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
                special 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 (1650   )



                76.14.273            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



                                                                                1651

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1619   )



                76.15            EAbort



                76.15.1          Description

                Abort  is  raised  by  the  Abort  (1518   )  procedure.   It  is  not  displayed  in  GUI  applications,
                and serves only to immediately abort the current procedure, and return control to the main
                program loop.


    See also:    Abort (1518   )



                76.16            EAbstractError



                76.16.1          Description

                EAbstractError is raised when an abstract error occurs, i.e.  when an unimplemented ab-
                stract method is called.



                76.17            EAccessViolation



                76.17.1          Description

                EAccessViolation  is  raised  when  the  OS  reports  an  Access  Violation,  i.e.   when  invalid
                memory is accessed.


    See also:    EObjectCheck (1656   )



                76.18            EArgumentException



                76.18.1          Description

                EArgumentException is raised by many character conversion/handling routines to indicate
                an erroneous argument was passed to the function (usually indicating an invalid codepoint
                in a unicode string).


    See also:    EArgumentOutOfRangeException (1652   )



                76.19            EArgumentOutOfRangeException



                76.19.1          Description

                EArgumentOutOfRangeException is raised by many character conversion/handling routines
                to indicate an erroneous argument was passed to the function (indicating an invalid character
                index in a unicode string).


    See also:    EArgumentException (1652   )



                                                                                1652

            _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            76.20            EAssertionFailed



            76.20.1          Description

            EAssertionFailed is raised when an application that is compiled with assertions, encounters
            an invalid assertion.



            76.21            EBusError



            76.21.1          Description

            EBusError is raised in case of a bus error.



            76.22            EControlC



            76.22.1          Description

            EControlC is raised when the user has pressed CTRL-C in a console application.



            76.23            EConvertError



            76.23.1          Description

            EConvertError is raised by the various conversion routines in the SysUtils unit.  The message
            will contain more specific error information.



            76.24            EDivByZero



            76.24.1          Description

            EDivByZero is used when the operating system or CPU signals a division by zero error.



            76.25            EExternal



            76.25.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.


See also:    EInterror (1654   ), EExternal (1653   ), EMathError (1656   ), EExternalException (1653   ), EAc-
            cessViolation (1652   ), EPrivilege (1657   ), EStackOverflow (1658   ), EControlC (1653   )



            76.26            EExternalException



            76.26.1          Description

            EExternalException is raised when an external routine raises an exception.



                                                                            1653

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    EExternal (1653   )



                76.27            EFormatError



                76.27.1          Description

                EformatError is raised in case of an error in one of the various Format (1581   ) functions.


    See also:    Format (1581   )



                76.28            EHeapMemoryError



                76.28.1          Description

                EHeapMemoryError is raised when an error occurs in heap (dynamically allocated) memory.


    See also:    EHeapException (1504   ), EoutOfMemory (1657   ), EInvalidPointer (1655   )



                76.28.2          Method  overview

                __Page______Method________________Description______________________________________________________________________*
 *___________
                __1654______FreeInstance__________Free_the_exception_instance______________________________________________________*
 *___________



                76.28.3          EHeapMemoryError.FreeInstance

    Synopsis:    Free the exception instance

Declaration:     procedure  FreeInstance;    Override

    Visibility:   public

Description:     FreeInstance  checks  whether  the  exception  instance  may  be  freed  prior  to  calling  the
                inherited FreeInstance.  The exception is only freed in case of normal program shutdown,
                if a heap error occured, the exception instance is not freed.



                76.29            EInOutError



                76.29.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 (??  ).


    See also:    EInOutError.ErrorCode (??  )



                76.30            EInterror



                76.30.1          Description

                EInterror  is  used  when  the  operating  system  or  CPU  signals  an  integer  operation  error,
                e.g., an overflow.



                                                                                1654

            _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            76.31            EIntfCastError



            76.31.1          Description

            EIntfCastError is raised when an invalid interface cast is encountered.


See also:    EInvalidCast (1655   )



            76.32            EIntOverflow



            76.32.1          Description

            EIntOverflow is used when the operating system or CPU signals a integer overflow error.


See also:    EIntError (1654   ), EDivByZero (1653   ), ERangeError (1658   )



            76.33            EInvalidCast



            76.33.1          Description

            EInvalidCast is raised when an invalid typecast error (using the as operator) is encountered.


See also:    EIntfCastError (1655   )



            76.34            EInvalidContainer



            76.34.1          Description

            EInvalidContainer is not yet used by Free Pascal, and is provided for Delphi compatibility
            only.



            76.35            EInvalidInsert



            76.35.1          Description

            EInvalidInsert  is  not  yet  used  by  Free  Pascal,  and  is  provided  for  Delphi  compatibility
            only.



            76.36            EInvalidOp



            76.36.1          Description

            EInvalidOp is raised when an invalid operation is encountered.



            76.37            EInvalidPointer



            76.37.1          Description

            EInvalidPointer is raised when an invalid heap pointer is used.



                                                                            1655

            _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



See also:    EHeapException (1504   ), EHeapMemoryError (1654   ), EOutOfMemory (1657   )



            76.38            EMathError



            76.38.1          Description

            EMathError  is  used  when  the  operating  system  or  CPU  signals  a  floating  point  overflow
            error.


See also:    EIntError (1654   ), EIntOverflow (1655   ), EDivByZero (1653   ), ERangeError (1658   )



            76.39            ENoConstructException



            76.39.1          Description

            ENoConstructException  is  the  exception  raised  when  an  instance  of  type  TCharacter  is
            being created.  The TCharacter class only contains static methods, no instances of this class
            should be instantiated.



            76.40            ENoThreadSupport



            76.40.1          Description

            ENoThreadSupport is raised when some thread routines are invoked, and thread support was
            not enabled when the program was compiled.



            76.41            ENotImplemented



            76.41.1          Description

            ENotImplemented can be used to raise an exception when a particular call had been defined,
            but was not implemented.



            76.42            ENoWideStringSupport



            76.42.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.



            76.43            EOb jectCheck



            76.43.1          Description

            EObjectCheck  is  raised  when  the  -CR  (check  object  references)  command-line  option  or
            {$OBJECTCHECKS  ON}  directive  is  in  effect  and  a  Nil  reference  to  an  object  or  class  was
            encountered.


See also:    EAccessViolation (1652   )



                                                                            1656

            _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            76.44            EOSError



            76.44.1          Description

            EOSError  is  raised  when  some  Operating  System  call  fails.  The  ErrorCode  (??  )  property
            contains the operating system error code.


See also:    EOSError.ErrorCode (??  )



            76.45            EOutOfMemory



            76.45.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.


See also:    EHeapException (1504   ), EHeapMemoryError (1654   ), EInvalidPointer (1655   )



            76.46            EOverflow



            76.46.1          Description

            EOverflow occurs when a float operation overflows.  (i.e.  result is too big to represent).


See also:    EIntError (1654   ), EIntOverflow (1655   ), EDivByZero (1653   ), ERangeError (1658   ), EUnder-
            Flow (1658   )



            76.47            EPackageError



            76.47.1          Description

            EPackageError is not yet used by Free Pascal, and is provided for Delphi compatibility only.



            76.48            EPrivilege



            76.48.1          Description

            EPrivilege is raised when the OS reports that an invalid instruction was executed.



            76.49            EPropReadOnly



            76.49.1          Description

            EPropReadOnly is raised when an attempt is made to write to a read-only property.



            76.50            EPropWriteOnly



            76.50.1          Description

            EPropWriteOnly is raised when an attempt is made to read from a write-only property.



                                                                            1657

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    EPropReadOnly (1657   )



                76.51            ERangeError



                76.51.1          Description

                ERangeError is raised by the Free Pascal runtime library if range checking is on, and a range
                check error occurs.


    See also:    EIntError (1654   ), EDivByZero (1653   ), EIntOverflow (1655   )



                76.52            ESafecallException



                76.52.1          Description

                ESafecallException is not yet used by Free Pascal, and is provided for Delphi compatibility
                only.



                76.53            EStackOverflow



                76.53.1          Description

                EStackOverflow occurs when the stack has grown too big (e.g.  by infinite recursion).



                76.54            EUnderflow



                76.54.1          Description

                EOverflow occurs when a float operation underflows (i.e.  result is too small to represent).


    See also:    EIntError (1654   ), EIntOverflow (1655   ), EDivByZero (1653   ), ERangeError (1658   ), EOver-
                Flow (1657   )



                76.55            EVariantError



                76.55.1          Description

                EVariantError is raised by the internal variant routines.



                76.55.2          Method  overview

                __Page______Method______________Description________________________________________________________________________*
 *___________
                __1658______CreateCode__________Create_an_instance_of_EVariantError_with_a_particular_error_code.__________________*
 *___________



                76.55.3          EVariantError.CreateCode

    Synopsis:    Create an instance of  EVariantError with a particular error code.

Declaration:     constructor  CreateCode(Code:  LongInt)



                                                                                1658

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    Visibility:  default

Description:     CreateCode calls the inherited constructor, and sets the ErrCode (??  ) property to Code.

    See also:    ErrCode (??  )



                76.56            Exception



                76.56.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.


    See also:    ExceptObject (1555   ), ExceptAddr (1554   ), ExceptionErrorMessage (1555   ), ShowException
                (1612   ), Abort (1518   )



                76.56.2          Method  overview

                __Page______Method________________________Description______________________________________________________________*
 *___________
                  1659      Create                        Constructs a new exception object with a given message.
                  1660      CreateFmt                     Constructs a new exception object and formats a new mes-
                                                          sage.
                  1661      CreateFmtHelp                 Constructs a new exception object and sets the help context
                                                          and formats the message
                  1660      CreateHelp                    Constructs a new exception object and sets the help context.
                  1660      CreateRes                     Constructs  a  new  exception  object  and  gets  the  message
                                                          from a resource.
                  1660      CreateResFmt                  Constructs a new exception object and formats the message
                                                          from a reasource.
                  1661      CreateResFmtHelp              Constructs a new exception object and sets the help context
                                                          and formats the message from a resource
                  1661      CreateResHelp                 Constructs a new exception object and sets the help context
                                                          and gets the message from a resource
                __1661______ToString______________________Nicely_formatted_version_of_the_exception_message________________________*
 *___________



                76.56.3          Property  overview

                __Page______Properties____________Access______Description__________________________________________________________*
 *___________
                  1662      HelpContext           rw          Help context associated with the exception.
                __1662______Message_______________rw__________Message_associated_with_the_exception._______________________________*
 *___________



                76.56.4          Exception.Create

    Synopsis:    Constructs a new exception object with a given message.

Declaration:     constructor  Create(const  msg:  string)

    Visibility:   public



                                                                                1659

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   Construction may fail if there is not enough memory on the heap.

    See also:    Exception.CreateFmt (1660   ), Exception.Message (1662   )



                76.56.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 (1659   ), Exception.Message (1662   ), Format (1581   )



                76.56.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  (1659   ),  Exception.CreateFmt  (1660   ),  Exception.CreateResFmt  (1660   ),
                Exception.Message (1662   )



                76.56.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  (1660   ),  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  (1659   ),  Exception.CreateFmt  (1660   ),  Exception.CreateRes  (1660   ),  Ex-
                ception.Message (1662   )



                76.56.8          Exception.CreateHelp

    Synopsis:    Constructs a new exception object and sets the help context.

Declaration:     constructor  CreateHelp(const  Msg:  string;AHelpContext:  LongInt)

    Visibility:   public

Description:     CreateHelp does the same as the Create (1659   ) constructor, but additionally stores AHelpContext
                in the HelpContext (1662   ) property.

    See also:    Exception.Create (1659   )



                                                                                1660

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.56.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:  LongInt)

    Visibility:   public

Description:     CreateFmtHelp does the same as the CreateFmt (1660   ) constructor, but additionally stores
                AHelpContext in the HelpContext (1662   ) property.

    See also:    Exception.CreateFmt (1660   )



                76.56.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:  LongInt)

    Visibility:   public

Description:     CreateResHelp does the same as the CreateRes (1660   ) constructor, but additionally stores
                AHelpContext in the HelpContext (1662   ) property.

    See also:    Exception.CreateRes (1660   )



                76.56.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:  LongInt)

    Visibility:   public

Description:     CreateResFmtHelp does the same as the CreateResFmt (1660   ) constructor, but additionally
                stores AHelpContext in the HelpContext (1662   ) property.

    See also:    Exception.CreateResFmt (1660   )



                76.56.12           Exception.ToString

    Synopsis:    Nicely formatted version of the exception message

Declaration:     function  ToString  :  string;    Override

    Visibility:   public

Description:     ToString overrides the ToString method to return a concatenation of classname and Ex-
                ception.Message (1662   ).

    See also:    Exception.Message (1662   )



                                                                                1661

                _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                76.56.13           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 (1660   ), Exception.Message (1662   )



                76.56.14           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 (1612   ) routine, and should be set in the constructor when the exception
                is raised.

    See also:    Exception.Create (1659   ), Exception.HelpContext (1662   )



                76.57            EZeroDivide



                76.57.1          Description

                EZeroDivide occurs when a float division by zero occurs.

    See also:    EIntError (1654   ), EIntOverflow (1655   ), EDivByZero (1653   ), ERangeError (1658   )



                76.58            IReadWriteSync



                76.58.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.



                76.59            TMultiReadExclusiveWriteSynchronizer



                76.59.1          Description

                TMultiReadExclusiveWriteSynchronizer is a default implementation of the IReadWriteSync
                (1662   ) interface.  It uses a single mutex to protect access to the read/write resource, resulting
                in a single thread having access to the resource.

    See also:    IReadWriteSync (1662   )



                                                                                1662

            _______________________________________________________CHAPTER_76.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            76.59.2          Interfaces  overview

            __Page______Interfaces_________________Description_____________________________________________________________________*
 *_______
            __1662______IReadWriteSync_____________Read/Write_synchronizer_________________________________________________________*
 *_______



            76.60            TSimpleRWSync



            76.60.1          Description

            TSimpleRWSync implements a simple read/write locking mechanism.  It controls access to an
            object:  only a single thread is allowed access to an object for either read or write operations.

            Access is controlled through a single critical section.


See also:    TMultiReadExclusiveWriteSynchronizer (1662   )



            76.60.2          Interfaces  overview

            __Page______Interfaces_________________Description_____________________________________________________________________*
 *_______
            __1662______IReadWriteSync_____________Read/Write_synchronizer_________________________________________________________*
 *_______



                                                                            1663




Chapter   77



Reference   for   unit   'Types'



77.1          Overview


Starting with D6, types from Windows specific units that were needed in Kylix were extracted
to  this  unit.   So  it  mostly  contains  type  of  Windows  origin  that  are  needed  in  the  VCL
framework.



77.2          Constants,  types  and  variables



77.2.1         Constants

E_FAIL  =  ($80004005)


Defined for Delphi compatibility, this should not be used.


E_INVALIDARG  =  ($80070057)


Defined for Delphi compatibility, this should not be used.


GUID_NULL  :  TGUID  =  '{00000000-0000-0000-0000-000000000000}'


GUID_NULL is the definition of the NULL (empty) GUID.


LOCK_EXCLUSIVE  =  2


Defined for Delphi compatibility, this should not be used.


LOCK_ONLYONCE  =  4


Defined for Delphi compatibility, this should not be used.


LOCK_WRITE  =  1


Defined for Delphi compatibility, this should not be used.


STATFLAG_DEFAULT  =  0



                                                            1664

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



Defined for Delphi compatibility, this should not be used.


STATFLAG_NONAME  =  1


Defined for Delphi compatibility, this should not be used.


STATFLAG_NOOPEN  =  2


Defined for Delphi compatibility, this should not be used.


STGTY_LOCKBYTES  =  3


Defined for Delphi compatibility, this should not be used.


STGTY_PROPERTY  =  4


Defined for Delphi compatibility, this should not be used.


STGTY_STORAGE  =  1


Defined for Delphi compatibility, this should not be used.


STGTY_STREAM  =  2


Defined for Delphi compatibility, this should not be used.


STG_E_ABNORMALAPIEXIT  =  ($800300FA)


Defined for Delphi compatibility, this should not be used.


STG_E_ACCESSDENIED  =  ($80030005)


Defined for Delphi compatibility, this should not be used.


STG_E_BADBASEADDRESS  =  ($80030110)


Defined for Delphi compatibility, this should not be used.


STG_E_CANTSAVE  =  ($80030103)


Defined for Delphi compatibility, this should not be used.


STG_E_DISKISWRITEPROTECTED  =  ($80030013)


Defined for Delphi compatibility, this should not be used.


STG_E_DOCFILECORRUPT  =  ($80030109)


Defined for Delphi compatibility, this should not be used.


STG_E_EXTANTMARSHALLINGS  =  ($80030108)



                                                                1665

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



Defined for Delphi compatibility, this should not be used.


STG_E_FILEALREADYEXISTS  =  ($80030050)


Defined for Delphi compatibility, this should not be used.


STG_E_FILENOTFOUND  =  ($80030002)


Defined for Delphi compatibility, this should not be used.


STG_E_INCOMPLETE  =  ($80030201)


Defined for Delphi compatibility, this should not be used.


STG_E_INSUFFICIENTMEMORY  =  ($80030008)


Defined for Delphi compatibility, this should not be used.


STG_E_INUSE  =  ($80030100)


Defined for Delphi compatibility, this should not be used.


STG_E_INVALIDFLAG  =  ($800300FF)


Defined for Delphi compatibility, this should not be used.


STG_E_INVALIDFUNCTION  =  ($80030001)


Defined for Delphi compatibility, this should not be used.


STG_E_INVALIDHANDLE  =  ($80030006)


Defined for Delphi compatibility, this should not be used.


STG_E_INVALIDHEADER  =  ($800300FB)


Defined for Delphi compatibility, this should not be used.


STG_E_INVALIDNAME  =  ($800300FC)


Defined for Delphi compatibility, this should not be used.


STG_E_INVALIDPARAMETER  =  ($80030057)


Defined for Delphi compatibility, this should not be used.


STG_E_INVALIDPOINTER  =  ($80030009)


Defined for Delphi compatibility, this should not be used.


STG_E_LOCKVIOLATION  =  ($80030021)



                                                                1666

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



Defined for Delphi compatibility, this should not be used.


STG_E_MEDIUMFULL  =  ($80030070)


Defined for Delphi compatibility, this should not be used.


STG_E_NOMOREFILES  =  ($80030012)


Defined for Delphi compatibility, this should not be used.


STG_E_NOTCURRENT  =  ($80030101)


Defined for Delphi compatibility, this should not be used.


STG_E_OLDDLL  =  ($80030105)


Defined for Delphi compatibility, this should not be used.


STG_E_OLDFORMAT  =  ($80030104)


Defined for Delphi compatibility, this should not be used.


STG_E_PATHNOTFOUND  =  ($80030003)


Defined for Delphi compatibility, this should not be used.


STG_E_PROPSETMISMATCHED  =  ($800300F0)


Defined for Delphi compatibility, this should not be used.


STG_E_READFAULT  =  ($8003001E)


Defined for Delphi compatibility, this should not be used.


STG_E_REVERTED  =  ($80030102)


Defined for Delphi compatibility, this should not be used.


STG_E_SEEKERROR  =  ($80030019)


Defined for Delphi compatibility, this should not be used.


STG_E_SHAREREQUIRED  =  ($80030106)


Defined for Delphi compatibility, this should not be used.


STG_E_SHAREVIOLATION  =  ($80030020)


Defined for Delphi compatibility, this should not be used.


STG_E_TERMINATED  =  ($80030202)



                                                                1667

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



Defined for Delphi compatibility, this should not be used.


STG_E_TOOMANYOPENFILES  =  ($80030004)


Defined for Delphi compatibility, this should not be used.


STG_E_UNIMPLEMENTEDFUNCTION  =  ($800300FE)


Defined for Delphi compatibility, this should not be used.


STG_E_UNKNOWN  =  ($800300FD)


Defined for Delphi compatibility, this should not be used.


STG_E_WRITEFAULT  =  ($8003001D)


Defined for Delphi compatibility, this should not be used.


STG_S_BLOCK  =  $00030201


Defined for Delphi compatibility, this should not be used.


STG_S_CONVERTED  =  $00030200


Defined for Delphi compatibility, this should not be used.


STG_S_MONITORING  =  $00030203


Defined for Delphi compatibility, this should not be used.


STG_S_RETRYNOW  =  $00030202


Defined for Delphi compatibility, this should not be used.


STREAM_SEEK_CUR  =  1


Defined for Delphi compatibility, this should not be used.


STREAM_SEEK_END  =  2


Defined for Delphi compatibility, this should not be used.


STREAM_SEEK_SET  =  0


Defined for Delphi compatibility, this should not be used.



                                                                1668

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



77.2.2         Types

ArgList  =  Pointer


ArgList is defined for Delphi/Kylix compatibility and should not be used.


DWORD  =  LongWord


Alias for cardinal type


FILETIME  =  _FILETIME


Alias for the _FILETIME type


Largeint  =  Int64


Largeint  is  an  alias  for  the  Int64  type  defined  in  the  system  unit.   This  is  an  alias  for
Delphi/Kylix compatibility.


LargeUint  =  QWord


LargeUInt  is  an  alias  for  the  QWord  type  defined  in  the  system  unit.  This  is  an  alias  for
Delphi/Kylix compatibility.


LARGE_INT  =  Largeint


LARGE_INT  is  an  alias  for  the  Int64  type  defined  in  the  system  unit.   This  is  an  alias  for
Delphi/Kylix compatibility.


LARGE_UINT  =  LargeUint


LARGE_UINT is an alias for the QWord type defined in the system unit.  This is an alias for
Delphi/Kylix compatibility.


PByte  =  System.PByte


PByte is defined in the system unit.  This is an alias for Delphi/Kylix compatibility.


PCLSID  =  PGUID


PCLSID is a pointer to a TCLSID type.


PDisplay  =  Pointer


PDisplay is defined for Delphi/Kylix compatibility and should not be used.


PDouble  =  System.PDouble


PDouble is defined in the system unit.  This is an alias for Delphi/Kylix compatibility.


PDWord  =  ^DWORD



                                                                1669

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



PDWord is equivalent to the PCardinal type.


PEvent  =  Pointer


PEvent is defined for Delphi/Kylix compatibility and should not be used.


PFileTime  =  ^TFileTime


Pointer to TFileTime type


PLargeInt  =  ^Largeint


PLargeInt is an alias for the PInt64 type defined in the system unit.  This is an alias for
Delphi/Kylix compatibility.


PLargeuInt  =  ^LargeUint


PLargeUInt is an alias for the PQWord type defined in the system unit.  This is an alias for
Delphi/Kylix compatibility.


PLongint  =  System.PLongint


PLongint is defined in the system unit.  This is an alias for Delphi/Kylix compatibility.


POleStr  =  PWideChar


POleStr is a pointer to a (double) null-terminated array of  TOleChar characters.


PPoint  =  ^TPoint


PPoint is a typed pointer to the TPoint (1673   ) type.


PPOleStr  =  ^POleStr


PPOleStr is a typed pointer to a POleStr variable.


PRect  =  ^TRect


PRect is a typed pointer to the TRect (1674   ) type.


PSize  =  ^TSize


PSize is a typed pointer to the TSize (1674   ) type.


PSmallInt  =  System.PSmallInt


PSmallInt is defined in the system unit.  This is an alias for Delphi/Kylix compatibility.


PSmallPoint  =  ^TSmallPoint


PSmallPoint is a typed pointer to the TSmallPoint (1674   ) record.



                                                                1670

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



PStatStg  =  ^TStatStg


Pointer to TStatStg record.


PXrmOptionDescRec  =  ^TXrmOptionDescRec


PXrmOptionDescRec is defined for Delphi/Kylix compatibility and should not be used.


Region  =  Pointer


Region is defined for Delphi/Kylix compatibility and should not be used.


STATSTG  =  TStatStg


Alias for the TStatStg type.


tagPOINT  =  TPoint


tagPOINT is a simple alias for TPoint (1673   )


tagSIZE  =  TSize


tagSize is an alias for the TSize (1674   ) type.


tagSTATSTG  =  record
   pwcsName  :  POleStr;
   dwType  :  DWORD;
   cbSize  :  LARGE_UINT;
   mtime  :  TFileTime;
   ctime  :  TFileTime;
   atime  :  TFileTime;
   grfMode  :  DWORD;
   grfLocksSupported  :  DWORD;
   clsid  :  TCLSID;
   grfStateBits  :  DWORD;
   reserved  :  DWORD;
end



tagSTATSTG is used in the IStream.Stat (1682   ) call.  It describes a storage medium (typically
a file).


TBooleanDynArray  =  Array  of  Boolean


TBooleanDynArray is a standard definition of a dynamical array of booleans.


TByteDynArray  =  Array  of  Byte


TByteDynArray is a standard definition of a dynamical array of (8-bit, unsigned) bytes.


TCardinalDynArray  =  Array  of  Cardinal



                                                                1671

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



TCardinalDynArray is a standard definition of a dynamical array of (32-bit, unsigned) car-
dinals.


TCLSID  =  TGUID


TCLSID is an alias for the #rtl.system.TGUID (1283   ) type.


TDoubleDynArray  =  Array  of  Double


TSoubleDynArray is a standard definition of a dynamical array of doubles.  (regular floating
point type)


TDuplicates  =  (dupIgnore,dupAccept,dupError)



                          Table 77.1:  Enumeration values for type TDuplicates


           __Value_____________Explanation__________________________________________________________________________
             dupAccept          Accept duplicates, adding them to the list.
             dupError           Raise an error when an attempt is made to add a duplicate.
             dupIgnore          Ignore the new item, do not add it to the list.



TDuplicates can be used to indicate how a list structure acts on the addition of a duplicate
item to the list.


dupIgnore        Ignore the new item, do not add it to the list.

dupAccept         Accept duplicates, adding them to the list.

dupError        Raise an error when an attempt is made to add a duplicate.


TFileTime  =  _FILETIME


Alias for the _FILETIME type


TInt64DynArray  =  Array  of  Int64


TInt64DynArray is a standard definition of a dynamical array of (64-bit, signed) int64s.


TIntegerDynArray  =  Array  of  Integer


TIntegerDynArray is a standard definition of a dynamical array of (32-bit, signed) integers.


TListCallback  =  procedure(data:  pointer;arg:  pointer)  of  object


TListCallback is the prototype for a Foreach operation on a list.  It will be called with as
Data the pointer in the list, and Arg will contain the extra user data added to the Foreach
call.  It can be used in methods of objects; for a version that can be used as a global procedure,
see TListStaticCallback (1673   )


TListStaticCallback  =  procedure(data:  pointer;arg:  pointer)



                                                                1672

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



TListStaticCallback is the prototype for a Foreach operation on a list.  It will be called
with as Data the pointer in the list, and Arg will contain the extra user data added to the
Foreach call.  It can be used in plain procedures; for a version that can be used as a method,
see TListCallback (1672   )


TLongWordDynArray  =  Array  of  LongWord


TLongWordDynArray is a standard definition of a dynamical array of (32-bit, unsigned) Long-
Words.


TOleChar  =  WideChar


TOleChar is an alias for the WideChar type, defined in the system unit.


TPoint  =  packed  record
   X  :  LongInt;
   Y  :  LongInt;
end



TPoint is a generic definition of a point in a 2-dimensional discrete plane, where X indicates
the  horizontal  position,  and  Y  the  vertical  position  (positions  usually  measured  in  pixels),
and 0,0 is the origin of the plane.

Usually,  the  origin  is  the  upper-left  corner  of  the  screen,  with  Y  increasing  as  one  moves
further down the screen - this is opposite to the mathematical view where Y increases as one
moves upwards.

The coordinates are integers, (32-bit, signed) so the coordinate system runs from -MaxInt
to MaxInt.


TPointerDynArray  =  Array  of  Pointer


Dynamic array of untyped pointers


TQWordDynArray  =  Array  of  QWord


TQWordDynArray is a standard definition of a dynamical array of (64-bit, unsigned) QWords.


TRect  =  packed  record
case  Integer  of
0:  (
   Left  :  LongInt;
   Top  :  LongInt;
   Right  :  LongInt;
   Bottom  :  LongInt;
);
1:  (
   TopLeft  :  TPoint;
   BottomRight  :  TPoint;
);
end



                                                                1673

____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



TRect defines a rectangle in a discrete plane.  It is described by the horizontal (left, right)
or vertical (top, Bottom) positions (in pixels) of the edges, or, alternatively, by the coordi-
nates of the top left (TopLeft) and bottom right (BottomRight) corners.


TShortIntDynArray  =  Array  of  ShortInt


TShortintDynArray is a standard definition of a dynamical array of (8-bit, signed) shortints.


TSingleDynArray  =  Array  of  Single


TSingleDynArray is a standard definition of a dynamical array of singles.  (smallest floating
point type)


TSize  =  packed  record
   cx  :  LongInt;
   cy  :  LongInt;
end



TSize is a type to describe the size of a rectangular area, where cx is the width, cy is the
height (in pixels) of the rectangle.


TSmallIntDynArray  =  Array  of  SmallInt


TSmallintDynArray is a standard definition of a dynamical array of (16-bit, unsigned) inte-
gers.


TSmallPoint  =  packed  record
   x  :  SmallInt;
   y  :  SmallInt;
end



TSmallPoint  defines  a  point  in  a  2-dimensional  plane,  just  like  TPoint  (1673   ),  but  the
coordinates  have  a  smaller  range:  The  coordinates  are  smallints  (16-bit,  signed)  and  they
run from -MaxSmallInt to maxSmallint.


TStatStg  =  tagSTATSTG


TStatStg is a record type describing a storage medium.  It is uses in the IStream.Stat (1682   )
function.


TStringDynArray  =  Array  of  AnsiString


TStringDynArray is a standard definition of a dynamical array of Ansistrings.


TWideStringDynArray  =  Array  of  WideString


TWideStringDynArray is a standard definition of a dynamical array of WideStrings.


TWordDynArray  =  Array  of  Word



                                                                1674

                ____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                TWordDynArray is a standard definition of a dynamical array of (16-bit, unsigned) words.


                TXrmOptionDescRec  =  record
                end



                TXrmOptionDescRec is defined for Delphi/Kylix compatibility and should not be used.


                Widget  =  Pointer


                Widget is defined for Delphi/Kylix compatibility and should not be used.


                WidgetClass  =  Pointer


                WidgetClass is defined for Delphi/Kylix compatibility and should not be used.


                XrmOptionDescRec  =  TXrmOptionDescRec


                XrmOptionDescRec is defined for Delphi/Kylix compatibility and should not be used.


                _FILETIME  =  packed  record
                   dwLowDateTime  :  DWORD;
                   dwHighDateTime  :  DWORD;
                end



                _FILETIME describes a file time stamp.  It is defined or Delphi/Kylix compatibility and should
                not be used except when implementing or accessing the IStream interface.  The TDateTime
                type should be used instead.



                77.3          Procedures  and  functions



                77.3.1         Bounds

    Synopsis:    Create a rectangle, given a position and size

Declaration:     function  Bounds(ALeft:  Integer;ATop:  Integer;AWidth:  Integer;
                                         AHeight:  Integer)  :  TRect

    Visibility:   default

Description:     Bounds returns a TRect structure with the indicated position (Left=ALeft and Top=ATop)
                and size (Right=ALeft+AWidth and Bottom=ATop+AHeight)

    See also:    Rect (1677   ), PtInRect (1677   ), IntersectRect (1676   ), UnionRect (1678   )



                77.3.2         CenterPoint

    Synopsis:    Return the center point of a rectangle

Declaration:     function  CenterPoint(const  Rect:  TRect)  :  TPoint

    Visibility:   default

Description:     CenterPoint returns the center point of the rectangle Rect.

    See also:    PtinRect (1677   ), IntersectRect (1676   ), IsRectEmpty (1676   ), OffsetRect (1677   ), InflateRect
                (1676   ), Size (1678   ), IsRectEmpty (1676   )



                                                                                1675

                ____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                77.3.3         EqualRect

    Synopsis:    Check if two rectangles are equal.

Declaration:     function  EqualRect(const  r1:  TRect;const  r2:  TRect)  :  Boolean

    Visibility:   default

Description:     EqualRect returns True if the rectangles R1 and R2 are equal (i.e.  have the position and
                size).  If the rectangles differ, the function returns False

    See also:    Rect (1677   ), Bounds (1675   ), PtInRect (1677   ), IntersectRect (1676   ), UnionRect (1678   ), Is-
                RectEmpty (1676   ), OffsetRect (1677   ), InflateRect (1676   ), Size (1678   )



                77.3.4         InflateRect

    Synopsis:    Increase the rectangle in size, keeping it centered

Declaration:     function  InflateRect(var  Rect:  TRect;dx:  Integer;dy:  Integer)  :  Boolean

    Visibility:   default

Description:     InflateRect inflates the rectangle horizontally with dx pixels on each side, and vertically
                with  dy  pixels,  thus  keeping  its  center  point  on  the  same  location.  It  returns  true  if  the
                operation was succesfully, False if it was not (only possible if the address of  Rect is Nil).

    See also:    PtinRect (1677   ), IntersectRect (1676   ), IsRectEmpty (1676   ), OffsetRect (1677   ), CenterPoint
                (1675   ), Size (1678   ), IsRectEmpty (1676   )



                77.3.5         IntersectRect

    Synopsis:    Return the intersection of 2 rectangles

Declaration:     function  IntersectRect(var  Rect:  TRect;const  R1:  TRect;const  R2:  TRect)
                                                      :  Boolean

    Visibility:   default

Description:     IntersectRect returns the intersection of the 2 rectangles R1 and R2 in Rect.  It returns
                True if the 2 rectangles have an intersection, otherwise False is returned, and Rect is filled
                with zero.

    See also:    PtinRect  (1677   ),  UnionRect  (1678   ),  IsRectEmpty  (1676   ),  OffsetRect  (1677   ),  InflateRect
                (1676   ), Size (1678   )



                77.3.6         IsRectEmpty

    Synopsis:    Check whether a rectangle is empty

Declaration:     function  IsRectEmpty(const  Rect:  TRect)  :  Boolean

    Visibility:   default

Description:     IsRectEmpty  returns  true  if  the  rectangle  is  empty,  i.e.  has  a  zero  or  negative  width  or
                height.

    See also:    PtinRect (1677   ), IntersectRect (1676   ), IsRectEmpty (1676   ), OffsetRect (1677   ), InflateRect
                (1676   ), Size (1678   )



                                                                                1676

                ____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                77.3.7         OffsetRect

    Synopsis:    Offset the rectangle

Declaration:     function  OffsetRect(var  Rect:  TRect;DX:  Integer;DY:  Integer)  :  Boolean

    Visibility:   default

Description:     OffsetRect offsets the rectangle Rect by a horizontal distance DX and a vertical distance
                DY.  The  operation  returns  True  if  the  operation  was  successfull,  false  if  it  was  not  (only
                possible if the address of  Rect is Nil).

    See also:    PtinRect (1677   ), IntersectRect (1676   ), IsRectEmpty (1676   ), OffsetRect (1677   ), InflateRect
                (1676   ), Size (1678   ), IsRectEmpty (1676   )



                77.3.8         Point

    Synopsis:    Create a point

Declaration:     function  Point(x:  Integer;y:  Integer)  :  TPoint

    Visibility:   default

Description:     Point returns a TPoint structure with the given position (X,  Y).

    See also:    Rect (1677   ), PtInRect (1677   )



                77.3.9         PtInRect

    Synopsis:    Check whether a point is inside a rectangle.

Declaration:     function  PtInRect(const  Rect:  TRect;const  p:  TPoint)  :  Boolean

    Visibility:   default

Description:     PtInRect  returns  True  if  p  is  located  inside  Rect,  and  False  if  it  is  located  outside  the
                rectangle.

 Remark:         Note that the bottom, right edges are not considered part of the rectangle, therefor a point
                located on one of these edges will not be considered part of the rectangle, meaning that for
                a  record  (10,10,100,100)  the  point  (90,100)  will  not  be  considered  part  of  the  record,  but
                90,10 will be.

    See also:    IntersectRect (1676   ), UnionRect (1678   ), IsRectEmpty (1676   ), OffsetRect (1677   ), InflateRect
                (1676   ), Size (1678   )



                77.3.10          Rect

    Synopsis:    Create a rectangle record

Declaration:     function  Rect(Left:  Integer;Top:  Integer;Right:  Integer;Bottom:  Integer)
                                       :  TRect

    Visibility:   default

Description:     Rect  returns  a  rectangle  structure  with  the  4  members  Left,  Top,  Right  and  Bottom  as
                passed in the arguments.

    See also:    Bounds  (1675   ),  PtInRect  (1677   ),  IntersectRect  (1676   ),  UnionRect  (1678   ),  IsRectEmpty
                (1676   ), OffsetRect (1677   ), InflateRect (1676   ), Size (1678   )



                                                                                1677

                ____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                77.3.11          Size

    Synopsis:    Return the size of the rectangle

Declaration:     function  Size(AWidth:  Integer;AHeight:  Integer)  :  TSize
                function  Size(const  ARect:  TRect)  :  TSize

    Visibility:   default

Description:     Size  returns  a  TSize  record  with  the  indicated  AWidth,  AHeight.  In  the  case  ARect  is
                passed, the width and height are calculated (taking into account that the right, bottom are
                not considered part of the rectangle).

    See also:    PtinRect (1677   ), IntersectRect (1676   ), IsRectEmpty (1676   ), OffsetRect (1677   ), InflateRect
                (1676   ), CenterPoint (1675   ), IsRectEmpty (1676   )



                77.3.12          UnionRect

    Synopsis:    Return the union of 2 rectangles.

Declaration:     function  UnionRect(var  Rect:  TRect;const  R1:  TRect;const  R2:  TRect)
                                                :  Boolean

    Visibility:   default

Description:     UnionRect retuns the rectangle that encompasses both R1 and R2 in Rect.  It returns True
                if the resulting rectangle is not empty, False if the result is an empty rectangle (in which
                case the result is filled with zeroes)

    See also:    PtinRect (1677   ), IntersectRect (1676   ), IsRectEmpty (1676   ), OffsetRect (1677   ), InflateRect
                (1676   ), Size (1678   )



                77.4          IClassFactory



                77.4.1         Description

                IClassFactory is defined for Delphi/Kylix compatibility and should not be used.



                77.4.2         Method  overview

                __Page______Method___________________Description___________________________________________________________________*
 *___________
                  1678      CreateInstance           Create a new instance of an interface.
                __1679______LockServer_______________Lock_ActiveX_server_object.___________________________________________________*
 *___________



                77.4.3         IClassFactory.CreateInstance

    Synopsis:    Create a new instance of an interface.

Declaration:     function  CreateInstance(const  unkOuter:  IUnknown;const  riid:  TGUID;
                                                      out  vObject)  :  HResult

    Visibility:   default

Description:     IClassFactory.CreateInstance is defined for Delphi/Kylix compatibility and should not
                be used.



                                                                                1678

                ____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                77.4.4         IClassFactory.LockServer

    Synopsis:    Lock ActiveX server object.

Declaration:     function  LockServer(fLock:  LongBool)  :  HResult

    Visibility:   default

Description:     IClassFactory.LocksServer is defined for Delphi/Kylix compatibility and should not be
                used.



                77.5          ISequentialStream



                77.5.1         Description

                ISequentialStream  is  the  interface  for  streams  which  only  support  sequential  reading  of
                chunks of data.  It is defined for Delphi/Kylix compatibility and should not be used.


    See also:    IStream (1680   )



                77.5.2         Method  overview

                __Page______Method_________Description_____________________________________________________________________________*
 *___________
                  1679      Read           Read data from the stream
                __1679______Write__________Write_data_to_the_stream________________________________________________________________*
 *___________



                77.5.3         ISequentialStream.Read

    Synopsis:    Read data from the stream

Declaration:     function  Read(pv:  Pointer;cb:  DWORD;pcbRead:  PDWord)  :  HRESULT

    Visibility:   default

Description:     Read reads cbCount bytes from the stream into the memory pointed to by pv and returns
                the number of bytes read in pcbread.  The result is zero for success or an error code.

    See also:    ISequentialStream.Write (1679   )



                77.5.4         ISequentialStream.Write

    Synopsis:    Write data to the stream

Declaration:     function  Write(pv:  Pointer;cb:  DWORD;pcbWritten:  PDWord)  :  HRESULT

    Visibility:   default

Description:     Write writes cbCount bytes from the memory pointed to by pv to the stream and returns
                the number of bytes written in pcbwritten.  The result is zero for success or an error code.

    See also:    ISequentialStream.Read (1679   )



                                                                                1679

                ____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                77.6          IStream



                77.6.1         Description

                An  abstract  interface  for  an  external  (non  pascal)  stream,  as  defined  in  Microsoft  COM
                interfaces



                77.6.2         Method  overview

                __Page______Method_________________Description_____________________________________________________________________*
 *___________
                  1682      Clone                  Clone the stream instance
                  1681      Commit                 Commit data to the stream
                  1680      CopyTo                 Copy data from one stream to another
                  1681      LockRegion             Lock a region of bytes in the stream
                  1681      Revert                 Revert changes
                  1680      Seek                   Set the stream position
                  1680      SetSize                Set the stream size
                  1682      Stat                   return information about the stream.
                __1681______UnlockRegion___________Unlocks_a_previously_locked_region_of_bytes_in_the_stream_______________________*
 *___________



                77.6.3         IStream.Seek

    Synopsis:    Set the stream position

Declaration:     function  Seek(dlibMove:  Largeint;dwOrigin:  LongInt;
                                      out  libNewPosition:  Largeint)  :  HResult

    Visibility:   default

Description:     Seek  sets  the  stream  position  at  dlibMove  bytes  from  dwOrigin  (one  of  the  SEEK_*  con-
                stants) and returns the new absolute position in libNewPosition.  The function returns zero
                on success, or an error code.

       Errors:   On error, a nonzero exit code is returned.



                77.6.4         IStream.SetSize

    Synopsis:    Set the stream size

Declaration:     function  SetSize(libNewSize:  Largeint)  :  HRESULT

    Visibility:   default

Description:     SetSize sets the size of the stream to libNewSize bytes, if the stream allows it.  On sucess,
                zero is returned.

       Errors:   On error, a nonzero exit code is returned.



                77.6.5         IStream.CopyTo

    Synopsis:    Copy data from one stream to another

Declaration:     function  CopyTo(stm:  IStream;cb:  Largeint;out  cbRead:  Largeint;
                                         out  cbWritten:  Largeint)  :  HRESULT

    Visibility:   default



                                                                                1680

                ____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



Description:     CopyTo copies cb bytes from the stream to target stream stm.  cbRead returns how many
                bytes were read from the stream, cbwrite returns how many bytes were actually written to
                the destination stream.  The function returns zero on success.

       Errors:   On error, a nonzero exit code is returned.



                77.6.6         IStream.Commit

    Synopsis:    Commit data to the stream

Declaration:     function  Commit(grfCommitFlags:  LongInt)  :  HRESULT

    Visibility:   default

Description:     Commit commits the data in the stream to the underlying medium.  Flags is a set of options
                to control the commit operation (see MSDN for the possible flags).

       Errors:   On error, a nonzero exit code is returned.



                77.6.7         IStream.Revert

    Synopsis:    Revert changes

Declaration:     function  Revert  :  HRESULT

    Visibility:   default

Description:     Revert reverts all changes that were done to a transacted stream, i.e.  all changes since the
                last commit.  The function returns zero on success.

       Errors:   On error, a nonzero exit code is returned.



                77.6.8         IStream.LockRegion

    Synopsis:    Lock a region of bytes in the stream

Declaration:     function  LockRegion(libOffset:  Largeint;cb:  Largeint;
                                                dwLockType:  LongInt)  :  HRESULT

    Visibility:   default

Description:     LockRegion locks a region of the storage, starting at libOffset, for cbCount bytes.  The
                applied  lock  is  of  type  dwLockType.  The  function  returns  zero  if  the  lock  was  succesfully
                applied.

       Errors:   On error, a nonzero exit code is returned.



                77.6.9         IStream.UnlockRegion

    Synopsis:    Unlocks a previously locked region of bytes in the stream

Declaration:     function  UnlockRegion(libOffset:  Largeint;cb:  Largeint;
                                                   dwLockType:  LongInt)  :  HRESULT

    Visibility:   default



                                                                                1681

                ____________________________________________________________CHAPTER_77.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



Description:     UnlockRegion  removes  the  lock  on  a  region  of  the  storage,  starting  at  libOffset,  for
                cbCount bytes.  The lock must be of type dwLockType.  The function returns zero if the lock
                was succesfully removed.

       Errors:   On error, a nonzero exit code is returned.



                77.6.10          IStream.Stat

    Synopsis:    return information about the stream.

Declaration:     function  Stat(out  statstg:  TStatStg;grfStatFlag:  LongInt)  :  HRESULT

    Visibility:   default

Description:     Stat  returns  information  about  the  stream  in  statstg,  taking  into  account  the  flags  in
                grfStatFlag  (one  of  the  STATFLAG_  constants).  The  function  returns  zero  if  the  call  was
                successful.

       Errors:   On error, a nonzero exit code is returned.



                77.6.11          IStream.Clone

    Synopsis:    Clone the stream instance

Declaration:     function  Clone(out  stm:  IStream)  :  HRESULT

    Visibility:   default

Description:     Clone returns an independent but initially equal copy of the stream in stm.  The function
                returns zero if the call was successful.

       Errors:   On error, a nonzero exit code is returned.



                                                                                1682




Chapter   78



Reference   for   unit   'typinfo'



78.1          Used  units



                                    Table 78.1:  Used units by unit 'typinfo'


                                                   __Name__________Page_____
                                                     System        1235
                                                     sysutils      1489



78.2          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
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 auxiliary unit, which contains an object that has
a published property for all supported types.  It also contains some auxiliary routines and
definitions.  This unit is included in the documentation sources, in the directory typinfex.



78.3          Auxiliary  functions


Other typinfo related functions.



                                                            1683

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



                                                       Table 78.2:



__Name_______________________________________Description___________________________________________________________________________*
 *____
  GetEnumName (1701   )                      Get an enumerated type element name
  GetEnumValue (1703   )                     Get ordinal number of an enumerated type, based on the name.
  GetEnumNameCount (1702   )                 Get number of elements in an enumerated type.
  GetTypeData (1715   )                      Skip type name and return a pointer to the type data
  SetToString (1725   )                      Convert a set to its string representation
  StringToSet (1727   )                      Convert a string representation of a set to a set



78.4          Getting  or  setting  property  values


Functions to set or set a property's value.



                                                       Table 78.3:

         __Name________________________________Description____________________________________________________________
           GetEnumProp (1702   )                Return the value of an enumerated type property
           GetFloatProp (1703   )               Return the value of a float property
           GetInt64Prop (1704   )               Return the value of an Int64 property
           GetMethodProp (1705   )              Return the value of a procedural type property
           GetObjectProp (1707   )              Return the value of an object property
           GetOrdProp (1709   )                 Return the value of an ordinal type property
           GetPropValue (1713   )               Return the value of a property as a variant
           GetSetProp (1713   )                 Return the value of a set property
           GetStrProp (1714   )                 Return the value of a string property
           GetWideStrProp (1716   )             Return the value of a widestring property
           GetVariantProp (1716   )             Return the value of a variant property
           SetEnumProp (1720   )                Set the value of an enumerated type property
           SetFloatProp (1720   )               Set the value of a float property
           SetInt64Prop (1721   )               Set the value of an Int64 property
           SetMethodProp (1722   )              Set the value of a procedural type property
           SetObjectProp (1722   )              Set the value of an object property
           SetOrdProp (1723   )                 Set the value of an ordinal type property
           SetPropValue (1723   )               Set the value of a property trhough a variant
           SetSetProp (1724   )                 Set the value of a set property
           SetStrProp (1724   )                 Set the value of a string property
           SetWideStrProp (1726   )             Set the value of a widestring property
           SetVariantProp (1726   )             Set the value of a variant property



78.5          Examining  published  property  information


Functions for retrieving or examining property information



                                                                1684

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



                                                       Table 78.4:

  _Name______________________________________Description______________________________________________________________________
    FindPropInfo (1700   )                    Getting property type information, With error checking.
    GetPropInfo (1710   )                     Getting property type information, No error checking.
    GetPropInfos (1710   )                    Find property information of a certain kind
    GetObjectPropClass (1708   )              Return the declared class of an object property
    GetPropList (1711   )                     Get a list of all published properties
    IsPublishedProp (1717   )                 Is a property published
    IsStoredProp (1717   )                    Is a property stored
    PropIsType (1718   )                      Is a property of a certain kind
    PropType (1719   )                        Return the type of a property



78.6          Constants,  types  and  variables



78.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 (1713   ) function.


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 (1716   ) 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 (1723   ) 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 (1716   ) function.


ptConst  =  3


Constant used in acces method


ptField  =  0



                                                                1685

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



Property acces directly from field


ptStatic  =  1


Property acces via static method


ptVirtual  =  2


Property acces via virtual method


tkAny  =  [(TTypeKind)..(TTypeKind)]


Any property type


tkMethods  =  [tkMethod]


Only method properties.  (event handlers)


tkProcedure  =  tkProcVar


Procedure kind


tkProperties  =  tkAny  -  tkMethods  -  [tkUnknown]


Real properties.  (not methods)


tkString  =  tkSString


Alias for the tsSString enumeration value



78.6.2         Types

PManagedField  =  ^TManagedField


PManagedField is a pointer to TManagedField (1689   ).  It is used to describe automatically
managed fields in records when the type kind is tkRecord.


PProcedureParam  =  ^TProcedureParam


PProcedureParam  is  a  pointer  to  TProcedureParam.   It  is  used  in  TProcedureSignature
(1727   ).


PPropInfo  =  ^TPropInfo


Pointer to TPropInfo (1691   ) record


PPropList  =  ^TPropList


Pointer to TPropList (1691   )


PPTypeInfo  =  ^PTypeInfo



                                                                1686

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



Pointer to PTypeInfo (1687   ) pointer


PTypeData  =  ^TTypeData


Pointer to TTypeData (1698   ) record.


PTypeInfo  =  ^TTypeInfo


Pointer to TTypeInfo (1698   ) record


PVmtFieldEntry  =  ^TVmtFieldEntry


Pointer to #rtl.typinfo.TVmtFieldEntry (1699   ) type.


PVmtFieldTable  =  ^TVmtFieldTable


Pointer to #rtl.typinfo.TVmtFieldTable (1700   ) type.


ShortStringBase  =  string


ShortStringBase is the base definition of a short string.


TArrayTypeData  =  packed  record
   Size  :  SizeInt;
   ElCount  :  SizeInt;
   ElType  :  PTypeInfo;
   DimCount  :  Byte;
   Dims  :  Array[0..255]  of  PTypeInfo;
end



TArrayTypeData is used to describe arrays in RTTI. It can be encountered when the type kind
is tkArray, and is used for both static and dynamic arrays and single or multi-dimensional
arrays.  The type of the array elements is described in elType,  and the ranges for each of
the dimensions (specified in DimCount in Dims.


TCallConv  =  (ccReg,ccCdecl,ccPascal,ccStdCall,ccSafeCall,ccCppdecl,
                     ccFar16,ccOldFPCCall,ccInternProc,ccSysCall,ccSoftFloat,
                     ccMWPascal)



                           Table 78.5:  Enumeration values for type TCallConv


              __Value__________________Explanation_______________________________________________________________
                ccCdecl                 Cdecl calling convention.
                ccCppdecl               Cppdecl calling convention
                ccFar16                 Far16 calling convention (Delphi compatibility)
                ccInternProc            InternProc calling convention (compiler internal)
                ccMWPascal              MWPascal (MetroWerks Pascal) calling convention.
                ccOldFPCCall            OldFPCCall calling convention (deprecated)
                ccPascal                Pascal calling convention.
                ccReg                   Register calling convention
                ccSafeCall              SafeCall calling convention.
                ccSoftFloat             Softfloat calling convention.
                ccStdCall               stdcall calling convention.
                ccSysCall               SysCall calling convention.



                                                                1687

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



TCallConv  is  a  type  describing  the  calling  convention  used  by  a  method.   It  contains  an
element for all supported calling conventions.


TFloatType  =  (ftSingle,ftDouble,ftExtended,ftComp,ftCurr)



                          Table 78.6:  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



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.


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 78.7:  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  TIntfFlag


Set of TIntfFlag (1688   ).


TIntfFlagsBase  =  Set  of  TIntfFlag



                                                                1688

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



Set of TIntfFlag (1688   ).


TManagedField  =  packed  record
   TypeRef  :  PTypeInfo;
   FldOffset  :  SizeInt;
end



TManagedField  describes  1  managed  field  in  a  record.   It  consists  of  type  information
(TypeRef)  and  an  offset  in  the  record's  memory  layout  (FldOffset).   Size  can  be  deter-
mined from the type information.


TMethodKind  =  (mkProcedure,mkFunction,mkConstructor,mkDestructor,
                        mkClassProcedure,mkClassFunction,mkClassConstructor,
                        mkClassDestructor,mkOperatorOverload)



                        Table 78.8:  Enumeration values for type TMethodKind


                           __Value____________________________Explanation___________________________
                             mkClassConstructor               Class constructor method.
                             mkClassDestructor                Class destructor method.
                             mkClassFunction                  Class function
                             mkClassProcedure                 Class procedure
                             mkConstructor                    Class constructor
                             mkDestructor                     Class Desctructor
                             mkFunction                       Function method
                             mkOperatorOverload               Operator overloader
                             mkProcedure                      Procedure method.



Method type description


TOrdType  =  (otSByte,otUByte,otSWord,otUWord,otSLong,otULong)



                           Table 78.9:  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



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)



                                                                1689

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



                         Table 78.10:  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)



TParamFlag describes a parameter.


TParamFlags  =  Set  of  TParamFlag


The kind of parameter for a method


TProcedureParam  =  packed  record
   Flags  :  Byte;
   ParamType  :  PTypeInfo;
   Name  :  ShortString;
end



TProcedureParam describes a single parameter to a procedure (or function).


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  :  CodePointer;
   SetProc  :  CodePointer;
   StoredProc  :  CodePointer;
   Index  :  Integer;
   Default  :  LongInt;
   NameIndex  :  SmallInt;
   PropProcs  :  Byte;
   Name  :  ShortString;
end



                                                                1690

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



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
case  TTypeKind  of
tkUnKnown:  (
);,  tkLString:  (
);,  tkWString:  (
);,  tkVariant:  (
);,  tkUString:  (
);
tkAString:  (
   CodePage  :  Word;
);
tkInteger:  (
   OrdType  :  TOrdType;
case  TTypeKind  of
tkInteger:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkEnumeration:  (
   MinValue  :  LongInt;



                                                                1691

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkBool:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkWChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);
tkSet:  (
   CompType  :  PTypeInfo;
);
);,  tkChar:  (
   OrdType  :  TOrdType;
case  TTypeKind  of
tkInteger:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkEnumeration:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkBool:  (



                                                                1692

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkWChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);
tkSet:  (
   CompType  :  PTypeInfo;
);
);,  tkEnumeration:  (
   OrdType  :  TOrdType;
case  TTypeKind  of
tkInteger:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkEnumeration:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkBool:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);



                                                                1693

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



);,  tkWChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);
tkSet:  (
   CompType  :  PTypeInfo;
);
);,  tkBool:  (
   OrdType  :  TOrdType;
case  TTypeKind  of
tkInteger:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkEnumeration:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkBool:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkWChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;



                                                                1694

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



);
);
tkSet:  (
   CompType  :  PTypeInfo;
);
);,  tkWChar:  (
   OrdType  :  TOrdType;
case  TTypeKind  of
tkInteger:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkEnumeration:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkBool:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkWChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);
tkSet:  (
   CompType  :  PTypeInfo;
);
);,  tkSet:  (
   OrdType  :  TOrdType;



                                                                1695

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



case  TTypeKind  of
tkInteger:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkEnumeration:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkBool:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);,  tkWChar:  (
   MinValue  :  LongInt;
   MaxValue  :  LongInt;
case  TTypeKind  of
tkEnumeration:  (
   BaseType  :  PTypeInfo;
   NameList  :  ShortString;
);
);
tkSet:  (
   CompType  :  PTypeInfo;
);
);
tkFloat:  (
   FloatType  :  TFloatType;
);
tkSString:  (
   MaxLength  :  Byte;
);
tkClass:  (
   ClassType  :  TClass;



                                                                1696

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



   ParentInfo  :  PTypeInfo;
   PropCount  :  SmallInt;
   UnitName  :  ShortString;
);
tkRecord:  (
   RecSize  :  Integer;
   ManagedFldCount  :  Integer;
);
tkHelper:  (
   HelperParent  :  PTypeInfo;
   ExtendedInfo  :  PTypeInfo;
   HelperProps  :  SmallInt;
   HelperUnit  :  ShortString;
);
tkMethod:  (
   MethodKind  :  TMethodKind;
   ParamCount  :  Byte;
   ParamList  :  Array[0..1023]  of  Char;
);
tkProcVar:  (
   ProcSig  :  TProcedureSignature;
);
tkInt64:  (
   MinInt64Value  :  Int64;
   MaxInt64Value  :  Int64;
);
tkQWord:  (
   MinQWordValue  :  QWord;
   MaxQWordValue  :  QWord;
);
tkInterface:  (
   IntfParent  :  PTypeInfo;
   IntfFlags  :  TIntfFlagsBase;
   GUID  :  TGuid;
   IntfUnit  :  ShortString;
);
tkInterfaceRaw:  (
   RawIntfParent  :  PTypeInfo;
   RawIntfFlags  :  TIntfFlagsBase;
   IID  :  TGuid;
   RawIntfUnit  :  ShortString;
   IIDStr  :  ShortString;
);
tkArray:  (
   ArrayData  :  TArrayTypeData;
);
tkDynArray:  (
   elSize  :  PtrUInt;
   elType2  :  PTypeInfo;
   varType  :  LongInt;
   elType  :  PTypeInfo;
   DynUnitName  :  ShortStringBase;
);
tkClassRef:  (



                                                                1697

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



   InstanceType  :  PTypeInfo;
);
tkPointer:  (
   RefType  :  PTypeInfo;
);
end



If the typeinfo kind is tkClass, then the property information follows the UnitName string,
as an array of TPropInfo (1691   ) 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 immediately follows the TTypeInfo record as
a TTypeData (1698   ) record.


TTypeKind  =  (tkUnknown,tkInteger,tkChar,tkEnumeration,tkFloat,tkSet,
                     tkMethod,tkSString,tkLString,tkAString,tkWString,tkVariant,
                     tkArray,tkRecord,tkInterface,tkClass,tkObject,tkWChar,
                     tkBool,tkInt64,tkQWord,tkDynArray,tkInterfaceRaw,tkProcVar,
                     tkUString,tkUChar,tkHelper,tkFile,tkClassRef,tkPointer)



                                                                1698

________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



                         Table 78.11:  Enumeration values for type TTypeKind


                           _Value____________________Explanation_____________________________________
                             tkArray                  Array property.
                             tkAString                Ansistring property.
                             tkBool                   Boolean property.
                             tkChar                   Char property.
                             tkClass                  Class property.
                             tkClassRef               Class of type
                             tkDynArray               Dynamical array property.
                             tkEnumeration            Enumeration type property.
                             tkFile                   File type (both text and binary)
                             tkFloat                  Float property.
                             tkHelper                 Helper class type.
                             tkInt64                  Int64 property.
                             tkInteger                Integer property.
                             tkInterface              Interface property.
                             tkInterfaceRaw           Raw interface property.
                             tkLString                Longstring property.
                             tkMethod                 Method property.
                             tkObject                 Object property.
                             tkPointer                Pointer type
                             tkProcVar                Procedural variable
                             tkQWord                  QWord property.
                             tkRecord                 Record property.
                             tkSet                    Set property.
                             tkSString                Shortstring property.
                             tkUChar                  Unicode character
                             tkUnknown                Unknown property type.
                             tkUString                Unicode string
                             tkVariant                Variant property.
                             tkWChar                  Widechar property.
                             tkWString                Widestring property.



Type of a property.


TTypeKinds  =  Set  of  TTypeKind


Set of TTypeKind (1698   ) enumeration.


TVmtFieldEntry  =  packed  record
   FieldOffset  :  PtrUInt;
   TypeIndex  :  Word;
   Name  :  ShortString;
end



TVmtFieldEntry records are generated by the compiler for all fields of a record or class that
have RTTI associated with them.  They describe the field as known to the compiler.


TVmtFieldTable  =  packed  record



                                                                1699

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                   Count  :  Word;
                   ClassTab  :  Pointer;
                   Fields  :  Array[0..0]  of  TVmtFieldEntry;
                end



                TVmtFieldTable  describes  the  fields  for  which  RTTI  was  generated.   A  TVmtFieldTable
                entry is generated by the compiler in the RTI information, it is not something one creates
                manually.  Basically it contains a list of TVmtFieldEntry (1699   ) values.



                78.7          Procedures  and  functions



                78.7.1         FindPropInfo

    Synopsis:    Return property information by property name.

Declaration:     function  FindPropInfo(Instance:  TObject;const  PropName:  string)
                                                     :  PPropInfo
                function  FindPropInfo(Instance:  TObject;const  PropName:  string;
                                                   AKinds:  TTypeKinds)  :  PPropInfo
                function  FindPropInfo(AClass:  TClass;const  PropName:  string)  :  PPropInfo
                function  FindPropInfo(AClass:  TClass;const  PropName:  string;
                                                   AKinds:  TTypeKinds)  :  PPropInfo

    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
                (1710   ) 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 (1710   ), GetPropList (1711   ), GetPropInfos (1710   )


                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          ;



                                                                                1700

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                78.7.2         GetEnumName

    Synopsis:    Return name of enumeration constant.

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 (1709   ), GetEnumValue (1703   )


                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;



                                                                                1701

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                78.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 (1703   ), GetEnumName (1701   )



                78.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 (1720   ), GetOrdProp (1709   ), GetStrProp (1714   ), GetInt64Prop (1704   ), Get-
                MethodProp (1705   ), GetSetProp (1713   ), GetObjectProp (1707   ), GetEnumProp (1702   )


                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;



                                                                                1702

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                78.7.5         GetEnumValue

    Synopsis:    Get ordinal value for enumerated type by name

Declaration:     function  GetEnumValue(TypeInfo:  PTypeInfo;const  Name:  string)  :  Integer

    Visibility:   default

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 (1701   ).

       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 (1701   ), SetOrdProp (1723   )



                78.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 (1720   ), GetOrdProp (1709   ), GetStrProp (1714   ), GetInt64Prop (1704   ), Get-
                MethodProp (1705   ), GetSetProp (1713   ), GetObjectProp (1707   ), GetEnumProp (1702   )



                                                                                1703

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                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:   ' ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                78.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 (1721   ), GetOrdProp (1709   ), GetStrProp (1714   ), GetFloatProp (1703   ), Get-
                MethodProp (1705   ), GetSetProp (1713   ), GetObjectProp (1707   ), GetEnumProp (1702   )



                                                                                1704

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                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;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________



                78.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  (1721   ),  GetOrdProp  (1709   ),  GetStrProp  (1714   ),  GetFloatProp  (1703   ),
                GetInt64Prop (1704   ), GetSetProp (1713   ), GetObjectProp (1707   ), GetEnumProp (1702   )



                78.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



                                                                                1705

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



    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  (1722   ),  GetOrdProp  (1709   ),  GetStrProp  (1714   ),  GetFloatProp  (1703   ),
                GetInt64Prop (1704   ), GetSetProp (1713   ), GetObjectProp (1707   ), GetEnumProp (1702   )


                Listing:  ./typinfex/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 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



                                                                                1706

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                        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                                  :   ') ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                78.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



                                                                                1707

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



    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  (1722   ),  GetOrdProp  (1709   ),  GetStrProp  (1714   ),  GetFloatProp  (1703   ),
                GetInt64Prop (1704   ), GetSetProp (1713   ), GetObjectProp (1707   ), GetEnumProp (1702   )


                Listing:__./typinfex/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 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___.____________________________________________________________________________________________________________*
 *___________



                78.7.11          GetObjectPropClass

    Synopsis:    Return class of property.



                                                                                1708

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



Declaration:     function  GetObjectPropClass(Instance:  TObject;const  PropName:  string)
                                                              :  TClass
                function  GetObjectPropClass(AClass:  TClass;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 (1707   ).

       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  (1722   ),  GetOrdProp  (1709   ),  GetStrProp  (1714   ),  GetFloatProp  (1703   ),
                GetInt64Prop (1704   )



                78.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 (1723   ), GetStrProp (1714   ), GetFloatProp (1703   ), GetInt64Prop (1704   ), Get-
                MethodProp (1705   ), GetSetProp (1713   ), GetObjectProp (1707   ), GetEnumProp (1702   )


                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



                                                                                1709

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                78.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)
                                                   :  PPropInfo
                function  GetPropInfo(Instance:  TObject;const  PropName:  string;
                                                 AKinds:  TTypeKinds)  :  PPropInfo
                function  GetPropInfo(AClass:  TClass;const  PropName:  string)  :  PPropInfo
                function  GetPropInfo(AClass:  TClass;const  PropName:  string;
                                                 AKinds:  TTypeKinds)  :  PPropInfo

    Visibility:   default

Description:     GetPropInfo  returns  a  pointer  to  the  TPropInfo  record  for  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 (1710   ), GetPropList (1711   )



                78.7.14          GetPropInfos

    Synopsis:    Return a list of published properties.



                                                                                1710

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



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 (1710   ), GetPropList (1711   )


                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 }


                 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___.____________________________________________________________________________________________________________*
 *___________



                78.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



                                                                                1711

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                function  GetPropList(TypeInfo:  PTypeInfo;out  PropList:  PPropList)
                                                  :  SizeInt
                function  GetPropList(AClass:  TClass;out  PropList:  PPropList)  :  Integer
                function  GetPropList(Instance:  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 (1710   ), GetPropInfo (1710   )


                Listing:  ./typinfex/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 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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1712

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                78.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.



                78.7.17          GetRawInterfaceProp

    Synopsis:    Get a raw (CORBA) interface property.

Declaration:     function  GetRawInterfaceProp(Instance:  TObject;const  PropName:  string)
                                                                :  Pointer
                function  GetRawInterfaceProp(Instance:  TObject;PropInfo:  PPropInfo)
                                                                :  Pointer

    Visibility:   default

Description:     GetRawInterfaceProp can be used to retrieve the value of a published CORBA interface
                property with name PropName from object Instance.  Alternatively, the required property
                information can be specified by PropInfo instead of the property name.  In difference with
                the GetInterfaceProp (1705   ) function, no reference counting is done.

       Errors:   If the property PropName does not exist, an EPropertyError exception is raised.

    See also:    GetInterfaceProp (1705   ), SetRawInterfaceProp (1723   )



                78.7.18          GetSetProp

    Synopsis:    Return the value of a set property.

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 (1725   ).  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  (1724   ),  GetStrProp  (1714   ),  GetFloatProp  (1703   ),  GetInt64Prop  (1704   ),  Get-
                MethodProp (1705   )



                                                                                1713

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                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      :  ' ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                78.7.19          GetStrProp

    Synopsis:    Return the value of a string property.

Declaration:     function  GetStrProp(Instance:  TObject;PropInfo:  PPropInfo)  :  Ansistring



                                                                                1714

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                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  (1724   ),  SetWideStrProp  (1726   ),  GetOrdProp  (1709   ),  GetFloatProp  (1703   ),
                GetInt64Prop (1704   ), GetMethodProp (1705   )


                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') ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                78.7.20          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.



                                                                                1715

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                78.7.21          GetUnicodeStrProp

    Synopsis:    Get UnicodeString-valued property

Declaration:     function  GetUnicodeStrProp(Instance:  TObject;PropInfo:  PPropInfo)
                                                             :  UnicodeString
                function  GetUnicodeStrProp(Instance:  TObject;const  PropName:  string)
                                                             :  UnicodeString

    Visibility:   default

Description:     GetUnicodeStrProp returns the UnicodeString property from Instance, where the property
                is identified by the PropInfo pointer or the PropertyName.

       Errors:   If no property of the indicated name exists, or the value is not a unicode string, an exception
                will occur.

    See also:    GetStrProp (1714   ), SetUnicodeStrProp (1726   )



                78.7.22          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  missing  Variant  support,  the  GetVariantProp  function  is  not  yet  implemented.
                Provided for Delphi compatibility only.

    See also:    SetVariantProp (1726   )



                78.7.23          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  (1714   ),  SetWideStrProp  (1726   ),  GetOrdProp  (1709   ),  GetFloatProp  (1703   ),
                GetInt64Prop (1704   ), GetMethodProp (1705   )



                                                                                1716

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                78.7.24          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 (1717   ), PropIsType (1718   )


                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___.____________________________________________________________________________________________________________*
 *___________



                78.7.25          IsStoredProp

    Synopsis:    Check whether a property is stored.

Declaration:     function  IsStoredProp(Instance:  TObject;PropInfo:  PPropInfo)  :  Boolean
                function  IsStoredProp(Instance:  TObject;const  PropName:  string)
                                                     :  Boolean



                                                                                1717

                ________________________________________________________CHAPTER_78.___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 (1717   ), PropIsType (1718   )


                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___.____________________________________________________________________________________________________________*
 *___________



                78.7.26          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.



                                                                                1718

                ________________________________________________________CHAPTER_78.___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 (1717   ), IsStoredProp (1717   ), PropType (1719   )


                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___.____________________________________________________________________________________________________________*
 *___________



                78.7.27          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 (1717   ), IsStoredProp (1717   ), PropIsType (1718   )


                Listing:  ./typinfex/ex17.pp



                                                                                1719

                ________________________________________________________CHAPTER_78.___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___.____________________________________________________________________________________________________________*
 *___________



                78.7.28          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 (1703   ).

                For an example, see GetEnumProp (1702   ).

       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 (1702   ), SetStrProp (1724   ), SetFloatProp (1720   ), SetInt64Prop (1721   ), Set-
                MethodProp (1722   )



                78.7.29          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)



                                                                                1720

                ________________________________________________________CHAPTER_78.___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 (1703   ).

       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  (1703   ),  SetOrdProp  (1723   ),  SetStrProp  (1724   ),  SetInt64Prop  (1721   ),  Set-
                MethodProp (1722   )



                78.7.30          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 (1704   ).

       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 (1704   ), GetMethodProp (1705   ), SetOrdProp (1723   ), SetStrProp (1724   ), Set-
                FloatProp (1720   )



                78.7.31          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  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  (1705   ),  SetObjectProp  (1722   ),  SetOrdProp  (1723   ),  SetStrProp  (1724   ),
                SetFloatProp (1720   ), SetInt64Prop (1721   ), SetMethodProp (1722   )



                                                                                1721

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                78.7.32          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 (1705   ).

       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 (1705   ), SetOrdProp (1723   ), SetStrProp (1724   ), SetFloatProp (1720   ), SetInt64Prop
                (1721   )



                78.7.33          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 object property described by PropInfo or with name
                Propname for the object Instance.

                For an example, see GetObjectProp (1707   ).

       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 (1707   ), SetOrdProp (1723   ), SetStrProp (1724   ), SetFloatProp (1720   ), SetInt64Prop
                (1721   ), SetMethodProp (1722   )



                                                                                1722

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                78.7.34          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  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 (1709   ).

       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  (1709   ),  SetStrProp  (1724   ),  SetFloatProp  (1720   ),  SetInt64Prop  (1721   ),  Set-
                MethodProp (1722   )



                78.7.35          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.



                78.7.36          SetRawInterfaceProp

    Synopsis:    Set a raw (CORBA) interface property.

Declaration:     procedure  SetRawInterfaceProp(Instance:  TObject;const  PropName:  string;
                                                                const  Value:  Pointer)
                procedure  SetRawInterfaceProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                                const  Value:  Pointer)

    Visibility:   default

Description:     SetRawInterfaceProp can be used to set the value of a published CORBA interface with
                name PropName from object Instance to Value.  Alternatively, the required property infor-
                mation can be specified by PropInfo instead of the property name.  In difference with the
                SetInterfaceProp (1721   ) procedure, no reference counting is done.



                                                                                1723

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



       Errors:   If the property PropName does not exist, an EPropertyError exception is raised.

    See also:    SetInterfaceProp (1721   ), GetRawInterfaceProp (1713   )



                78.7.37          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

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 (1727   ) function.

                The value can be formed using the SetToString (1725   ) function.

                For an example, see GetSetProp (1713   ).

       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 (1713   ), SetOrdProp (1723   ), SetStrProp (1724   ), SetFloatProp (1720   ), SetInt64Prop
                (1721   ), SetMethodProp (1722   ), SetToString (1725   ), StringToSet (1727   )



                78.7.38          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 (1714   )

       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 (1714   ), SetWideStrProp (1726   ), SetOrdProp (1723   ), SetFloatProp (1720   ), SetInt64Prop
                (1721   ), SetMethodProp (1722   )



                                                                                1724

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                78.7.39          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.

       Errors:   No checking is done to see whether PropInfo points to valid property information.

    See also:    GetEnumName (1701   ), GetEnumValue (1703   ), StringToSet (1727   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1725

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                78.7.40          SetUnicodeStrProp

    Synopsis:    Set UnicodeString-valued property

Declaration:     procedure  SetUnicodeStrProp(Instance:  TObject;const  PropName:  string;
                                                             const  Value:  UnicodeString)
                procedure  SetUnicodeStrProp(Instance:  TObject;PropInfo:  PPropInfo;
                                                             const  Value:  UnicodeString)

    Visibility:   default

Description:     SetUnicodeStrProp sets the UnicodeString property from Instance to Value, where the
                property is identified by the PropInfo pointer or the PropertyName.

       Errors:   If no property of the indicated name exists, or it is not of type unicodestring, an exception
                will occur.

    See also:    SetStrProp (1724   ), GetUnicodeStrProp (1716   )



                78.7.41          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.



                78.7.42          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 (1716   ), SetStrProp (1724   ), SetOrdProp (1723   ), SetFloatProp (1720   ), SetInt64Prop
                (1721   ), SetMethodProp (1722   )



                                                                                1726

                ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                78.7.43          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 (1703   ) function.

                For an example, see SetToString (1725   ).

       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 (1701   ), GetEnumValue (1703   ), SetToString (1725   )



                78.8          TProcedureSignature


                TProcedureSignature  =  packed  record
                    Flags  :  Byte;
                    CC  :  TCallConv;
                    ResultType  :  PTypeInfo;
                    ParamCount  :  Byte;
                    function  GetParam(ParamIndex:  Integer)  :  PProcedureParam;
                end



                TProcedureSignature  describes  a  procedure/method  call  signature.   It  consists  of  some
                flags (Flags),  a calling convention (CC), the result type (ResultType) if any,  and a list of
                ParamCount parameters (of type TProcedureParam (1690   )).



                78.8.1         Method  overview

                __Page______Method____________Description__________________________________________________________________________*
 *___________
                __1727______GetParam__________Get_parameter_signature______________________________________________________________*
 *___________



                78.8.2         TProcedureSignature.GetParam

    Synopsis:    Get parameter signature

Declaration:     function  GetParam(ParamIndex:  Integer)  :  PProcedureParam

    Visibility:   default

Description:     GetParam can be used to retrieve a pointer to the description of a parameter.  The index
                ParamIndex is zero-based.



                                                                                1727

            ________________________________________________________CHAPTER_78.___REFERENCE_FOR_UNIT_'TYPINFO'_____________________*
 *_______________



   Errors:   In case of an invalid parameter index, Nil is returned.

See also:    TProcedureParam (1690   )



            78.9          EPropertyConvertError



            78.9.1         Description

            EPropertyConvertError is not used in the Free Pascal implementation of the typinfo unit,
            but is declared for Delphi compatibility.



            78.10            EPropertyError



            78.10.1          Description

            Exception raised in case of an error in one of the functions.



                                                                            1728




Chapter   79



Reference   for   unit   'unicodedata'



79.1          Overview


The fpwidestring (1729   ) unit relies on having relevant unicode collation data linked in the
binary.  The unicode data is managed using the routines in the unicodedata unit.  The FPC
project distributes some unicode collation data in .bco files which can be loaded using the
LoadCollation (1738   ) routines.  The LoadCollation is the main routine of this unit.

All collation data requires at least the Default Unicode Collation Element Table to be reg-
istered (called DUCET). The DUCET encoding is provided by the unicodeducet unit, part of
the rtl-unicode package.

There are two ways to register collations :


    1.  at compile time:  by including the desired collation unit, for example for Russian and
        Japanese languages to be available you will have to include collation_ru and collation_ja
        from package "rtl-unicode".

    2.  at runtime using the abovementioned LoadCollation function.


The two ways can co-exist:  some collations may be compile time included (for example for
most used collations) and others can be loaded at runtime in the same application.

The binary collation files are endian sensitive:


     o  there are files for little endian systems named collation_ _le.bco (such as collation_ru_le.bco
        and collation_ja_le.bco)

     o  there are files for big endian systems named collation_ _be.bco (such as collation_ru_be.bco
        and collation_ja_be.bco).


Note  that  the  compile  time  units  collation  units  (collation_lang.pas)  include  already  the
unicodeducet.pas (DUCET) unit so it is not necessary to include it manually,  contrary to
the binary files.  So an application that only uses the binary collation files should at least
include  the  unicodeducet  unit  or  manually  load  the  binary  collation  collation_ducet_le.bco
or collation_ducet_be.bco, depending on the endianness of the platform.  The LoadCollation
(1738   ) call using a directory and the language ducet automatically select the correct file.



                                                            1729

_______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________________________*
 *___



79.2          Constants,  types  and  variables



79.2.1         Resource  strings

SCollationNotFound  =  'Collation  not  found  :  "%s".'


Error message when a collation is not found.



79.2.2         Constants

ENDIAN_SUFFIX  :  Array[TEndianKind]  of  string  =  ('le',  'be')


ENDIAN_SUFFIX contains the suffixes used in LoadCollation (1738   ) when constructing a col-
lation filename for a language.


ERROR_INVALID_CODEPOINT_SEQUENCE  =  1


Error exit code for UnicodeToLower/UnicodeToUpper


HIGH_SURROGATE_BEGIN  =  ($D800)


First value for high surrogate values.


HIGH_SURROGATE_COUNT  =  HIGH_SURROGATE_END  -  HIGH_SURROGATE_BEGIN  +  1


Number of high surrogate values.


HIGH_SURROGATE_END  =  ($DBFF)


Last value for high surrogate values.


LOW_SURROGATE_BEGIN  =  ($DC00)


First value for low surrogate values.


LOW_SURROGATE_END  =  ($DFFF)


Last value for low surrogate values.


MAX_LEGAL_UTF32  =  $10FFFF


Maximum value of a legally encoded UTF32 value (currently unused)


MAX_WORD  =  (Word)


MAX_WORD is the maximum value of a WORD typed value.


ROOT_COLLATION_NAME  =  'DUCET'


Name of the root collation (used if no collation name is given)



                                                                1730

_______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________________________*
 *___



UCS4_HALF_BASE  =  ($10000)


Offset for UCS4 character encoding


UCS4_HALF_MASK  =  ($3FF)


Unused currently


UGC_ClosePunctuation  =  14


Unicode token category:  Close punctuation


UGC_CombiningMark  =  6


Unicode token category:  Uppercase letter


UGC_ConnectPunctuation  =  11


Unicode token category:  Connect punctuation


UGC_Control  =  25


Unicode token category:  control token


UGC_CurrencySymbol  =  19


Unicode token category:  Currency symbol


UGC_DashPunctuation  =  12


Unicode token category:  Dash punctuation


UGC_DecimalNumber  =  8


Unicode token category:  Uppercase letter


UGC_EnclosingMark  =  7


Unicode token category:  Uppercase letter


UGC_FinalPunctuation  =  16


Unicode token category:  Final punctuation


UGC_Format  =  26


Unicode token category:  Formatting token


UGC_InitialPunctuation  =  15


Unicode token category:  Initial punctuation



                                                                1731

_______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________________________*
 *___



UGC_LetterNumber  =  9


Unicode token category:  Letter-number


UGC_LineSeparator  =  23


Unicode token category:  Line separator


UGC_LowercaseLetter  =  1


Unicode general category:  Lowercase letter


UGC_MathSymbol  =  18


Unicode token category:  Math symbol


UGC_ModifierLetter  =  3


Unicode general category:  modifier letter


UGC_ModifierSymbol  =  20


Unicode token category:  modifier symbol


UGC_NonSpacingMark  =  5


Unicode general category:  Non-spacing mark


UGC_OpenPunctuation  =  13


Unicode token category:  Open puntctuation


UGC_OtherLetter  =  4


Unicode general category:  Other letter


UGC_OtherNumber  =  10


Unicode token category:  Other number


UGC_OtherPunctuation  =  17


Unicode token category:  Other punctuation


UGC_OtherSymbol  =  21


Unicode token category:  Other symbol


UGC_ParagraphSeparator  =  24


Unicode token category:  Paragraph separator



                                                                1732

_______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________________________*
 *___



UGC_PrivateUse  =  28


Unicode token category:  For private use


UGC_SpaceSeparator  =  22


Unicode token category:  Space separator


UGC_Surrogate  =  27


Unicode token category:  Surrogate token


UGC_TitlecaseLetter  =  2


Unicode general category:  Titlecase letter


UGC_Unassigned  =  29


Unicode token category:  As yet unassigned


UGC_UppercaseLetter  =  0


Unicode general category:  Uppercase letter


ZERO_UINT24  :  UInt24  =  (byte2:  0;  byte1:  0;  byte0:  0)


TUInt24Rec value with all bytes zero.



79.2.3         Types

PUCA_DataBook  =  ^TUCA_DataBook


Pointer to TUCA_DataBook type.


PUCA_PropItemContextRec  =  ^TUCA_PropItemContextRec


Pointer to TUCA_PropItemContextRec


PUCA_PropItemContextTreeNodeRec  =  ^TUCA_PropItemContextTreeNodeRec


Pointer to TUCA_PropItemContextTreeNodeRec


PUCA_PropItemContextTreeRec  =  ^TUCA_PropItemContextTreeRec


Pointer to TUCA_PropItemContextTreeRec


PUCA_PropItemRec  =  ^TUCA_PropItemRec


Pointer to TUCA_PropItemRec



                                                                1733

_______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________________________*
 *___



PUCA_PropWeights  =  ^TUCA_PropWeights


Pointer to TUCA_PropWeights


PUC_Prop  =  ^TUC_Prop


Pointer to TUC_Prop record


PUInt24  =  ^UInt24


Pointer to TUInt24Rec


TCollationField  =  (BackWard,VariableLowLimit,VariableHighLimit)



                       Table 79.1:  Enumeration values for type TCollationField


                     __Value________________________Explanation___________________________________________
                       BackWard                     Backwards encoded
                       VariableHighLimit            Has upper bound on variable weights
                       VariableLowLimit             Has lower bound on variable weights



TCollationField describes some properties of the collation data items.


TCollationFields  =  Set  of  TCollationField


Set of  TCollationField


TCollationName  =  string


Collation name string type (fixed lenght)


TEndianKind  =  (Little,Big)



                         Table 79.2:  Enumeration values for type TEndianKind


                                        __Value_______Explanation_____________________
                                          Big         Big-endian platform
                                          Little      Little-endian platform



TEndianKind is an auxiliary enumerated type to enumerate the endianness of platforms.


TUCASortKey  =  Array  of  TUCASortKeyItem


Array of  TUCASortKeyItem


TUCASortKeyItem  =  Word



                                                                1734

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                Alias for WORD


                TUCA_PropWeights  =  packed  record
                   Weights  :  Array[0..2]  of  Word;
                end



                TUC_PropWeights describes the weights of collation characteristics of a unicode character.  It
                is an internal structure which should not be used directly, the actual structure is subject to
                change.


                TUCA_VariableKind  =  (ucaShifted,ucaNonIgnorable,ucaBlanked,
                                                  ucaShiftedTrimmed,ucaIgnoreSP)



                                    Table 79.3:  Enumeration values for type TUCA_VariableKind



                __Value__________________________Explanation_______________________________________________________________________*
 *_____________________________________________________________________________________________________________________
                  ucaBlanked                     Variable collation elements and any subsequent ignorable collation elements are re*
 *set so that all weights (except for the identical level) are zero
                  ucaIgnoreSP                    Not implemented (variant of Shifted that reduces the set of variable collation ele*
 *ments to include only spaces and punctuation)
                  ucaNonIgnorable                Variable collation elements are not reset to be quaternary collation elements
                  ucaShifted                     Variable collation elements are reset to zero at levels one through three
                  ucaShiftedTrimmed              This option is the same as Shifted, except that all trailing FFFFs are trimmed fro*
 *m the sort key.



                Options for weighting data


                UInt24  =  TUInt24Rec


                Alias for TUInt24Rec



                79.3          Procedures  and  functions



                79.3.1         CanonicalOrder

    Synopsis:    Put unicode string in canonical order.

Declaration:     procedure  CanonicalOrder(var  AString:  UnicodeString);    Overload
                procedure  CanonicalOrder(AStr:  PUnicodeChar;const  ALength:  SizeInt)
                                                        ;    Overload

    Visibility:   default

Description:     CanonicalOrder transforms a unicode string AString (or the alternate form using a null-
                terminated AStr with length Alength) so it is in canonical order (as defined by the unicode
                specification).  A string needs to be in canonical order to be able to compare strings.  This
                function is called as part of NormalizeNFD (1739   ).

    See also:    NormalizeNFD (1739   )



                                                                                1735

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.3.2         CompareSortKey

    Synopsis:    Compare two sort keys.

Declaration:     function  CompareSortKey(const  A:  TUCASortKey;const  B:  TUCASortKey)
                                                        :  Integer;    Overload
                function  CompareSortKey(const  A:  TUCASortKey;const  B:  Array  of  Word)
                                                        :  Integer;    Overload

    Visibility:   default

Description:     CompareSortKey compares 2 sort keys A and B. It returns


                      oa negative number if  A comes alphabetically ordered before B.

                      oZero if  A is alphabetically identical to B.

                      oA positive number iff  A is alphabetically ordered after B.


                Sort keys can be constructed from unicode strings using ComputeSortKey (1736   ).

    See also:    ComputeSortKey (1736   )



                79.3.3         ComputeSortKey

    Synopsis:    Compute the sort key for a string

Declaration:     function  ComputeSortKey(const  AString:  UnicodeString;
                                                      const  ACollation:  PUCA_DataBook)  :  TUCASortKey
                                                      ;    Overload
                function  ComputeSortKey(const  AStr:  PUnicodeChar;const  ALength:  SizeInt;
                                                      const  ACollation:  PUCA_DataBook)  :  TUCASortKey
                                                      ;    Overload

    Visibility:   default

Description:     ComputeSortKey computes the sort key for a unicode string AString (or the alternate form
                using a null-terminated AStr with length Alength) using the Unicode Collation Algorithm
                dat  in  ACollation.   This  key  can  then  be  used  in  CompareSortKey  (1736   )  to  compare
                unicode strings.

    See also:    CompareSortKey (1736   )



                79.3.4         FindCollation

    Synopsis:    Find a collation by name

Declaration:     function  FindCollation(const  AName:  ansistring)  :  PUCA_DataBook
                                                     ;    Overload
                function  FindCollation(const  AIndex:  Integer)  :  PUCA_DataBook;    Overload

    Visibility:   default

Description:     FindCollection searches a collation with name AName or index AIndex in the list of known
                collations and returns a pointer to the collation data.  If the requested collation is not known,
                i.e.  the  name  is  not  found,  or  the  index  is  out  of  range,  then  Nil  is  returned.  The  valid
                index range is 0 to GetCollationCount-1.

    See also:    GetCollationCount (1737   )



                                                                                1736

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.3.5         FreeCollation

    Synopsis:    Free collation data.

Declaration:     procedure  FreeCollation(AItem:  PUCA_DataBook)

    Visibility:   default

Description:     FreeCollation  removes  all  structures  in  the  collation  data  from  memory.  It  will  not  do
                anything  when  the  header  field  Dynamic  is  false.  (collations  loaded  and  registered  using
                LoadCollation (1738   ) are always dynamic and must be freed).

    See also:    LoadCollation (1738   )



                79.3.6         FromUCS4

    Synopsis:    Convert UCS4 to UNicodeChar

Declaration:     procedure  FromUCS4(const  AValue:  UCS4Char;var  AHighS:  UnicodeChar;
                                              var  ALowS:  UnicodeChar)

    Visibility:   default

Description:     FromUCS4 converts the UCS4 encoded unicode character AValue to a set of unicode (surro-
                gate pair) characters encoded in UTF16:  AHighS, ALowS.

    See also:    ToUCS4 (1740   ), UnicodeIsHighSurrogate (1740   ), UnicodeIsLowSurrogate (1740   ), UnicodeIs-
                SurrogatePair (1741   )



                79.3.7         GetCollationCount

    Synopsis:    Return the number of known collations.

Declaration:     function  GetCollationCount  :  Integer

    Visibility:   default

Description:     GetCollationCount returns the number of registered collations.  The collation data can be
                retrieved by index using the FindCollation (1736   ).  The maximum index is GetCollationCount-1.

    See also:    FindCollation (1736   )



                79.3.8         GetProps

    Synopsis:    Get unicode character data

Declaration:     function  GetProps(const  ACodePoint:  Word)  :  PUC_Prop;    Overload
                function  GetProps(const  AHighS:  UnicodeChar;const  ALowS:  UnicodeChar)
                                              :  PUC_Prop;    Overload
                function  GetProps(const  ACodePoint:  Cardinal)  :  PUC_Prop;    Overload

    Visibility:   default

Description:     GetProps  returns  a  pointer  to  a  general  unicode  character  property  data  structure.  The
                character can be specified using a word or cardinal sized codepoint (ACodePoint), or using
                a UTF16 encoded surrogate pair (AHighS,ALowS).

                The returned pointer must not be freed, it points to part of a static structure.

    See also:    GetPropUCA (1738   )



                                                                                1737

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.3.9         GetPropUCA

    Synopsis:    Get unicode collation algorithm properties for a unicode character

Declaration:     function  GetPropUCA(const  AHighS:  UnicodeChar;const  ALowS:  UnicodeChar;
                                                const  ABook:  PUCA_DataBook)  :  PUCA_PropItemRec
                                                ;    Overload
                function  GetPropUCA(const  AChar:  UnicodeChar;const  ABook:  PUCA_DataBook)
                                                 :  PUCA_PropItemRec;    Overload

    Visibility:   default

Description:     GetPropUCA returns UCA data for the unicode character (AChar) or surrogate pair AHighS,
                ALowS) in the collation data book ABook.  If no data is available, Nil is returned.

       Errors:   if an invalid ABook is specified, an access violation may occur.

    See also:    GetProps (1737   )



                79.3.10          IncrementalCompareString

    Synopsis:    Compare 2 strings using the specified collation

Declaration:     function  IncrementalCompareString(const  AStrA:  PUnicodeChar;
                                                                       const  ALengthA:  SizeInt;
                                                                       const  AStrB:  PUnicodeChar;
                                                                       const  ALengthB:  SizeInt;
                                                                       const  ACollation:  PUCA_DataBook)
                                                                        :  Integer;    Overload
                function  IncrementalCompareString(const  AStrA:  UnicodeString;
                                                                       const  AStrB:  UnicodeString;
                                                                       const  ACollation:  PUCA_DataBook)
                                                                        :  Integer;    Overload

    Visibility:   default

Description:     IncrementalCompareString creates 2 compare keys from the strings AStrA and AStrB using
                collation data in ACollation.  The keys are computed only to the point where the two strings
                differ.  This means the keys cannot be reused for other comparisons if the strings differ.  The
                two strings can be specified as a unicode string or as a pointer to a null-terminated character
                array with a length (ALengthA and ALengthB). It returns then the result of CompareSortKey
                (1736   ).

       Errors:   None.

    See also:    ComputeSortKey (1736   ), CompareSortKey (1736   )



                79.3.11          LoadCollation

    Synopsis:    Load a binary collation data file from file

Declaration:     function  LoadCollation(const  AData:  Pointer;const  ADataLength:  Integer)
                                                      :  PUCA_DataBook;    Overload
                function  LoadCollation(const  AFileName:  string)  :  PUCA_DataBook
                                                     ;    Overload
                function  LoadCollation(const  ADirectory:  string;const  ALanguage:  string)
                                                      :  PUCA_DataBook;    Overload



                                                                                1738

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



    Visibility:  default

Description:     LoadCollation loads collation data from file AFileName,  or from a memory block AData
                with length ADataLength.  If successful, it returns a pointer which can be used to register the
                collation using RegisterCollation (1739   ).  if there is a problem with the data, Nil is returned.

                The  filename  can  also  be  specified  as  a  Directory  and  language  name  ALanguage.   The
                latter is prepended with collation_ and appended with the native endianness of the current
                platform, and has extension .bco

       Errors:   If the file containing data does not exist or has a size which is less than the encoded header
                size, Nil is returned.

    See also:    RegisterCollation (1739   )



                79.3.12          NormalizeNFD

    Synopsis:    Perform unicode normalization D on a string

Declaration:     function  NormalizeNFD(const  AString:  UnicodeString)  :  UnicodeString
                                                   ;    Overload
                function  NormalizeNFD(const  AStr:  PUnicodeChar;ALength:  SizeInt)
                                                     :  UnicodeString;    Overload

    Visibility:   default

Description:     NormalizeNFD normalizes the string AString (or the alternate form using a null-terminated
                AStr with length Alength) to Unicode Normalization Form D. The resulting string can be
                used to determine equivalence of unicode strings.

    See also:    CanonicalOrder (1735   )



                79.3.13          PrepareCollation

    Synopsis:    Prepare a collation for use in the list

Declaration:     procedure  PrepareCollation(ACollation:  PUCA_DataBook;
                                                           const  ABaseName:  ansistring;
                                                           const  AChangedFields:  TCollationFields)

    Visibility:   default

Description:     PrepareCollation  will  link  collation  definition  ACollation  to  the  base  collection  with
                name ABaseName (if empty, it defaults to the root collation).  It will also initialize some fields
                in the definition, copying them from the base collation, but excludes the fields enumerated
                in AChangedFields.

                It should normally not be needed to call this function, it is called as part of LoadCollation
                (1738   ).

    See also:    LoadCollation (1738   )



                79.3.14          RegisterCollation

    Synopsis:    Register a new collation



                                                                                1739

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



Declaration:     function  RegisterCollation(const  ACollation:  PUCA_DataBook)  :  Boolean
                                                          ;    Overload
                function  RegisterCollation(const  ADirectory:  string;
                                                          const  ALanguage:  string)  :  Boolean;    Overload

    Visibility:  default

Description:     RegisterCollation registers a new collation ACollation in the list of known collations.
                The collation data can be specified directly (ACollation) or a name of a language (ALanguage)
                in a directory (ADirectory).  The latter option will load the binary encodeded collation from
                file using LoadCollation (1738   ).

                If the collation is loaded correctly, True is returned, otherwise False is returned (for instance
                when a collation with the same name is already loaded).

    See also:    UnRegisterCollation (1742   ), UnRegisterCollations (1742   ), LoadCollation (1738   )



                79.3.15          ToUCS4

    Synopsis:    Encode unicode UTF16 surrogate pair to UCS4 character

Declaration:     function  ToUCS4(const  AHighS:  UnicodeChar;const  ALowS:  UnicodeChar)
                                           :  UCS4Char

    Visibility:   default

Description:     ToUCS4  converts  set  of  unicode  (surrogate  pair)  characters  encoded  in  UTF16:  AHighS,
                ALowS to a UCS4 encoded unicode character.

    See also:    FromUCS4  (1737   ),  UnicodeIsHighSurrogate  (1740   ),  UnicodeIsLowSurrogate  (1740   ),  Uni-
                codeIsSurrogatePair (1741   )



                79.3.16          UnicodeIsHighSurrogate

    Synopsis:    Check if a UTF16 character is the high character in a surrogate pair.

Declaration:     function  UnicodeIsHighSurrogate(const  AValue:  UnicodeChar)  :  Boolean

    Visibility:   default

Description:     UnicodeIsHighSurrogate checks whether AValue is a valid high character of a surrogate
                pair,  and returns True if this is the case.  It does this by checking whether the values are
                within the bounds for high characters in surrogate pairs.

    See also:    FromUCS4  (1737   ),  ToUCS4  (1740   ),  UnicodeIsHighSurrogate  (1740   ),  UnicodeIsLowSurro-
                gate (1740   ), UnicodeIsSurrogatePair (1741   )



                79.3.17          UnicodeIsLowSurrogate

    Synopsis:    Check if a UTF16 character is the low character in a surrogate pair.

Declaration:     function  UnicodeIsLowSurrogate(const  AValue:  UnicodeChar)  :  Boolean

    Visibility:   default

Description:     UnicodeIsHighSurrogate checks whether AValue is a valid high character of a surrogate
                pair,  and returns True if this is the case.  It does this by checking whether the values are
                within the bounds for high characters in surrogate pairs.



                                                                                1740

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



    See also:    FromUCS4 (1737   ), ToUCS4 (1740   ), UnicodeIsHighSurrogate (1740   ), UnicodeIsSurrogatePair
                (1741   )



                79.3.18          UnicodeIsSurrogatePair

    Synopsis:    Check if a pair of UTF16 encoded characters is a valid surrogate pair.

Declaration:     function  UnicodeIsSurrogatePair(const  AHighSurrogate:  UnicodeChar;
                                                                   const  ALowSurrogate:  UnicodeChar)
                                                                     :  Boolean

    Visibility:   default

Description:     UnicodeIsSurrogatePair  checks  whether  AHighSurrogate,ALowSurrogate  constitute  a
                valid surrogate pair, and returns True if this is the case.  It does this by checking whether
                the values are within the bounds for high and low surrogate pairs.

    See also:    FromUCS4  (1737   ),  ToUCS4  (1740   ),  UnicodeIsHighSurrogate  (1740   ),  UnicodeIsLowSurro-
                gate (1740   )



                79.3.19          UnicodeToLower

    Synopsis:    Transform unicode string to lowercase

Declaration:     function  UnicodeToLower(const  AString:  UnicodeString;
                                                      const  AIgnoreInvalidSequence:  Boolean;
                                                      out  AResultString:  UnicodeString)  :  Integer

    Visibility:   default

Description:     UnicodeToLower  transforms  a  UTF16  unicode  string  AString  to  its  lowercase  equivalent
                and returns this in AResultString.  If the transformation was succesful, then the function
                returns  0.  A  nonzero  return  value  means  an  error  occurred.  AResultString  will  remain
                untouched in that case.

                If  a  character  in  AString  cannot  be  found  in  the  unicode  data  tables,  an  error  will  be
                reported, unless AIgnoreInvalidSequence is set to True, in which case the character will
                be copied as-is to the output.

                Unicode collation data can be loaded using RegisterCollation (1739   ) or LoadCollation (1738   )

       Errors:   On error, a nonzero value will be returned.

    See also:    UnicodeToUpper (1741   ), RegisterCollation (1739   ), LoadCollation (1738   )



                79.3.20          UnicodeToUpper

    Synopsis:    Transform unicode string to uppercase

Declaration:     function  UnicodeToUpper(const  AString:  UnicodeString;
                                                      const  AIgnoreInvalidSequence:  Boolean;
                                                      out  AResultString:  UnicodeString)  :  Integer

    Visibility:   default



                                                                                1741

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



Description:     UnicodeToUpper transforms a UTF16 unicode string AString to its uppercase equivalent
                and returns this in AResultString.  If the transformation was succesful, then the function
                returns  0.  A  nonzero  return  value  means  an  error  occurred.  AResultString  will  remain
                untouched in that case.

                If  a  character  in  AString  cannot  be  found  in  the  unicode  data  tables,  an  error  will  be
                reported, unless AIgnoreInvalidSequence is set to True, in which case the character will
                be copied as-is to the output.

                Unicode collation data can be loaded using RegisterCollation (1739   ) or LoadCollation (1738   )

       Errors:   On error, a nonzero value will be returned.

    See also:    UnicodeToLower (1741   ), RegisterCollation (1739   ), LoadCollation (1738   )



                79.3.21          UnregisterCollation

    Synopsis:    Remove a collation from the list of known collections.

Declaration:     function  UnregisterCollation(const  AName:  ansistring)  :  Boolean

    Visibility:   default

Description:     UnRegisterCollation  removes  a  collation  AName  from  the  list  of  known  collations.   It
                returns True if the collation was found and succesfully removed.

       Errors:   If the collation was not found, False is returned.

    See also:    RegisterCollation (1739   ), UnRegisterCollations (1742   ), LoadCollation (1738   )



                79.3.22          UnregisterCollations

    Synopsis:    Unregister all collations.

Declaration:     procedure  UnregisterCollations(const  AFreeDynamicCollations:  Boolean)

    Visibility:   default

Description:     UnregisterCollations  unregisters  all  known  collations.  If  AFreeDynamicCollations  is
                True,  then  dynamic  collations  will  be  removed  from  memory  using  FreeCollation  (1737   ).
                This must normally be set to true.

    See also:    RegisterCollation (1739   ), UnRegisterCollation (1742   ), LoadCollation (1738   ), FreeCollation
                (1737   )



                79.4          TUCA __DataBook


                TUCA_DataBook  =  record
                public
                    Base  :  PUCA_DataBook;
                    Version  :  TCollationName;
                    CollationName  :  TCollationName;
                    VariableWeight  :  TUCA_VariableKind;
                    Backwards  :  Array[0..3]  of  Boolean;
                    BMP_Table1  :  PByte;
                    BMP_Table2  :  PUInt24;
                    OBMP_Table1  :  PWord;



                                                                                1742

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                   OBMP_Table2  :  PUInt24;
                   PropCount  :  Integer;
                   Props  :  PUCA_PropItemRec;
                   VariableLowLimit  :  Word;
                   VariableHighLimit  :  Word;
                   Dynamic  :  Boolean;
                   function  IsVariable(const  AWeight:  PUCA_PropWeights)  :  Boolean;
                end



                TUCA_DataBook  describes  a  Unicode  Collation  Alghorithm  data  set.  data  sets  can  be  reg-
                istered using the RegisterCollation (1739   ) function or loaded from file using LoadCollation
                (1738   ).  A collation data book must be specified when comparing unicode strings.



                79.4.1         Method  overview

                __Page______Method____________Description__________________________________________________________________________*
 *___________
                __1743______IsVariable________Check_if_a_weight_is_a_variable_weight_______________________________________________*
 *___________



                79.4.2         TUCA__DataBook.IsVariable

    Synopsis:    Check if a weight is a variable weight

Declaration:     function  IsVariable(const  AWeight:  PUCA_PropWeights)  :  Boolean

    Visibility:   public

Description:     IsVariable checks whether AWeight is between the VariableLowLimit and VariableHighLimit
                limits.



                79.5          TUCA __PropItemContextRec


                TUCA_PropItemContextRec  =  packed  record
                public
                    CodePointCount  :  Byte;
                    WeightCount  :  Byte;
                    function  GetCodePoints  :  PUInt24;
                    function  GetWeights  :  PUCA_PropWeights;
                end



                This is an internal structure which should not be used directly, the actual structure is subject
                to change.



                79.5.1         Method  overview

                __Page______Method___________________Description___________________________________________________________________*
 *___________
                  1744      GetCodePoints            get the address of actual code points.
                __1744______GetWeights_______________Get_the_Address_of_actual_weights.____________________________________________*
 *___________



                                                                                1743

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.5.2         TUCA__PropItemContextRec.GetCodePoints

    Synopsis:    get the address of actual code points.

Declaration:     function  GetCodePoints  :  PUInt24

    Visibility:   public



                79.5.3         TUCA__PropItemContextRec.GetWeights

    Synopsis:    Get the Address of actual weights.

Declaration:     function  GetWeights  :  PUCA_PropWeights

    Visibility:   public



                79.6          TUCA __PropItemContextTreeNodeRec


                TUCA_PropItemContextTreeNodeRec  =  packed  record
                public
                    Left  :  Word;
                    Right  :  Word;
                    Data  :  TUCA_PropItemContextRec;
                    function  GetLeftNode  :  PUCA_PropItemContextTreeNodeRec;
                    function  GetRightNode  :  PUCA_PropItemContextTreeNodeRec;
                end



                This  is  an  internal  structure  for  the  tree  which  should  not  be  used  directly,  the  actual
                structure is subject to change.



                79.6.1         Method  overview

                __Page______Method__________________Description____________________________________________________________________*
 *___________
                  1744      GetLeftNode             Access to left tree node data
                __1744______GetRightNode____________Access_to_right_tree_node_data_________________________________________________*
 *___________



                79.6.2         TUCA__PropItemContextTreeNodeRec.GetLeftNode

    Synopsis:    Access to left tree node data

Declaration:     function  GetLeftNode  :  PUCA_PropItemContextTreeNodeRec

    Visibility:   public



                79.6.3         TUCA__PropItemContextTreeNodeRec.GetRightNode

    Synopsis:    Access to right tree node data

Declaration:     function  GetRightNode  :  PUCA_PropItemContextTreeNodeRec

    Visibility:   public



                                                                                1744

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.7          TUCA __PropItemContextTreeRec


                TUCA_PropItemContextTreeRec  =  packed  record
                public
                    Size  :  UInt24;
                    function  GetData  :  PUCA_PropItemContextTreeNodeRec;
                    property  Data  :  PUCA_PropItemContextTreeNodeRec;
                    function  Find(const  AChars:  PUInt24;const  ACharCount:  Integer;
                                         out  ANode:  PUCA_PropItemContextTreeNodeRec)  :  Boolean;
                end



                This is an internal tree structure for storing unicode collation data which should not be used
                directly, the actual structure is subject to change.



                79.7.1         Method  overview

                __Page______Method__________Description____________________________________________________________________________*
 *___________
                  1745      Find            Find data for encoded character
                __1745______GetData_________Access_to_tree_data_(getter_for_Data_property)_________________________________________*
 *___________



                79.7.2         Property  overview

                __Page______Properties________Access_______Description_____________________________________________________________*
 *___________
                __1745______Data______________r____________Read-only_access_to_tree_data___________________________________________*
 *___________



                79.7.3         TUCA__PropItemContextTreeRec.GetData

    Synopsis:    Access to tree data (getter for Data property)

Declaration:     function  GetData  :  PUCA_PropItemContextTreeNodeRec

    Visibility:   public



                79.7.4         TUCA__PropItemContextTreeRec.Find

    Synopsis:    Find data for encoded character

Declaration:     function  Find(const  AChars:  PUInt24;const  ACharCount:  Integer;
                                      out  ANode:  PUCA_PropItemContextTreeNodeRec)  :  Boolean

    Visibility:   public

Description:     Find searches the tree for the collation data for the character encoded in AChars (ACharCount).
                It returns true if the data was found, false if not.  A pointer to the collation data is returned
                in ANode.



                79.7.5         TUCA__PropItemContextTreeRec.Data

    Synopsis:    Read-only access to tree data

Declaration:     Property  Data  :  PUCA_PropItemContextTreeNodeRec

    Visibility:   public

      Access:    Read



                                                                                1745

_______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________________________*
 *___



79.8          TUCA __PropItemRec


TUCA_PropItemRec  =  packed  record
private
    FLAG_VALID  =  0;
    FLAG_CODEPOINT  =  1;
    FLAG_CONTEXTUAL  =  2;
    FLAG_DELETION  =  3;
    FLAG_COMPRESS_WEIGHT_1  =  6;
    FLAG_COMPRESS_WEIGHT_2  =  7;
    function  GetCodePoint  :  UInt24;
public
    WeightLength  :  Byte;
    ChildCount  :  Byte;
    Size  :  Word;
    Flags  :  Byte;
    function  HasCodePoint  :  Boolean;
    property  CodePoint  :  UInt24;
    function  IsValid  :  Boolean;
    procedure  GetWeightArray(ADest:  PUCA_PropWeights);
    function  GetSelfOnlySize  :  Cardinal;
    function  GetContextual  :  Boolean;
    property  Contextual  :  Boolean;
    function  GetContext  :  PUCA_PropItemContextTreeRec;
    function  IsDeleted  :  Boolean;
    function  IsWeightCompress_1  :  Boolean;
    function  IsWeightCompress_2  :  Boolean;
end



TUCA_PropItemRec encodes 1 entry from the Unicode Collation data in an encoded form.



79.8.1         Method  overview

__Page______Method____________________________Description_____________________________________________________________________
  1747      GetContext                        Access to context data
  1747      GetContextual                     Check if the contextual bit is set in the flags (getter for
                                              Contextual)
  1747      GetSelfOnlySize                   Size of this item data (in bytes).
  1747      GetWeightArray                    Return an array of weights
  1747      HasCodePoint                      Check flags whether a codepoint is present.
  1748      IsDeleted                         Check flags if deleted bit is set
  1747      IsValid                           Check flags for validity
  1748      IsWeightCompress\_1               Check whether weight compression flag 1 is set
__1748______IsWeightCompress\_2_______________Check_whether_weight_compression_flag_2_is_set__________________________________



79.8.2         Property  overview

__Page______Properties_________Access_______Description_______________________________________________________________________
  1748      CodePoint          r            Get the codepoint
__1748______Contextual_________r____________Check_if_the_contextual_bit_is_set_in_the_flags___________________________________



                                                                1746

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.8.3         TUCA__PropItemRec.HasCodePoint

    Synopsis:    Check flags whether a codepoint is present.

Declaration:     function  HasCodePoint  :  Boolean

    Visibility:   public



                79.8.4         TUCA__PropItemRec.IsValid

    Synopsis:    Check flags for validity

Declaration:     function  IsValid  :  Boolean

    Visibility:   public



                79.8.5         TUCA__PropItemRec.GetWeightArray

    Synopsis:    Return an array of weights

Declaration:     procedure  GetWeightArray(ADest:  PUCA_PropWeights)

    Visibility:   public

Description:     GetWeightArray returns an array with the weights in ADest.  ADest must point to enough
                room for WeightLength weights.



                79.8.6         TUCA__PropItemRec.GetSelfOnlySize

    Synopsis:    Size of this item data (in bytes).

Declaration:     function  GetSelfOnlySize  :  Cardinal

    Visibility:   public

Description:     Return the size of the item's data and properties.



                79.8.7         TUCA__PropItemRec.GetContextual

    Synopsis:    Check if the contextual bit is set in the flags (getter for Contextual)

Declaration:     function  GetContextual  :  Boolean

    Visibility:   public



                79.8.8         TUCA__PropItemRec.GetContext

    Synopsis:    Access to context data

Declaration:     function  GetContext  :  PUCA_PropItemContextTreeRec

    Visibility:   public

Description:     GetContext returns a pointer to the context data.  It is Nil if the context flag is not set.



                                                                                1747

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.8.9         TUCA__PropItemRec.IsDeleted

    Synopsis:    Check flags if deleted bit is set

Declaration:     function  IsDeleted  :  Boolean

    Visibility:   public



                79.8.10          TUCA__PropItemRec.IsWeightCompress__1

    Synopsis:    Check whether weight compression flag 1 is set

Declaration:     function  IsWeightCompress_1  :  Boolean

    Visibility:   public



                79.8.11          TUCA__PropItemRec.IsWeightCompress__2

    Synopsis:    Check whether weight compression flag 2 is set

Declaration:     function  IsWeightCompress_2  :  Boolean

    Visibility:   public



                79.8.12          TUCA__PropItemRec.CodePoint

    Synopsis:    Get the codepoint

Declaration:     Property  CodePoint  :  UInt24

    Visibility:   public

      Access:    Read

Description:     Access to codepoint if  HasCodePoint returns true.  If  HasCodePoint returns false, an ex-
                ception will be raised.



                79.8.13          TUCA__PropItemRec.Contextual

    Synopsis:    Check if the contextual bit is set in the flags

Declaration:     Property  Contextual  :  Boolean

    Visibility:   public

      Access:    Read



                79.9          TUC __Prop


                TUC_Prop  =  packed  record
                private
                    function  GetCategory  :  Byte;
                    procedure  SetCategory(AValue:  Byte);
                    function  GetWhiteSpace  :  Boolean;
                    procedure  SetWhiteSpace(AValue:  Boolean);
                    function  GetHangulSyllable  :  Boolean;



                                                                                1748

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                   procedure  SetHangulSyllable(AValue:  Boolean);
                   function  GetNumericValue  :  Double;
                public
                   CategoryData  :  Byte;
                   CCC  :  Byte;
                   NumericIndex  :  Byte;
                   SimpleUpperCase  :  UInt24;
                   SimpleLowerCase  :  UInt24;
                   DecompositionID  :  SmallInt;
                   property  Category  :  Byte;
                   property  WhiteSpace  :  Boolean;
                   property  HangulSyllable  :  Boolean;
                   property  NumericValue  :  Double;
                end



                TUC_Prop  describes  the  collation  characteristics  of  a  unicode  character.   It  is  an  internal
                structure which should not be used directly, the actual structure is subject to change.



                79.9.1         Property  overview

                __Page______Properties_______________Access_______Description______________________________________________________*
 *___________
                  1749      Category                 rw           Get the category
                  1750      HangulSyllable           rw           Is the character a hangul syllable
                  1750      NumericValue             r            Numeric value
                __1749______WhiteSpace_______________rw___________Is_the_character_considered_whitespace___________________________*
 *___________



                79.9.2         TUC__Prop.Category

    Synopsis:    Get the category

Declaration:     Property  Category  :  Byte

    Visibility:   public

      Access:    Read,Write

Description:     CategoryData provides access to the category part of CategoryData (encoded).



                79.9.3         TUC__Prop.WhiteSpace

    Synopsis:    Is the character considered whitespace

Declaration:     Property  WhiteSpace  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Whitespace provides easy access to the Whitespace part of CategoryData (encoded).



                                                                                1749

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.9.4         TUC__Prop.HangulSyllable

    Synopsis:    Is the character a hangul syllable

Declaration:     Property  HangulSyllable  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Whitespace provides easy access to the HangulSyllable part of CategoryData (encoded).



                79.9.5         TUC__Prop.NumericValue

    Synopsis:    Numeric value

Declaration:     Property  NumericValue  :  Double

    Visibility:   public

      Access:    Read

Description:     NumericValue uses numericalindex to get the numerical value.



                79.10            TUInt24Rec


                TUInt24Rec  =  packed  record
                public
                    byte2  :  Byte;
                    byte1  :  Byte;
                    byte0  :  Byte;
                    TUInt24Rec.class  operator  implicit(a:  TUInt24Rec)  :  Cardinal;
                    TUInt24Rec.class  operator  implicit(a:  TUInt24Rec)  :  LongInt;
                    TUInt24Rec.class  operator  implicit(a:  TUInt24Rec)  :  Word;
                    TUInt24Rec.class  operator  implicit(a:  TUInt24Rec)  :  Byte;
                    TUInt24Rec.class  operator  implicit(a:  Cardinal)  :  TUInt24Rec;
                    TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  TUInt24Rec)  :  Boolean;
                    TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  Cardinal)  :  Boolean;
                    TUInt24Rec.class  operator  equal(a:  Cardinal;b:  TUInt24Rec)  :  Boolean;
                    TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  LongInt)  :  Boolean;
                    TUInt24Rec.class  operator  equal(a:  LongInt;b:  TUInt24Rec)  :  Boolean;
                    TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  Word)  :  Boolean;
                    TUInt24Rec.class  operator  equal(a:  Word;b:  TUInt24Rec)  :  Boolean;
                    TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  Byte)  :  Boolean;
                    TUInt24Rec.class  operator  equal(a:  Byte;b:  TUInt24Rec)  :  Boolean;
                    TUInt24Rec.class  operator  notequal(a:  TUInt24Rec;b:  TUInt24Rec)
                                                                             :  Boolean;
                    TUInt24Rec.class  operator  notequal(a:  TUInt24Rec;b:  Cardinal)  :  Boolean;
                    TUInt24Rec.class  operator  notequal(a:  Cardinal;b:  TUInt24Rec)  :  Boolean;
                    TUInt24Rec.class  operator  greaterthan(a:  TUInt24Rec;b:  TUInt24Rec)
                                                                                  :  Boolean;
                    TUInt24Rec.class  operator  greaterthan(a:  TUInt24Rec;b:  Cardinal)
                                                                                  :  Boolean;
                    TUInt24Rec.class  operator  greaterthan(a:  Cardinal;b:  TUInt24Rec)
                                                                                  :  Boolean;



                                                                                1750

_______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________________________*
 *___



   TUInt24Rec.class  operator  greaterthanorequal(a:  TUInt24Rec;
                                                                           b:  TUInt24Rec)  :  Boolean;
   TUInt24Rec.class  operator  greaterthanorequal(a:  TUInt24Rec;b:  Cardinal)
                                                                             :  Boolean;
   TUInt24Rec.class  operator  greaterthanorequal(a:  Cardinal;b:  TUInt24Rec)
                                                                             :  Boolean;
   TUInt24Rec.class  operator  lessthan(a:  TUInt24Rec;b:  TUInt24Rec)
                                                             :  Boolean;
   TUInt24Rec.class  operator  lessthan(a:  TUInt24Rec;b:  Cardinal)  :  Boolean;
   TUInt24Rec.class  operator  lessthan(a:  Cardinal;b:  TUInt24Rec)  :  Boolean;
   TUInt24Rec.class  operator  lessthanorequal(a:  TUInt24Rec;b:  TUInt24Rec)
                                                                        :  Boolean;
   TUInt24Rec.class  operator  lessthanorequal(a:  TUInt24Rec;b:  Cardinal)
                                                                        :  Boolean;
   TUInt24Rec.class  operator  lessthanorequal(a:  Cardinal;b:  TUInt24Rec)
                                                                        :  Boolean;
end



Unicode data exists mostly of 24-bit data (3 bytes).  This type is meant to deal efficiently
with this data.  it has members to split out the data in bytes,  and functions to query the
various properties stored in the data.



                                                                1751

_______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________________________*
 *___



                                                                1752

_______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________________________*
 *___



79.10.1         Method  overview

_Page_______Method________________________________________________________________________Description_________________________
  1756      equal(Byte,TUInt24Rec):Boolean                                                 Check      whether      a
                                                                                           TUInt24Rec          value
                                                                                           equals a byte value.
  1755      equal(Cardinal,TUInt24Rec):Boolean                                             Check      whether      a
                                                                                           TUInt24Rec          value
                                                                                           equals a cardinal value.
  1756      equal(LongInt,TUInt24Rec):Boolean                                              Check      whether      a
                                                                                           TUInt24Rec          value
                                                                                           equals a longint value.
  1756      equal(TUInt24Rec,Byte):Boolean                                                 Check      whether      a
                                                                                           TUInt24Rec          value
                                                                                           equals a byte value.
  1755      equal(TUInt24Rec,Cardinal):Boolean                                             Check  if  cardinal  and
                                                                                           TUInt24Rec are equal
  1755      equal(TUInt24Rec,LongInt):Boolean                                              Check      whether      a
                                                                                           TUInt24Rec          value
                                                                                           equals a longint value.
  1755      equal(TUInt24Rec,TUInt24Rec):Boolean                                           Determine equality of 2
                                                                                           TUInt24Rec records
  1756      equal(TUInt24Rec,Word):Boolean                                                 Check      whether      a
                                                                                           TUInt24Rec          value
                                                                                           equals a word value.
  1756      equal(Word,TUInt24Rec):Boolean                                                 Check      whether      a
                                                                                           TUInt24Rec          value
                                                                                           equals a word value.
  1757      greaterthan(Cardinal,TUInt24Rec):Boolean                                       Check  whether  a  cardi-
                                                                                           nal value is greater than
                                                                                           a TUInt24Rec value
  1758      greaterthanorequal(Cardinal,TUInt24Rec):Boolean                                Check  whether  a  car-
                                                                                           dinal   value   is   greater
                                                                                           than   or   equal   to   a
                                                                                           TUInt24Rec value
  1758      greaterthanorequal(TUInt24Rec,Cardinal):Boolean                                Check      whether      a
                                                                                           TUInt24Rec    value    is
                                                                                           greater than or equal to
                                                                                           a cardinal value
  1758      greaterthanorequal(TUInt24Rec,TUInt24Rec):Boolean                              Check      whether      a
                                                                                           TUInt24Rec    value    is
                                                                                           greater than or equal to
                                                                                           a cardinal value
  1757      greaterthan(TUInt24Rec,Cardinal):Boolean                                       Check      whether      a
                                                                                           TUInt24Rec    value    is
                                                                                           greater  than  a  cardinal
                                                                                           value
  1757      greaterthan(TUInt24Rec,TUInt24Rec):Boolean                                     Check      whether      a
                                                                                           TUInt24Rec    value    is
                                                                                           greater    than    another
                                                                                           TUInt24Rec value
  1755      implicit(Cardinal):TUInt24Rec                                                  Assign TUInt24Recfrom
                                                                                           Cardinal
  1754      implicit(TUInt24Rec):Byte                                                      Assign   TUInt24Rec   to
                                                                                           byte
  1754      implicit(TUInt24Rec):Cardinal                                                  Assign   TUInt24Rec   to
                                                                1753                       cardinal
  1754      implicit(TUInt24Rec):LongInt                                                   Assign   TUInt24Rec   to
                                                                                           longint
  1754      implicit(TUInt24Rec):Word                                                      Assign   TUInt24Rec   to
                                                                                           word
  1759      lessthan(Cardinal,TUInt24Rec):Boolean                                          Check  whether  a  cardi-
                                                                                           nal  value  is  less  than  a
                                                                                           TUInt24Rec value
  1759      lessthanorequal(Cardinal,TUInt24Rec):Boolean                                   Check  whether  a  cardi-
                                                                                           nal value is less than or
                                                                                           equal  to  a  TUInt24Rec
                                                                                           value
  1759      lessthanorequal(TUInt24Rec,Cardinal):Boolean                                   Check      whether      a
                                                                                           TUInt24Rec    value    is
                                                                                           less  than  or  equal  to  a
                                                                                           cardinal value
  1759      lessthanorequal(TUInt24Rec,TUInt24Rec):Boolean                                 Check      whether      a
                                                                                           TUInt24Rec    value    is
                                                                                           less   than   or   equal   to
                                                                                           another      TUInt24Rec
                                                                                           value
  1758      lessthan(TUInt24Rec,Cardinal):Boolean                                          Check      whether      a
                                                                                           TUInt24Rec    value    is
                                                                                           less   than   a   cardinal
                                                                                           value
  1758      lessthan(TUInt24Rec,TUInt24Rec):Boolean                                        Check      whether      a
                                                                                           TUInt24Rec          value
                                                                                           is   less   than   another
                                                                                           TUInt24Rec value
  1757      notequal(Cardinal,TUInt24Rec):Boolean                                          Check      whether      a
                                                                                           TUInt24Rec   value   dif-
                                                                                           fers   from   a   cardinal
                                                                                           value.
  1757      notequal(TUInt24Rec,Cardinal):Boolean                                          Check      whether      a
                                                                                           TUInt24Rec   value   dif-
                                                                                           fers   from   a   cardinal
                                                                                           value.
  1756      notequal(TUInt24Rec,TUInt24Rec):Boolean                                        Check      whether      2
                                                                                           TUInt24Rec        values
___________________________________________________________________________________________differ.____________________________

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.10.2          TUInt24Rec.implicit(TUInt24Rec):Cardinal

    Synopsis:    Assign TUInt24Rec to cardinal

Declaration:     TUInt24Rec.class  operator  implicit(a:  TUInt24Rec)  :  Cardinal

    Visibility:   public

Description:     Assign to cardinal, byte0 to MSB and so on.

    See also:    TUInt24Rec.implicit(TUInt24Rec):LongInt (1754   ), TUInt24Rec.implicit(TUInt24Rec):Word
                (1754   ), TUInt24Rec.implicit(TUInt24Rec):Byte (1754   ), TUInt24Rec.implicit(Cardinal):TUInt24Rec
                (1755   ), TUInt24Rec.implicit(Longint):TUInt24Rec (1751   ), TUInt24Rec.implicit(Word):TUInt24Rec
                (1751   ), TUInt24Rec.implicit(Byte):TUInt24Rec (1751   )



                79.10.3          TUInt24Rec.implicit(TUInt24Rec):LongInt

    Synopsis:    Assign TUInt24Rec to longint

Declaration:     TUInt24Rec.class  operator  implicit(a:  TUInt24Rec)  :  LongInt

    Visibility:   public

Description:     Assign to cardinal, byte0 to MSB and so on.

    See also:    TUInt24Rec.implicit(TUInt24Rec):Cardinal (1754   ), TUInt24Rec.implicit(TUInt24Rec):Word
                (1754   ), TUInt24Rec.implicit(TUInt24Rec):Byte (1754   )



                79.10.4          TUInt24Rec.implicit(TUInt24Rec):Word

    Synopsis:    Assign TUInt24Rec to word

Declaration:     TUInt24Rec.class  operator  implicit(a:  TUInt24Rec)  :  Word

    Visibility:   public

Description:     Assign to word, byte0 to MSB, byte1 to MSB.

       Errors:   If the value is too big (>$FFFF) to be assigned, an overflow error occurs.

    See also:    TUInt24Rec.implicit(TUInt24Rec):Cardinal (1754   ), TUInt24Rec.implicit(TUInt24Rec):Longint
                (1754   ), TUInt24Rec.implicit(TUInt24Rec):Byte (1754   ), TUInt24Rec.implicit(Cardinal):TUInt24Rec
                (1755   ), TUInt24Rec.implicit(Longint):TUInt24Rec (1751   ), TUInt24Rec.implicit(Word):TUInt24Rec
                (1751   ), TUInt24Rec.implicit(Byte):TUInt24Rec (1751   )



                79.10.5          TUInt24Rec.implicit(TUInt24Rec):Byte

    Synopsis:    Assign TUInt24Rec to byte

Declaration:     TUInt24Rec.class  operator  implicit(a:  TUInt24Rec)  :  Byte

    Visibility:   public

Description:     Assign to byte, byte0 is assigned.

       Errors:   If the value is too big (>$FF) to be assigned, an overflow error occurs.

    See also:    TUInt24Rec.implicit(TUInt24Rec):Cardinal (1754   ), TUInt24Rec.implicit(TUInt24Rec):Longint
                (1754   ), TUInt24Rec.implicit(TUInt24Rec):Word (1754   ), TUInt24Rec.implicit(Cardinal):TUInt24Rec
                (1755   ), TUInt24Rec.implicit(Longint):TUInt24Rec (1751   ), TUInt24Rec.implicit(Word):TUInt24Rec
                (1751   ), TUInt24Rec.implicit(Byte):TUInt24Rec (1751   )



                                                                                1754

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.10.6          TUInt24Rec.implicit(Cardinal):TUInt24Rec

    Synopsis:    Assign TUInt24Recfrom Cardinal

Declaration:     TUInt24Rec.class  operator  implicit(a:  Cardinal)  :  TUInt24Rec

    Visibility:   public

Description:     Assign from cardinal, byte0 to MSB.

       Errors:   If the value is too big (>$FFFFFF) to be assigned, an overflow error occurs.

    See also:    TUInt24Rec.implicit(TUInt24Rec):Longint (1754   ), TUInt24Rec.implicit(TUInt24Rec):Word
                (1754   ), TUInt24Rec.implicit(TUInt24Rec):Byte (1754   ), TUInt24Rec.implicit(Longint):TUInt24Rec
                (1751   ), TUInt24Rec.implicit(Word):TUInt24Rec (1751   ), TUInt24Rec.implicit(Byte):TUInt24Rec
                (1751   )



                79.10.7          TUInt24Rec.equal(TUInt24Rec,TUInt24Rec):Boolean

    Synopsis:    Determine equality of 2 TUInt24Rec records

Declaration:     TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  TUInt24Rec)  :  Boolean

    Visibility:   public

Description:     The 2 records are considered equal if the 3 bytes are equal.



                79.10.8          TUInt24Rec.equal(TUInt24Rec,Cardinal):Boolean

    Synopsis:    Check if cardinal and TUInt24Rec are equal

Declaration:     TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  Cardinal)  :  Boolean

    Visibility:   public

Description:     The cardinal b is considered equal to a if the fourth byte (LSB) is zero, and the first three
                bytes equal byte0, byte1, and byte2.



                79.10.9          TUInt24Rec.equal(Cardinal,TUInt24Rec):Boolean

    Synopsis:    Check whether a TUInt24Rec value equals a cardinal value.

Declaration:     TUInt24Rec.class  operator  equal(a:  Cardinal;b:  TUInt24Rec)  :  Boolean

    Visibility:   public

Description:     The cardinal a is considered equal to b if the fourth byte (LSB) is zero, and the first three
                bytes equal byte0, byte1, and byte2.



                79.10.10           TUInt24Rec.equal(TUInt24Rec,LongInt):Boolean

    Synopsis:    Check whether a TUInt24Rec value equals a longint value.

Declaration:     TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  LongInt)  :  Boolean

    Visibility:   public

Description:     The longint b is considered equal to a if the fourth byte (LSB) is zero, and the first three
                bytes equal byte0, byte1, and byte2.



                                                                                1755

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.10.11           TUInt24Rec.equal(LongInt,TUInt24Rec):Boolean

    Synopsis:    Check whether a TUInt24Rec value equals a longint value.

Declaration:     TUInt24Rec.class  operator  equal(a:  LongInt;b:  TUInt24Rec)  :  Boolean

    Visibility:   public

Description:     The longint a is considered equal to b if the fourth byte (LSB) is zero, and the first three
                bytes equal byte0, byte1, and byte2.



                79.10.12           TUInt24Rec.equal(TUInt24Rec,Word):Boolean

    Synopsis:    Check whether a TUInt24Rec value equals a word value.

Declaration:     TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  Word)  :  Boolean

    Visibility:   public

Description:     The word b is considered equal to a if its 2 bytes equal byte0, byte1 and byte2 is zero.



                79.10.13           TUInt24Rec.equal(Word,TUInt24Rec):Boolean

    Synopsis:    Check whether a TUInt24Rec value equals a word value.

Declaration:     TUInt24Rec.class  operator  equal(a:  Word;b:  TUInt24Rec)  :  Boolean

    Visibility:   public

Description:     The word a is considered equal to b if its 2 bytes equal byte0, byte1 and byte2 is zero.



                79.10.14           TUInt24Rec.equal(TUInt24Rec,Byte):Boolean

    Synopsis:    Check whether a TUInt24Rec value equals a byte value.

Declaration:     TUInt24Rec.class  operator  equal(a:  TUInt24Rec;b:  Byte)  :  Boolean

    Visibility:   public

Description:     The byte b is considered equal to a if it equals byte0 and byte1 and byte1 are zero.



                79.10.15           TUInt24Rec.equal(Byte,TUInt24Rec):Boolean

    Synopsis:    Check whether a TUInt24Rec value equals a byte value.

Declaration:     TUInt24Rec.class  operator  equal(a:  Byte;b:  TUInt24Rec)  :  Boolean

    Visibility:   public

Description:     The byte b is considered equal to a if it equals byte0 and byte1 and byte1 are zero.



                79.10.16           TUInt24Rec.notequal(TUInt24Rec,TUInt24Rec):Boolean

    Synopsis:    Check whether 2 TUInt24Rec values differ.

Declaration:     TUInt24Rec.class  operator  notequal(a:  TUInt24Rec;b:  TUInt24Rec)
                                                                          :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing byte0, byte1 and byte2.



                                                                                1756

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.10.17           TUInt24Rec.notequal(TUInt24Rec,Cardinal):Boolean

    Synopsis:    Check whether a TUInt24Rec value differs from a cardinal value.

Declaration:     TUInt24Rec.class  operator  notequal(a:  TUInt24Rec;b:  Cardinal)  :  Boolean

    Visibility:   public

Description:     The cardinal a is considered not equal to b if the fourth byte (LSB) is nonzero, or one of
                the first three bytes differ from byte0, byte1, and byte2.



                79.10.18           TUInt24Rec.notequal(Cardinal,TUInt24Rec):Boolean

    Synopsis:    Check whether a TUInt24Rec value differs from a cardinal value.

Declaration:     TUInt24Rec.class  operator  notequal(a:  Cardinal;b:  TUInt24Rec)  :  Boolean

    Visibility:   public

Description:     The cardinal a is considered not equal to b if the fourth byte (LSB) is nonzero, or one of
                the first three bytes differ from byte0, byte1, and byte2.



                79.10.19           TUInt24Rec.greaterthan(TUInt24Rec,TUInt24Rec):Boolean

    Synopsis:    Check whether a TUInt24Rec value is greater than another TUInt24Rec value

Declaration:     TUInt24Rec.class  operator  greaterthan(a:  TUInt24Rec;b:  TUInt24Rec)
                                                                               :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing 3 bytes byte0, byte1 and byte2



                79.10.20           TUInt24Rec.greaterthan(TUInt24Rec,Cardinal):Boolean

    Synopsis:    Check whether a TUInt24Rec value is greater than a cardinal value

Declaration:     TUInt24Rec.class  operator  greaterthan(a:  TUInt24Rec;b:  Cardinal)
                                                                               :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing 3 first bytes of the cardinal value with bytes byte0,
                byte1 and byte2.



                79.10.21           TUInt24Rec.greaterthan(Cardinal,TUInt24Rec):Boolean

    Synopsis:    Check whether a cardinal value is greater than a TUInt24Rec value

Declaration:     TUInt24Rec.class  operator  greaterthan(a:  Cardinal;b:  TUInt24Rec)
                                                                               :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing 3 first bytes of the cardinal value with bytes byte0,
                byte1 and byte2.



                                                                                1757

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.10.22           TUInt24Rec.greaterthanorequal(TUInt24Rec,TUInt24Rec):Boolean

    Synopsis:    Check whether a TUInt24Rec value is greater than or equal to a cardinal value

Declaration:     TUInt24Rec.class  operator  greaterthanorequal(a:  TUInt24Rec;
                                                                                         b:  TUInt24Rec)  :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing 3 first bytes of the cardinal value with bytes byte0,
                byte1 and byte2.



                79.10.23           TUInt24Rec.greaterthanorequal(TUInt24Rec,Cardinal):Boolean

    Synopsis:    Check whether a TUInt24Rec value is greater than or equal to a cardinal value

Declaration:     TUInt24Rec.class  operator  greaterthanorequal(a:  TUInt24Rec;b:  Cardinal)
                                                                                          :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing 3 first bytes of the cardinal value with bytes byte0,
                byte1 and byte2.



                79.10.24           TUInt24Rec.greaterthanorequal(Cardinal,TUInt24Rec):Boolean

    Synopsis:    Check whether a cardinal value is greater than or equal to a TUInt24Rec value

Declaration:     TUInt24Rec.class  operator  greaterthanorequal(a:  Cardinal;b:  TUInt24Rec)
                                                                                          :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing 3 first bytes of the cardinal value with bytes byte0,
                byte1 and byte2.



                79.10.25           TUInt24Rec.lessthan(TUInt24Rec,TUInt24Rec):Boolean

    Synopsis:    Check whether a TUInt24Rec value is less than another TUInt24Rec value

Declaration:     TUInt24Rec.class  operator  lessthan(a:  TUInt24Rec;b:  TUInt24Rec)
                                                                          :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing the bytes byte0, byte1 and byte2.



                79.10.26           TUInt24Rec.lessthan(TUInt24Rec,Cardinal):Boolean

    Synopsis:    Check whether a TUInt24Rec value is less than a cardinal value

Declaration:     TUInt24Rec.class  operator  lessthan(a:  TUInt24Rec;b:  Cardinal)  :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing 3 first bytes of the cardinal value with bytes byte0,
                byte1 and byte2.



                                                                                1758

                _______________________________________________CHAPTER_79.___REFERENCE_FOR_UNIT_'UNICODEDATA'______________________*
 *___________________



                79.10.27           TUInt24Rec.lessthan(Cardinal,TUInt24Rec):Boolean

    Synopsis:    Check whether a cardinal value is less than a TUInt24Rec value

Declaration:     TUInt24Rec.class  operator  lessthan(a:  Cardinal;b:  TUInt24Rec)  :  Boolean

    Visibility:   public

Description:     Check whether a cardinal value is less than a TUInt24Rec value



                79.10.28           TUInt24Rec.lessthanorequal(TUInt24Rec,TUInt24Rec):Boolean

    Synopsis:    Check whether a TUInt24Rec value is less than or equal to another TUInt24Rec value

Declaration:     TUInt24Rec.class  operator  lessthanorequal(a:  TUInt24Rec;b:  TUInt24Rec)
                                                                                     :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing the bytes byte0, byte1 and byte2.



                79.10.29           TUInt24Rec.lessthanorequal(TUInt24Rec,Cardinal):Boolean

    Synopsis:    Check whether a TUInt24Rec value is less than or equal to a cardinal value

Declaration:     TUInt24Rec.class  operator  lessthanorequal(a:  TUInt24Rec;b:  Cardinal)
                                                                                     :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing 3 first bytes of the cardinal value with bytes byte0,
                byte1 and byte2.



                79.10.30           TUInt24Rec.lessthanorequal(Cardinal,TUInt24Rec):Boolean

    Synopsis:    Check whether a cardinal value is less than or equal to a TUInt24Rec value

Declaration:     TUInt24Rec.class  operator  lessthanorequal(a:  Cardinal;b:  TUInt24Rec)
                                                                                     :  Boolean

    Visibility:   public

Description:     The comparison is done by comparing 3 first bytes of the cardinal value with bytes byte0,
                byte1 and byte2.



                                                                                1759




Chapter   80



Reference   for   unit



'unicodeducet'



80.1          Overview


The unicodeducet unit registers the root Unicode collation (DUCET). This collation is needed
by all other collations, so any collation unit will include this file.

This unit does not contain any routines.  It simply registers the collation in the initialization
section of the unit, so including the unit in the uses clause of the program is sufficient.



                                                            1760




Chapter   81



Reference   for   unit   'Unix'



81.1          Used  units



                                     Table 81.1:  Used units by unit 'Unix'


                                                  _Name_____________Page______
                                                    BaseUnix           113
                                                    System           1235
                                                    unixtype         1798



81.2          Constants,  types  and  variables



81.2.1         Constants

ARG_MAX  =  UnixType  .  ARG_MAX


Maximum number of arguments to a program.


fs_ext  =  $137d


File system type (TStatFS (1776   )):  (ext) Extended


fs_ext2  =  $ef53


File system type (TStatFS (1776   )):  (ext2) Second extended


fs_iso  =  $9660


File system type (TStatFS (1776   )):  ISO 9660


fs_minix  =  $137f


File system type (TStatFS (1776   )):  Minix


fs_minix_30  =  $138f



                                                            1761

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



File system type (TStatFS (1776   )):  Minix 3.0


fs_minux_V2  =  $2468


File system type (TStatFS (1776   )):  Minix V2


fs_msdos  =  $4d44


File system type (TStatFS (1776   )):  MSDOS (FAT)


fs_nfs  =  $6969


File system type (TStatFS (1776   )):  NFS


fs_old_ext2  =  $ef51


File system type (TStatFS (1776   )):  (ext2) Old second extended


fs_proc  =  $9fa0


File system type (TStatFS (1776   )):  PROC fs


fs_xia  =  $012FD16D


File system type (TStatFS (1776   )):  XIA


IOCtl_TCGETS  =  $5401


IOCTL call number:  get Terminal Control settings


LOCK_EX  =  2


FpFLock (1785   ) Exclusive lock


LOCK_NB  =  4


FpFLock (1785   ) Non-blocking operation


LOCK_SH  =  1


FpFLock (1785   ) Shared lock


LOCK_UN  =  8


FpFLock (1785   ) unlock


MAP_FAILED  =  baseunix  .  MAP_FAILED


Error return value for mmap:  mmap operation failed.


MAP_FIXED  =  baseunix  .  MAP_FIXED



                                                                1762

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



#rtl.baseunix.FpMMap (178  ) map type:  Interpret addr exactly


MAP_PRIVATE  =  baseunix  .  MAP_PRIVATE


#rtl.baseunix.FpMMap (178  ) map type:  Changes are private


MAP_SHARED  =  baseunix  .  MAP_SHARED


#rtl.baseunix.FpMMap (178  ) map type:  Share changes


MAP_TYPE  =  baseunix  .  MAP_TYPE


#rtl.baseunix.FpMMap (178  ) map type:  Bitmask for type of mapping


MS_ASYNC  =  1deprecated


Asynchronous operation flag for msync call


MS_INVALIDATE  =  2deprecated


Invalidate other mappings of file flag for msync call


MS_SYNC  =  4deprecated


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



                                                                1763

______________________________________________________________CHAPTER_81.___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 (1764   )


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


#rtl.baseunix.fpGetPriority (172  ) option:  Get process group priority.


PRIO_PROCESS  =  UnixType  .  PRIO_PROCESS



                                                                1764

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



#rtl.baseunix.fpGetPriority (172  ) option:  Get process priority.


PRIO_USER  =  UnixType  .  PRIO_USER


#rtl.baseunix.fpGetPriority (172  ) option:  Get user priority.


PROT_EXEC  =  baseunix  .  PROT_EXEC


#rtl.baseunix.FpMMap (178  ) memory access:  page can be executed


PROT_NONE  =  baseunix  .  PROT_NONE


#rtl.baseunix.FpMMap (178  ) memory access:  page can not be accessed


PROT_READ  =  baseunix  .  PROT_READ


#rtl.baseunix.FpMMap (178  ) memory access:  page can be read


PROT_WRITE  =  baseunix  .  PROT_WRITE


#rtl.baseunix.FpMMap (178  ) 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 (149  ) record) mode:  Block device


STAT_IFCHR  =  $2000


File (#rtl.baseunix.stat (149  ) record) mode:  Character device


STAT_IFDIR  =  $4000


File (#rtl.baseunix.stat (149  ) record) mode:  Directory


STAT_IFIFO  =  $1000


File (#rtl.baseunix.stat (149  ) record) mode:  FIFO


STAT_IFLNK  =  $a000



                                                                1765

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



File (#rtl.baseunix.stat (149  ) record) mode:  Link


STAT_IFMT  =  $f000


File (#rtl.baseunix.stat (149  ) record) mode:  File type bit mask


STAT_IFREG  =  $8000


File (#rtl.baseunix.stat (149  ) record) mode:  Regular file


STAT_IFSOCK  =  $c000


File (#rtl.baseunix.stat (149  ) record) mode:  Socket


STAT_IRGRP  =  STAT_IROTH  shl  3


File (#rtl.baseunix.stat (149  ) record) mode:  Group read permission


STAT_IROTH  =  $4


File (#rtl.baseunix.stat (149  ) record) mode:  Other read permission


STAT_IRUSR  =  STAT_IROTH  shl  6


File (#rtl.baseunix.stat (149  ) record) mode:  Owner read permission


STAT_IRWXG  =  STAT_IRWXO  shl  3


File (#rtl.baseunix.stat (149  ) record) mode:  Group permission bits mask


STAT_IRWXO  =  $7


File (#rtl.baseunix.stat (149  ) record) mode:  Other permission bits mask


STAT_IRWXU  =  STAT_IRWXO  shl  6


File (#rtl.baseunix.stat (149  ) record) mode:  Owner permission bits mask


STAT_ISGID  =  $0400


File (#rtl.baseunix.stat (149  ) record) mode:  GID bit set


STAT_ISUID  =  $0800


File (#rtl.baseunix.stat (149  ) record) mode:  UID bit set


STAT_ISVTX  =  $0200


File (#rtl.baseunix.stat (149  ) record) mode:  Sticky bit set


STAT_IWGRP  =  STAT_IWOTH  shl  3



                                                                1766

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



File (#rtl.baseunix.stat (149  ) record) mode:  Group write permission


STAT_IWOTH  =  $2


File (#rtl.baseunix.stat (149  ) record) mode:  Other write permission


STAT_IWUSR  =  STAT_IWOTH  shl  6


File (#rtl.baseunix.stat (149  ) record) mode:  Owner write permission


STAT_IXGRP  =  STAT_IXOTH  shl  3


File (#rtl.baseunix.stat (149  ) record) mode:  Others execute permission


STAT_IXOTH  =  $1


File (#rtl.baseunix.stat (149  ) record) mode:  Others execute permission


STAT_IXUSR  =  STAT_IXOTH  shl  6


File (#rtl.baseunix.stat (149  ) record) mode:  Others execute permission


SYS_NMLN  =  UnixType  .  SYS_NMLN


Max system name length.


Wait_Any  =  -1


#rtl.baseunix.fpWaitPID (207  ):  Wait on any process


Wait_Clone  =  $80000000


#rtl.baseunix.fpWaitPID (207  ):  Wait on clone processes only.


Wait_MyPGRP  =  0


#rtl.baseunix.fpWaitPID (207  ):  Wait processes from current process group


Wait_NoHang  =  1


#rtl.baseunix.fpWaitPID (207  ):  Do not wait


Wait_UnTraced  =  2


#rtl.baseunix.fpWaitPID (207  ):  Also report stopped but untraced processes



                                                                1767

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



81.2.2         Types

cbool  =  UnixType.cbool


Boolean type


cchar  =  UnixType.cchar


Alias for #rtl.UnixType.cchar (1800   )


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)


clonglong  =  UnixType.clonglong


C type:  64-bit (double long) signed integer.


coff_t  =  UnixType.TOff



                                                                1768

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



character offset type.


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 (1768   ).


csint  =  UnixType.csint


Signed integer


csize_t  =  UnixType.size_t


Character size type.


cslong  =  UnixType.cslong


The size is CPU dependent.


cslonglong  =  UnixType.cslonglong


cslonglong is an alias for clonglong (1768   ).


csshort  =  UnixType.csshort


Short signed integer type


cuchar  =  UnixType.cuchar


Alias for #rtl.UnixType.cuchar (1801   )


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



                                                                1769

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



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 (1802   )


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 (1768   )


pcchar  =  UnixType.pcchar



                                                                1770

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Alias for #rtl.UnixType.pcchar (1803   )


pcdouble  =  UnixType.pcdouble


Pointer to cdouble (137  ) type.


pcfloat  =  UnixType.pcfloat


Pointer to cfloat (137  ) type.


pcint  =  UnixType.pcint


Pointer to cInt (1768   ) 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 (1775   ) type.


pclong  =  UnixType.pclong


Pointer to cLong (1768   ) type.


pclonglong  =  UnixType.pclonglong


Pointer to longlong type.


pcschar  =  UnixType.pcschar


Pointer to character type cschar (1769   ).


pcshort  =  UnixType.pcshort


Pointer to cShort (1769   ) type.


pcsigned  =  UnixType.pcsigned



                                                                1771

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Pointer to signed integer type csigned (1769   ).


pcsint  =  UnixType.pcsint


Pointer to signed integer type csint (1769   )


pcsize_t  =  UnixType.psize_t


Pointer to character size type pcsize_t.


pcslong  =  UnixType.pcslong


Pointer ot the signed long cslong (1769   )


pcslonglong  =  UnixType.pcslonglong


Pointer to Signed longlong type cslonglong (1769   )


pcsshort  =  UnixType.pcsshort


Pointer to short signed integer type csshort (1769   )


pcuchar  =  UnixType.pcuchar


Alias for #rtl.UnixType.pcuchar (1805   )


pcuint  =  UnixType.pcuint


Pointer to cUInt (1769   ) 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 (1770   ) type.


pculonglong  =  UnixType.pculonglong



                                                                1772

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Unsigned longlong type


pcunsigned  =  UnixType.pcunsigned


Alias for #rtl.unixtype.pcunsigned (1805   )


pcushort  =  UnixType.pcushort


Pointer to cuShort (1770   ) type.


pDev  =  UnixType.pDev


Pointer to TDev (1775   ) type.


pGid  =  UnixType.pGid


Pointer to TGid (1775   ) type.


pid_t  =  UnixType.pid_t


Process ID type.


pIno  =  UnixType.pIno


Pointer to TIno (1775   ) type.


pMode  =  UnixType.pMode


Pointer to TMode (1776   ) type.


pnLink  =  UnixType.pnLink


Pointer to TnLink (1776   ) type.


pOff  =  UnixType.pOff


Pointer to TOff (1776   ) type.


pPid  =  UnixType.pPid


Pointer to TPid (1776   ) type.


pSize  =  UnixType.pSize


Pointer to TSize (1776   ) type.


pSize_t  =  UnixType.pSize_t


Pointer to type Size_t.


pSocklen  =  UnixType.pSocklen



                                                                1773

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Pointer to TSockLen (1776   ) type.


psSize  =  UnixType.psSize


Pointer to TsSize (1776   ) type


pstatfs  =  UnixType.PStatFs


Pointer to statfs 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 (1776   ) type.


ptimespec  =  UnixType.ptimespec


Pointer to timespec (1775   ) type.


ptimeval  =  UnixType.ptimeval


Pointer to timeval (1775   ) type.


ptime_t  =  UnixType.ptime_t


Pointer to time_t (1775   ) type.


pUid  =  UnixType.pUid


Pointer to TUid (1776   ) type.


size_t  =  UnixType.size_t


Size specification type.


socklen_t  =  UnixType.socklen_t


Socket address length type.


ssize_t  =  UnixType.ssize_t



                                                                1774

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Small size type.


TClock  =  UnixType.TClock


Alias for clock_t (1768   ) type.


TDev  =  UnixType.TDev


Alias for dev_t (1770   ) type.


TFSearchOption  =  (NoCurrentDirectory,CurrentDirectoryFirst,
                             CurrentDirectoryLast)



                       Table 81.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.



Describes the search strategy used by FSearch (1787   )


TGid  =  UnixType.TGid


Alias for gid_t (1770   ) 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 (1770   ) type.


TIOCtlRequest  =  UnixType.TIOCtlRequest


Alias for the TIOCtlRequest (1810   ) type in unixtypes


TMode  =  UnixType.TMode



                                                                1775

______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Alias for mode_t (1770   ) type.


TnLink  =  UnixType.TnLink


Alias for nlink_t (1770   ) type.


TOff  =  UnixType.TOff


Alias for off_t (1770   ) type.


TPid  =  UnixType.TPid


Alias for pid_t (1773   ) type.


Tpipe  =  baseunix.tfildes  deprecated


Array describing a pipe pair of filedescriptors.


TSize  =  UnixType.TSize


Alias for size_t (1774   ) type


TSocklen  =  UnixType.TSocklen


Alias for socklen_t (1774   ) type.


TsSize  =  UnixType.TsSize


Alias for ssize_t (1775   ) type


tstatfs  =  UnixType.TStatFs


StatFS returns in Info information about the filesystem on which the file Path resides.  Info
is of type TStatFS (1811   ).

The  function  returns  zero  if  the  call  was  succesful,  a  nonzero  value  is  returned  if  the  call
failed.


TTime  =  UnixType.TTime


Alias for TTime (1776   ) type.


Ttimespec  =  UnixType.Ttimespec


Alias for TimeSpec (1775   ) type.


TTimeVal  =  UnixType.TTimeVal


Alias for timeval (1775   ) type.


TUid  =  UnixType.TUid


Alias for uid_t (1776   ) type.


uid_t  =  UnixType.uid_t


User ID type



                                                                1776

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                81.2.3         Variables

                tzdaylight  :  Boolean


                Indicates whether daylight savings time is active.


                tzname  :  Array[boolean]  of  PChar


                Timezone name.



                81.3          Procedures  and  functions



                81.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 (169  ) function:


                sys__emfile     Too many file descriptors for this process.

                sys__enfile    The system file table is full.


    See also:    POpen (1790   ), #rtl.baseunix.FpMkFifo (178  )


                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) ;



                                                                                1777

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                81.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 (169  ) 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 (1777   ), POpen (1790   )


                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 ;



                                                                                1778

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                       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  ;
                        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___.____________________________________________________________________________________________________________*
 *___________



                81.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.



                                                                                1779

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



       Errors:   Extended error information is returned by the FpGetErrno (169  ) 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:    FpExecve  (163  ),  FpExecv  (1782   ),  FpExecvp  (1783   ),  FpExecle  (1780   ),  FpExeclp  (1781   ),
                FpFork (166  )


                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___.____________________________________________________________________________________________________________*
 *___________



                81.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 (169  ) 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.



                                                                                1780

                ______________________________________________________________CHAPTER_81.___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:    FpExecve (163  ), FpExecv (1782   ), FpExecvp (1783   ), FpExecl (1779   ), FpExeclp (1781   ), Fp-
                Fork (166  )


                Listing:  ./unixex/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     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___.____________________________________________________________________________________________________________*
 *___________



                81.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 (169  ) 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:    FpExecve (163  ), FpExecv (1782   ), FpExecvp (1783   ), FpExecle (1780   ), FpExecl (1779   ), Fp-
                Fork (166  )


                Listing:  ./unixex/ex76.pp



                                                                                1781

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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.}
                    {  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___.____________________________________________________________________________________________________________*
 *___________



                81.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 (1781   ), 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 (1781   ), FpExecLE (1780   )



                81.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 (169  ) 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).



                                                                                1782

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



    See also:    FpExecve  (163  ),  FpExecvp  (1783   ),  FpExecle  (1780   ),  FpExecl  (1779   ),  FpExeclp  (1781   ),
                FpFork (166  )


                Listing:  ./unixex/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___.____________________________________________________________________________________________________________*
 *___________



                81.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 (169  ) 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:    FpExecve (163  ), FpExecv (1782   ), FpExecle (1780   ), FpExecl (1779   ), FpExeclp (1781   ), Fp-
                Fork (166  )



                                                                                1783

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                Listing:  ./unixex/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  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___.____________________________________________________________________________________________________________*
 *___________



                81.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 (169  ) 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:    FpExecve (163  ), FpExecv (1782   ), FpExecle (1780   ), FpExecl (1779   ), FpExeclp (1781   ), Fp-
                Fork (166  )



                                                                                1784

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                Listing:  ./unixex/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  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___.____________________________________________________________________________________________________________*
 *___________



                81.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 (169  ) function:

    See also:    #rtl.baseunix.FpFcntl (164  ), FSync (1761   )



                81.3.11          fpfStatFS

    Synopsis:    Retrieve filesystem information.

Declaration:     function  fpfStatFS(Fd:  cint;Info:  pstatfs)  :  cint



                                                                                1785

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



    Visibility:  default

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 (1786   ), #rtl.baseunix.fpfStat (167  )



                81.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.



                81.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.



                81.3.14          fpStatFS

    Synopsis:    Retrieve filesystem information.

Declaration:     function  fpStatFS(Path:  PChar;Info:  pstatfs)  :  cint
                function  fpStatFS(Path:  ansistring;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 (1785   ), #rtl.baseunix.fpStat (199  )



                                                                                1786

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                81.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 in wait(3) format, or 127 if it could not complete the FpFork (166  )
                or FpExecve (163  ) calls.  To convert the return value of fpsystem to the real return value use
                WEXITSTATUS() (209  ).

       Errors:   Errors are reported in (fpget)ErrNo (169  )

    See also:    POpen (1790   ), FpFork (166  ), FpExecve (163  )


                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___.____________________________________________________________________________________________________________*
 *___________



                81.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



                                                                                1787

                ______________________________________________________________CHAPTER_81.___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 (1813   )


                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___.____________________________________________________________________________________________________________*
 *___________



                81.3.17          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 (1788   )


                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___.____________________________________________________________________________________________________________*
 *___________



                81.3.18          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.



                                                                                1788

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



       Errors:   None.

    See also:    GetDomainName (1788   )


                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___.____________________________________________________________________________________________________________*
 *___________



                81.3.19          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 (1789   ), ReadTimezoneFile (1791   )



                81.3.20          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 (1791   )



                                                                                1789

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                81.3.21          PClose

    Synopsis:    Close file opened with POpen (1790   )

Declaration:     function  PClose(var  F:  File)  :  cint
                function  PClose(var  F:  text)  :  cint

    Visibility:   default

Description:     PClose closes a file opened with POpen (1790   ).  It waits for the command to complete, and
                then returns the exit status of the command.

                For an example, see POpen (1790   )

       Errors:   Extended error information is returned by the FpGetErrno (169  ) function.

    See also:    POpen (1790   )



                81.3.22          POpen

    Synopsis:    Pipe file to standard input/output of program

Declaration:     function  POpen(var  F:  text;const  Prog:  RawByteString;rw:  Char)  :  cint
                function  POpen(var  F:  File;const  Prog:  RawByteString;rw:  Char)  :  cint
                function  POpen(var  F:  text;const  Prog:  UnicodeString;rw:  Char)  :  cint
                function  POpen(var  F:  File;const  Prog:  UnicodeString;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 (1790   ).  The
                result is the same, but PClose returns the exit status of the command Prog.

       Errors:   Extended  error  information  is  returned  by  the  FpGetErrno  (169  )  function.   Errors  are
                essentially those of the Execve, Dup and AssignPipe commands.

    See also:    AssignPipe (1777   ), PClose (1790   )


                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. . . . ' ) ;



                                                                                1790

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                81.3.23          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 (1789   ), GetLocalTimezone (1789   )



                81.3.24          ReReadLocalTime

    Synopsis:    Re-Read the local time files.

Declaration:     procedure  ReReadLocalTime

    Visibility:   default

Description:     ReReadLocalTime can be used to re-initialize the local timezone information.

                To speed up conversion of epoch (UTC) time to local time, the timezone information is loaded
                only once, at program startup.  Calling this routine re-reads the timezone information using
                current timezone settings.

                The  EpochToLocal  (1814   )  function  uses  timezone  information  to  transform  epoch  time  to
                local time.  This timezone information does not change while the application is running:  in
                particular, on DST transitions or when the timezone files change, the time returned by local
                time routines will be wrong.

    See also:    Date (1543   ), Time (1639   ), Now (1607   ), EpochToLocal (1814   )



                                                                                1791

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                81.3.25          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 (183  ).

       Errors:   Extended error information is returned by the FpGetErrno (169  ) function:

    See also:    #rtl.baseunix.fpCloseDir  (160  ),  #rtl.baseunix.fpReadDir  (187  ),  #rtl.baseunix.fpOpenDir
                (183  ), TellDir (1793   )



                81.3.26          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  (190  )  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 (190  ).  SYS_EBADF can also mean that the file wasn't opened.

    See also:    #rtl.baseunix.FpSelect (190  )



                81.3.27          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 (174  ), #rtl.baseunix.FpGetPid (171  )


                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



                                                                                1792

                ______________________________________________________________CHAPTER_81.___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___.____________________________________________________________________________________________________________*
 *___________



                81.3.28          TellDir

    Synopsis:    Return current location in a directory

Declaration:     function  TellDir(p:  pDir)  :  TOff

    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 #rtl.baseunix.fpOpenDir (183  ).

    See also:    #rtl.baseunix.fpCloseDir  (160  ),  #rtl.baseunix.fpReadDir  (187  ),  #rtl.baseunix.fpOpenDir
                (183  ), SeekDir (1792   )



                81.3.29          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
                (207  ) 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



                                                                                1793

                ______________________________________________________________CHAPTER_81.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



       Errors:   None.

    See also:    #rtl.baseunix.FpWaitPID (207  ), #rtl.baseunix.WTERMSIG (210  ), #rtl.baseunix.WSTOPSIG
                (210  ), #rtl.baseunix.WIFEXITED (209  ), WIFSTOPPED (1794   ), #rtl.baseunix.WIFSIGNALED
                (209  ), W_EXITCODE (1794   ), W_STOPCODE (1794   ), #rtl.baseunix.WEXITSTATUS (209  )



                81.3.30          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 (207  ).

    See also:    #rtl.baseunix.FpWaitPID  (207  ),  WaitProcess  (1793   ),  #rtl.baseunix.WTERMSIG  (210  ),
                #rtl.baseunix.WSTOPSIG (210  ), #rtl.baseunix.WIFEXITED (209  ), #rtl.baseunix.WIFSIGNALED
                (209  ), W_EXITCODE (1794   ), W_STOPCODE (1794   ), #rtl.baseunix.WEXITSTATUS (209  )



                81.3.31          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  (207  ),  WaitProcess  (1793   ),  #rtl.baseunix.WTERMSIG  (210  ),
                #rtl.baseunix.WSTOPSIG (210  ), #rtl.baseunix.WIFEXITED (209  ), WIFSTOPPED (1794   ),
                #rtl.baseunix.WIFSIGNALED (209  ), W_EXITCODE (1794   ), W_STOPCODE (1794   ), #rtl.baseunix.WEXITSTATUS
                (209  )



                81.3.32          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
                (209  ) to return True

    See also:    #rtl.baseunix.FpWaitPID  (207  ),  WaitProcess  (1793   ),  #rtl.baseunix.WTERMSIG  (210  ),
                #rtl.baseunix.WSTOPSIG (210  ), #rtl.baseunix.WIFEXITED (209  ), WIFSTOPPED (1794   ),
                #rtl.baseunix.WIFSIGNALED (209  ), W_EXITCODE (1794   ), #rtl.baseunix.WEXITSTATUS
                (209  )



                                                                                1794




Chapter   82



Reference   for   unit   'unixcp'



82.1          Used  units



                                    Table 82.1:  Used units by unit 'unixcp'


                                                  _Name_____________Page______
                                                    BaseUnix           113
                                                    System           1235



82.2          Overview


The unixcp unit provides routines to handle mapping of code page names to numerical values
as used in libiconv>.  The GetCodepageByName (1796   ) function is the main function for this.
The GetCodepageData (1796   ) can be used to map a code page number to a name.  These
function can be used for instance to map code page information in environment variables to
code page numbers used in string encodings.  The supported code page names are the ones
commonly in use in libiconv.

This unit is used for example in unit cwstring (534  ).



82.3          Constants,  types  and  variables



82.3.1         Constants

UnixCpMap  :  Array[-1..UnixCpMapLimit]  of  TUnixCpData  =  ((cp:  0;  name:  'UTF-8'),  (cp:  37;  name:  'IBM037'),  (cp:  37;  *
 *name:  'IBM-037'),  (cp:  154;  name:  'CP154'),  (cp:  154;  name:  'CYRILLIC-ASIAN'),  (cp:  154;  name:  'PT154'),  (cp:  154;*
 *  name:  'PTCP154'),  (cp:  154;  name:  'CSPTCP154'),  (cp:  437;  name:  '437'),  (@


UnixCpMap  is  a  fixed  structure  with  codepage  number/codepage  name  pairs.  It  is  used  in
GetCodepageData (1796   ), GetSystemCodepage (1796   ) and GetCodepageByName (1796   ) to
map code page names to numbers and vice versa.

The map is ordered on code page number, and for equal code page numbers, the names are
ordered so the most common one is used first.


UnixCpMapLimit  =  406  -  83


Number of code pages in map UnixCpMap.



                                                            1795

                __________________________________________________________CHAPTER_82.___REFERENCE_FOR_UNIT_'UNIXCP'________________*
 *___________________



                82.3.2         Types

                TUnixCpData  =  record
                    cp  :  Word;
                    name  :  ansistring;
                end



                TUnixCpData contains 2 fields necessary to construct a map between code page number (cp)
                and name (name).



                82.4          Procedures  and  functions



                82.4.1         GetCodepageByName

    Synopsis:    Find code page by name

Declaration:     function  GetCodepageByName(cpname:  RawByteString)  :  TSystemCodePage

    Visibility:   default

Description:     GetCodepageByName returns the code page number matching cpname.  The supported code
                page  names  are  the  ones  commonly  in  use  in  libiconv.  Names  are  searched  case-sentively,
                with the exception that 'cpN' is converted to 'CPN', where N is a digit.

       Errors:   If no matching code page name is found, CP_NONE is returned.

    See also:    UnixCpMap (1795   ), GetSystemCodepage (1796   ), GetCodepageData (1796   )



                82.4.2         GetCodepageData

    Synopsis:    Return index of codepage.

Declaration:     function  GetCodepageData(cp:  TSystemCodePage)  :  LongInt

    Visibility:   default

Description:     GetCodepageData returns the index of the first entry in UnixCpMap (1795   ) which matches
                cp.  Since the entries are ordered by code page number, this means the entries can be scanned
                for alternate code names starting at this index.

       Errors:   If no matching code page is found, -1 is returned.

    See also:    UnixCpMap (1795   ), GetSystemCodepage (1796   ), GetCodepageByName (1796   )



                82.4.3         GetSystemCodepage

    Synopsis:    Return the system code page based on the program environment.

Declaration:     function  GetSystemCodepage  :  TSystemCodePage

    Visibility:   default

Description:     GetSystemCodepage returns the system code page, based on one of the environment vari-
                ables LC_ALL, LC_CTYPE or LANG. The first non-empty variable (in the order mentioned here)
                is used.



                                                                                1796

            __________________________________________________________CHAPTER_82.___REFERENCE_FOR_UNIT_'UNIXCP'____________________*
 *_______________



   Errors:   If none is found, then a system default is used:  Linux and Darwin use CP_UTF8, others use
            CP_ASCII.

See also:    UnixCpMap (1795   ), GetSystemCodepage (1796   ), GetCodepageByName (1796   )



                                                                            1797




Chapter   83



Reference   for   unit   'unixtype'



83.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.



83.2          Constants,  types  and  variables



83.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.baseunix.fpGetPriority (172  ) option:  Get process group priority.


Prio_Process  =  0


#rtl.baseunix.fpGetPriority (172  ) option:  Get process priority.


Prio_User  =  2


#rtl.baseunix.fpGetPriority (172  ) option:  Get user priority.



                                                            1798

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



pthreadrwlocksize  =  56


Size of  pthread_rwlock_t _data structure


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:  ?



                                                                1799

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



83.2.2         Types

cbool  =  longbool


Boolean type


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  =  cuint64


Clock ticks type


clong  =  Int64


C type:  long signed integer (double sized)


clongdouble  =  extended


Usually translates to an extended, but is CPU dependent.


clonglong  =  cint64



                                                                1800

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



C type:  64-bit (double long) signed integer.


cschar  =  cint8


Signed character type


cshort  =  cint16


C type:  short signed integer (half sized)


csigned  =  cint


csigned is an alias for cint (1800   ).


csint  =  cint32


Signed integer


cslong  =  Int64


The size is CPU dependent.


cslonglong  =  cint64


cslonglong is an alias for clonglong (1801   ).


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



                                                                1801

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



C type:  8 bits sized, unsigned integer.


culong  =  QWord


C type:  long unsigned integer (double sized)


culonglong  =  cuint64


C type:  64-bit (double long) unsigned integer.


cunsigned  =  cuint


Alias for #rtl.unixtype.cuint (1801   )


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  =  cint


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.



                                                                1802

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



mbstate_value_t  =  record
case  Byte  of
0:  (
   __wch  :  wint_t;
);
1:  (
   __wchb  :  Array[0..3]  of  Char;
);
end



This type should never be used directly.  It is part of the mbstate_t (1802   ) type.


mode_t  =  cint


Inode mode type.


nlink_t  =  cuint32


Number of links type.


off64_t  =  cint64


64-bit offset type.


off_t  =  cint


Offset type.


pcbool  =  ^cbool


Pointer to boolean type cbool (1800   )


pcchar  =  ^cchar


Pointer to #rtl.UnixType.cchar (1800   )


pcdouble  =  ^cdouble


Pointer to cdouble (1800   ) type.


pcfloat  =  ^cfloat


Pointer to cfloat (1800   ) type.


pcint  =  ^cint


Pointer to cInt (1800   ) type.


pcint16  =  ^cint16



                                                                1803

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



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 (1809   ) type.


pclong  =  ^clong


Pointer to cLong (1800   ) type.


pclongdouble  =  ^clongdouble


Pointer to the long double type clongdouble (1800   )


pclonglong  =  ^clonglong


Pointer to longlong type.


pcschar  =  ^cschar


Pointer to character type cschar (1801   ).


pcshort  =  ^cshort


Pointer to cShort (1801   ) type.


pcsigned  =  ^csigned


Pointer to signed integer type csigned (1801   ).


pcsint  =  ^csint


Pointer to signed integer type csint (1801   )


pcslong  =  ^cslong


Pointer ot the signed long cslong (1801   )


pcslonglong  =  ^cslonglong



                                                                1804

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



Pointer to Signed longlong type cslonglong (1801   )


pcsshort  =  ^csshort


Pointer to short signed integer type csshort (1801   )


pcuchar  =  ^cuchar


Pointer to #rtl.UnixType.cuchar (1801   )


pcuint  =  ^cuint


Pointer to cUInt (1801   ) type.


pcuint16  =  ^cuint16


Pointer to 16-bit unsigned integer type


pcuint32  =  ^cuint32


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 (1802   ) type.


pculonglong  =  ^culonglong


Unsigned longlong type


pcunsigned  =  ^cunsigned


Pointer to #rtl.unixtype.cunsigned (1802   )


pcushort  =  ^cushort


Pointer to cuShort (1802   ) type.


pDev  =  ^dev_t


Pointer to TDev (1809   ) type.


pGid  =  ^gid_t



                                                                1805

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



Pointer to TGid (1810   ) type.


pid_t  =  cint


Process ID type.


pIno  =  ^ino_t


Pointer to TIno (1810   ) type.


pIno64  =  ^ino64_t


Pointer to ino64_t (1802   )


pkDev  =  ^kDev_t


Pointer to TkDev (1810   ) type.


pmbstate_t  =  ^mbstate_t


Pointer to mbstate_t (1802   ) type


pMode  =  ^mode_t


Pointer to TMode (1810   ) type.


pnLink  =  ^nlink_t


Pointer to TnLink (1810   ) type.


pOff  =  ^off_t


Pointer to TOff (1810   ) type.


pOff64  =  ^off64_t


Pointer to off64_t type


pPid  =  ^pid_t


Pointer to TPid (1811   ) type.


pSize  =  ^size_t


Pointer to TSize (1811   ) type.


psize_t  =  pSize


Pointer to size_t (1809   ) type.


pSockLen  =  ^socklen_t



                                                                1806

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



Pointer to TSockLen (1811   ) type.


pSSize  =  ^ssize_t


Pointer to TsSize (1811   ) type


PStatFS  =  ^TStatfs


Pointer to TStatFS (1811   ) 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



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



                                                                1807

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



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



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
case  Boolean  of
False:  (
   _data  :  Array[0..pthreadrwlocksize-1]  of  Char;
);
True:  (
   align  :  clong;
);
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 (1811   ) type.


ptimespec  =  ^timespec


Pointer to timespec (1810   ) record.


ptimeval  =  ^timeval



                                                                1808

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



Pointer to timeval (1810   ) record.


ptime_t  =  ^time_t


Pointer to time_t (1810   ) type.


pUid  =  ^uid_t


Pointer to TUid (1812   ) type.


pwchar_t  =  ^wchar_t


Pointer to wchar_t (1812   ) type.


sched_param  =  record
   __sched_priority  :  cint;
end



Scheduling parameter description record.


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  =  cuint64


Size specification type.


socklen_t  =  cuint32


Socket address length type.


ssize_t  =  cint64


Small size type.


TClock  =  clock_t


Alias for clock_t (1800   ) type.


TDev  =  dev_t


Alias for dev_t (1802   ) type.



                                                                1809

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



TGid  =  gid_t


Alias for gid_t (1802   ) type.


timespec  =  record
   tv_sec  :  time_t;
   tv_nsec  :  clong;
end



Record specifying time interval.


timeval  =  record
   tv_sec  :  time_t;
   tv_usec  :  clong;
end



Time specification type.


time_t  =  cint64


Time span type


TIno  =  ino_t


Alias for ino_t (1802   ) type.


TIno64  =  ino64_t


Alias for ino64_t (1802   )


TIOCtlRequest  =  cint


Opaque type used in FpIOCtl (174  )


TkDev  =  kDev_t


Alias for kDev_t (1802   ) type.


TMode  =  mode_t


Alias for mode_t (1803   ) type.


TnLink  =  nlink_t


Alias for nlink_t (1803   ) type.


TOff  =  off_t


Alias for off_t (1803   ) type.



                                                                1810

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



TOff64  =  off64_t


Alias for off64_t type.


TPid  =  pid_t


Alias for pid_t (1806   ) type.


TSize  =  size_t


Alias for size_t (1809   ) type


TSockLen  =  socklen_t


Alias for socklen_t (1809   ) type.


TSSize  =  ssize_t


Alias for ssize_t (1809   ) type


TStatfs  =  record
   fstype  :  clong;
   bsize  :  clong;
   blocks  :  culong;
   bfree  :  culong;
   bavail  :  culong;
   files  :  culong;
   ffree  :  culong;
   fsid  :  Array[0..1]  of  cint;
   namelen  :  clong;
   frsize  :  clong;
   spare  :  Array[0..4]  of  clong;
end



Record describing a file system in the unix.fpstatfs (1798   ) call.


TTime  =  time_t


Alias for TTime (1811   ) type.


TTimeSpec  =  timespec


Alias for TimeSpec (1810   ) type.


TTimeVal  =  timeval


Alias for TimeVal (1810   ) record.


TUid  =  uid_t



                                                                1811

______________________________________________________CHAPTER_83.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



Alias for uid_t (1812   ) 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.



                                                                1812




Chapter   84



Reference   for   unit   'unixutil'



84.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 (1761   ) or baseunix (113  ) units.

Most of the functions described here have cross-platform counterparts in the SysUtils (1489   )
unit.  It is therefore recommended to use that unit.



84.2          Constants,  types  and  variables



84.2.1         Types

ComStr  =  string  deprecated


Command-line string type.


DirStr  =  string  deprecated


Filename directory part string type.


ExtStr  =  string  deprecated


Filename extension part string type.


NameStr  =  string  deprecated


Filename name part string type.


PathStr  =  string  deprecated


Filename full path string type.



84.2.2         Variables

Tzseconds  :  LongInt


Seconds west of GMT



                                                            1813

                _______________________________________________________CHAPTER_84.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



                84.3          Procedures  and  functions



                84.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 (1817   )



                84.3.2         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 (1816   )


                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   ;


                 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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1814

                _______________________________________________________CHAPTER_84.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



                84.3.3         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
                (190  ) call or so.

       Errors:   In case the file was not opened, then -1 is returned.

    See also:    #rtl.baseunix.fpSelect (190  )


                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;


                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___.____________________________________________________________________________________________________________*
 *___________



                84.3.4         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 (1816   )



                                                                                1815

                _______________________________________________________CHAPTER_84.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



                84.3.5         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 (1815   )



                84.3.6         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

Description:     Converts  the  Local  time  to  epoch  time  (=Number  of  seconds  since  00:00:00,  January  1,
                1970).

       Errors:   None

    See also:    EpochToLocal (1814   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1816

                _______________________________________________________CHAPTER_84.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



                84.3.7         StringToPPChar

    Synopsis:    Split string in list of null-terminated strings

Declaration:     function  StringToPPChar(S:  PChar;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 (1814   ), #rtl.baseunix.FpExecve (163  )


                Listing:  ./unutilex/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  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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1817




Chapter   85



Reference   for   unit   'video'



85.1          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  (1837   ),  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 (1840   ) will then cp the text to the screen in the most optimal way.
(an example can be found further on).

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.



                                                            1818

               ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'________________*
 *__________________



               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 (1837   ) function can be used:  This will increment an internal counter.  As
               long as the counter differs from zero, calling UpdateScreen (1840   ) will not do anything.  The
               counter can be lowered with UnlockScreenUpdate (1840   ).  When it reaches zero, the next call
               to UpdateScreen (1840   ) 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 (1839   )
               call.  The current video driver can be retrieved using the GetVideoDriver (1834   ) 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.



               85.2          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:

               Listing:  ./videoex/vidutil.pp
               ____________________________________________________________________________________________________________________*
 *__________
                u n i t  v i d u t i l;


                I n t e r f a c e


                u s e s
                   v i d e o;


                P r o c e d u r eTextOut     ( X ,Y   :  Word    ;Const     S   :   S t r i n g) ;


                I m p l e m e n t a t i o n


                P r o c e d u r eTextOut     ( X ,Y   :  Word    ;Const     S   :   S t r i n g) ;


               Var
                  W  ,P , I ,M   :  Word    ;


                b e g i n
                   P : = ( (X-1)+(    Y -1)*   S c r e e n W i d t)h;
                  M  := Length     (S ) ;
                   I f  P+ M > S c r e e n W i d t*hS c r e e n H e i g h tthen
                      M :=  S c r e e n W i d t*hS c r e e n H e i g h-tP;
                   For    I : = 1  t o M   do
                       V i d e o B u f^ [P+I -1]:=    Ord  ( S [ i] ) + ($07    s h l  8 ) ;
               end   ;


               end___._____________________________________________________________________________________________________________*
 *__________



                                                                               1819

____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___



85.3          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 (1839   ) function.  The various
functions that can be implemented are located in the TVideoDriver (1829   ) 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
        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)



                                                                1820

____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___



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)

Listing:  ./videoex/viddbg.pp
______________________________________________________________________________________________________________________________
 u n i t v i d d b g;


 I n t e r f a c e


 u s e s v i d e o;



 P r o c e d u r eS t a r t V i d e o L o g g i n;g
 P r o c e d u r eS t o p V i d e o L o g g i n;g
 F u n c t i o n  I s V i d e o L o g g i n g:  B o o l e a n;
 P r o c e d u r e  S e t V i d e o L o g F i l e N a(mFei l e N a m e:   S t r i n g) ;


Const
    D e t a i l e d V i d e o L o g g i n:g B o o l e a n =   F a l s e;


 I m p l e m e n t a t i o n


 u s e s s y s u t i l s,k e y b o a r d;


 v a r
    N e w V i d e o D r i v e,r
    O l d V i d e o D r i v e r:  T V i d e o D r i v e;r
    A c t i v e,L o g g i n g :   B o o l e a n;
    L o g F i l e N a m e:   S t r i n g;
    V i d e o L o g :  T e x t;


 F u n c t i o nTimeStamp         :  S t r i n g;


 b e g i n
    TimeStamp       := FormatDateTime           ( 'hh  :nn  : s s' ,Time    ( ) ) ;
end   ;


 P r o c e d u r eS t a r t V i d e o L o g g i n;g


 b e g i n
    L o g g i n g:= True   ;
    W r i t e l n(V i d e o L o g,' S t a r t l o g g i n g v i d e o o p e r a t i o n sa t :   ', TimeStamp       ) ;
end   ;


 P r o c e d u r eS t o p V i d e o L o g g i n;g


 b e g i n
    W r i t e l n(V i d e o L o g,'S t o p  l o g g i n g v i d e o  o p e r a t i o n sa t:   ' ,TimeStamp       ) ;
    L o g g i n g:= F a l s e;



                                                                1821

____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___



end   ;


 F u n c t i o nI s V i d e o L o g g i n g:  B o o l e a n;


 b e g i n
    I s V i d e o L o g g i n:g=L o g g i n g;
end   ;


Var
    ColUpd     ,RowUpd       :  A r r a y[ 0 . . 1 0 2 4 ]o f  I n t e g e r;


 P r o c e d u r eD u m p S c r e e n S t a t i s t i(cFso r c e :   B o o l e a n) ;


Var
    I ,Count      :   I n t e g e r;


 b e g i n
    I f  F o r c e  then
       Write    ( V i d e o L o g,' f o r c e d ' ) ;
    W r i t e l n(V i d e o L o g,' v i d e o u p d a t e a t   ', TimeStamp       , '  :   ') ;
    F i l l C h a r(Colupd    , S i z e O f(ColUpd     ) , # 0 ) ;
    F i l l C h a r(Rowupd    , S i z e O f(RowUpd     ) , # 0 ) ;
    Count    : = 0 ;
    For    I : = 0  t o  V i d e o B u f S i z ed i v  S i z e O f(T V i d e o C e l)l  do
        b e g i n
        I f  V i d e o B u f^ [i]<>  O l d V i d e o B u^f[ i ]  then
           b e g i n
           I n c( Count    ) ;
           I n c( ColUpd     [I  mod     S c r e e n W i d t]h) ;
           I n c( RowUpd     [I   d i v  S c r e e n H e i g h]t) ;
           end  ;
       end   ;
    Write    (V i d e o L o g,Count    , '  v i d e o c e l l s d i f f e r e dd i v i d e d o v e r  ' ) ;
    Count    : = 0 ;
    For    I : = 0  t o  S c r e e n W i d t-h1  do
        I f  ColUpd    [ I ]<>0    then
           I n c( Count    ) ;
    Write    (V i d e o L o g,Count    , '  c o l u m n s and    ' ) ;
    Count    : = 0 ;
    For    I : = 0  t o  S c r e e n H e i g h-t1  do
        I f RowUpd     [ I ]<>0    then
           I n c( Count    ) ;
    W r i t e l n(V i d e o L o g,Count    ,'   r o w s. ') ;
    I f  D e t a i l e d V i d e o L o g g i nTghen
      b e g i n
      For    I: = 0  t o   S c r e e n W i d t-h1  do
         I f  ( ColUpd     [ I] < >0)    then
             W r i t e l n(V i d e o L o g,'C o l  ' , i, '   :  ' ,ColUpd     [ I ] : 3 ,'  r o w s  c h a n g e d') ;
      For    I: = 0  t o   S c r e e n H e i g h-t1  do
         I f  ( RowUpd     [ I] < >0)    then
             W r i t e l n(V i d e o L o g,'Row    ' , i, '   :  ' ,RowUpd     [ I ] : 3 ,'  c o l u m s c h a n g e d') ;
      end  ;
end   ;


 P r o c e d u r eL o g U p d a t e S c r e e(nF o r c e:   B o o l e a n) ;


 b e g i n
    I f  L o g g i n g then



                                                                1822

____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___



        D u m p S c r e e n S t a t i s t i(cFso r c e) ;
    O l d V i d e o D r i v e.rU p d a t e S c r e e(nF o r c e) ;
end   ;


 P r o c e d u r eL o g I n i t V i d e;o


 b e g i n
    O l d V i d e o D r i v e.rI n i t D r i v e(r) ;
    A s s i g n(V i d e o L o g,l o g F i l e N a m)e;
    R e w r i t e(V i d e o L o g) ;
    A c t i v e:= True   ;
    S t a r t V i d e o L o g g i n;g
end   ;


 P r o c e d u r eLogDoneVideo         ;


 b e g i n
    S t o p V i d e o L o g g i n;g
    C l o s e(V i d e o L o g) ;
    A c t i v e:= F a l s e;
    O l d V i d e o D r i v e.rD o n e D r i v e(r) ;
end   ;


 P r o c e d u r eS e t V i d e o L o g F i l e N a(mFei l e N a m e :  S t r i n g) ;


 b e g i n
    I f  Not    A c t i v e then
       L o g F i l e N a m e:=F i l e N a m e;
end   ;


 I n i t i a l i z a t i o n
    G e t V i d e o D r i v e(rO l d V i d e o D r i v e)r;
    N e w V i d e o D r i v e:r=O l d V i d e o D r i v e;r
    N e w V i d e o D r i v e.rU p d a t e S c r e e:n=@ L o g U p d a t e S c r e e;n
    N e w V i d e o D r i v e.rI n i t D r i v e:r=@ L o g I n i t V i d e;o
    N e w V i d e o D r i v e.rD o n e D r i v e:r=@LogDoneVideo          ;
    L o g F i l e N a m:e= 'V i d e o. l o g' ;
    L o g g i n g:= F a l s e;
    S e t V i d e o D r i v e(rN e w V i d e o D r i v e)r;
end___._______________________________________________________________________________________________________________________



85.4          Constants,  types  and  variables



85.4.1         Constants

Black  =  0


Black color attribute


Blink  =  128


Blink attribute


Blue  =  1



                                                                1823

____________________________________________________________CHAPTER_85.___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



                                                                1824

____________________________________________________________CHAPTER_85.___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 (1831   ) 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  =  240


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



                                                                1825

____________________________________________________________CHAPTER_85.___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



                                                                1826

____________________________________________________________CHAPTER_85.___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



85.4.2         Types

PVideoBuf  =  ^TVideoBuf


Pointer type to TVideoBuf (1828   )


PVideoCell  =  ^TVideoCell


Pointer type to TVideoCell (1829   )


PVideoMode  =  ^TVideoMode


Pointer to TVideoMode (1829   ) record.


Tencoding  =  (cp437,cp850,cp852,cp866,koi8r,iso01,iso02,iso03,iso04,
                      iso05,iso06,iso07,iso08,iso09,iso10,iso13,iso14,iso15,utf8)



                                                                1827

____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___



                           Table 85.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
                                             utf8        UTF-8 encoding



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)



               Table 85.2:  Enumeration values for type TErrorHandlerReturnValue


                         __Value_______________Explanation___________________________________________
                           errAbort            abort and return error code
                           errContinue         abort without returning an errorcode.
                           errRetry            retry the operation



Type used to report and respond to error conditions


TVideoBuf  =  Array[0..32759]  of  TVideoCell


The TVideoBuf type represents the screen.



                                                                1828

____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___



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;
   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
(1839   ) 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.



85.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.



                                                                1829

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                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.


                OldVideoBuf  :  PVideoBuf


                The OldVideoBuf contains the state of the video screen after the last screen update.  The
                UpdateScreen (1840   ) 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 (1840   ) will write the actual characters to the
                screen.


                VideoBufSize  :  LongInt


                Current size of the video buffer pointed to by VideoBuf (1830   )



                85.5          Procedures  and  functions



                85.5.1         ClearScreen

    Synopsis:    Clear the video screen.

Declaration:     procedure  ClearScreen

    Visibility:   default

Description:     ClearScreen  clears  the  entire  screen,  and  calls  UpdateScreen  (1840   )  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).



                                                                                1830

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



       Errors:   None.

    See also:    InitVideo (1837   ), UpdateScreen (1840   )


                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
                       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___.____________________________________________________________________________________________________________*
 *___________



                85.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.



                85.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.



                                                                                1831

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                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 (1837   )



                85.5.4         GetCapabilities

    Synopsis:    Get current driver capabilities.

Declaration:     function  GetCapabilities  :  Word

    Visibility:   default

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 (1833   ), GetVideoDriver (1834   )


                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



                                                                                1832

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                85.5.5         GetCursorType

    Synopsis:    Get screen cursor type

Declaration:     function  GetCursorType  :  Word

    Visibility:   default

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 (1839   ), GetCapabilities (1832   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1833

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                85.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 (1840   ) will actually update the screen.

       Errors:   None.

    See also:    LockScreenUpdate (1837   ), UnlockScreenUpdate (1840   ), UpdateScreen (1840   )


                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. }


                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___.____________________________________________________________________________________________________________*
 *___________



                85.5.7         GetVideoDriver

    Synopsis:    Get a copy of the current video driver.

Declaration:     procedure  GetVideoDriver(var  Driver:  TVideoDriver)

    Visibility:   default



                                                                                1834

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



Description:     GetVideoDriver returns the currently active video driver record in Driver.  It can be used
                to clone the current video driver, or to override certain parts of it using the SetVideoDriver
                (1839   ) call.

       Errors:   None.

    See also:    SetVideoDriver (1839   )



                85.5.8         GetVideoMode

    Synopsis:    Return current video mode

Declaration:     procedure  GetVideoMode(var  Mode:  TVideoMode)

    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.

    See also:    SetVideoMode (1839   ), GetVideoModeData (1837   )


                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;


                 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___.____________________________________________________________________________________________________________*
 *___________



                85.5.9         GetVideoModeCount

    Synopsis:    Get the number of video modes supported by the driver.



                                                                                1835

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



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  (1837   )  function  to
                retrieve data for the supported video modes.

       Errors:   None.

    See also:    GetVideoModeData (1837   ), GetVideoMode (1835   )


                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) ;


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1836

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                85.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 (1835   ).

       Errors:   In case Index has a wrong value, False is returned.

    See also:    GetVideoModeCount (1835   ), SetVideoMode (1839   ), GetVideoMode (1835   )



                85.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 (1831   )



                85.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 (1840   ) 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 (1840   ) after the drawing, followed by a UpdateScreen (1840   ) call,
                all writing will be shown on screen at once.

                For an example, see GetLockScreenCount (1834   ).

       Errors:   None.

    See also:    UpdateScreen (1840   ), UnlockScreenUpdate (1840   ), GetLockScreenCount (1834   )



                                                                                1837

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                85.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 (1839   )


                Listing:  ./videoex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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



                                                                                1838

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                           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___.____________________________________________________________________________________________________________*
 *___________



                85.5.14          SetCursorType

    Synopsis:    Set cursor type

Declaration:     procedure  SetCursorType(NewType:  Word)

    Visibility:   default

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 (1838   )



                85.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 (1837   )) or after it was deactivated (i.e after a call to DoneVideo).

                For more information about installing a videodriver, see viddriver (1820   ).

                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 (1820   )



                85.5.16          SetVideoMode

    Synopsis:    Set current video mode.

Declaration:     function  SetVideoMode(const  Mode:  TVideoMode)  :  Boolean

    Visibility:   default



                                                                                1839

                ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



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
                (1837   )  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 (1835   ) and GetVideoMode-
                Data (1837   ) functions.  To retrieve the current video mode, use the GetVideoMode (1835   )
                procedure.

       Errors:   If the specified mode cannot be set, then errVioNoSuchMode may be set in ErrorCode

    See also:    GetVideoModeCount (1835   ), GetVideoModeData (1837   ), GetVideoMode (1835   )



                85.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 (1840   ) 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 (1837   ) is matched by exactly
                one call to UnlockScreenUpdate

                For an example, see GetLockScreenCount (1834   ).

       Errors:   None.

    See also:    LockScreenUpdate (1837   ), GetLockScreenCount (1834   ), UpdateScreen (1840   )



                85.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



                                                                                1840

            ____________________________________________________________CHAPTER_85.___REFERENCE_FOR_UNIT_'VIDEO'___________________*
 *_______________



            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 (1830   )



                                                                            1841




                Chapter   86



                Reference   for   unit   'wincrt'



                86.1          Overview


                The wincrt unit provides some auxiliary routines for use with the graph (767  ) unit, namely
                keyboard support.  It has no connection with the crt (507  ) unit, nor with the Turbo-Pascal
                for  Windows  WinCrt  unit.  As  such,  it  should  not  be  used  by  end  users.  Refer  to  the  crt
                (507  ) unit instead.



                86.2          Constants,  types  and  variables



                86.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.



                86.3          Procedures  and  functions



                86.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 (1843   ), nosound (1843   )



                86.3.2         keypressed

    Synopsis:    Check if a key was pressed.



                                                                            1842

                _________________________________________________________CHAPTER_86.___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 (1843   )



                86.3.3         nosound

    Synopsis:    Stop the speaker

Declaration:     procedure  nosound

    Visibility:   default

Description:     NoSound does nothing, windows does not support this.

    See also:    sound (1843   )



                86.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 (1842   )



                86.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 (1843   )



                86.3.6         textmode

    Synopsis:    Set indicated text mode

Declaration:     procedure  textmode(mode:  Integer)

    Visibility:   default

Description:     TextMode does nothing.



                                                                                1843




Chapter   87



Reference   for   unit   'windirs'



87.1          Used  units



                                    Table 87.1:  Used units by unit 'windirs'


                                                  __Name____________Page____
                                                    System          1235
                                                    windows            ??



87.2          Overview


This unit contains only one function:  GetWindowsSpecialDir (1847   ).  It is a simple pascal
wrapper around the shfolder.dll library, and is available under Windows only.



87.3          Constants,  types  and  variables



87.3.1         Constants

CSIDL_ADMINTOOLS  =  $0030


ID for the personal "Start Menu\Programs\Administrative tools" folder (In the user's per-
sonal folder)


CSIDL_APPDATA  =  $001A


ID for the roaming "Application Data" folder (in the user's personal folder)


CSIDL_CDBURN_AREA  =  $003B


ID for the personal "Local Settings\Application Data\Microsoft\CD Burning" folder (Under
"All users" folder)


CSIDL_COMMON_ADMINTOOLS  =  $002F



                                                            1844

________________________________________________________CHAPTER_87.___REFERENCE_FOR_UNIT_'WINDIRS'_________________________________*
 *___



ID for the common "Start Menu\Programs\Administrative tools" folder (Under "All users"
folder)


CSIDL_COMMON_APPDATA  =  $0023


ID for the common "Application Data" folder (Under "All users" folder)


CSIDL_COMMON_DESKTOPDIRECTORY  =  $0019


ID for the public "Desktop" folder (Under "All users" folder)


CSIDL_COMMON_DOCUMENTS  =  $002E


ID for the common "Documents" folder (Under "All users" folder)


CSIDL_COMMON_FAVORITES  =  $001F


ID for the public "Favorites" folder (Under "All users" folder)


CSIDL_COMMON_MUSIC  =  $0035


ID for the common "Documents\My Music" folder (Under "All users" folder)


CSIDL_COMMON_PICTURES  =  $0036


ID for the common "Documents\My Pictures" folder (Under "All users" folder)


CSIDL_COMMON_PROGRAMS  =  $0017


ID for the public "Programs" folder (Under "All users" Start menu folder)


CSIDL_COMMON_STARTMENU  =  $0016


ID for the public "Start Menu" folder (Under "All users")


CSIDL_COMMON_STARTUP  =  $0018


ID for the public "Startup" folder (Under "All users\Start menu\Programs" folder)


CSIDL_COMMON_TEMPLATES  =  $002D


ID for the common "Templates" folder (Under "All users" folder)


CSIDL_COMMON_VIDEO  =  $0037


ID for the common "Documents\My Video" folder (Under "All users" folder)


CSIDL_COOKIES  =  $0021


ID for the "Cookies" folder (in the user's personal folder)



                                                                1845

________________________________________________________CHAPTER_87.___REFERENCE_FOR_UNIT_'WINDIRS'_________________________________*
 *___



CSIDL_DESKTOPDIRECTORY  =  $0010


ID for the "Desktop" folder (in the user's personal folder)


CSIDL_FAVORITES  =  $0006


ID for the "Favourites" folder (in the user's personal folder)


CSIDL_FLAG_CREATE  =  $8000


Flag to specify if the requested folder must be created if it didn't exist yet.


CSIDL_HISTORY  =  $0022


ID for the "History" folder (in the user's personal folder)


CSIDL_INTERNET_CACHE  =  $0020


ID for the "Temporary Internet Files" folder (in the user's personal folder)


CSIDL_LOCAL_APPDATA  =  $001C


ID for the local "Application Data" folder (in the user's personal folder)


CSIDL_MYMUSIC  =  $000D


ID for the "My Music" folder (in the user's personal folder)


CSIDL_MYPICTURES  =  $0027


ID for the "My Pictures" folder (in the user's personal folder)


CSIDL_MYVIDEO  =  $000E


ID for the "My Videos" folder (in the user's personal folder)


CSIDL_NETHOOD  =  $0013


ID for the "Nethood" folder (in the user's personal folder)


CSIDL_PERSONAL  =  $0005


ID for the "My Documents" folder (in the user's personal folder)


CSIDL_PRINTHOOD  =  $001B


ID for the "Printhood" folder (in the user's personal folder)


CSIDL_PROFILE  =  $0028


ID for the user's personal folder



                                                                1846

                ________________________________________________________CHAPTER_87.___REFERENCE_FOR_UNIT_'WINDIRS'_________________*
 *___________________



                CSIDL_PROFILES  =  $003E


                ID for the parent folder for the user's folders


                CSIDL_PROGRAMS  =  $0002


                ID for the "Program files" folder


                CSIDL_PROGRAM_FILES  =  $0026


                ID for the "Program Files" folder (alias for CSIDL_PROGRAMS)


                CSIDL_PROGRAM_FILES_COMMON  =  $002B


                ID for the Common folder under the "Program Files" folder.


                CSIDL_RECENT  =  $0008


                ID for the "Recent" folder (in the user's personal folder)


                CSIDL_SENDTO  =  $0009


                ID for the "Send to" folder (in the user's personal folder)


                CSIDL_STARTMENU  =  $000B


                ID for the "Start menu" folder (in the user's personal folder)


                CSIDL_STARTUP  =  $0007


                ID for the "Startup" menu folder (in the user's personal folder)


                CSIDL_SYSTEM  =  $0025


                ID for the Windows System32 dir.


                CSIDL_TEMPLATES  =  $0015


                ID for the "Templates" folder (in the user's personal folder)


                CSIDL_WINDOWS  =  $0024


                ID for the Windows installation dir.



                87.4          Procedures  and  functions



                87.4.1         GetWindowsSpecialDir

    Synopsis:    Get the location of a special directory.

Declaration:     function  GetWindowsSpecialDir(ID:  Integer)  :  string



                                                                                1847

                ________________________________________________________CHAPTER_87.___REFERENCE_FOR_UNIT_'WINDIRS'_________________*
 *___________________



    Visibility:  default

Description:     GetWindowsSpecialDir can be used to to get the path of special folders on the Windows
                system.   The  locations  are  identified  using  one  of  the  CSIDL_*  constants.   If  the  ID  of  a
                location is or-ed with the CSIDL_FLAG_CREATE constant, then the directory will be created if
                it didn't exist yet (and the user has sufficient rights to do so).

       Errors:   On error, an empty string is returned.



                                                                                1848




                Chapter   88



                Reference   for   unit   'x86'



                88.1          Used  units



                                                      Table 88.1:  Used units by unit 'x86'


                                                                  _Name_____________Page______
                                                                    BaseUnix           113
                                                                    System           1235



                88.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.



                88.3          Procedures  and  functions



                88.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 (166  ), the permissions are reset.  When doing a FpExecVE (163  )
                       they are kept.

       Errors:   Extended error information can be retrieved with FpGetErrno (169  )



                                                                            1849

                _________________________________________________________________CHAPTER_88.___REFERENCE_FOR_UNIT_'X86'____________*
 *___________________



                88.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.



                88.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 (1849   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm  (1849   ),  ReadPortB  (1850   ),  ReadPortW  (1851   ),  ReadPortL  (1851   ),  WritePort
                (1851   ), WritePortB (1852   ), WritePortL (1852   ), WritePortW (1852   )



                88.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 (1849   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm  (1849   ),  ReadPort  (1850   ),  ReadPortW  (1851   ),  ReadPortL  (1851   ),  WritePort
                (1851   ), WritePortB (1852   ), WritePortL (1852   ), WritePortW (1852   )



                                                                                1850

                _________________________________________________________________CHAPTER_88.___REFERENCE_FOR_UNIT_'X86'____________*
 *___________________



                88.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 (1849   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm  (1849   ),  ReadPort  (1850   ),  ReadPortW  (1851   ),  ReadPortB  (1850   ),  WritePort
                (1851   ), WritePortB (1852   ), WritePortL (1852   ), WritePortW (1852   )



                88.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 (1849   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm (1849   ), ReadPort (1850   ), ReadPortB (1850   ), ReadPortL (1851   ), WritePort (1851   ),
                WritePortB (1852   ), WritePortL (1852   ), WritePortW (1852   )



                88.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 (1849   ) call.



                                                                                1851

                _________________________________________________________________CHAPTER_88.___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 (1849   ), WritePortB (1852   ), WritePortL (1852   ), WritePortW (1852   ), ReadPortB
                (1850   ), ReadPortL (1851   ), ReadPortW (1851   )



                88.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 (1849   ) call.

       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm (1849   ),  WritePort (1851   ),  WritePortL (1852   ),  WritePortW (1852   ),  ReadPortB
                (1850   ), ReadPortL (1851   ), ReadPortW (1851   )



                88.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 (1849   ) call.

       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm (1849   ), WritePort (1851   ), WritePortB (1852   ), WritePortW (1852   ), ReadPortB
                (1850   ), ReadPortL (1851   ), ReadPortW (1851   )



                88.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



                                                                                1852

                _________________________________________________________________CHAPTER_88.___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 (1849   ) call.

       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm  (1849   ),  WritePort  (1851   ),  WritePortL  (1852   ),  WritePortB  (1852   ),  ReadPortB
                (1850   ), ReadPortL (1851   ), ReadPortW (1851   )



                                                                                1853
