



Run-Time  Library  (RTL)  :

Reference  guide.

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

                                                                                   Free Pascal version 2.6.0:

                                                                          Reference guide for RTL units.

                                                                                         Document version 2.6

                                                                                                    December 2011



Micha"el Van Canneyt
______________________________________________________________________________________________________________________________




Contents



     0.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  101


1    Reference for unit 'BaseUnix'                                                                                       102

     1.1      Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  102

     1.2      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  102

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

             1.3.1        Constants        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  102

             1.3.2        Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  125

     1.4      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  142

             1.4.1        CreateShellArgV            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  142

             1.4.2        FpAccess      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  142

             1.4.3        FpAlarm       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  143

             1.4.4        FpChdir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  144

             1.4.5        FpChmod          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  144

             1.4.6        FpChown       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  145

             1.4.7        FpClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  146

             1.4.8        FpClosedir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  146

             1.4.9        FpDup       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  147

             1.4.10       FpDup2        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  148

             1.4.11       FpExecv       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  149

             1.4.12       FpExecve         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  150

             1.4.13       FpExit      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  151

             1.4.14       FpFcntl       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  151

             1.4.15       fpfdfillset   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  152

             1.4.16       fpFD_CLR         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  152

             1.4.17       fpFD_ISSET         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  152

             1.4.18       fpFD_SET         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  152

             1.4.19       fpFD_ZERO          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  153

             1.4.20       FpFork      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  153

             1.4.21       FPFStat       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  153

             1.4.22       FpFtruncate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  154



                                                              1

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             1.4.23       FpGetcwd        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  155

             1.4.24       FpGetegid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  155

             1.4.25       FpGetEnv        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  155

             1.4.26       fpgeterrno      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  156

             1.4.27       FpGeteuid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  156

             1.4.28       FpGetgid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  157

             1.4.29       FpGetgroups       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  157

             1.4.30       FpGetpgrp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  157

             1.4.31       FpGetpid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  158

             1.4.32       FpGetppid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  158

             1.4.33       fpGetPriority        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  159

             1.4.34       FpGetRLimit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  159

             1.4.35       FpGetsid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  159

             1.4.36       FpGetuid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  160

             1.4.37       FpIOCtl       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  160

             1.4.38       FpKill     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  161

             1.4.39       FpLink     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  161

             1.4.40       FpLseek       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  162

             1.4.41       fpLstat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  163

             1.4.42       FpMkdir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  164

             1.4.43       FpMkfifo      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  165

             1.4.44       Fpmmap        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  165

             1.4.45       Fpmunmap        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  166

             1.4.46       FpNanoSleep       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  167

             1.4.47       fpNice     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  168

             1.4.48       FpOpen        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  168

             1.4.49       FpOpendir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  170

             1.4.50       FpPause       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  171

             1.4.51       FpPipe     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  171

             1.4.52       FpPoll     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  172

             1.4.53       FppRead       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  172

             1.4.54       FppWrite      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  172

             1.4.55       FpRead     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  173

             1.4.56       FpReaddir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  174

             1.4.57       fpReadLink        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  174

             1.4.58       FpReadV       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  175

             1.4.59       FpRename        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  176

             1.4.60       FpRmdir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  176

             1.4.61       fpSelect   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  177

             1.4.62       fpseterrno      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  178



                                                                  2

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             1.4.63       FpSetgid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  178

             1.4.64       fpSetPriority     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  179

             1.4.65       FpSetRLimit       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  179

             1.4.66       FpSetsid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  180

             1.4.67       fpsettimeofday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  180

             1.4.68       FpSetuid      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  180

             1.4.69       FPSigaction       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  180

             1.4.70       FpSigAddSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  182

             1.4.71       FpSigDelSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  182

             1.4.72       FpsigEmptySet          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  182

             1.4.73       FpSigFillSet      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  183

             1.4.74       FpSigIsMember          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  183

             1.4.75       FpSignal      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  183

             1.4.76       FpSigPending         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  184

             1.4.77       FpSigProcMask          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  184

             1.4.78       FpSigSuspend         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  185

             1.4.79       FpSigTimedWait            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  185

             1.4.80       FpSleep       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  185

             1.4.81       FpStat     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  186

             1.4.82       fpSymlink       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  187

             1.4.83       fpS_ISBLK       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  188

             1.4.84       fpS_ISCHR       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  188

             1.4.85       fpS_ISDIR       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  189

             1.4.86       fpS_ISFIFO        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  189

             1.4.87       fpS_ISLNK       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  189

             1.4.88       fpS_ISREG       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  190

             1.4.89       fpS_ISSOCK        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  190

             1.4.90       fptime     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  190

             1.4.91       FpTimes       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  191

             1.4.92       FpUmask       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  191

             1.4.93       FpUname         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  192

             1.4.94       FpUnlink      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  192

             1.4.95       FpUtime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  193

             1.4.96       FpWait     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  193

             1.4.97       FpWaitPid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  194

             1.4.98       FpWrite       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  195

             1.4.99       FpWriteV        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  195

             1.4.100      FreeShellArgV        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  195

             1.4.101      wexitStatus       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  195

             1.4.102      wifexited     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  196



                                                                  3

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             1.4.103      wifsignaled     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  196

             1.4.104      wstopsig      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  196

             1.4.105      wtermsig      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  196


2    Reference for unit 'Classes'                                                                                       197

    2.1      Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  197

    2.2      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  197

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

             2.3.1        Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  197

             2.3.2        Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  200

             2.3.3        Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  211

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

             2.4.1        ActivateClassGroup          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  213

             2.4.2        BeginGlobalLoading          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  213

             2.4.3        BinToHex        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  213

             2.4.4        Bounds     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  213

             2.4.5        CheckSynchronize          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  214

             2.4.6        ClassGroupOf         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  214

             2.4.7        CollectionsEqual       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  214

             2.4.8        EndGlobalLoading            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  214

             2.4.9        ExtractStrings       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  215

             2.4.10       FindClass       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  215

             2.4.11       FindGlobalComponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  215

             2.4.12       FindIdentToInt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  215

             2.4.13       FindIntToIdent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  216

             2.4.14       FindNestedComponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  216

             2.4.15       GetClass      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  216

             2.4.16       GetFixupInstanceNames               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  217

             2.4.17       GetFixupReferenceNames                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  217

             2.4.18       GlobalFixupReferences            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  217

             2.4.19       GroupDescendentsWith             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  217

             2.4.20       HexToBin        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  218

             2.4.21       IdentToInt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  218

             2.4.22       InitComponentRes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  218

             2.4.23       InitInheritedComponent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  219

             2.4.24       IntToIdent      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  219

             2.4.25       InvalidPoint      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  219

             2.4.26       LineStart     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  219

             2.4.27       NotifyGlobalLoading            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  220

             2.4.28       ObjectBinaryToText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  220



                                                                  4

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.4.29       ObjectResourceToText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  220

             2.4.30       ObjectTextToBinary             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  220

             2.4.31       ObjectTextToResource             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  220

             2.4.32       Point    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  221

             2.4.33       PointsEqual       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  221

             2.4.34       ReadComponentRes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  221

             2.4.35       ReadComponentResEx               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  221

             2.4.36       ReadComponentResFile                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  222

             2.4.37       Rect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  222

             2.4.38       RedirectFixupReferences             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  222

             2.4.39       RegisterClass        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  222

             2.4.40       RegisterClassAlias        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  223

             2.4.41       RegisterClasses        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  223

             2.4.42       RegisterComponents             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  223

             2.4.43       RegisterFindGlobalComponentProc                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *23

             2.4.44       RegisterInitComponentHandler                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *224

             2.4.45       RegisterIntegerConsts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  224

             2.4.46       RegisterNoIcon         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  224

             2.4.47       RegisterNonActiveX             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  225

             2.4.48       RemoveFixupReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  225

             2.4.49       RemoveFixups         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  225

             2.4.50       SmallPoint      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  225

             2.4.51       StartClassGroup        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  226

             2.4.52       UnRegisterClass        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  226

             2.4.53       UnRegisterClasses         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  226

             2.4.54       UnregisterFindGlobalComponentProc                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *26

             2.4.55       UnRegisterModuleClasses               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  227

             2.4.56       WriteComponentResFile               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  227

    2.5      EBitsError       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  227

             2.5.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  227

    2.6      EClassNotFound          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  227

             2.6.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  227

    2.7      EComponentError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  227

             2.7.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  227

    2.8      EFCreateError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  228

             2.8.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  228

    2.9      EFilerError      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  228

             2.9.1        Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  228

    2.10     EFOpenError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  228

             2.10.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  228



                                                                  5

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    2.11     EInvalidImage         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  228

             2.11.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  228

    2.12     EInvalidOperation          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  228

             2.12.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  228

    2.13     EListError       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  229

             2.13.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  229

    2.14     EMethodNotFound              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  229

             2.14.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  229

    2.15     EOutOfResources            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  229

             2.15.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  229

    2.16     EParserError       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  229

             2.16.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  229

    2.17     EReadError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  229

             2.17.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  229

    2.18     EResNotFound          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  230

             2.18.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  230

    2.19     EStreamError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  230

             2.19.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  230

    2.20     EStringListError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  230

             2.20.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  230

    2.21     EThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  230

             2.21.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  230

    2.22     EThreadDestroyCalled              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  231

             2.22.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  231

    2.23     EWriteError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  231

             2.23.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  231

    2.24     IDesignerNotify         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  231

             2.24.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  231

             2.24.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  231

             2.24.3       IDesignerNotify.Modified            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  231

             2.24.4       IDesignerNotify.Notification            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 231

    2.25     IInterfaceComponentReference                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  232

             2.25.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  232

             2.25.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  232

             2.25.3       IInterfaceComponentReference.GetComponent                        .  .  .  .  .  .  .  .  .  .  .  .  232

    2.26     IInterfaceList     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  232

             2.26.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  232

             2.26.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  233

             2.26.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  233

             2.26.4       IInterfaceList.Get        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  233



                                                                  6

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.26.5       IInterfaceList.GetCapacity            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  233

             2.26.6       IInterfaceList.GetCount             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  234

             2.26.7       IInterfaceList.Put        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  234

             2.26.8       IInterfaceList.SetCapacity            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  234

             2.26.9       IInterfaceList.SetCount          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  234

             2.26.10      IInterfaceList.Clear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  235

             2.26.11      IInterfaceList.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  235

             2.26.12      IInterfaceList.Exchange          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  235

             2.26.13      IInterfaceList.First        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  235

             2.26.14      IInterfaceList.IndexOf           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  236

             2.26.15      IInterfaceList.Add        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  236

             2.26.16      IInterfaceList.Insert       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  236

             2.26.17      IInterfaceList.Last       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  236

             2.26.18      IInterfaceList.Remove          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  236

             2.26.19      IInterfaceList.Lock         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  237

             2.26.20      IInterfaceList.Unlock          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  237

             2.26.21      IInterfaceList.Capacity          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  237

             2.26.22      IInterfaceList.Count        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  237

             2.26.23      IInterfaceList.Items        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  238

    2.27     IStreamPersist        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  238

             2.27.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  238

             2.27.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  238

             2.27.3       IStreamPersist.LoadFromStream                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *238

             2.27.4       IStreamPersist.SaveToStream                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 238

    2.28     IStringsAdapter         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  239

             2.28.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  239

             2.28.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  239

             2.28.3       IStringsAdapter.ReferenceStrings                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *239

             2.28.4       IStringsAdapter.ReleaseStrings               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *239

    2.29     IVCLComObject           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  239

             2.29.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  239

             2.29.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  239

             2.29.3       IVCLComObject.GetTypeInfoCount                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *40

             2.29.4       IVCLComObject.GetTypeInfo                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 240

             2.29.5       IVCLComObject.GetIDsOfNames                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *240

             2.29.6       IVCLComObject.Invoke                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  240

             2.29.7       IVCLComObject.SafeCallException                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *41

             2.29.8       IVCLComObject.FreeOnRelease                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *241

    2.30     TAbstractObjectReader             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  241

             2.30.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  241



                                                                  7

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.30.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  242

             2.30.3       TAbstractObjectReader.NextValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *42

             2.30.4       TAbstractObjectReader.ReadValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *42

             2.30.5       TAbstractObjectReader.BeginRootComponent                         .  .  .  .  .  .  .  .  .  .  .  .  243

             2.30.6       TAbstractObjectReader.BeginComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  243

             2.30.7       TAbstractObjectReader.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  243

             2.30.8       TAbstractObjectReader.Read                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 243

             2.30.9       TAbstractObjectReader.ReadBinary                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *44

             2.30.10      TAbstractObjectReader.ReadFloat                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *44

             2.30.11      TAbstractObjectReader.ReadSingle                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *44

             2.30.12      TAbstractObjectReader.ReadDate                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *245

             2.30.13      TAbstractObjectReader.ReadCurrency                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  245

             2.30.14      TAbstractObjectReader.ReadIdent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *45

             2.30.15      TAbstractObjectReader.ReadInt8                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *246

             2.30.16      TAbstractObjectReader.ReadInt16                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *46

             2.30.17      TAbstractObjectReader.ReadInt32                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *46

             2.30.18      TAbstractObjectReader.ReadInt64                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *47

             2.30.19      TAbstractObjectReader.ReadSet                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *247

             2.30.20      TAbstractObjectReader.ReadStr                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *247

             2.30.21      TAbstractObjectReader.ReadString                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *48

             2.30.22      TAbstractObjectReader.ReadWideString                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  248

             2.30.23      TAbstractObjectReader.ReadUnicodeString                       .  .  .  .  .  .  .  .  .  .  .  .  .  248

             2.30.24      TAbstractObjectReader.SkipComponent                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  249

             2.30.25      TAbstractObjectReader.SkipValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *49

    2.31     TAbstractObjectWriter             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  249

             2.31.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  249

             2.31.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  250

             2.31.3       TAbstractObjectWriter.BeginCollection                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  250

             2.31.4       TAbstractObjectWriter.BeginComponent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  250

             2.31.5       TAbstractObjectWriter.BeginList                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *250

             2.31.6       TAbstractObjectWriter.EndList                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *251

             2.31.7       TAbstractObjectWriter.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  251

             2.31.8       TAbstractObjectWriter.EndProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *51

             2.31.9       TAbstractObjectWriter.Write                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 251

             2.31.10      TAbstractObjectWriter.WriteBinary                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *51

             2.31.11      TAbstractObjectWriter.WriteBoolean                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *52

             2.31.12      TAbstractObjectWriter.WriteFloat                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *52

             2.31.13      TAbstractObjectWriter.WriteSingle                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *52

             2.31.14      TAbstractObjectWriter.WriteDate                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *252

             2.31.15      TAbstractObjectWriter.WriteCurrency                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  252



                                                                  8

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.31.16      TAbstractObjectWriter.WriteIdent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *53

             2.31.17      TAbstractObjectWriter.WriteInteger                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *53

             2.31.18      TAbstractObjectWriter.WriteUInt64                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *53

             2.31.19      TAbstractObjectWriter.WriteVariant                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *53

             2.31.20      TAbstractObjectWriter.WriteMethodName                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  253

             2.31.21      TAbstractObjectWriter.WriteSet                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *254

             2.31.22      TAbstractObjectWriter.WriteString                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *54

             2.31.23      TAbstractObjectWriter.WriteWideString                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  254

             2.31.24      TAbstractObjectWriter.WriteUnicodeString                      .  .  .  .  .  .  .  .  .  .  .  .  .  254

    2.32     TBasicAction          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  254

             2.32.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  254

             2.32.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  255

             2.32.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  255

             2.32.4       TBasicAction.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  255

             2.32.5       TBasicAction.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  255

             2.32.6       TBasicAction.HandlesTarget              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 255

             2.32.7       TBasicAction.UpdateTarget               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 256

             2.32.8       TBasicAction.ExecuteTarget              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 256

             2.32.9       TBasicAction.Execute             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  256

             2.32.10      TBasicAction.RegisterChanges               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 257

             2.32.11      TBasicAction.UnRegisterChanges                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *257

             2.32.12      TBasicAction.Update            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  257

             2.32.13      TBasicAction.ActionComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *257

             2.32.14      TBasicAction.OnExecute              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  258

             2.32.15      TBasicAction.OnUpdate               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  258

    2.33     TBasicActionLink           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  258

             2.33.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  258

             2.33.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  259

             2.33.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  259

             2.33.4       TBasicActionLink.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  259

             2.33.5       TBasicActionLink.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  259

             2.33.6       TBasicActionLink.Execute              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  259

             2.33.7       TBasicActionLink.Update               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  260

             2.33.8       TBasicActionLink.Action             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  260

             2.33.9       TBasicActionLink.OnChange                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 260

    2.34     TBinaryObjectReader            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  261

             2.34.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  261

             2.34.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  261

             2.34.3       TBinaryObjectReader.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 261

             2.34.4       TBinaryObjectReader.Destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 262



                                                                  9

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.34.5       TBinaryObjectReader.NextValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *262

             2.34.6       TBinaryObjectReader.ReadValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *262

             2.34.7       TBinaryObjectReader.BeginRootComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  262

             2.34.8       TBinaryObjectReader.BeginComponent                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  263

             2.34.9       TBinaryObjectReader.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *63

             2.34.10      TBinaryObjectReader.Read                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 263

             2.34.11      TBinaryObjectReader.ReadBinary                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *63

             2.34.12      TBinaryObjectReader.ReadFloat                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *263

             2.34.13      TBinaryObjectReader.ReadSingle                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *264

             2.34.14      TBinaryObjectReader.ReadDate                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *264

             2.34.15      TBinaryObjectReader.ReadCurrency                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *64

             2.34.16      TBinaryObjectReader.ReadIdent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *264

             2.34.17      TBinaryObjectReader.ReadInt8                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *264

             2.34.18      TBinaryObjectReader.ReadInt16                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *265

             2.34.19      TBinaryObjectReader.ReadInt32                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *265

             2.34.20      TBinaryObjectReader.ReadInt64                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *265

             2.34.21      TBinaryObjectReader.ReadSet                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *265

             2.34.22      TBinaryObjectReader.ReadStr                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *266

             2.34.23      TBinaryObjectReader.ReadString                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *266

             2.34.24      TBinaryObjectReader.ReadWideString                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  266

             2.34.25      TBinaryObjectReader.ReadUnicodeString                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  266

             2.34.26      TBinaryObjectReader.SkipComponent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  267

             2.34.27      TBinaryObjectReader.SkipValue                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *267

    2.35     TBinaryObjectWriter            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  267

             2.35.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  267

             2.35.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  268

             2.35.3       TBinaryObjectWriter.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 268

             2.35.4       TBinaryObjectWriter.Destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 268

             2.35.5       TBinaryObjectWriter.BeginCollection                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *68

             2.35.6       TBinaryObjectWriter.BeginComponent                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  269

             2.35.7       TBinaryObjectWriter.BeginList                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *269

             2.35.8       TBinaryObjectWriter.EndList                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 269

             2.35.9       TBinaryObjectWriter.BeginProperty                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *69

             2.35.10      TBinaryObjectWriter.EndProperty                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *69

             2.35.11      TBinaryObjectWriter.Write               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 269

             2.35.12      TBinaryObjectWriter.WriteBinary                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *70

             2.35.13      TBinaryObjectWriter.WriteBoolean                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *70

             2.35.14      TBinaryObjectWriter.WriteFloat                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *270

             2.35.15      TBinaryObjectWriter.WriteSingle                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *270

             2.35.16      TBinaryObjectWriter.WriteDate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *270



                                                                 10

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.35.17      TBinaryObjectWriter.WriteCurrency                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *70

             2.35.18      TBinaryObjectWriter.WriteIdent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *271

             2.35.19      TBinaryObjectWriter.WriteInteger                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *71

             2.35.20      TBinaryObjectWriter.WriteUInt64                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *71

             2.35.21      TBinaryObjectWriter.WriteMethodName                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  271

             2.35.22      TBinaryObjectWriter.WriteSet                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *271

             2.35.23      TBinaryObjectWriter.WriteString                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *271

             2.35.24      TBinaryObjectWriter.WriteWideString                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  272

             2.35.25      TBinaryObjectWriter.WriteUnicodeString                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  272

             2.35.26      TBinaryObjectWriter.WriteVariant                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *72

    2.36     TBits     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  27@

             2.36.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  272

             2.36.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  273

             2.36.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  273

             2.36.4       TBits.Create      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  273

             2.36.5       TBits.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  273

             2.36.6       TBits.GetFSize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  274

             2.36.7       TBits.SetOn       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  274

             2.36.8       TBits.Clear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  274

             2.36.9       TBits.Clearall       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  274

             2.36.10      TBits.AndBits        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  275

             2.36.11      TBits.OrBits      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  275

             2.36.12      TBits.XorBits        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  275

             2.36.13      TBits.NotBits        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  276

             2.36.14      TBits.Get       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  276

             2.36.15      TBits.Grow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  276

             2.36.16      TBits.Equals      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  276

             2.36.17      TBits.SetIndex         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  277

             2.36.18      TBits.FindFirstBit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  277

             2.36.19      TBits.FindNextBit           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  277

             2.36.20      TBits.FindPrevBit           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  278

             2.36.21      TBits.OpenBit        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  278

             2.36.22      TBits.Bits      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  278

             2.36.23      TBits.Size      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  279

    2.37     TCollection      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  279

             2.37.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  279

             2.37.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  279

             2.37.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  279

             2.37.4       TCollection.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  280

             2.37.5       TCollection.Destroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  280



                                                                 11

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.37.6       TCollection.Owner           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  280

             2.37.7       TCollection.Add        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  280

             2.37.8       TCollection.Assign          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  281

             2.37.9       TCollection.BeginUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  281

             2.37.10      TCollection.Clear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  281

             2.37.11      TCollection.EndUpdate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  282

             2.37.12      TCollection.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  282

             2.37.13      TCollection.GetEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 282

             2.37.14      TCollection.GetNamePath               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  282

             2.37.15      TCollection.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  283

             2.37.16      TCollection.FindItemID              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  283

             2.37.17      TCollection.Exchange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  283

             2.37.18      TCollection.Sort       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  284

             2.37.19      TCollection.Count         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  284

             2.37.20      TCollection.ItemClass            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  284

             2.37.21      TCollection.Items         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  284

    2.38     TCollectionEnumerator             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  285

             2.38.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  285

             2.38.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  285

             2.38.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  285

             2.38.4       TCollectionEnumerator.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 285

             2.38.5       TCollectionEnumerator.GetCurrent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *85

             2.38.6       TCollectionEnumerator.MoveNext                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *286

             2.38.7       TCollectionEnumerator.Current                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *286

    2.39     TCollectionItem         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  286

             2.39.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  286

             2.39.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  287

             2.39.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  287

             2.39.4       TCollectionItem.Create           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  287

             2.39.5       TCollectionItem.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  287

             2.39.6       TCollectionItem.GetNamePath                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *287

             2.39.7       TCollectionItem.Collection            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  288

             2.39.8       TCollectionItem.ID          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  288

             2.39.9       TCollectionItem.Index            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  288

             2.39.10      TCollectionItem.DisplayName                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 289

    2.40     TComponent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  289

             2.40.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  289

             2.40.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  289

             2.40.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  290

             2.40.4       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  290



                                                                 12

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.40.5       TComponent.WriteState               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  290

             2.40.6       TComponent.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  291

             2.40.7       TComponent.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  291

             2.40.8       TComponent.BeforeDestruction                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *291

             2.40.9       TComponent.DestroyComponents                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *292

             2.40.10      TComponent.Destroying               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  292

             2.40.11      TComponent.ExecuteAction                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 292

             2.40.12      TComponent.FindComponent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 292

             2.40.13      TComponent.FreeNotification                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 293

             2.40.14      TComponent.RemoveFreeNotification                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *93

             2.40.15      TComponent.FreeOnRelease                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 293

             2.40.16      TComponent.GetEnumerator                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 293

             2.40.17      TComponent.GetNamePath                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 294

             2.40.18      TComponent.GetParentComponent                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *94

             2.40.19      TComponent.HasParent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  294

             2.40.20      TComponent.InsertComponent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *294

             2.40.21      TComponent.RemoveComponent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *295

             2.40.22      TComponent.SafeCallException                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *295

             2.40.23      TComponent.SetSubComponent                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *295

             2.40.24      TComponent.UpdateAction                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 295

             2.40.25      TComponent.IsImplementorOf                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 296

             2.40.26      TComponent.ReferenceInterface                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *296

             2.40.27      TComponent.ComObject                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  296

             2.40.28      TComponent.Components                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  296

             2.40.29      TComponent.ComponentCount                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *297

             2.40.30      TComponent.ComponentIndex                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 297

             2.40.31      TComponent.ComponentState                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 297

             2.40.32      TComponent.ComponentStyle                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 298

             2.40.33      TComponent.DesignInfo               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  298

             2.40.34      TComponent.Owner               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  298

             2.40.35      TComponent.VCLComObject                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 298

             2.40.36      TComponent.Name             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  299

             2.40.37      TComponent.Tag            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  299

    2.41     TComponentEnumerator                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  299

             2.41.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  299

             2.41.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  299

             2.41.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  300

             2.41.4       TComponentEnumerator.Create                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *300

             2.41.5       TComponentEnumerator.GetCurrent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *00

             2.41.6       TComponentEnumerator.MoveNext                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *00



                                                                 13

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.41.7       TComponentEnumerator.Current                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *300

    2.42     TCustomMemoryStream                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  301

             2.42.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  301

             2.42.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  301

             2.42.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  301

             2.42.4       TCustomMemoryStream.Read                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 301

             2.42.5       TCustomMemoryStream.Seek                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 301

             2.42.6       TCustomMemoryStream.SaveToStream                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  302

             2.42.7       TCustomMemoryStream.SaveToFile                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *02

             2.42.8       TCustomMemoryStream.Memory                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *303

    2.43     TDataModule           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  303

             2.43.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  303

             2.43.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  303

             2.43.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  303

             2.43.4       TDataModule.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  304

             2.43.5       TDataModule.CreateNew               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  304

             2.43.6       TDataModule.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  304

             2.43.7       TDataModule.AfterConstruction                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *304

             2.43.8       TDataModule.BeforeDestruction                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *305

             2.43.9       TDataModule.DesignOffset              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  305

             2.43.10      TDataModule.DesignSize              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  305

             2.43.11      TDataModule.OnCreate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  305

             2.43.12      TDataModule.OnDestroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  306

             2.43.13      TDataModule.OldCreateOrder                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 306

    2.44     TFiler    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  30@

             2.44.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  306

             2.44.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  306

             2.44.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  307

             2.44.4       TFiler.DefineProperty            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  307

             2.44.5       TFiler.DefineBinaryProperty             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 307

             2.44.6       TFiler.Root       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  307

             2.44.7       TFiler.LookupRoot           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  307

             2.44.8       TFiler.Ancestor        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  308

             2.44.9       TFiler.IgnoreChildren          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  308

    2.45     TFileStream        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  308

             2.45.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  308

             2.45.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  308

             2.45.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  308

             2.45.4       TFileStream.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  309

             2.45.5       TFileStream.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  309



                                                                 14

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.45.6       TFileStream.FileName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  309

    2.46     TFPList       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  310

             2.46.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  310

             2.46.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  310

             2.46.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  310

             2.46.4       TFPList.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  310

             2.46.5       TFPList.AddList           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  311

             2.46.6       TFPList.Add          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  311

             2.46.7       TFPList.Clear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  311

             2.46.8       TFPList.Delete         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  311

             2.46.9       TFPList.Error        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  312

             2.46.10      TFPList.Exchange            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  312

             2.46.11      TFPList.Expand            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  312

             2.46.12      TFPList.Extract        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  312

             2.46.13      TFPList.First        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  313

             2.46.14      TFPList.GetEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  313

             2.46.15      TFPList.IndexOf           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  313

             2.46.16      TFPList.Insert       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  313

             2.46.17      TFPList.Last         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  314

             2.46.18      TFPList.Move         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  314

             2.46.19      TFPList.Assign         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  314

             2.46.20      TFPList.Remove            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  314

             2.46.21      TFPList.Pack         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  315

             2.46.22      TFPList.Sort         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  315

             2.46.23      TFPList.ForEachCall            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  315

             2.46.24      TFPList.Capacity          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  315

             2.46.25      TFPList.Count          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  316

             2.46.26      TFPList.Items        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  316

             2.46.27      TFPList.List      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  316

    2.47     TFPListEnumerator            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  317

             2.47.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  317

             2.47.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  317

             2.47.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  317

             2.47.4       TFPListEnumerator.Create                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 317

             2.47.5       TFPListEnumerator.GetCurrent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *317

             2.47.6       TFPListEnumerator.MoveNext                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *317

             2.47.7       TFPListEnumerator.Current               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 318

    2.48     THandleStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  318

             2.48.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  318

             2.48.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  318



                                                                 15

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.48.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  318

             2.48.4       THandleStream.SetSize            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  319

             2.48.5       THandleStream.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  319

             2.48.6       THandleStream.Read             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  319

             2.48.7       THandleStream.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  319

             2.48.8       THandleStream.Seek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  320

             2.48.9       THandleStream.Handle             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  320

    2.49     TInterfacedPersistent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  320

             2.49.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  320

             2.49.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  320

             2.49.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  320

             2.49.4       TInterfacedPersistent.QueryInterface                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *20

             2.49.5       TInterfacedPersistent.AfterConstruction                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  321

    2.50     TInterfaceList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  321

             2.50.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  321

             2.50.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  321

             2.50.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  321

             2.50.4       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  322

             2.50.5       TInterfaceList.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  322

             2.50.6       TInterfaceList.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  322

             2.50.7       TInterfaceList.Clear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  322

             2.50.8       TInterfaceList.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  322

             2.50.9       TInterfaceList.Exchange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  323

             2.50.10      TInterfaceList.First        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  323

             2.50.11      TInterfaceList.GetEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 323

             2.50.12      TInterfaceList.IndexOf           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  323

             2.50.13      TInterfaceList.Add          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  324

             2.50.14      TInterfaceList.Insert          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  324

             2.50.15      TInterfaceList.Last         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  324

             2.50.16      TInterfaceList.Remove            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  324

             2.50.17      TInterfaceList.Lock         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  325

             2.50.18      TInterfaceList.Unlock          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  325

             2.50.19      TInterfaceList.Expand            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  325

             2.50.20      TInterfaceList.Capacity          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  325

             2.50.21      TInterfaceList.Count           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  326

             2.50.22      TInterfaceList.Items           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  326

    2.51     TInterfaceListEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  326

             2.51.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  326

             2.51.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  326

             2.51.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  326



                                                                 16

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.51.4       TInterfaceListEnumerator.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *327

             2.51.5       TInterfaceListEnumerator.GetCurrent                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  327

             2.51.6       TInterfaceListEnumerator.MoveNext                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *27

             2.51.7       TInterfaceListEnumerator.Current                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *327

    2.52     TList     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  32@

             2.52.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  328

             2.52.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  328

             2.52.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  328

             2.52.4       TList.Create      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  328

             2.52.5       TList.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  329

             2.52.6       TList.AddList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  329

             2.52.7       TList.Add       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  329

             2.52.8       TList.Clear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  329

             2.52.9       TList.Delete      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  330

             2.52.10      TList.Error       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  330

             2.52.11      TList.Exchange         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  330

             2.52.12      TList.Expand         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  330

             2.52.13      TList.Extract        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  331

             2.52.14      TList.First     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  331

             2.52.15      TList.GetEnumerator            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  331

             2.52.16      TList.IndexOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  331

             2.52.17      TList.Insert      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  332

             2.52.18      TList.Last      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  332

             2.52.19      TList.Move      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  332

             2.52.20      TList.Assign      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  332

             2.52.21      TList.Remove         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  333

             2.52.22      TList.Pack      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  333

             2.52.23      TList.Sort      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  333

             2.52.24      TList.Capacity       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  333

             2.52.25      TList.Count       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  334

             2.52.26      TList.Items       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  334

             2.52.27      TList.List      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  334

    2.53     TListEnumerator            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  335

             2.53.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  335

             2.53.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  335

             2.53.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  335

             2.53.4       TListEnumerator.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  335

             2.53.5       TListEnumerator.GetCurrent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 335

             2.53.6       TListEnumerator.MoveNext                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 335

             2.53.7       TListEnumerator.Current               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  336



                                                                 17

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    2.54     TMemoryStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  336

             2.54.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  336

             2.54.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  336

             2.54.3       TMemoryStream.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  336

             2.54.4       TMemoryStream.Clear              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  337

             2.54.5       TMemoryStream.LoadFromStream                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *37

             2.54.6       TMemoryStream.LoadFromFile                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *337

             2.54.7       TMemoryStream.SetSize               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  338

             2.54.8       TMemoryStream.Write              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  338

    2.55     TOwnedCollection           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  338

             2.55.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  338

             2.55.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  338

             2.55.3       TOwnedCollection.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  338

    2.56     TOwnerStream            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  339

             2.56.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  339

             2.56.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  339

             2.56.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  339

             2.56.4       TOwnerStream.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  339

             2.56.5       TOwnerStream.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  339

             2.56.6       TOwnerStream.Source              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  340

             2.56.7       TOwnerStream.SourceOwner                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 340

    2.57     TParser     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  340

             2.57.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  340

             2.57.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  341

             2.57.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  341

             2.57.4       TParser.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  341

             2.57.5       TParser.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  341

             2.57.6       TParser.CheckToken             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  342

             2.57.7       TParser.CheckTokenSymbol                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 342

             2.57.8       TParser.Error        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  342

             2.57.9       TParser.ErrorFmt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  342

             2.57.10      TParser.ErrorStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  342

             2.57.11      TParser.HexToBinary            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  343

             2.57.12      TParser.NextToken           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  343

             2.57.13      TParser.SourcePos           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  343

             2.57.14      TParser.TokenComponentIdent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *344

             2.57.15      TParser.TokenFloat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  344

             2.57.16      TParser.TokenInt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  344

             2.57.17      TParser.TokenString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  345

             2.57.18      TParser.TokenWideString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  345



                                                                 18

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.57.19      TParser.TokenSymbolIs            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  345

             2.57.20      TParser.FloatType           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  346

             2.57.21      TParser.SourceLine          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  346

             2.57.22      TParser.Token        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  346

    2.58     TPersistent      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  347

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

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

             2.58.3       TPersistent.Destroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  347

             2.58.4       TPersistent.Assign          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  347

             2.58.5       TPersistent.GetNamePath               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  348

    2.59     TProxyStream          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  348

             2.59.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  348

             2.59.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  348

             2.59.3       TProxyStream.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  349

             2.59.4       TProxyStream.Read              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  349

             2.59.5       TProxyStream.Write             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  349

             2.59.6       TProxyStream.Seek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  349

             2.59.7       TProxyStream.Check             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  349

    2.60     TReader       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  349

             2.60.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  349

             2.60.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  350

             2.60.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  351

             2.60.4       TReader.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  351

             2.60.5       TReader.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  351

             2.60.6       TReader.BeginReferences             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  351

             2.60.7       TReader.CheckValue             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  352

             2.60.8       TReader.DefineProperty              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  352

             2.60.9       TReader.DefineBinaryProperty                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *352

             2.60.10      TReader.EndOfList           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  352

             2.60.11      TReader.EndReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  352

             2.60.12      TReader.FixupReferences               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  353

             2.60.13      TReader.NextValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  353

             2.60.14      TReader.Read         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  353

             2.60.15      TReader.ReadBoolean              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  353

             2.60.16      TReader.ReadChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  353

             2.60.17      TReader.ReadWideChar                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  354

             2.60.18      TReader.ReadUnicodeChar                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 354

             2.60.19      TReader.ReadCollection              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  354

             2.60.20      TReader.ReadComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  354

             2.60.21      TReader.ReadComponents                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  354



                                                                 19

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.60.22      TReader.ReadFloat           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  355

             2.60.23      TReader.ReadSingle             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  355

             2.60.24      TReader.ReadDate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  355

             2.60.25      TReader.ReadCurrency             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  355

             2.60.26      TReader.ReadIdent           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  355

             2.60.27      TReader.ReadInteger            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  356

             2.60.28      TReader.ReadInt64           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  356

             2.60.29      TReader.ReadSet           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  356

             2.60.30      TReader.ReadListBegin               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  356

             2.60.31      TReader.ReadListEnd              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  356

             2.60.32      TReader.ReadRootComponent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 357

             2.60.33      TReader.ReadVariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  357

             2.60.34      TReader.ReadString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  357

             2.60.35      TReader.ReadWideString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  357

             2.60.36      TReader.ReadUnicodeString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 357

             2.60.37      TReader.ReadValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  358

             2.60.38      TReader.CopyValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  358

             2.60.39      TReader.Driver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  358

             2.60.40      TReader.Owner          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  358

             2.60.41      TReader.Parent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  358

             2.60.42      TReader.OnError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  359

             2.60.43      TReader.OnPropertyNotFound                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *359

             2.60.44      TReader.OnFindMethod                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  359

             2.60.45      TReader.OnSetMethodProperty                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *359

             2.60.46      TReader.OnSetName              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  360

             2.60.47      TReader.OnReferenceName                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 360

             2.60.48      TReader.OnAncestorNotFound                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *360

             2.60.49      TReader.OnCreateComponent                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 360

             2.60.50      TReader.OnFindComponentClass                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *360

             2.60.51      TReader.OnReadStringProperty                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *361

    2.61     TRecall     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  361

             2.61.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  361

             2.61.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  361

             2.61.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  361

             2.61.4       TRecall.Create       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  362

             2.61.5       TRecall.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  362

             2.61.6       TRecall.Store        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  362

             2.61.7       TRecall.Forget       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  362

             2.61.8       TRecall.Reference         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  363

    2.62     TResourceStream            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  363



                                                                 20

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.62.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  363

             2.62.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  363

             2.62.3       TResourceStream.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  363

             2.62.4       TResourceStream.CreateFromID                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *363

             2.62.5       TResourceStream.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  364

    2.63     TStream       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  364

             2.63.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  364

             2.63.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  364

             2.63.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  365

             2.63.4       TStream.SetSize        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  365

             2.63.5       TStream.Read         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  365

             2.63.6       TStream.Write        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  365

             2.63.7       TStream.Seek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  366

             2.63.8       TStream.ReadBuffer             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  366

             2.63.9       TStream.WriteBuffer            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  367

             2.63.10      TStream.CopyFrom            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  367

             2.63.11      TStream.ReadComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  367

             2.63.12      TStream.ReadComponentRes                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 368

             2.63.13      TStream.WriteComponent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  368

             2.63.14      TStream.WriteComponentRes                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 368

             2.63.15      TStream.WriteDescendent               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  368

             2.63.16      TStream.WriteDescendentRes                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 369

             2.63.17      TStream.WriteResourceHeader                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 369

             2.63.18      TStream.FixupResourceHeader                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *369

             2.63.19      TStream.ReadResHeader               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  370

             2.63.20      TStream.ReadByte            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  370

             2.63.21      TStream.ReadWord            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  370

             2.63.22      TStream.ReadDWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  370

             2.63.23      TStream.ReadQWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  371

             2.63.24      TStream.ReadAnsiString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  371

             2.63.25      TStream.WriteByte           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  371

             2.63.26      TStream.WriteWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  372

             2.63.27      TStream.WriteDWord               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  372

             2.63.28      TStream.WriteQWord               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  372

             2.63.29      TStream.WriteAnsiString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  372

             2.63.30      TStream.Position          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  373

             2.63.31      TStream.Size         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  373

    2.64     TStreamAdapter          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  373

             2.64.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  373

             2.64.2       Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  373



                                                                 21

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.64.3       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  374

             2.64.4       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  374

             2.64.5       TStreamAdapter.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  374

             2.64.6       TStreamAdapter.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  374

             2.64.7       TStreamAdapter.Read              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  374

             2.64.8       TStreamAdapter.Write             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  375

             2.64.9       TStreamAdapter.Seek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  375

             2.64.10      TStreamAdapter.SetSize              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  375

             2.64.11      TStreamAdapter.CopyTo               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  376

             2.64.12      TStreamAdapter.Commit                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  376

             2.64.13      TStreamAdapter.Revert               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  376

             2.64.14      TStreamAdapter.LockRegion                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 376

             2.64.15      TStreamAdapter.UnlockRegion                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *377

             2.64.16      TStreamAdapter.Stat            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  377

             2.64.17      TStreamAdapter.Clone             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  377

             2.64.18      TStreamAdapter.Stream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  377

             2.64.19      TStreamAdapter.StreamOwnership                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  3*
 *78

    2.65     TStringList      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  378

             2.65.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  378

             2.65.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  378

             2.65.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  378

             2.65.4       TStringList.InsertItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  379

             2.65.5       TStringList.Destroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  379

             2.65.6       TStringList.Add        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  379

             2.65.7       TStringList.Clear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  379

             2.65.8       TStringList.Delete        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  379

             2.65.9       TStringList.Exchange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  380

             2.65.10      TStringList.Find          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  380

             2.65.11      TStringList.IndexOf         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  380

             2.65.12      TStringList.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  380

             2.65.13      TStringList.Sort       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  381

             2.65.14      TStringList.CustomSort              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  381

             2.65.15      TStringList.Duplicates           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  381

             2.65.16      TStringList.Sorted          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  382

             2.65.17      TStringList.CaseSensitive             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  382

             2.65.18      TStringList.OnChange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  382

             2.65.19      TStringList.OnChanging              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  383

             2.65.20      TStringList.OwnsObjects             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  383

    2.66     TStrings      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  383

             2.66.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  383



                                                                 22

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.66.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  384

             2.66.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  385

             2.66.4       TStrings.Error       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  385

             2.66.5       TStrings.Destroy          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  385

             2.66.6       TStrings.Add         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  386

             2.66.7       TStrings.AddObject          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  386

             2.66.8       TStrings.Append           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  386

             2.66.9       TStrings.AddStrings            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  386

             2.66.10      TStrings.Assign        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  387

             2.66.11      TStrings.BeginUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  387

             2.66.12      TStrings.Clear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  387

             2.66.13      TStrings.Delete        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  388

             2.66.14      TStrings.EndUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  388

             2.66.15      TStrings.Equals        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  388

             2.66.16      TStrings.Exchange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  389

             2.66.17      TStrings.GetEnumerator              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  389

             2.66.18      TStrings.GetText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  389

             2.66.19      TStrings.IndexOf          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  389

             2.66.20      TStrings.IndexOfName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  390

             2.66.21      TStrings.IndexOfObject              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  390

             2.66.22      TStrings.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  390

             2.66.23      TStrings.InsertObject          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  391

             2.66.24      TStrings.LoadFromFile            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  391

             2.66.25      TStrings.LoadFromStream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  391

             2.66.26      TStrings.Move        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  391

             2.66.27      TStrings.SaveToFile         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  392

             2.66.28      TStrings.SaveToStream            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  392

             2.66.29      TStrings.SetText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  393

             2.66.30      TStrings.GetNameValue               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  393

             2.66.31      TStrings.ExtractName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  393

             2.66.32      TStrings.TextLineBreakStyle             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 393

             2.66.33      TStrings.Delimiter          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  394

             2.66.34      TStrings.DelimitedText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  394

             2.66.35      TStrings.StrictDelimiter            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  395

             2.66.36      TStrings.QuoteChar          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  395

             2.66.37      TStrings.NameValueSeparator                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 395

             2.66.38      TStrings.ValueFromIndex               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  395

             2.66.39      TStrings.Capacity         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  396

             2.66.40      TStrings.CommaText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  396

             2.66.41      TStrings.Count         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  397



                                                                 23

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.66.42      TStrings.Names         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  397

             2.66.43      TStrings.Objects          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  397

             2.66.44      TStrings.Values        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  398

             2.66.45      TStrings.Strings       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  398

             2.66.46      TStrings.Text        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  399

             2.66.47      TStrings.StringsAdapter             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  399

    2.67     TStringsEnumerator           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  399

             2.67.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  399

             2.67.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  400

             2.67.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  400

             2.67.4       TStringsEnumerator.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 400

             2.67.5       TStringsEnumerator.GetCurrent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *400

             2.67.6       TStringsEnumerator.MoveNext                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *400

             2.67.7       TStringsEnumerator.Current              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 401

    2.68     TStringStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  401

             2.68.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  401

             2.68.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  401

             2.68.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  401

             2.68.4       TStringStream.Create           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  401

             2.68.5       TStringStream.Read             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  402

             2.68.6       TStringStream.ReadString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  402

             2.68.7       TStringStream.Seek          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  402

             2.68.8       TStringStream.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  402

             2.68.9       TStringStream.WriteString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  402

             2.68.10      TStringStream.DataString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  403

    2.69     TTextObjectWriter            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  403

             2.69.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  403

    2.70     TThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  403

             2.70.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  403

             2.70.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  403

             2.70.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  403

             2.70.4       TThread.Synchronize            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  404

             2.70.5       TThread.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  404

             2.70.6       TThread.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  404

             2.70.7       TThread.AfterConstruction               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 404

             2.70.8       TThread.Start        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  404

             2.70.9       TThread.Resume            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  405

             2.70.10      TThread.Suspend           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  405

             2.70.11      TThread.Terminate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  405

             2.70.12      TThread.WaitFor           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  405



                                                                 24

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.70.13      TThread.FreeOnTerminate               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  405

             2.70.14      TThread.Handle         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  406

             2.70.15      TThread.Priority          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  406

             2.70.16      TThread.Suspended           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  406

             2.70.17      TThread.ThreadID            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  406

             2.70.18      TThread.OnTerminate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  406

             2.70.19      TThread.FatalException              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  407

    2.71     TThreadList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  407

             2.71.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  407

             2.71.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  407

             2.71.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  407

             2.71.4       TThreadList.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  407

             2.71.5       TThreadList.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  408

             2.71.6       TThreadList.Add           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  408

             2.71.7       TThreadList.Clear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  408

             2.71.8       TThreadList.LockList           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  408

             2.71.9       TThreadList.Remove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  409

             2.71.10      TThreadList.UnlockList              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  409

             2.71.11      TThreadList.Duplicates           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  409

    2.72     TWriter     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  409

             2.72.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  409

             2.72.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  410

             2.72.3       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  410

             2.72.4       TWriter.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  410

             2.72.5       TWriter.Destroy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  411

             2.72.6       TWriter.DefineProperty              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  411

             2.72.7       TWriter.DefineBinaryProperty               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 411

             2.72.8       TWriter.Write        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  411

             2.72.9       TWriter.WriteBoolean             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  411

             2.72.10      TWriter.WriteCollection             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  412

             2.72.11      TWriter.WriteComponent                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  412

             2.72.12      TWriter.WriteChar           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  412

             2.72.13      TWriter.WriteWideChar               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  412

             2.72.14      TWriter.WriteDescendent               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  412

             2.72.15      TWriter.WriteFloat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  413

             2.72.16      TWriter.WriteSingle         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  413

             2.72.17      TWriter.WriteDate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  413

             2.72.18      TWriter.WriteCurrency            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  413

             2.72.19      TWriter.WriteIdent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  413

             2.72.20      TWriter.WriteInteger           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  414



                                                                 25

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             2.72.21      TWriter.WriteSet          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  414

             2.72.22      TWriter.WriteListBegin           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  414

             2.72.23      TWriter.WriteListEnd             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  414

             2.72.24      TWriter.WriteRootComponent                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 414

             2.72.25      TWriter.WriteString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  415

             2.72.26      TWriter.WriteWideString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  415

             2.72.27      TWriter.WriteUnicodeString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 415

             2.72.28      TWriter.WriteVariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  415

             2.72.29      TWriter.RootAncestor             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  415

             2.72.30      TWriter.OnFindAncestor              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  416

             2.72.31      TWriter.OnWriteMethodProperty                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *416

             2.72.32      TWriter.OnWriteStringProperty                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *416

             2.72.33      TWriter.Driver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  416

             2.72.34      TWriter.PropertyPath             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  417


3    Reference for unit 'clocale'                                                                                       418

    3.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  418


4    Reference for unit 'cmem'                                                                                          419

    4.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  419

    4.2      Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  419

             4.2.1        Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  419

    4.3      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  419

             4.3.1        CAlloc     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  419

             4.3.2        Free  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  420

             4.3.3        Malloc     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  420

             4.3.4        ReAlloc    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  420


5    Reference for unit 'Crt'                                                                                           421

    5.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  421

    5.2      Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  421

             5.2.1        Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  421

             5.2.2        Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  424

             5.2.3        Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  424

    5.3      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  425

             5.3.1        AssignCrt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  425

             5.3.2        ClrEol     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  426

             5.3.3        ClrScr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  427

             5.3.4        cursorbig     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  427

             5.3.5        cursoroff     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  427

             5.3.6        cursoron      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  428



                                                                 26

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             5.3.7        Delay    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  428

             5.3.8        DelLine    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  428

             5.3.9        GotoXY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  429

             5.3.10       HighVideo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  430

             5.3.11       InsLine    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  430

             5.3.12       KeyPressed        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  431

             5.3.13       LowVideo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  431

             5.3.14       NormVideo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  432

             5.3.15       NoSound       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  432

             5.3.16       ReadKey       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  432

             5.3.17       Sound      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  433

             5.3.18       TextBackground         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  433

             5.3.19       TextColor       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  434

             5.3.20       TextMode        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  435

             5.3.21       WhereX        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  435

             5.3.22       WhereY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  435

             5.3.23       Window        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  436


6    Reference for unit 'cthreads'                                                                                      437

    6.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  437

    6.2      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  437

             6.2.1        SetCThreadManager              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  437


7    Reference for unit 'ctypes'                                                                                        438

    7.1      Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  438

    7.2      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  438

    7.3      Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  438

             7.3.1        Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  438

    7.4      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  443

             7.4.1        operator *(clongdouble, Double):  Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  443

             7.4.2        operator *(Double, clongdouble):  Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  443

             7.4.3        operator +(clongdouble, Double):  Double                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  444

             7.4.4        operator +(Double, clongdouble):  Double                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  444

             7.4.5        operator -(clongdouble, Double):  Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  444

             7.4.6        operator -(Double, clongdouble):  Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  444

             7.4.7        operator /(clongdouble, Double):  Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  445

             7.4.8        operator /(Double, clongdouble):  Double                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  445

             7.4.9        operator :=(clongdouble):  Double               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *445

             7.4.10       operator :=(Double):  clongdouble               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *445

             7.4.11       operator <(clongdouble, Double):  Boolean                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  445

             7.4.12       operator <(Double, clongdouble):  Boolean                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  446



                                                                 27

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             7.4.13       operator <=(clongdouble, Double):  Boolean                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  446

             7.4.14       operator <=(Double, clongdouble):  Boolean                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  446

             7.4.15       operator =(clongdouble, Double):  Boolean                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  446

             7.4.16       operator =(Double, clongdouble):  Boolean                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  447

             7.4.17       operator >(clongdouble, Double):  Boolean                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  447

             7.4.18       operator >(Double, clongdouble):  Boolean                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  447

             7.4.19       operator >=(clongdouble, Double):  Boolean                    .  .  .  .  .  .  .  .  .  .  .  .  .  447

             7.4.20       operator >=(Double, clongdouble):  Boolean                    .  .  .  .  .  .  .  .  .  .  .  .  .  448


8    Reference for unit 'cwstring'                                                                                      449

    8.1      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  449

    8.2      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  449

             8.2.1        SetCWidestringManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  449


9    Reference for unit 'dateutils'                                                                                     450

    9.1      Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  450

    9.2      Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  450

    9.3      Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  450

             9.3.1        Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  450

    9.4      Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  452

             9.4.1        CompareDate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  452

             9.4.2        CompareDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  453

             9.4.3        CompareTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  454

             9.4.4        DateOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  455

             9.4.5        DateTimeToDosDateTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  456

             9.4.6        DateTimeToJulianDate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  456

             9.4.7        DateTimeToMac             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  456

             9.4.8        DateTimeToModifiedJulianDate                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *457

             9.4.9        DateTimeToUnix            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  457

             9.4.10       DayOf      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  457

             9.4.11       DayOfTheMonth             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  458

             9.4.12       DayOfTheWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  458

             9.4.13       DayOfTheYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  458

             9.4.14       DaysBetween          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  459

             9.4.15       DaysInAMonth           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  460

             9.4.16       DaysInAYear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  460

             9.4.17       DaysInMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  461

             9.4.18       DaysInYear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  461

             9.4.19       DaySpan       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  462

             9.4.20       DecodeDateDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  462

             9.4.21       DecodeDateMonthWeek                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  463



                                                                 28

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             9.4.22       DecodeDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  464

             9.4.23       DecodeDateWeek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  464

             9.4.24       DecodeDayOfWeekInMonth                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 465

             9.4.25       DosDateTimeToDateTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  465

             9.4.26       EncodeDateDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  466

             9.4.27       EncodeDateMonthWeek                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  466

             9.4.28       EncodeDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  466

             9.4.29       EncodeDateWeek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  467

             9.4.30       EncodeDayOfWeekInMonth                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 467

             9.4.31       EncodeTimeInterval          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  468

             9.4.32       EndOfADay         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  468

             9.4.33       EndOfAMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  469

             9.4.34       EndOfAWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  469

             9.4.35       EndOfAYear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  470

             9.4.36       EndOfTheDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  470

             9.4.37       EndOfTheMonth             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  471

             9.4.38       EndOfTheWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  471

             9.4.39       EndOfTheYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  472

             9.4.40       HourOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  472

             9.4.41       HourOfTheDay           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  473

             9.4.42       HourOfTheMonth            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  473

             9.4.43       HourOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  474

             9.4.44       HourOfTheYear          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  474

             9.4.45       HoursBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  474

             9.4.46       HourSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  475

             9.4.47       IncDay     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  476

             9.4.48       IncHour       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  476

             9.4.49       IncMilliSecond       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  477

             9.4.50       IncMinute       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  477

             9.4.51       IncSecond       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  478

             9.4.52       IncWeek       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  479

             9.4.53       IncYear    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  479

             9.4.54       InvalidDateDayError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  480

             9.4.55       InvalidDateMonthWeekError               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 480

             9.4.56       InvalidDateTimeError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  480

             9.4.57       InvalidDateWeekError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  481

             9.4.58       InvalidDayOfWeekInMonthError                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *481

             9.4.59       IsInLeapYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  481

             9.4.60       IsPM     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  482

             9.4.61       IsSameDay       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  482



                                                                 29

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             9.4.62       IsSameMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  483

             9.4.63       IsToday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  483

             9.4.64       IsValidDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  484

             9.4.65       IsValidDateDay         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  484

             9.4.66       IsValidDateMonthWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  485

             9.4.67       IsValidDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  486

             9.4.68       IsValidDateWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  487

             9.4.69       IsValidTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  487

             9.4.70       JulianDateToDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  488

             9.4.71       MacTimeStampToUnix               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  488

             9.4.72       MacToDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  488

             9.4.73       MilliSecondOf        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  488

             9.4.74       MilliSecondOfTheDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  489

             9.4.75       MilliSecondOfTheHour             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  489

             9.4.76       MilliSecondOfTheMinute              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  489

             9.4.77       MilliSecondOfTheMonth               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  490

             9.4.78       MilliSecondOfTheSecond              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  490

             9.4.79       MilliSecondOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  490

             9.4.80       MilliSecondOfTheYear             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  491

             9.4.81       MilliSecondsBetween            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  491

             9.4.82       MilliSecondSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  492

             9.4.83       MinuteOf      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  493

             9.4.84       MinuteOfTheDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  493

             9.4.85       MinuteOfTheHour           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  493

             9.4.86       MinuteOfTheMonth            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  494

             9.4.87       MinuteOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  494

             9.4.88       MinuteOfTheYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  494

             9.4.89       MinutesBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  495

             9.4.90       MinuteSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  496

             9.4.91       ModifiedJulianDateToDateTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *496

             9.4.92       MonthOf       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  497

             9.4.93       MonthOfTheYear            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  497

             9.4.94       MonthsBetween          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  497

             9.4.95       MonthSpan         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  498

             9.4.96       NthDayOfWeek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  499

             9.4.97       PreviousDayOfWeek              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  500

             9.4.98       RecodeDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  500

             9.4.99       RecodeDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  501

             9.4.100      RecodeDay       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  502

             9.4.101      RecodeHour        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  502



                                                                 30

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             9.4.102      RecodeMilliSecond           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  503

             9.4.103      RecodeMinute         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  504

             9.4.104      RecodeMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  504

             9.4.105      RecodeSecond         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  505

             9.4.106      RecodeTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  506

             9.4.107      RecodeYear        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  506

             9.4.108      SameDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  507

             9.4.109      SameDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  508

             9.4.110      SameTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  509

             9.4.111      ScanDateTime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  509

             9.4.112      SecondOf      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  510

             9.4.113      SecondOfTheDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  510

             9.4.114      SecondOfTheHour           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  510

             9.4.115      SecondOfTheMinute              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  511

             9.4.116      SecondOfTheMonth            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  511

             9.4.117      SecondOfTheWeek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  511

             9.4.118      SecondOfTheYear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  512

             9.4.119      SecondsBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  512

             9.4.120      SecondSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  513

             9.4.121      StartOfADay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  514

             9.4.122      StartOfAMonth          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  515

             9.4.123      StartOfAWeek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  515

             9.4.124      StartOfAYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  516

             9.4.125      StartOfTheDay          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  516

             9.4.126      StartOfTheMonth           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  517

             9.4.127      StartOfTheWeek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  517

             9.4.128      StartOfTheYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  518

             9.4.129      TimeOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  518

             9.4.130      Today      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  519

             9.4.131      Tomorrow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  519

             9.4.132      TryEncodeDateDay            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  520

             9.4.133      TryEncodeDateMonthWeek                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 520

             9.4.134      TryEncodeDateTime              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  521

             9.4.135      TryEncodeDateWeek              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  522

             9.4.136      TryEncodeDayOfWeekInMonth                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *522

             9.4.137      TryEncodeTimeInterval            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  523

             9.4.138      TryJulianDateToDateTime               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  523

             9.4.139      TryModifiedJulianDateToDateTime                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *24

             9.4.140      TryRecodeDateTime              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  524

             9.4.141      UnixTimeStampToMac               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  525



                                                                 31

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             9.4.142      UnixToDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  525

             9.4.143      WeekOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  525

             9.4.144      WeekOfTheMonth            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  526

             9.4.145      WeekOfTheYear          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  526

             9.4.146      WeeksBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  527

             9.4.147      WeeksInAYear         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  528

             9.4.148      WeeksInYear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  528

             9.4.149      WeekSpan        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  529

             9.4.150      WithinPastDays         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  530

             9.4.151      WithinPastHours           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  531

             9.4.152      WithinPastMilliSeconds              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  532

             9.4.153      WithinPastMinutes           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  533

             9.4.154      WithinPastMonths            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  534

             9.4.155      WithinPastSeconds           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  535

             9.4.156      WithinPastWeeks           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  536

             9.4.157      WithinPastYears           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  537

             9.4.158      YearOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  538

             9.4.159      YearsBetween         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  538

             9.4.160      YearSpan      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  539

             9.4.161      Yesterday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  540


10   Reference for unit 'Dos'                                                                                           541

    10.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  541

    10.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  541

    10.3     System information           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  541

    10.4     Process handling        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  542

    10.5     Directory and disk handling              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  542

    10.6     File handling      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  543

    10.7     File open mode constants.              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  543

    10.8     File attributes       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  543

    10.9     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  544

             10.9.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  544

             10.9.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  546

             10.9.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  548

    10.10    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  548

             10.10.1      AddDisk       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  548

             10.10.2      DiskFree      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  549

             10.10.3      DiskSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  549

             10.10.4      DosExitCode       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  550

             10.10.5      DosVersion      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  551



                                                                 32

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             10.10.6      DTToUnixDate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  551

             10.10.7      EnvCount        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  552

             10.10.8      EnvStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  552

             10.10.9      Exec     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  552

             10.10.10     FExpand       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  553

             10.10.11     FindClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  553

             10.10.12     FindFirst     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  554

             10.10.13     FindNext      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  554

             10.10.14     FSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  555

             10.10.15     FSplit     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  555

             10.10.16     GetCBreak       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  556

             10.10.17     GetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  556

             10.10.18     GetEnv     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  557

             10.10.19     GetFAttr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  557

             10.10.20     GetFTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  558

             10.10.21     GetIntVec       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  559

             10.10.22     GetLongName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  559

             10.10.23     GetMsCount        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  560

             10.10.24     GetShortName         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  560

             10.10.25     GetTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  561

             10.10.26     GetVerify     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  561

             10.10.27     Intr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  562

             10.10.28     Keep     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  562

             10.10.29     MSDos      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  562

             10.10.30     PackTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  562

             10.10.31     SetCBreak       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  563

             10.10.32     SetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  564

             10.10.33     SetFAttr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  564

             10.10.34     SetFTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  564

             10.10.35     SetIntVec     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  565

             10.10.36     SetTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  565

             10.10.37     SetVerify     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  565

             10.10.38     SwapVectors       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  566

             10.10.39     UnixDateToDt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  566

             10.10.40     UnpackTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  566

             10.10.41     weekday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  566


11   Reference for unit 'dxeload'                                                                                       567

    11.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  567

    11.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  567



                                                                 33

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             11.2.1       dxe_load      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  567


12   Reference for unit 'dynlibs'                                                                                       568

    12.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  568

    12.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  568

             12.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  568

             12.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  568

    12.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  569

             12.3.1       FreeLibrary       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  569

             12.3.2       GetProcAddress         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  569

             12.3.3       GetProcedureAddress            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  569

             12.3.4       LoadLibrary       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  569

             12.3.5       SafeLoadLibrary        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  570

             12.3.6       UnloadLibrary        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  570


13   Reference for unit 'emu387'                                                                                        571

    13.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  571

    13.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  571

             13.2.1       npxsetup      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  571


14   Reference for unit 'exeinfo'                                                                                       573

    14.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  573

    14.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  573

             14.2.1       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  573

    14.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  574

             14.3.1       CloseExeFile      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  574

             14.3.2       FindExeSection         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  574

             14.3.3       GetModuleByAddr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  574

             14.3.4       OpenExeFile       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  574

             14.3.5       ReadDebugLink          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  575


15   Reference for unit 'getopts'                                                                                       576

    15.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  576

    15.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  576

             15.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  576

             15.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  577

             15.2.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  577

    15.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  578

             15.3.1       GetLongOpts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  578

             15.3.2       GetOpt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  578


16   Reference for unit 'go32'                                                                                          581



                                                                 34

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    16.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  581

    16.2     Real mode callbacks          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  581

    16.3     Executing software interrupts               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  582

    16.4     Software interrupts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  584

    16.5     Hardware interrupts          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  584

    16.6     Disabling interrupts         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  586

    16.7     Creating your own interrupt handlers                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 586

    16.8     Protected mode interrupts vs.  Real mode interrupts                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  586

    16.9     Handling interrupts with DPMI                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  587

    16.10    Interrupt redirection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  587

    16.11    Processor access        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  587

    16.12    I/O port access         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  587

    16.13    dos memory access            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  587

    16.14    FPC specialities        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  588

    16.15    Selectors and descriptors           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  588

    16.16    What is DPMI          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  588

    16.17    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  588

             16.17.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  588

             16.17.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  591

             16.17.3      Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  592

    16.18    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  592

             16.18.1      allocate_ldt_descriptors         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  592

             16.18.2      allocate_memory_block            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  594

             16.18.3      copyfromdos       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  595

             16.18.4      copytodos       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  595

             16.18.5      create_code_segment_alias_descriptor              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  5*
 *95

             16.18.6      disable    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  596

             16.18.7      dpmi_dosmemfillchar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  596

             16.18.8      dpmi_dosmemfillword            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  596

             16.18.9      dpmi_dosmemget            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  597

             16.18.10     dpmi_dosmemmove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  597

             16.18.11     dpmi_dosmemput            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  597

             16.18.12     enable     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  597

             16.18.13     free_ldt_descriptor       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  598

             16.18.14     free_memory_block           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  598

             16.18.15     free_rm_callback       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  598

             16.18.16     get_cs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  599

             16.18.17     get_descriptor_access_right           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  599

             16.18.18     get_ds   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  599

             16.18.19     get_exception_handler          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  600



                                                                 35

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             16.18.20     get_linear_addr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  600

             16.18.21     get_meminfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  600

             16.18.22     get_next_selector_increment_value               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *601

             16.18.23     get_page_size     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  602

             16.18.24     get_pm_exception_handler            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  602

             16.18.25     get_pm_interrupt          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  602

             16.18.26     get_rm_callback        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  603

             16.18.27     get_rm_interrupt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  606

             16.18.28     get_run_mode         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  606

             16.18.29     get_segment_base_address            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  607

             16.18.30     get_segment_limit         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  607

             16.18.31     get_ss   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  608

             16.18.32     global_dos_alloc       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  608

             16.18.33     global_dos_free      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  609

             16.18.34     inportb    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  610

             16.18.35     inportl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  610

             16.18.36     inportw    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  611

             16.18.37     lock_code     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  611

             16.18.38     lock_data     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  611

             16.18.39     lock_linear_region        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  612

             16.18.40     map_device_in_memory_block              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 612

             16.18.41     outportb      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  612

             16.18.42     outportl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  613

             16.18.43     outportw      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  613

             16.18.44     realintr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  614

             16.18.45     request_linear_region          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  614

             16.18.46     segment_to_descriptor          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  615

             16.18.47     seg_fillchar    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  615

             16.18.48     seg_fillword    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  616

             16.18.49     seg_move      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  616

             16.18.50     set_descriptor_access_right           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  617

             16.18.51     set_exception_handler          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  617

             16.18.52     set_pm_exception_handler            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  617

             16.18.53     set_pm_interrupt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  618

             16.18.54     set_rm_interrupt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  619

             16.18.55     set_segment_base_address            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  619

             16.18.56     set_segment_limit         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  620

             16.18.57     tb_offset     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  620

             16.18.58     tb_segment      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  620

             16.18.59     tb_size    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  620



                                                                 36

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             16.18.60     transfer_buffer      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  621

             16.18.61     unlock_code       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  621

             16.18.62     unlock_data       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  621

             16.18.63     unlock_linear_region        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  622


17   Reference for unit 'gpm'                                                                                           623

    17.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  623

    17.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  623

    17.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  623

             17.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  623

             17.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  625

             17.3.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  627

    17.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  628

             17.4.1       Gpm_AnyDouble             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  628

             17.4.2       Gpm_AnySingle          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  628

             17.4.3       Gpm_AnyTriple          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  628

             17.4.4       gpm_close       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  629

             17.4.5       gpm_fitvalues        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  629

             17.4.6       gpm_fitvaluesM         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  629

             17.4.7       gpm_getevent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  629

             17.4.8       gpm_getsnapshot           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  631

             17.4.9       gpm_lowerroi      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  631

             17.4.10      gpm_open        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  631

             17.4.11      gpm_poproi        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  632

             17.4.12      gpm_pushroi       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  632

             17.4.13      gpm_raiseroi      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  632

             17.4.14      gpm_repeat      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  632

             17.4.15      Gpm_StrictDouble          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  633

             17.4.16      Gpm_StrictSingle          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  633

             17.4.17      Gpm_StrictTriple          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  633


18   Reference for unit 'Graph'                                                                                         634

    18.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  634

    18.2     Categorized functions:  Text and font handling                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  6*
 *34

    18.3     Categorized functions:  Filled drawings                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 634

    18.4     Categorized functions:  Drawing primitives                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *635

    18.5     Categorized functions:  Color management                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *635

    18.6     Categorized functions:  Screen management                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *636

    18.7     Categorized functions:  Initialization             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  636

    18.8     Target specific issues:  Linux           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  637

    18.9     Target specific issues:  DOS           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  638



                                                                 37

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    18.10    A word about mode selection              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  638

    18.11    Requirements          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  642

    18.12    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  643

             18.12.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  643

             18.12.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  659

             18.12.3      Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  665

    18.13    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  667

             18.13.1      Arc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  667

             18.13.2      Bar   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  667

             18.13.3      Bar3D      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  668

             18.13.4      ClearDevice       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  668

             18.13.5      Closegraph      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  668

             18.13.6      DetectGraph       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  668

             18.13.7      DrawPoly        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  669

             18.13.8      Ellipse    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  669

             18.13.9      FillEllipse     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  669

             18.13.10     FillPoly   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  670

             18.13.11     FloodFill     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  670

             18.13.12     GetArcCoords         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  670

             18.13.13     GetAspectRatio         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  670

             18.13.14     GetColor      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  671

             18.13.15     GetDefaultPalette         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  671

             18.13.16     GetDirectVideo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  671

             18.13.17     GetDriverName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  671

             18.13.18     GetFillPattern       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  672

             18.13.19     GetFillSettings        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  672

             18.13.20     GetGraphMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  672

             18.13.21     GetLineSettings        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  672

             18.13.22     GetMaxColor          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  673

             18.13.23     GetMaxMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  673

             18.13.24     GetMaxX         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  673

             18.13.25     GetMaxY         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  673

             18.13.26     GetModeName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  674

             18.13.27     GetModeRange           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  674

             18.13.28     GetPalette      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  674

             18.13.29     GetPaletteSize       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  674

             18.13.30     GetTextSettings        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  675

             18.13.31     GetViewSettings        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  675

             18.13.32     GetX     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  675

             18.13.33     GetY     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  675



                                                                 38

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             18.13.34     GraphDefaults        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  676

             18.13.35     GraphErrorMsg          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  676

             18.13.36     GraphResult       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  676

             18.13.37     InitGraph       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  677

             18.13.38     InstallUserDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  677

             18.13.39     InstallUserFont        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  678

             18.13.40     LineRel    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  678

             18.13.41     LineTo     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  678

             18.13.42     MoveRel       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  678

             18.13.43     MoveTo        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  679

             18.13.44     OutText       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  679

             18.13.45     PieSlice   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  679

             18.13.46     queryadapterinfo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  679

             18.13.47     Rectangle       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  680

             18.13.48     RegisterBGIDriver           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  680

             18.13.49     RegisterBGIfont        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  680

             18.13.50     RestoreCrtMode         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  680

             18.13.51     Sector     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  681

             18.13.52     SetAspectRatio         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  681

             18.13.53     SetColor      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  681

             18.13.54     SetDirectVideo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  681

             18.13.55     SetFillPattern       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  682

             18.13.56     SetFillStyle      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  682

             18.13.57     SetGraphMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  682

             18.13.58     SetLineStyle      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  683

             18.13.59     SetPalette      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  683

             18.13.60     SetTextJustify       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  683

             18.13.61     SetTextStyle      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  684

             18.13.62     SetUserCharSize        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  685

             18.13.63     SetViewPort       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  685

             18.13.64     SetWriteMode         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  685

             18.13.65     TextHeight      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  686

             18.13.66     TextWidth       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  686


19   Reference for unit 'heaptrc'                                                                                       687

    19.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  687

    19.2     Controlling HeapTrc with environment variables                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  687

    19.3     HeapTrc Usage         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  688

    19.4     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  689

             19.4.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  689



                                                                 39

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             19.4.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  690

    19.5     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  690

             19.5.1       DumpHeap        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  690

             19.5.2       SetHeapExtraInfo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  691

             19.5.3       SetHeapTraceOutput             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  692


20   Reference for unit 'ipc'                                                                                           693

    20.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  693

    20.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  693

    20.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  693

             20.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  693

             20.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  696

    20.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  700

             20.4.1       ftok  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  700

             20.4.2       msgctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  700

             20.4.3       msgget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  702

             20.4.4       msgrcv     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  703

             20.4.5       msgsnd     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  704

             20.4.6       semctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  704

             20.4.7       semget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  709

             20.4.8       semop      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  709

             20.4.9       semtimedop        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  710

             20.4.10      shmat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  710

             20.4.11      shmctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  711

             20.4.12      shmdt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  713

             20.4.13      shmget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  713


21   Reference for unit 'keyboard'                                                                                      715

    21.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  715

    21.2     Unix specific notes        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  715

    21.3     Writing a keyboard driver              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  716

    21.4     Keyboard scan codes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  719

    21.5     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  721

             21.5.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  721

             21.5.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  726

    21.6     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  727

             21.6.1       AddSequence          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  727

             21.6.2       AddSpecialSequence             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  727

             21.6.3       DoneKeyboard         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  728

             21.6.4       FindSequence         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  728

             21.6.5       FunctionKeyName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  728



                                                                 40

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             21.6.6       GetKeyboardDriver           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  729

             21.6.7       GetKeyEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  729

             21.6.8       GetKeyEventChar           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  730

             21.6.9       GetKeyEventCode             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  731

             21.6.10      GetKeyEventFlags            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  731

             21.6.11      GetKeyEventShiftState            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  732

             21.6.12      GetKeyEventUniCode               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  732

             21.6.13      InitKeyboard         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  733

             21.6.14      IsFunctionKey        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  733

             21.6.15      KeyEventToString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  734

             21.6.16      KeyPressed        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  734

             21.6.17      PollKeyEvent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  734

             21.6.18      PollShiftStateEvent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  735

             21.6.19      PutKeyEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  736

             21.6.20      RawReadKey           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  737

             21.6.21      RawReadString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  737

             21.6.22      RestoreStartMode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  737

             21.6.23      SetKeyboardDriver           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  737

             21.6.24      ShiftStateToString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  738

             21.6.25      TranslateKeyEvent           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  738

             21.6.26      TranslateKeyEventUniCode                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 738


22   Reference for unit 'lineinfo'                                                                                      739

    22.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  739

    22.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  739

             22.2.1       GetLineInfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  739


23   Reference for unit 'Linux'                                                                                         740

    23.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  740

    23.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  740

    23.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  740

             23.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  740

             23.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  751

    23.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  753

             23.4.1       capget     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  753

             23.4.2       capset     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  753

             23.4.3       epoll_create      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  754

             23.4.4       epoll_ctl     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  754

             23.4.5       epoll_wait      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  755

             23.4.6       fdatasync     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  755

             23.4.7       futex    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  755



                                                                 41

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             23.4.8       futex_op      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  756

             23.4.9       sched_yield     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  756

             23.4.10      sync_file_range      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  756

             23.4.11      Sysinfo    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  757


24   Reference for unit 'lnfodwrf '                                                                                     759

    24.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  759

    24.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  759

             24.2.1       GetLineInfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  759


25   Reference for unit 'math'                                                                                          760

    25.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  760

    25.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  760

    25.3     Geometrical functions          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  760

    25.4     Statistical functions        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  761

    25.5     Number converting            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  761

    25.6     Exponential and logarithmic functions                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 761

    25.7     Hyperbolic functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  762

    25.8     Trigoniometric functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  762

    25.9     Angle unit conversion          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  762

    25.10    Min/max determination             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  762

    25.11    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  763

             25.11.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  763

             25.11.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  764

    25.12    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  766

             25.12.1      arccos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  766

             25.12.2      arccosh    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  767

             25.12.3      arcosh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  767

             25.12.4      arcsin   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  768

             25.12.5      arcsinh    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  768

             25.12.6      arctan2    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  769

             25.12.7      arctanh    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  769

             25.12.8      arsinh   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  770

             25.12.9      artanh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  770

             25.12.10     ceil  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  771

             25.12.11     ClearExceptions        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  771

             25.12.12     CompareValue         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  771

             25.12.13     cosecant      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  772

             25.12.14     cosh  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  772

             25.12.15     cot   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  772

             25.12.16     cotan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  773



                                                                 42

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             25.12.17     csc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  773

             25.12.18     cycletorad      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  773

             25.12.19     degtograd       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  774

             25.12.20     degtorad      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  774

             25.12.21     DivMod        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  775

             25.12.22     EnsureRange       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  775

             25.12.23     floor    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  775

             25.12.24     Frexp    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  776

             25.12.25     GetExceptionMask            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  777

             25.12.26     GetPrecisionMode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  777

             25.12.27     GetRoundMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  777

             25.12.28     gradtodeg       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  777

             25.12.29     gradtorad       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  778

             25.12.30     hypot    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  778

             25.12.31     ifthen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  779

             25.12.32     InRange       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  779

             25.12.33     intpower      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  779

             25.12.34     IsInfinite    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  780

             25.12.35     IsNan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  780

             25.12.36     IsZero     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  780

             25.12.37     ldexp    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  781

             25.12.38     lnxp1    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  781

             25.12.39     log10    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  782

             25.12.40     log2  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  782

             25.12.41     logn  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  783

             25.12.42     Max      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  783

             25.12.43     MaxIntValue       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  784

             25.12.44     maxvalue      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  785

             25.12.45     mean     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  786

             25.12.46     meanandstddev          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  786

             25.12.47     Min   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  787

             25.12.48     MinIntValue       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  788

             25.12.49     minvalue      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  789

             25.12.50     momentskewkurtosis             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  789

             25.12.51     norm     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  790

             25.12.52     operator **(float, float):  float          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 791

             25.12.53     operator **(Int64, Int64):  Int64            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *791

             25.12.54     popnstddev        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  791

             25.12.55     popnvariance      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  792

             25.12.56     power    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  793



                                                                 43

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             25.12.57     radtocycle      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  793

             25.12.58     radtodeg      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  794

             25.12.59     radtograd       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  794

             25.12.60     randg    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  795

             25.12.61     RandomFrom           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  795

             25.12.62     RandomRange          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  796

             25.12.63     RoundTo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  796

             25.12.64     SameValue       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  796

             25.12.65     sec   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  797

             25.12.66     secant     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  797

             25.12.67     SetExceptionMask          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  797

             25.12.68     SetPrecisionMode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  797

             25.12.69     SetRoundMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  798

             25.12.70     Sign  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  798

             25.12.71     SimpleRoundTo          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  798

             25.12.72     sincos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  798

             25.12.73     sinh  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  799

             25.12.74     stddev     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  799

             25.12.75     sum   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  800

             25.12.76     sumInt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  801

             25.12.77     sumofsquares      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  801

             25.12.78     sumsandsquares         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  802

             25.12.79     tan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  803

             25.12.80     tanh     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  803

             25.12.81     totalvariance     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  804

             25.12.82     variance      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  804

    25.13    EInvalidArgument           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  805

             25.13.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  805


26   Reference for unit 'matrix'                                                                                        806

    26.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  806

    26.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  807

             26.2.1       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  807

    26.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  809

             26.3.1       operator *(Tmatrix2_double, Double):  Tmatrix2_double                           .  .  .  .  .  .  809

             26.3.2       operator *(Tmatrix2_double, Tmatrix2_double):  Tmatrix2_double                              .  809

             26.3.3       operator *(Tmatrix2_double, Tvector2_double):  Tvector2_double                           .  .  810

             26.3.4       operator *(Tmatrix2_extended, extended):  Tmatrix2_extended                            .  .  .  810

             26.3.5       operator *(Tmatrix2_extended, Tmatrix2_extended):  Tmatrix2_extended                                810

             26.3.6       operator *(Tmatrix2_extended, Tvector2_extended):  Tvector2_extended                              810



                                                                 44

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.3.7       operator *(Tmatrix2_single, single):  Tmatrix2_single                      .  .  .  .  .  .  .  .  811

             26.3.8       operator *(Tmatrix2_single, Tmatrix2_single):  Tmatrix2_single                         .  .  .  811

             26.3.9       operator *(Tmatrix2_single, Tvector2_single):  Tvector2_single                         .  .  .  811

             26.3.10      operator *(Tmatrix3_double, Double):  Tmatrix3_double                           .  .  .  .  .  .  811

             26.3.11      operator *(Tmatrix3_double, Tmatrix3_double):  Tmatrix3_double                              .  812

             26.3.12      operator *(Tmatrix3_double, Tvector3_double):  Tvector3_double                           .  .  812

             26.3.13      operator *(Tmatrix3_extended, extended):  Tmatrix3_extended                            .  .  .  812

             26.3.14      operator *(Tmatrix3_extended, Tmatrix3_extended):  Tmatrix3_extended                                813

             26.3.15      operator *(Tmatrix3_extended, Tvector3_extended):  Tvector3_extended                              813

             26.3.16      operator *(Tmatrix3_single, single):  Tmatrix3_single                      .  .  .  .  .  .  .  .  813

             26.3.17      operator *(Tmatrix3_single, Tmatrix3_single):  Tmatrix3_single                         .  .  .  813

             26.3.18      operator *(Tmatrix3_single, Tvector3_single):  Tvector3_single                         .  .  .  814

             26.3.19      operator *(Tmatrix4_double, Double):  Tmatrix4_double                           .  .  .  .  .  .  814

             26.3.20      operator *(Tmatrix4_double, Tmatrix4_double):  Tmatrix4_double                              .  814

             26.3.21      operator *(Tmatrix4_double, Tvector4_double):  Tvector4_double                           .  .  814

             26.3.22      operator *(Tmatrix4_extended, extended):  Tmatrix4_extended                            .  .  .  815

             26.3.23      operator *(Tmatrix4_extended, Tmatrix4_extended):  Tmatrix4_extended                                815

             26.3.24      operator *(Tmatrix4_extended, Tvector4_extended):  Tvector4_extended                              815

             26.3.25      operator *(Tmatrix4_single, single):  Tmatrix4_single                      .  .  .  .  .  .  .  .  816

             26.3.26      operator *(Tmatrix4_single, Tmatrix4_single):  Tmatrix4_single                         .  .  .  816

             26.3.27      operator *(Tmatrix4_single, Tvector4_single):  Tvector4_single                         .  .  .  816

             26.3.28      operator *(Tvector2_double, Double):  Tvector2_double                        .  .  .  .  .  .  .  816

             26.3.29      operator *(Tvector2_double, Tvector2_double):  Tvector2_double                           .  .  817

             26.3.30      operator *(Tvector2_extended, extended):  Tvector2_extended                            .  .  .  817

             26.3.31      operator *(Tvector2_extended, Tvector2_extended):  Tvector2_extended                             817

             26.3.32      operator *(Tvector2_single, single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  817

             26.3.33      operator *(Tvector2_single, Tvector2_single):  Tvector2_single                      .  .  .  .  818

             26.3.34      operator *(Tvector3_double, Double):  Tvector3_double                        .  .  .  .  .  .  .  818

             26.3.35      operator *(Tvector3_double, Tvector3_double):  Tvector3_double                           .  .  818

             26.3.36      operator *(Tvector3_extended, extended):  Tvector3_extended                            .  .  .  818

             26.3.37      operator *(Tvector3_extended, Tvector3_extended):  Tvector3_extended                             819

             26.3.38      operator *(Tvector3_single, single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  819

             26.3.39      operator *(Tvector3_single, Tvector3_single):  Tvector3_single                      .  .  .  .  819

             26.3.40      operator *(Tvector4_double, Double):  Tvector4_double                        .  .  .  .  .  .  .  819

             26.3.41      operator *(Tvector4_double, Tvector4_double):  Tvector4_double                           .  .  820

             26.3.42      operator *(Tvector4_extended, extended):  Tvector4_extended                            .  .  .  820

             26.3.43      operator *(Tvector4_extended, Tvector4_extended):  Tvector4_extended                             820

             26.3.44      operator *(Tvector4_single, single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  820

             26.3.45      operator *(Tvector4_single, Tvector4_single):  Tvector4_single                      .  .  .  .  821

             26.3.46      operator **(Tvector2_double, Tvector2_double):  Double                          .  .  .  .  .  .  821



                                                                 45

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.3.47      operator **(Tvector2_extended, Tvector2_extended):  extended                           .  .  .  821

             26.3.48      operator **(Tvector2_single, Tvector2_single):  single                     .  .  .  .  .  .  .  .  821

             26.3.49      operator **(Tvector3_double, Tvector3_double):  Double                          .  .  .  .  .  .  822

             26.3.50      operator **(Tvector3_extended, Tvector3_extended):  extended                           .  .  .  822

             26.3.51      operator **(Tvector3_single, Tvector3_single):  single                     .  .  .  .  .  .  .  .  822

             26.3.52      operator **(Tvector4_double, Tvector4_double):  Double                          .  .  .  .  .  .  822

             26.3.53      operator **(Tvector4_extended, Tvector4_extended):  extended                           .  .  .  823

             26.3.54      operator **(Tvector4_single, Tvector4_single):  single                     .  .  .  .  .  .  .  .  823

             26.3.55      operator +(Tmatrix2_double, Double):  Tmatrix2_double                           .  .  .  .  .  .  823

             26.3.56      operator +(Tmatrix2_double, Tmatrix2_double):  Tmatrix2_double                              .  823

             26.3.57      operator +(Tmatrix2_extended, extended):  Tmatrix2_extended                              .  .  824

             26.3.58      operator +(Tmatrix2_extended, Tmatrix2_extended):  Tmatrix2_extended                                824

             26.3.59      operator +(Tmatrix2_single, single):  Tmatrix2_single                      .  .  .  .  .  .  .  .  824

             26.3.60      operator +(Tmatrix2_single, Tmatrix2_single):  Tmatrix2_single                           .  .  824

             26.3.61      operator +(Tmatrix3_double, Double):  Tmatrix3_double                           .  .  .  .  .  .  825

             26.3.62      operator +(Tmatrix3_double, Tmatrix3_double):  Tmatrix3_double                              .  825

             26.3.63      operator +(Tmatrix3_extended, extended):  Tmatrix3_extended                              .  .  825

             26.3.64      operator +(Tmatrix3_extended, Tmatrix3_extended):  Tmatrix3_extended                                825

             26.3.65      operator +(Tmatrix3_single, single):  Tmatrix3_single                      .  .  .  .  .  .  .  .  826

             26.3.66      operator +(Tmatrix3_single, Tmatrix3_single):  Tmatrix3_single                           .  .  826

             26.3.67      operator +(Tmatrix4_double, Double):  Tmatrix4_double                           .  .  .  .  .  .  826

             26.3.68      operator +(Tmatrix4_double, Tmatrix4_double):  Tmatrix4_double                              .  826

             26.3.69      operator +(Tmatrix4_extended, extended):  Tmatrix4_extended                              .  .  827

             26.3.70      operator +(Tmatrix4_extended, Tmatrix4_extended):  Tmatrix4_extended                                827

             26.3.71      operator +(Tmatrix4_single, single):  Tmatrix4_single                      .  .  .  .  .  .  .  .  827

             26.3.72      operator +(Tmatrix4_single, Tmatrix4_single):  Tmatrix4_single                           .  .  827

             26.3.73      operator +(Tvector2_double, Double):  Tvector2_double                        .  .  .  .  .  .  .  828

             26.3.74      operator +(Tvector2_double, Tvector2_double):  Tvector2_double                           .  .  828

             26.3.75      operator +(Tvector2_extended, extended):  Tvector2_extended                            .  .  .  828

             26.3.76      operator +(Tvector2_extended, Tvector2_extended):  Tvector2_extended                              828

             26.3.77      operator +(Tvector2_single, single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  829

             26.3.78      operator +(Tvector2_single, Tvector2_single):  Tvector2_single                         .  .  .  829

             26.3.79      operator +(Tvector3_double, Double):  Tvector3_double                        .  .  .  .  .  .  .  829

             26.3.80      operator +(Tvector3_double, Tvector3_double):  Tvector3_double                           .  .  829

             26.3.81      operator +(Tvector3_extended, extended):  Tvector3_extended                            .  .  .  830

             26.3.82      operator +(Tvector3_extended, Tvector3_extended):  Tvector3_extended                              830

             26.3.83      operator +(Tvector3_single, single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  830

             26.3.84      operator +(Tvector3_single, Tvector3_single):  Tvector3_single                         .  .  .  830

             26.3.85      operator +(Tvector4_double, Double):  Tvector4_double                        .  .  .  .  .  .  .  831

             26.3.86      operator +(Tvector4_double, Tvector4_double):  Tvector4_double                           .  .  831



                                                                 46

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.3.87      operator +(Tvector4_extended, extended):  Tvector4_extended                            .  .  .  831

             26.3.88      operator +(Tvector4_extended, Tvector4_extended):  Tvector4_extended                              831

             26.3.89      operator +(Tvector4_single, single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  832

             26.3.90      operator +(Tvector4_single, Tvector4_single):  Tvector4_single                         .  .  .  832

             26.3.91      operator -(Tmatrix2_double):  Tmatrix2_double                      .  .  .  .  .  .  .  .  .  .  .  832

             26.3.92      operator -(Tmatrix2_double, Double):  Tmatrix2_double                        .  .  .  .  .  .  .  832

             26.3.93      operator -(Tmatrix2_double, Tmatrix2_double):  Tmatrix2_double                              .  833

             26.3.94      operator -(Tmatrix2_extended):  Tmatrix2_extended                       .  .  .  .  .  .  .  .  .  833

             26.3.95      operator -(Tmatrix2_extended, extended):  Tmatrix2_extended                            .  .  .  833

             26.3.96      operator -(Tmatrix2_extended, Tmatrix2_extended):  Tmatrix2_extended                               833

             26.3.97      operator -(Tmatrix2_single):  Tmatrix2_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  834

             26.3.98      operator -(Tmatrix2_single, single):  Tmatrix2_single                   .  .  .  .  .  .  .  .  .  834

             26.3.99      operator -(Tmatrix2_single, Tmatrix2_single):  Tmatrix2_single                         .  .  .  834

             26.3.100     operator -(Tmatrix3_double):  Tmatrix3_double                      .  .  .  .  .  .  .  .  .  .  .  834

             26.3.101     operator -(Tmatrix3_double, Double):  Tmatrix3_double                        .  .  .  .  .  .  .  835

             26.3.102     operator -(Tmatrix3_double, Tmatrix3_double):  Tmatrix3_double                              .  835

             26.3.103     operator -(Tmatrix3_extended):  Tmatrix3_extended                       .  .  .  .  .  .  .  .  .  835

             26.3.104     operator -(Tmatrix3_extended, extended):  Tmatrix3_extended                            .  .  .  835

             26.3.105     operator -(Tmatrix3_extended, Tmatrix3_extended):  Tmatrix3_extended                               836

             26.3.106     operator -(Tmatrix3_single):  Tmatrix3_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  836

             26.3.107     operator -(Tmatrix3_single, single):  Tmatrix3_single                   .  .  .  .  .  .  .  .  .  836

             26.3.108     operator -(Tmatrix3_single, Tmatrix3_single):  Tmatrix3_single                         .  .  .  836

             26.3.109     operator -(Tmatrix4_double):  Tmatrix4_double                      .  .  .  .  .  .  .  .  .  .  .  837

             26.3.110     operator -(Tmatrix4_double, Double):  Tmatrix4_double                        .  .  .  .  .  .  .  837

             26.3.111     operator -(Tmatrix4_double, Tmatrix4_double):  Tmatrix4_double                              .  837

             26.3.112     operator -(Tmatrix4_extended):  Tmatrix4_extended                       .  .  .  .  .  .  .  .  .  837

             26.3.113     operator -(Tmatrix4_extended, extended):  Tmatrix4_extended                            .  .  .  838

             26.3.114     operator -(Tmatrix4_extended, Tmatrix4_extended):  Tmatrix4_extended                               838

             26.3.115     operator -(Tmatrix4_single):  Tmatrix4_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  838

             26.3.116     operator -(Tmatrix4_single, single):  Tmatrix4_single                   .  .  .  .  .  .  .  .  .  838

             26.3.117     operator -(Tmatrix4_single, Tmatrix4_single):  Tmatrix4_single                         .  .  .  839

             26.3.118     operator -(Tvector2_double):  Tvector2_double                    .  .  .  .  .  .  .  .  .  .  .  .  839

             26.3.119     operator -(Tvector2_double, Double):  Tvector2_double                        .  .  .  .  .  .  .  839

             26.3.120     operator -(Tvector2_double, Tvector2_double):  Tvector2_double                           .  .  839

             26.3.121     operator -(Tvector2_extended):  Tvector2_extended                       .  .  .  .  .  .  .  .  .  840

             26.3.122     operator -(Tvector2_extended, extended):  Tvector2_extended                         .  .  .  .  840

             26.3.123     operator -(Tvector2_extended, Tvector2_extended):  Tvector2_extended                             840

             26.3.124     operator -(Tvector2_single):  Tvector2_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  840

             26.3.125     operator -(Tvector2_single, single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  841

             26.3.126     operator -(Tvector2_single, Tvector2_single):  Tvector2_single                      .  .  .  .  841



                                                                 47

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.3.127     operator -(Tvector3_double):  Tvector3_double                    .  .  .  .  .  .  .  .  .  .  .  .  841

             26.3.128     operator -(Tvector3_double, Double):  Tvector3_double                        .  .  .  .  .  .  .  841

             26.3.129     operator -(Tvector3_double, Tvector3_double):  Tvector3_double                           .  .  842

             26.3.130     operator -(Tvector3_extended):  Tvector3_extended                       .  .  .  .  .  .  .  .  .  842

             26.3.131     operator -(Tvector3_extended, extended):  Tvector3_extended                         .  .  .  .  842

             26.3.132     operator -(Tvector3_extended, Tvector3_extended):  Tvector3_extended                             842

             26.3.133     operator -(Tvector3_single):  Tvector3_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  843

             26.3.134     operator -(Tvector3_single, single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  843

             26.3.135     operator -(Tvector3_single, Tvector3_single):  Tvector3_single                      .  .  .  .  843

             26.3.136     operator -(Tvector4_double):  Tvector4_double                    .  .  .  .  .  .  .  .  .  .  .  .  843

             26.3.137     operator -(Tvector4_double, Double):  Tvector4_double                        .  .  .  .  .  .  .  844

             26.3.138     operator -(Tvector4_double, Tvector4_double):  Tvector4_double                           .  .  844

             26.3.139     operator -(Tvector4_extended):  Tvector4_extended                       .  .  .  .  .  .  .  .  .  844

             26.3.140     operator -(Tvector4_extended, extended):  Tvector4_extended                         .  .  .  .  844

             26.3.141     operator -(Tvector4_extended, Tvector4_extended):  Tvector4_extended                             845

             26.3.142     operator -(Tvector4_single):  Tvector4_single                 .  .  .  .  .  .  .  .  .  .  .  .  .  845

             26.3.143     operator -(Tvector4_single, single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  845

             26.3.144     operator -(Tvector4_single, Tvector4_single):  Tvector4_single                      .  .  .  .  845

             26.3.145     operator /(Tmatrix2_double, Double):  Tmatrix2_double                           .  .  .  .  .  .  846

             26.3.146     operator /(Tmatrix2_extended, extended):  Tmatrix2_extended                            .  .  .  846

             26.3.147     operator /(Tmatrix2_single, single):  Tmatrix2_single                      .  .  .  .  .  .  .  .  846

             26.3.148     operator /(Tmatrix3_double, Double):  Tmatrix3_double                           .  .  .  .  .  .  846

             26.3.149     operator /(Tmatrix3_extended, extended):  Tmatrix3_extended                            .  .  .  847

             26.3.150     operator /(Tmatrix3_single, single):  Tmatrix3_single                      .  .  .  .  .  .  .  .  847

             26.3.151     operator /(Tmatrix4_double, Double):  Tmatrix4_double                           .  .  .  .  .  .  847

             26.3.152     operator /(Tmatrix4_extended, extended):  Tmatrix4_extended                            .  .  .  847

             26.3.153     operator /(Tmatrix4_single, single):  Tmatrix4_single                      .  .  .  .  .  .  .  .  848

             26.3.154     operator /(Tvector2_double, Double):  Tvector2_double                        .  .  .  .  .  .  .  848

             26.3.155     operator /(Tvector2_extended, extended):  Tvector2_extended                            .  .  .  848

             26.3.156     operator /(Tvector2_single, single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  848

             26.3.157     operator /(Tvector3_double, Double):  Tvector3_double                        .  .  .  .  .  .  .  849

             26.3.158     operator /(Tvector3_extended, extended):  Tvector3_extended                            .  .  .  849

             26.3.159     operator /(Tvector3_single, single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  849

             26.3.160     operator /(Tvector4_double, Double):  Tvector4_double                        .  .  .  .  .  .  .  849

             26.3.161     operator /(Tvector4_extended, extended):  Tvector4_extended                            .  .  .  850

             26.3.162     operator /(Tvector4_single, single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  850

             26.3.163     operator :=(Tmatrix2_double):  Tmatrix2_extended                        .  .  .  .  .  .  .  .  .  850

             26.3.164     operator :=(Tmatrix2_double):  Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  850

             26.3.165     operator :=(Tmatrix2_double):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  .  851

             26.3.166     operator :=(Tmatrix2_double):  Tmatrix3_extended                        .  .  .  .  .  .  .  .  .  851



                                                                 48

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.3.167     operator :=(Tmatrix2_double):  Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  851

             26.3.168     operator :=(Tmatrix2_double):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  .  851

             26.3.169     operator :=(Tmatrix2_double):  Tmatrix4_extended                        .  .  .  .  .  .  .  .  .  852

             26.3.170     operator :=(Tmatrix2_double):  Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  852

             26.3.171     operator :=(Tmatrix2_extended):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  852

             26.3.172     operator :=(Tmatrix2_extended):  Tmatrix2_single                      .  .  .  .  .  .  .  .  .  .  852

             26.3.173     operator :=(Tmatrix2_extended):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  853

             26.3.174     operator :=(Tmatrix2_extended):  Tmatrix3_extended                         .  .  .  .  .  .  .  .  853

             26.3.175     operator :=(Tmatrix2_extended):  Tmatrix3_single                      .  .  .  .  .  .  .  .  .  .  853

             26.3.176     operator :=(Tmatrix2_extended):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  853

             26.3.177     operator :=(Tmatrix2_extended):  Tmatrix4_extended                         .  .  .  .  .  .  .  .  854

             26.3.178     operator :=(Tmatrix2_extended):  Tmatrix4_single                      .  .  .  .  .  .  .  .  .  .  854

             26.3.179     operator :=(Tmatrix2_single):  Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  854

             26.3.180     operator :=(Tmatrix2_single):  Tmatrix2_extended                      .  .  .  .  .  .  .  .  .  .  854

             26.3.181     operator :=(Tmatrix2_single):  Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  855

             26.3.182     operator :=(Tmatrix2_single):  Tmatrix3_extended                      .  .  .  .  .  .  .  .  .  .  855

             26.3.183     operator :=(Tmatrix2_single):  Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  855

             26.3.184     operator :=(Tmatrix2_single):  Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  855

             26.3.185     operator :=(Tmatrix2_single):  Tmatrix4_extended                      .  .  .  .  .  .  .  .  .  .  856

             26.3.186     operator :=(Tmatrix2_single):  Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  856

             26.3.187     operator :=(Tmatrix3_double):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  .  856

             26.3.188     operator :=(Tmatrix3_double):  Tmatrix2_extended                        .  .  .  .  .  .  .  .  .  856

             26.3.189     operator :=(Tmatrix3_double):  Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  857

             26.3.190     operator :=(Tmatrix3_double):  Tmatrix3_extended                        .  .  .  .  .  .  .  .  .  857

             26.3.191     operator :=(Tmatrix3_double):  Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  857

             26.3.192     operator :=(Tmatrix3_double):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  .  857

             26.3.193     operator :=(Tmatrix3_double):  Tmatrix4_extended                        .  .  .  .  .  .  .  .  .  858

             26.3.194     operator :=(Tmatrix3_double):  Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  858

             26.3.195     operator :=(Tmatrix3_extended):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  858

             26.3.196     operator :=(Tmatrix3_extended):  Tmatrix2_extended                         .  .  .  .  .  .  .  .  858

             26.3.197     operator :=(Tmatrix3_extended):  Tmatrix2_single                      .  .  .  .  .  .  .  .  .  .  859

             26.3.198     operator :=(Tmatrix3_extended):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  859

             26.3.199     operator :=(Tmatrix3_extended):  Tmatrix3_single                      .  .  .  .  .  .  .  .  .  .  859

             26.3.200     operator :=(Tmatrix3_extended):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  859

             26.3.201     operator :=(Tmatrix3_extended):  Tmatrix4_extended                         .  .  .  .  .  .  .  .  860

             26.3.202     operator :=(Tmatrix3_extended):  Tmatrix4_single                      .  .  .  .  .  .  .  .  .  .  860

             26.3.203     operator :=(Tmatrix3_single):  Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  860

             26.3.204     operator :=(Tmatrix3_single):  Tmatrix2_extended                      .  .  .  .  .  .  .  .  .  .  860

             26.3.205     operator :=(Tmatrix3_single):  Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  861

             26.3.206     operator :=(Tmatrix3_single):  Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  861



                                                                 49

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.3.207     operator :=(Tmatrix3_single):  Tmatrix3_extended                      .  .  .  .  .  .  .  .  .  .  861

             26.3.208     operator :=(Tmatrix3_single):  Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  861

             26.3.209     operator :=(Tmatrix3_single):  Tmatrix4_extended                      .  .  .  .  .  .  .  .  .  .  862

             26.3.210     operator :=(Tmatrix3_single):  Tmatrix4_single                   .  .  .  .  .  .  .  .  .  .  .  .  862

             26.3.211     operator :=(Tmatrix4_double):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  .  862

             26.3.212     operator :=(Tmatrix4_double):  Tmatrix2_extended                        .  .  .  .  .  .  .  .  .  862

             26.3.213     operator :=(Tmatrix4_double):  Tmatrix2_single                     .  .  .  .  .  .  .  .  .  .  .  863

             26.3.214     operator :=(Tmatrix4_double):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  .  863

             26.3.215     operator :=(Tmatrix4_double):  Tmatrix3_extended                        .  .  .  .  .  .  .  .  .  863

             26.3.216     operator :=(Tmatrix4_double):  Tmatrix3_single                     .  .  .  .  .  .  .  .  .  .  .  863

             26.3.217     operator :=(Tmatrix4_double):  Tmatrix4_extended                        .  .  .  .  .  .  .  .  .  864

             26.3.218     operator :=(Tmatrix4_double):  Tmatrix4_single                     .  .  .  .  .  .  .  .  .  .  .  864

             26.3.219     operator :=(Tmatrix4_extended):  Tmatrix2_double                        .  .  .  .  .  .  .  .  .  864

             26.3.220     operator :=(Tmatrix4_extended):  Tmatrix2_extended                         .  .  .  .  .  .  .  .  864

             26.3.221     operator :=(Tmatrix4_extended):  Tmatrix2_single                      .  .  .  .  .  .  .  .  .  .  865

             26.3.222     operator :=(Tmatrix4_extended):  Tmatrix3_double                        .  .  .  .  .  .  .  .  .  865

             26.3.223     operator :=(Tmatrix4_extended):  Tmatrix3_extended                         .  .  .  .  .  .  .  .  865

             26.3.224     operator :=(Tmatrix4_extended):  Tmatrix3_single                      .  .  .  .  .  .  .  .  .  .  865

             26.3.225     operator :=(Tmatrix4_extended):  Tmatrix4_double                        .  .  .  .  .  .  .  .  .  866

             26.3.226     operator :=(Tmatrix4_extended):  Tmatrix4_single                      .  .  .  .  .  .  .  .  .  .  866

             26.3.227     operator :=(Tmatrix4_single):  Tmatrix2_double                     .  .  .  .  .  .  .  .  .  .  .  866

             26.3.228     operator :=(Tmatrix4_single):  Tmatrix2_extended                      .  .  .  .  .  .  .  .  .  .  866

             26.3.229     operator :=(Tmatrix4_single):  Tmatrix2_single                   .  .  .  .  .  .  .  .  .  .  .  .  867

             26.3.230     operator :=(Tmatrix4_single):  Tmatrix3_double                     .  .  .  .  .  .  .  .  .  .  .  867

             26.3.231     operator :=(Tmatrix4_single):  Tmatrix3_extended                      .  .  .  .  .  .  .  .  .  .  867

             26.3.232     operator :=(Tmatrix4_single):  Tmatrix3_single                   .  .  .  .  .  .  .  .  .  .  .  .  867

             26.3.233     operator :=(Tmatrix4_single):  Tmatrix4_double                     .  .  .  .  .  .  .  .  .  .  .  868

             26.3.234     operator :=(Tmatrix4_single):  Tmatrix4_extended                      .  .  .  .  .  .  .  .  .  .  868

             26.3.235     operator :=(Tvector2_double):  Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  868

             26.3.236     operator :=(Tvector2_double):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  868

             26.3.237     operator :=(Tvector2_double):  Tvector3_double                     .  .  .  .  .  .  .  .  .  .  .  869

             26.3.238     operator :=(Tvector2_double):  Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  869

             26.3.239     operator :=(Tvector2_double):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  869

             26.3.240     operator :=(Tvector2_double):  Tvector4_double                     .  .  .  .  .  .  .  .  .  .  .  869

             26.3.241     operator :=(Tvector2_double):  Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  870

             26.3.242     operator :=(Tvector2_double):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  870

             26.3.243     operator :=(Tvector2_extended):  Tvector2_double                      .  .  .  .  .  .  .  .  .  .  870

             26.3.244     operator :=(Tvector2_extended):  Tvector2_single                      .  .  .  .  .  .  .  .  .  .  870

             26.3.245     operator :=(Tvector2_extended):  Tvector3_double                      .  .  .  .  .  .  .  .  .  .  871

             26.3.246     operator :=(Tvector2_extended):  Tvector3_extended                         .  .  .  .  .  .  .  .  871



                                                                 50

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.3.247     operator :=(Tvector2_extended):  Tvector3_single                      .  .  .  .  .  .  .  .  .  .  871

             26.3.248     operator :=(Tvector2_extended):  Tvector4_double                      .  .  .  .  .  .  .  .  .  .  871

             26.3.249     operator :=(Tvector2_extended):  Tvector4_extended                         .  .  .  .  .  .  .  .  872

             26.3.250     operator :=(Tvector2_extended):  Tvector4_single                      .  .  .  .  .  .  .  .  .  .  872

             26.3.251     operator :=(Tvector2_single):  Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  872

             26.3.252     operator :=(Tvector2_single):  Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  872

             26.3.253     operator :=(Tvector2_single):  Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  873

             26.3.254     operator :=(Tvector2_single):  Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  873

             26.3.255     operator :=(Tvector2_single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  873

             26.3.256     operator :=(Tvector2_single):  Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  873

             26.3.257     operator :=(Tvector2_single):  Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  874

             26.3.258     operator :=(Tvector2_single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  874

             26.3.259     operator :=(Tvector3_double):  Tvector2_double                     .  .  .  .  .  .  .  .  .  .  .  874

             26.3.260     operator :=(Tvector3_double):  Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  874

             26.3.261     operator :=(Tvector3_double):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  875

             26.3.262     operator :=(Tvector3_double):  Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  875

             26.3.263     operator :=(Tvector3_double):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  875

             26.3.264     operator :=(Tvector3_double):  Tvector4_double                     .  .  .  .  .  .  .  .  .  .  .  875

             26.3.265     operator :=(Tvector3_double):  Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  876

             26.3.266     operator :=(Tvector3_double):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  876

             26.3.267     operator :=(Tvector3_extended):  Tvector2_double                      .  .  .  .  .  .  .  .  .  .  876

             26.3.268     operator :=(Tvector3_extended):  Tvector2_extended                         .  .  .  .  .  .  .  .  876

             26.3.269     operator :=(Tvector3_extended):  Tvector2_single                      .  .  .  .  .  .  .  .  .  .  877

             26.3.270     operator :=(Tvector3_extended):  Tvector3_double                      .  .  .  .  .  .  .  .  .  .  877

             26.3.271     operator :=(Tvector3_extended):  Tvector3_single                      .  .  .  .  .  .  .  .  .  .  877

             26.3.272     operator :=(Tvector3_extended):  Tvector4_double                      .  .  .  .  .  .  .  .  .  .  877

             26.3.273     operator :=(Tvector3_extended):  Tvector4_extended                         .  .  .  .  .  .  .  .  878

             26.3.274     operator :=(Tvector3_extended):  Tvector4_single                      .  .  .  .  .  .  .  .  .  .  878

             26.3.275     operator :=(Tvector3_single):  Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  878

             26.3.276     operator :=(Tvector3_single):  Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  878

             26.3.277     operator :=(Tvector3_single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  879

             26.3.278     operator :=(Tvector3_single):  Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  879

             26.3.279     operator :=(Tvector3_single):  Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  879

             26.3.280     operator :=(Tvector3_single):  Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  879

             26.3.281     operator :=(Tvector3_single):  Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  880

             26.3.282     operator :=(Tvector3_single):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  880

             26.3.283     operator :=(Tvector4_double):  Tvector2_double                     .  .  .  .  .  .  .  .  .  .  .  880

             26.3.284     operator :=(Tvector4_double):  Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  880

             26.3.285     operator :=(Tvector4_double):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  881

             26.3.286     operator :=(Tvector4_double):  Tvector3_double                     .  .  .  .  .  .  .  .  .  .  .  881



                                                                 51

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.3.287     operator :=(Tvector4_double):  Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  881

             26.3.288     operator :=(Tvector4_double):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  881

             26.3.289     operator :=(Tvector4_double):  Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  882

             26.3.290     operator :=(Tvector4_double):  Tvector4_single                   .  .  .  .  .  .  .  .  .  .  .  .  882

             26.3.291     operator :=(Tvector4_extended):  Tvector2_double                      .  .  .  .  .  .  .  .  .  .  882

             26.3.292     operator :=(Tvector4_extended):  Tvector2_extended                         .  .  .  .  .  .  .  .  882

             26.3.293     operator :=(Tvector4_extended):  Tvector2_single                      .  .  .  .  .  .  .  .  .  .  883

             26.3.294     operator :=(Tvector4_extended):  Tvector3_double                      .  .  .  .  .  .  .  .  .  .  883

             26.3.295     operator :=(Tvector4_extended):  Tvector3_extended                         .  .  .  .  .  .  .  .  883

             26.3.296     operator :=(Tvector4_extended):  Tvector3_single                      .  .  .  .  .  .  .  .  .  .  883

             26.3.297     operator :=(Tvector4_extended):  Tvector4_double                      .  .  .  .  .  .  .  .  .  .  884

             26.3.298     operator :=(Tvector4_extended):  Tvector4_single                      .  .  .  .  .  .  .  .  .  .  884

             26.3.299     operator :=(Tvector4_single):  Tvector2_double                   .  .  .  .  .  .  .  .  .  .  .  .  884

             26.3.300     operator :=(Tvector4_single):  Tvector2_extended                      .  .  .  .  .  .  .  .  .  .  884

             26.3.301     operator :=(Tvector4_single):  Tvector2_single                   .  .  .  .  .  .  .  .  .  .  .  .  885

             26.3.302     operator :=(Tvector4_single):  Tvector3_double                   .  .  .  .  .  .  .  .  .  .  .  .  885

             26.3.303     operator :=(Tvector4_single):  Tvector3_extended                      .  .  .  .  .  .  .  .  .  .  885

             26.3.304     operator :=(Tvector4_single):  Tvector3_single                   .  .  .  .  .  .  .  .  .  .  .  .  885

             26.3.305     operator :=(Tvector4_single):  Tvector4_double                   .  .  .  .  .  .  .  .  .  .  .  .  886

             26.3.306     operator :=(Tvector4_single):  Tvector4_extended                      .  .  .  .  .  .  .  .  .  .  886

             26.3.307     operator ><(Tvector3_double, Tvector3_double):  Tvector3_double                          .  .  886

             26.3.308     operator ><(Tvector3_extended, Tvector3_extended):  Tvector3_extended                             886

             26.3.309     operator ><(Tvector3_single, Tvector3_single):  Tvector3_single                        .  .  .  887

    26.4     Tmatrix2_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  887

             26.4.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  887

             26.4.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  887

             26.4.3       Tmatrix2_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  887

             26.4.4       Tmatrix2_double.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 888

             26.4.5       Tmatrix2_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  888

             26.4.6       Tmatrix2_double.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 888

             26.4.7       Tmatrix2_double.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  888

             26.4.8       Tmatrix2_double.set_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 888

             26.4.9       Tmatrix2_double.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  888

             26.4.10      Tmatrix2_double.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 889

             26.4.11      Tmatrix2_double.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  889

             26.4.12      Tmatrix2_double.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  889

    26.5     Tmatrix2_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  889

             26.5.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  889

             26.5.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  889

             26.5.3       Tmatrix2_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 890



                                                                 52

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.5.4       Tmatrix2_extended.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *890

             26.5.5       Tmatrix2_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  890

             26.5.6       Tmatrix2_extended.get_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 890

             26.5.7       Tmatrix2_extended.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  890

             26.5.8       Tmatrix2_extended.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 890

             26.5.9       Tmatrix2_extended.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  891

             26.5.10      Tmatrix2_extended.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *891

             26.5.11      Tmatrix2_extended.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  891

             26.5.12      Tmatrix2_extended.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 891

    26.6     Tmatrix2_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  891

             26.6.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  891

             26.6.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  892

             26.6.3       Tmatrix2_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  892

             26.6.4       Tmatrix2_single.init_identity           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 892

             26.6.5       Tmatrix2_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  892

             26.6.6       Tmatrix2_single.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 892

             26.6.7       Tmatrix2_single.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  893

             26.6.8       Tmatrix2_single.set_column            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  893

             26.6.9       Tmatrix2_single.set_row          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  893

             26.6.10      Tmatrix2_single.determinant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 893

             26.6.11      Tmatrix2_single.inverse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  893

             26.6.12      Tmatrix2_single.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  893

    26.7     Tmatrix3_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  894

             26.7.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  894

             26.7.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  894

             26.7.3       Tmatrix3_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  894

             26.7.4       Tmatrix3_double.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 894

             26.7.5       Tmatrix3_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  894

             26.7.6       Tmatrix3_double.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 895

             26.7.7       Tmatrix3_double.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  895

             26.7.8       Tmatrix3_double.set_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 895

             26.7.9       Tmatrix3_double.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  895

             26.7.10      Tmatrix3_double.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 895

             26.7.11      Tmatrix3_double.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  895

             26.7.12      Tmatrix3_double.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  896

    26.8     Tmatrix3_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  896

             26.8.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  896

             26.8.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  896

             26.8.3       Tmatrix3_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 896

             26.8.4       Tmatrix3_extended.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *896



                                                                 53

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.8.5       Tmatrix3_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  897

             26.8.6       Tmatrix3_extended.get_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 897

             26.8.7       Tmatrix3_extended.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  897

             26.8.8       Tmatrix3_extended.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 897

             26.8.9       Tmatrix3_extended.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  897

             26.8.10      Tmatrix3_extended.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *898

             26.8.11      Tmatrix3_extended.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  898

             26.8.12      Tmatrix3_extended.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 898

    26.9     Tmatrix3_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  898

             26.9.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  898

             26.9.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  898

             26.9.3       Tmatrix3_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  899

             26.9.4       Tmatrix3_single.init_identity           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 899

             26.9.5       Tmatrix3_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  899

             26.9.6       Tmatrix3_single.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 899

             26.9.7       Tmatrix3_single.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  899

             26.9.8       Tmatrix3_single.set_column            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  899

             26.9.9       Tmatrix3_single.set_row          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  900

             26.9.10      Tmatrix3_single.determinant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 900

             26.9.11      Tmatrix3_single.inverse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  900

             26.9.12      Tmatrix3_single.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  900

    26.10    Tmatrix4_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  900

             26.10.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  900

             26.10.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  901

             26.10.3      Tmatrix4_double.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  901

             26.10.4      Tmatrix4_double.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 901

             26.10.5      Tmatrix4_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  901

             26.10.6      Tmatrix4_double.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 901

             26.10.7      Tmatrix4_double.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  902

             26.10.8      Tmatrix4_double.set_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 902

             26.10.9      Tmatrix4_double.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  902

             26.10.10     Tmatrix4_double.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 902

             26.10.11     Tmatrix4_double.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  902

             26.10.12     Tmatrix4_double.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  903

    26.11    Tmatrix4_extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  903

             26.11.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  903

             26.11.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  903

             26.11.3      Tmatrix4_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 903

             26.11.4      Tmatrix4_extended.init_identity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *903

             26.11.5      Tmatrix4_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  904



                                                                 54

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.11.6      Tmatrix4_extended.get_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 904

             26.11.7      Tmatrix4_extended.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  904

             26.11.8      Tmatrix4_extended.set_column               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 904

             26.11.9      Tmatrix4_extended.set_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  904

             26.11.10     Tmatrix4_extended.determinant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *905

             26.11.11     Tmatrix4_extended.inverse             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  905

             26.11.12     Tmatrix4_extended.transpose                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 905

    26.12    Tmatrix4_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  905

             26.12.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  905

             26.12.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  905

             26.12.3      Tmatrix4_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  906

             26.12.4      Tmatrix4_single.init_identity           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 906

             26.12.5      Tmatrix4_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  906

             26.12.6      Tmatrix4_single.get_column              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 906

             26.12.7      Tmatrix4_single.get_row             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  906

             26.12.8      Tmatrix4_single.set_column            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  907

             26.12.9      Tmatrix4_single.set_row          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  907

             26.12.10     Tmatrix4_single.determinant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 907

             26.12.11     Tmatrix4_single.inverse          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  907

             26.12.12     Tmatrix4_single.transpose             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  907

    26.13    Tvector2_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  908

             26.13.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  908

             26.13.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  908

             26.13.3      Tvector2_double.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  908

             26.13.4      Tvector2_double.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  908

             26.13.5      Tvector2_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  908

             26.13.6      Tvector2_double.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  908

             26.13.7      Tvector2_double.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *909

    26.14    Tvector2_extended          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  909

             26.14.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  909

             26.14.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  909

             26.14.3      Tvector2_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 909

             26.14.4      Tvector2_extended.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  909

             26.14.5      Tvector2_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  909

             26.14.6      Tvector2_extended.length            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  910

             26.14.7      Tvector2_extended.squared_length                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *910

    26.15    Tvector2_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  910

             26.15.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  910

             26.15.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  910

             26.15.3      Tvector2_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  910



                                                                 55

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.15.4      Tvector2_single.init_one         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  910

             26.15.5      Tvector2_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  911

             26.15.6      Tvector2_single.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  911

             26.15.7      Tvector2_single.squared_length             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 911

    26.16    Tvector3_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  911

             26.16.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  911

             26.16.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  911

             26.16.3      Tvector3_double.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  911

             26.16.4      Tvector3_double.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  912

             26.16.5      Tvector3_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  912

             26.16.6      Tvector3_double.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  912

             26.16.7      Tvector3_double.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *912

    26.17    Tvector3_extended          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  912

             26.17.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  912

             26.17.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  912

             26.17.3      Tvector3_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 913

             26.17.4      Tvector3_extended.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  913

             26.17.5      Tvector3_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  913

             26.17.6      Tvector3_extended.length            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  913

             26.17.7      Tvector3_extended.squared_length                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *913

    26.18    Tvector3_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  913

             26.18.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  913

             26.18.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  914

             26.18.3      Tvector3_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  914

             26.18.4      Tvector3_single.init_one         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  914

             26.18.5      Tvector3_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  914

             26.18.6      Tvector3_single.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  914

             26.18.7      Tvector3_single.squared_length             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 914

    26.19    Tvector4_double         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  915

             26.19.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  915

             26.19.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  915

             26.19.3      Tvector4_double.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  915

             26.19.4      Tvector4_double.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  915

             26.19.5      Tvector4_double.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  915

             26.19.6      Tvector4_double.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  915

             26.19.7      Tvector4_double.squared_length               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *916

    26.20    Tvector4_extended          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  916

             26.20.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  916

             26.20.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  916

             26.20.3      Tvector4_extended.init_zero             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 916



                                                                 56

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             26.20.4      Tvector4_extended.init_one            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  916

             26.20.5      Tvector4_extended.init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  916

             26.20.6      Tvector4_extended.length            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  917

             26.20.7      Tvector4_extended.squared_length                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *917

    26.21    Tvector4_single         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  917

             26.21.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  917

             26.21.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  917

             26.21.3      Tvector4_single.init_zero           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  917

             26.21.4      Tvector4_single.init_one         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  917

             26.21.5      Tvector4_single.init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  918

             26.21.6      Tvector4_single.length           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  918

             26.21.7      Tvector4_single.squared_length             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 918


27   Reference for unit 'mmx'                                                                                           919

    27.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  919

    27.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  919

             27.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  919

             27.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  920

    27.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  921

             27.3.1       emms     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  921

             27.3.2       femms      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  921


28   Reference for unit 'Mouse'                                                                                         922

    28.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  922

    28.2     Writing a custom mouse driver               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  922

    28.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  924

             28.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  924

             28.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  925

             28.3.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  926

    28.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  926

             28.4.1       DetectMouse       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  926

             28.4.2       DoneMouse         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  927

             28.4.3       GetMouseButtons           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  927

             28.4.4       GetMouseDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  928

             28.4.5       GetMouseEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  928

             28.4.6       GetMouseX         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  929

             28.4.7       GetMouseY         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  929

             28.4.8       HideMouse       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  930

             28.4.9       InitMouse       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  930

             28.4.10      PollMouseEvent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  931

             28.4.11      PutMouseEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  931



                                                                 57

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             28.4.12      SetMouseDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  931

             28.4.13      SetMouseXY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  932

             28.4.14      ShowMouse         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  932


29   Reference for unit 'Objects'                                                                                       934

    29.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  934

    29.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  934

             29.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  934

             29.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  936

             29.2.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  940

    29.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  940

             29.3.1       Abstract      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  940

             29.3.2       CallPointerConstructor           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  940

             29.3.3       CallPointerLocal       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  941

             29.3.4       CallPointerMethod           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  941

             29.3.5       CallPointerMethodLocal              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  941

             29.3.6       CallVoidConstructor            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  942

             29.3.7       CallVoidLocal        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  942

             29.3.8       CallVoidMethod         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  942

             29.3.9       CallVoidMethodLocal            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  943

             29.3.10      DisposeStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  943

             29.3.11      LongDiv       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  943

             29.3.12      LongMul       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  944

             29.3.13      NewStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  944

             29.3.14      RegisterObjects        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  944

             29.3.15      RegisterType         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  945

             29.3.16      SetStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  946

    29.4     TBufStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  947

             29.4.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  947

             29.4.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  947

             29.4.3       TBufStream.Init        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  947

             29.4.4       TBufStream.Done           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  948

             29.4.5       TBufStream.Close          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  948

             29.4.6       TBufStream.Flush          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  948

             29.4.7       TBufStream.Truncate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  949

             29.4.8       TBufStream.Seek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  949

             29.4.9       TBufStream.Open           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  950

             29.4.10      TBufStream.Read           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  950

             29.4.11      TBufStream.Write          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  950

    29.5     TCollection      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  951



                                                                 58

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             29.5.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  951

             29.5.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  951

             29.5.3       TCollection.Init       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  951

             29.5.4       TCollection.Load          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  952

             29.5.5       TCollection.Done          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  953

             29.5.6       TCollection.At       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  953

             29.5.7       TCollection.IndexOf            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  954

             29.5.8       TCollection.GetItem            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  955

             29.5.9       TCollection.LastThat           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  955

             29.5.10      TCollection.FirstThat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  956

             29.5.11      TCollection.Pack          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  957

             29.5.12      TCollection.FreeAll         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  957

             29.5.13      TCollection.DeleteAll          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  958

             29.5.14      TCollection.Free       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  959

             29.5.15      TCollection.Insert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  960

             29.5.16      TCollection.Delete          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  960

             29.5.17      TCollection.AtFree          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  961

             29.5.18      TCollection.FreeItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  961

             29.5.19      TCollection.AtDelete           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  962

             29.5.20      TCollection.ForEach            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  962

             29.5.21      TCollection.SetLimit           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  963

             29.5.22      TCollection.Error         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  963

             29.5.23      TCollection.AtPut         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  964

             29.5.24      TCollection.AtInsert           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  964

             29.5.25      TCollection.Store         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  965

             29.5.26      TCollection.PutItem            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  965

    29.6     TDosStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  966

             29.6.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  966

             29.6.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  966

             29.6.3       TDosStream.Init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  966

             29.6.4       TDosStream.Done           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  966

             29.6.5       TDosStream.Close          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  967

             29.6.6       TDosStream.Truncate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  967

             29.6.7       TDosStream.Seek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  968

             29.6.8       TDosStream.Open             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  969

             29.6.9       TDosStream.Read           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  969

             29.6.10      TDosStream.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  970

    29.7     TMemoryStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  970

             29.7.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  970

             29.7.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  970



                                                                 59

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             29.7.3       TMemoryStream.Init             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  970

             29.7.4       TMemoryStream.Done               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  971

             29.7.5       TMemoryStream.Truncate                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  971

             29.7.6       TMemoryStream.Read               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  972

             29.7.7       TMemoryStream.Write              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  972

    29.8     TObject       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  972

             29.8.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  972

             29.8.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  973

             29.8.3       TObject.Init      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  973

             29.8.4       TObject.Free         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  973

             29.8.5       TObject.Is_Object         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  974

             29.8.6       TObject.Done         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  974

    29.9     TPoint      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  974

             29.9.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  974

    29.10    TRect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  97@

             29.10.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  974

             29.10.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  975

             29.10.3      TRect.Empty          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  975

             29.10.4      TRect.Equals         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  976

             29.10.5      TRect.Contains         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  976

             29.10.6      TRect.Copy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  976

             29.10.7      TRect.Union       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  977

             29.10.8      TRect.Intersect        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  978

             29.10.9      TRect.Move        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  978

             29.10.10     TRect.Grow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  979

             29.10.11     TRect.Assign         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  980

    29.11    TResourceCollection            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  980

             29.11.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  980

             29.11.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  981

             29.11.3      TResourceCollection.KeyOf               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 981

             29.11.4      TResourceCollection.GetItem                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 981

             29.11.5      TResourceCollection.FreeItem               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 981

             29.11.6      TResourceCollection.PutItem                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 982

    29.12    TResourceFile         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  982

             29.12.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  982

             29.12.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  982

             29.12.3      TResourceFile.Init          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  982

             29.12.4      TResourceFile.Done          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  983

             29.12.5      TResourceFile.Count            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  983

             29.12.6      TResourceFile.KeyAt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  983



                                                                 60

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             29.12.7      TResourceFile.Get           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  983

             29.12.8      TResourceFile.SwitchTo              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  984

             29.12.9      TResourceFile.Flush            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  984

             29.12.10     TResourceFile.Delete           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  984

             29.12.11     TResourceFile.Put           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  984

    29.13    TSortedCollection          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  985

             29.13.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  985

             29.13.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  985

             29.13.3      TSortedCollection.Init           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  985

             29.13.4      TSortedCollection.Load           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  986

             29.13.5      TSortedCollection.KeyOf             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  986

             29.13.6      TSortedCollection.IndexOf             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  986

             29.13.7      TSortedCollection.Compare               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 987

             29.13.8      TSortedCollection.Search            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  987

             29.13.9      TSortedCollection.Insert            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  989

             29.13.10     TSortedCollection.Store             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  990

    29.14    TStrCollection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  990

             29.14.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  990

             29.14.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  990

             29.14.3      TStrCollection.Compare              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  990

             29.14.4      TStrCollection.GetItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  991

             29.14.5      TStrCollection.FreeItem             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  991

             29.14.6      TStrCollection.PutItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  992

    29.15    TStream       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  992

             29.15.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  992

             29.15.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  993

             29.15.3      TStream.Init      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  993

             29.15.4      TStream.Get       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  993

             29.15.5      TStream.StrRead           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  994

             29.15.6      TStream.GetPos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  995

             29.15.7      TStream.GetSize           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  995

             29.15.8      TStream.ReadStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  996

             29.15.9      TStream.Open         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  996

             29.15.10     TStream.Close        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  997

             29.15.11     TStream.Reset        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  997

             29.15.12     TStream.Flush        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  997

             29.15.13     TStream.Truncate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  998

             29.15.14     TStream.Put       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  998

             29.15.15     TStream.StrWrite          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  998

             29.15.16     TStream.WriteStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  999



                                                                 61

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             29.15.17     TStream.Seek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  999

             29.15.18     TStream.Error        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  999

             29.15.19     TStream.Read         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  999

             29.15.20     TStream.Write        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1000

             29.15.21     TStream.CopyFrom            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1000

    29.16    TStringCollection          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1001

             29.16.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1001

             29.16.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1001

             29.16.3      TStringCollection.GetItem             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1002

             29.16.4      TStringCollection.Compare             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1002

             29.16.5      TStringCollection.FreeItem            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1003

             29.16.6      TStringCollection.PutItem             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1003

    29.17    TStringList      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1003

             29.17.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1003

             29.17.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1003

             29.17.3      TStringList.Load          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1004

             29.17.4      TStringList.Done          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1004

             29.17.5      TStringList.Get        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1004

    29.18    TStrListMaker         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1004

             29.18.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1004

             29.18.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1005

             29.18.3      TStrListMaker.Init          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1005

             29.18.4      TStrListMaker.Done             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1005

             29.18.5      TStrListMaker.Put           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1005

             29.18.6      TStrListMaker.Store            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1006

    29.19    TUnSortedStrCollection              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1006

             29.19.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1006

             29.19.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1006

             29.19.3      TUnSortedStrCollection.Insert              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1006


30   Reference for unit 'objpas'                                                                                      1008

    30.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1008

    30.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1008

             30.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1008

             30.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1008


31   Reference for unit 'oldlinux'                                                                                    1010

    31.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1010

    31.2     Utility routines        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1010

    31.3     Terminal functions         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1011

    31.4     System information           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1011



                                                                 62

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



    31.5     Signals     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  101@

    31.6     Process handling        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1012

    31.7     Directory handling routines            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1012

    31.8     Pipes, FIFOs and streams               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1013

    31.9     General File handling routines              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1013

    31.10    File Input/Output routines             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1014

    31.11    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1015

             31.11.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1015

             31.11.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1053

             31.11.3      Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1061

    31.12    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1062

             31.12.1      Access     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1062

             31.12.2      Alarm      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1063

             31.12.3      AssignPipe      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1064

             31.12.4      AssignStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1065

             31.12.5      Basename        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1066

             31.12.6      CFMakeRaw         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1067

             31.12.7      CFSetISpeed       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1067

             31.12.8      CFSetOSpeed          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1067

             31.12.9      Chmod      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1067

             31.12.10     Chown      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1069

             31.12.11     Clone    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1070

             31.12.12     CloseDir      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1072

             31.12.13     CreateShellArgV           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1072

             31.12.14     Dirname       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1073

             31.12.15     Dup   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1073

             31.12.16     Dup2     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1074

             31.12.17     EpochToLocal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1075

             31.12.18     Execl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1075

             31.12.19     Execle     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1076

             31.12.20     Execlp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1077

             31.12.21     Execv    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1078

             31.12.22     Execve     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1079

             31.12.23     Execvp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1080

             31.12.24     ExitProcess       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1081

             31.12.25     Fcntl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1081

             31.12.26     fdClose    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1082

             31.12.27     fdFlush    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1082

             31.12.28     fdOpen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1082

             31.12.29     fdRead     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1083



                                                                 63

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             31.12.30     fdSeek     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1085

             31.12.31     fdTruncate      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1085

             31.12.32     fdWrite    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1085

             31.12.33     FD_Clr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1086

             31.12.34     FD_IsSet      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1086

             31.12.35     FD_Set     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1086

             31.12.36     FD_Zero       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1086

             31.12.37     FExpand       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1087

             31.12.38     Flock    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1087

             31.12.39     FNMatch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1088

             31.12.40     Fork     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1088

             31.12.41     FReName         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1089

             31.12.42     FSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1089

             31.12.43     FSplit     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1090

             31.12.44     FSStat     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1091

             31.12.45     FStat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1092

             31.12.46     GetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1093

             31.12.47     GetDateTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1093

             31.12.48     GetDomainName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1094

             31.12.49     GetEGid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1094

             31.12.50     GetEnv     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1095

             31.12.51     GetEpochTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1095

             31.12.52     GetEUid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1096

             31.12.53     GetFS      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1096

             31.12.54     GetGid     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1097

             31.12.55     GetHostName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1097

             31.12.56     GetLocalTimezone            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1098

             31.12.57     GetPid     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1098

             31.12.58     GetPPid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1099

             31.12.59     GetPriority       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1099

             31.12.60     GetTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1100

             31.12.61     GetTimeOfDay           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1100

             31.12.62     GetTimezoneFile           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1101

             31.12.63     GetUid     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1101

             31.12.64     Glob     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1101

             31.12.65     Globfree      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1102

             31.12.66     IOCtl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1102

             31.12.67     IOperm     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1103

             31.12.68     IoPL     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1103

             31.12.69     IsATTY        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1104



                                                                 64

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             31.12.70     Kill  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1104

             31.12.71     Link     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1104

             31.12.72     LocalToEpoch         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1105

             31.12.73     Lstat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1106

             31.12.74     mkFifo     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1108

             31.12.75     MMap       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1108

             31.12.76     MUnMap        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1109

             31.12.77     NanoSleep       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1110

             31.12.78     Nice     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1111

             31.12.79     Octal    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1111

             31.12.80     OpenDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1112

             31.12.81     Pause    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1113

             31.12.82     PClose     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1113

             31.12.83     POpen      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1113

             31.12.84     ReadDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1114

             31.12.85     ReadLink      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1115

             31.12.86     ReadTimezoneFile          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1116

             31.12.87     SeekDir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1116

             31.12.88     Select   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1116

             31.12.89     SelectText      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1118

             31.12.90     SetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1118

             31.12.91     SetDateTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1118

             31.12.92     SetPriority     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1119

             31.12.93     SetTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1119

             31.12.94     Shell    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1120

             31.12.95     SigAction       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1120

             31.12.96     Signal   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1121

             31.12.97     SigPending      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1122

             31.12.98     SigProcMask       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1123

             31.12.99     SigRaise      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1123

             31.12.100    SigSuspend      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1124

             31.12.101    StringToPPChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1124

             31.12.102    SymLink       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1125

             31.12.103    SysCall    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1126

             31.12.104    Sysinfo    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1126

             31.12.105    S_ISBLK       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1128

             31.12.106    S_ISCHR       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1128

             31.12.107    S_ISDIR       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1128

             31.12.108    S_ISFIFO        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1128

             31.12.109    S_ISLNK       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1129



                                                                 65

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             31.12.110    S_ISREG       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1129

             31.12.111    S_ISSOCK        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1130

             31.12.112    TCDrain       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1130

             31.12.113    TCFlow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1130

             31.12.114    TCFlush       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1131

             31.12.115    TCGetAttr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1131

             31.12.116    TCGetPGrp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1132

             31.12.117    TCSendBreak          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1132

             31.12.118    TCSetAttr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1132

             31.12.119    TCSetPGrp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1133

             31.12.120    TellDir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1133

             31.12.121    TTYname         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1134

             31.12.122    Umask      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1134

             31.12.123    Uname      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1134

             31.12.124    UnLink     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1135

             31.12.125    Utime      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1135

             31.12.126    WaitPid       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1136

             31.12.127    WaitProcess       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1137

             31.12.128    WEXITSTATUS               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1137

             31.12.129    WIFEXITED            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1137

             31.12.130    WIFSIGNALED            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1138

             31.12.131    WIFSTOPPED             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1138

             31.12.132    WSTOPSIG          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1138

             31.12.133    WTERMSIG          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1138

             31.12.134    W_EXITCODE             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1139

             31.12.135    W_STOPCODE             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1139


32   Reference for unit 'ports'                                                                                       1140

    32.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1140

    32.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1140

             32.2.1       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1140

    32.3     tport     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  11@

             32.3.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1141

             32.3.2       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1141

             32.3.3       tport.pp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1141

    32.4     tportl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  11@

             32.4.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1142

             32.4.2       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1142

             32.4.3       tportl.pp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1142

    32.5     tportw      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  114@



                                                                 66

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             32.5.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1142

             32.5.2       Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1142

             32.5.3       tportw.pp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1142


33   Reference for unit 'printer'                                                                                     1143

    33.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1143

    33.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1143

             33.2.1       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1143

    33.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1143

             33.3.1       AssignLst       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1143

             33.3.2       InitPrinter     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1144

             33.3.3       IsLstAvailable       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1144


34   Reference for unit 'Sockets'                                                                                     1145

    34.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1145

    34.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1145

    34.3     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1145

             34.3.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1145

             34.3.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1166

    34.4     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1169

             34.4.1       Accept     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1169

             34.4.2       Bind     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1171

             34.4.3       CloseSocket       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1171

             34.4.4       Connect       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1171

             34.4.5       fpaccept      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1173

             34.4.6       fpbind     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1175

             34.4.7       fpconnect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1175

             34.4.8       fpgetpeername        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1177

             34.4.9       fpgetsockname        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1177

             34.4.10      fpgetsockopt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1178

             34.4.11      fplisten   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1178

             34.4.12      fprecv   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1179

             34.4.13      fprecvfrom      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1179

             34.4.14      fpsend     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1180

             34.4.15      fpsendto      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1180

             34.4.16      fpsetsockopt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1180

             34.4.17      fpshutdown        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1181

             34.4.18      fpsocket      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1181

             34.4.19      fpsocketpair      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1182

             34.4.20      HostAddrToStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1182

             34.4.21      HostAddrToStr6         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1182



                                                                 67

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             34.4.22      HostToNet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1183

             34.4.23      htonl    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1183

             34.4.24      htons    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1183

             34.4.25      NetAddrToStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1183

             34.4.26      NetAddrToStr6          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1184

             34.4.27      NetToHost       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1184

             34.4.28      NToHl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1184

             34.4.29      NToHs      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1184

             34.4.30      ShortHostToNet         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1185

             34.4.31      ShortNetToHost         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1185

             34.4.32      Sock2File     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1185

             34.4.33      Sock2Text       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1185

             34.4.34      socketerror     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1186

             34.4.35      Str2UnixSockAddr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1186

             34.4.36      StrToHostAddr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1186

             34.4.37      StrToHostAddr6         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1186

             34.4.38      StrToNetAddr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1187

             34.4.39      StrToNetAddr6          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1187


35   Reference for unit 'strings'                                                                                     1188

    35.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1188

    35.2     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1188

             35.2.1       stralloc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1188

             35.2.2       strcat   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1188

             35.2.3       strcomp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1189

             35.2.4       strcopy    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1189

             35.2.5       strdispose      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1190

             35.2.6       strecopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1190

             35.2.7       strend     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1191

             35.2.8       stricomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1192

             35.2.9       stripos    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1192

             35.2.10      striscan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1193

             35.2.11      strlcat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1193

             35.2.12      strlcomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1194

             35.2.13      strlcopy   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1194

             35.2.14      strlen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1195

             35.2.15      strlicomp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1195

             35.2.16      strlower   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1196

             35.2.17      strmove    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1196

             35.2.18      strnew     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1197



                                                                 68

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             35.2.19      strpas   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1198

             35.2.20      strpcopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1198

             35.2.21      strpos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1199

             35.2.22      strriscan     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1199

             35.2.23      strrscan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1200

             35.2.24      strscan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1200

             35.2.25      strupper      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1200


36   Reference for unit 'strutils'                                                                                    1201

    36.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1201

    36.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1201

             36.2.1       Resource strings       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1201

             36.2.2       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1201

             36.2.3       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1202

    36.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1203

             36.3.1       AddChar       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1203

             36.3.2       AddCharR        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1203

             36.3.3       AnsiContainsStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1203

             36.3.4       AnsiContainsText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1203

             36.3.5       AnsiEndsStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1204

             36.3.6       AnsiEndsText         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1204

             36.3.7       AnsiIndexStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1204

             36.3.8       AnsiIndexText        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1205

             36.3.9       AnsiLeftStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1205

             36.3.10      AnsiMatchStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1205

             36.3.11      AnsiMatchText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1205

             36.3.12      AnsiMidStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1206

             36.3.13      AnsiProperCase         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1206

             36.3.14      AnsiReplaceStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1206

             36.3.15      AnsiReplaceText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1207

             36.3.16      AnsiResemblesText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1207

             36.3.17      AnsiReverseString         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1207

             36.3.18      AnsiRightStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1207

             36.3.19      AnsiStartsStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1208

             36.3.20      AnsiStartsText         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1208

             36.3.21      BinToHex        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1208

             36.3.22      Copy2Space        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1209

             36.3.23      Copy2SpaceDel          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1209

             36.3.24      Copy2Symb         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1209

             36.3.25      Copy2SymbDel           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1210



                                                                 69

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             36.3.26      Dec2Numb        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1210

             36.3.27      DecodeSoundexInt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1210

             36.3.28      DecodeSoundexWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1210

             36.3.29      DelChars      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1211

             36.3.30      DelSpace      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1211

             36.3.31      DelSpace1       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1211

             36.3.32      DupeString      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1212

             36.3.33      ExtractDelimited          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1212

             36.3.34      ExtractSubstr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1212

             36.3.35      ExtractWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1213

             36.3.36      ExtractWordPos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1213

             36.3.37      FindPart      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1214

             36.3.38      GetCmdLineArg          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1214

             36.3.39      Hex2Dec       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1214

             36.3.40      HexToBin        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1215

             36.3.41      IfThen     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1215

             36.3.42      IntToBin      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1215

             36.3.43      IntToRoman        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1216

             36.3.44      IsEmptyStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1216

             36.3.45      IsWild     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1216

             36.3.46      IsWordPresent        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1217

             36.3.47      LeftBStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1217

             36.3.48      LeftStr    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1217

             36.3.49      MidBStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1218

             36.3.50      MidStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1218

             36.3.51      NPos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1218

             36.3.52      Numb2Dec        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1219

             36.3.53      Numb2USA          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1219

             36.3.54      PadCenter       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1219

             36.3.55      PadLeft       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1219

             36.3.56      PadRight      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1220

             36.3.57      PosEx      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1220

             36.3.58      PosSet     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1220

             36.3.59      PosSetEx      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1220

             36.3.60      RandomFrom           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1221

             36.3.61      Removeleadingchars          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1221

             36.3.62      RemovePadChars            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1221

             36.3.63      RemoveTrailingChars            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1222

             36.3.64      ReverseString        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1222

             36.3.65      RightBStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1222



                                                                 70

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             36.3.66      RightStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1223

             36.3.67      RomanToInt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1223

             36.3.68      RPos     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1223

             36.3.69      RPosex     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1223

             36.3.70      SearchBuf       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1224

             36.3.71      Soundex       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1224

             36.3.72      SoundexCompare            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1225

             36.3.73      SoundexInt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1225

             36.3.74      SoundexProc       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1225

             36.3.75      SoundexSimilar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1226

             36.3.76      SoundexWord          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1226

             36.3.77      StringsReplace       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1226

             36.3.78      StuffString     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1227

             36.3.79      Tab2Space       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1227

             36.3.80      TrimLeftSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1227

             36.3.81      TrimRightSet         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1227

             36.3.82      TrimSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1228

             36.3.83      WordCount         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1228

             36.3.84      WordPosition         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1228

             36.3.85      XorDecode       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1229

             36.3.86      XorEncode       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1229

             36.3.87      XorString       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1229


37   Reference for unit 'System'                                                                                      1230

    37.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1230

    37.2     A string consisting of widechars.             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1230

    37.3     Miscellaneous functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1230

    37.4     Operating System functions               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1231

    37.5     String handling         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1231

    37.6     Mathematical routines             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1232

    37.7     Memory management functions                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1233

    37.8     File handling functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1233

    37.9     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1234

             37.9.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1234

             37.9.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1257

             37.9.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1282

    37.10    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1285

             37.10.1      abs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1285

             37.10.2      AbstractError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1285

             37.10.3      AcquireExceptionObject              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1285



                                                                 71

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.4      AddExitProc       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1286

             37.10.5      Addr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1286

             37.10.6      Align    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1287

             37.10.7      AllocMem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1287

             37.10.8      AnsiToUtf8        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1287

             37.10.9      Append     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1287

             37.10.10     arctan     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1288

             37.10.11     ArrayStringToPPchar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1288

             37.10.12     Assert     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1289

             37.10.13     Assign     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1289

             37.10.14     Assigned      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1290

             37.10.15     BasicEventCreate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1291

             37.10.16     basiceventdestroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1291

             37.10.17     basiceventResetEvent           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1291

             37.10.18     basiceventSetEvent          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1291

             37.10.19     basiceventWaitFor         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1291

             37.10.20     BeginThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1292

             37.10.21     BEtoN      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1292

             37.10.22     binStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1292

             37.10.23     BlockRead       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1293

             37.10.24     BlockWrite      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1294

             37.10.25     Break    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1294

             37.10.26     BsfByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1295

             37.10.27     BsfDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1296

             37.10.28     BsfQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1296

             37.10.29     BsfWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1296

             37.10.30     BsrByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1296

             37.10.31     BsrDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1297

             37.10.32     BsrQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1297

             37.10.33     BsrWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1297

             37.10.34     chdir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1297

             37.10.35     chr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1298

             37.10.36     Close    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1298

             37.10.37     CloseThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1299

             37.10.38     CompareByte          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1299

             37.10.39     CompareChar          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1300

             37.10.40     CompareChar0           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1302

             37.10.41     CompareDWord           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1302

             37.10.42     CompareWord          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1303

             37.10.43     Concat     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1304



                                                                 72

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.44     Continue      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1305

             37.10.45     Copy     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1306

             37.10.46     cos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1306

             37.10.47     Cseg     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1307

             37.10.48     Dec   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1307

             37.10.49     DefaultAnsi2UnicodeMove               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1308

             37.10.50     DefaultAnsi2WideMove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1308

             37.10.51     DefaultUnicode2AnsiMove               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1308

             37.10.52     DefaultWide2AnsiMove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1309

             37.10.53     Delete     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1309

             37.10.54     Dispose    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1310

             37.10.55     DoneCriticalsection         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1311

             37.10.56     DoneThread        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1311

             37.10.57     Dseg     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1311

             37.10.58     DumpExceptionBackTrace                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1312

             37.10.59     Dump_Stack        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1312

             37.10.60     DynArraySetLength           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1312

             37.10.61     EndThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1312

             37.10.62     EnterCriticalsection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1313

             37.10.63     EnumResourceLanguages               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1313

             37.10.64     EnumResourceNames              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1314

             37.10.65     EnumResourceTypes              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1314

             37.10.66     EOF      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1314

             37.10.67     EOLn     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1315

             37.10.68     Erase    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1316

             37.10.69     Error    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1316

             37.10.70     Exclude       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1317

             37.10.71     Exit  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1318

             37.10.72     exp   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1319

             37.10.73     FilePos    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1319

             37.10.74     FileSize   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1320

             37.10.75     FillByte      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1321

             37.10.76     FillChar      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1321

             37.10.77     FillDWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1322

             37.10.78     FillQWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1323

             37.10.79     FillWord      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1323

             37.10.80     FindResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1323

             37.10.81     FindResourceEx         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1324

             37.10.82     float_raise     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1324

             37.10.83     Flush    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1325



                                                                 73

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.84     FlushThread       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1325

             37.10.85     FPower10        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1326

             37.10.86     frac  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1326

             37.10.87     Freemem       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1326

             37.10.88     Freememory        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1327

             37.10.89     FreeResource      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1327

             37.10.90     GetCurrentThreadId             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1327

             37.10.91     getdir   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1328

             37.10.92     GetFPCHeapStatus            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1328

             37.10.93     GetHeapStatus          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1328

             37.10.94     GetMem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1328

             37.10.95     GetMemory         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1329

             37.10.96     GetMemoryManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1329

             37.10.97     GetProcessID         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1329

             37.10.98     GetResourceManager             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1330

             37.10.99     GetThreadID          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1330

             37.10.100    GetThreadManager            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1330

             37.10.101    GetUnicodeStringManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1330

             37.10.102    GetVariantManager           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1331

             37.10.103    GetWideStringManager             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1331

             37.10.104    get_caller_addr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1331

             37.10.105    get_caller_frame       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1331

             37.10.106    get_cmdline       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1332

             37.10.107    get_frame     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1332

             37.10.108    halt  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1332

             37.10.109    hexStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1333

             37.10.110    hi  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1333

             37.10.111    High     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1334

             37.10.112    HINSTANCE            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1335

             37.10.113    Inc   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1335

             37.10.114    Include    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1336

             37.10.115    IndexByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1336

             37.10.116    IndexChar       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1337

             37.10.117    IndexChar0        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1338

             37.10.118    IndexDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1338

             37.10.119    IndexQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1339

             37.10.120    Indexword       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1339

             37.10.121    InitCriticalSection       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1340

             37.10.122    InitThread      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1340

             37.10.123    InitThreadVars         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1341



                                                                 74

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.124    Insert   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1341

             37.10.125    int   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1342

             37.10.126    InterlockedCompareExchange                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1342

             37.10.127    InterLockedDecrement             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1342

             37.10.128    InterLockedExchange            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1343

             37.10.129    InterLockedExchangeAdd              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1343

             37.10.130    InterLockedIncrement           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1344

             37.10.131    IOResult      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1344

             37.10.132    IsMemoryManagerSet             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1345

             37.10.133    Is_IntResource       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1346

             37.10.134    KillThread      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1346

             37.10.135    LeaveCriticalsection        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1346

             37.10.136    Length     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1346

             37.10.137    LEtoN      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1347

             37.10.138    ln  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1347

             37.10.139    lo  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1348

             37.10.140    LoadResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1348

             37.10.141    LockResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1349

             37.10.142    longjmp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1349

             37.10.143    Low   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1350

             37.10.144    lowerCase       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1350

             37.10.145    MakeLangID        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1351

             37.10.146    MemSize       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1351

             37.10.147    mkdir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1351

             37.10.148    Move     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1351

             37.10.149    MoveChar0       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1352

             37.10.150    New      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1352

             37.10.151    NtoBE      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1353

             37.10.152    NtoLE      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1353

             37.10.153    Null  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1353

             37.10.154    OctStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1354

             37.10.155    odd   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1354

             37.10.156    Ofs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1355

             37.10.157    operator *(variant, variant):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *355

             37.10.158    operator **(variant, variant):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *356

             37.10.159    operator +(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *356

             37.10.160    operator -(variant):  variant         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1356

             37.10.161    operator -(variant, variant):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *357

             37.10.162    operator /(variant, variant):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *357

             37.10.163    operator :=(ansistring):  olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1357



                                                                 75

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.164    operator :=(ansistring):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1357

             37.10.165    operator :=(Boolean):  olevariant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1358

             37.10.166    operator :=(Boolean):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1358

             37.10.167    operator :=(Byte):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1358

             37.10.168    operator :=(Byte):  variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1358

             37.10.169    operator :=(Char):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1358

             37.10.170    operator :=(Char):  variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1358

             37.10.171    operator :=(comp):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1359

             37.10.172    operator :=(comp):  variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1359

             37.10.173    operator :=(currency):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1359

             37.10.174    operator :=(currency):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1359

             37.10.175    operator :=(Double):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1359

             37.10.176    operator :=(Double):  variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1359

             37.10.177    operator :=(DWord):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1360

             37.10.178    operator :=(DWord):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1360

             37.10.179    operator :=(extended):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1360

             37.10.180    operator :=(extended):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1360

             37.10.181    operator :=(Int64):  olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1360

             37.10.182    operator :=(Int64):  variant          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1360

             37.10.183    operator :=(longbool):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1361

             37.10.184    operator :=(longbool):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1361

             37.10.185    operator :=(LongInt):  olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1361

             37.10.186    operator :=(LongInt):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1361

             37.10.187    operator :=(olevariant):  ansistring            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1361

             37.10.188    operator :=(olevariant):  Boolean               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1362

             37.10.189    operator :=(olevariant):  Byte             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1362

             37.10.190    operator :=(olevariant):  Char             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1362

             37.10.191    operator :=(olevariant):  comp             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1362

             37.10.192    operator :=(olevariant):  currency              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1362

             37.10.193    operator :=(olevariant):  Double             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1362

             37.10.194    operator :=(olevariant):  DWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1363

             37.10.195    operator :=(olevariant):  extended              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1363

             37.10.196    operator :=(olevariant):  Int64            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1363

             37.10.197    operator :=(olevariant):  longbool              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1363

             37.10.198    operator :=(olevariant):  LongInt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1363

             37.10.199    operator :=(olevariant):  QWord              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1364

             37.10.200    operator :=(olevariant):  Real             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1364

             37.10.201    operator :=(olevariant):  ShortInt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1364

             37.10.202    operator :=(olevariant):  shortstring             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *364

             37.10.203    operator :=(olevariant):  single           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1364



                                                                 76

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.204    operator :=(olevariant):  SmallInt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1364

             37.10.205    operator :=(olevariant):  TDateTime                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *365

             37.10.206    operator :=(olevariant):  TError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1365

             37.10.207    operator :=(olevariant):  UnicodeString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  13*
 *65

             37.10.208    operator :=(olevariant):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1365

             37.10.209    operator :=(olevariant):  WideChar                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *365

             37.10.210    operator :=(olevariant):  widestring              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *366

             37.10.211    operator :=(olevariant):  Word             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1366

             37.10.212    operator :=(olevariant):  wordbool              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1366

             37.10.213    operator :=(QWord):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1366

             37.10.214    operator :=(QWord):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1366

             37.10.215    operator :=(Real):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1366

             37.10.216    operator :=(Real):  variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1367

             37.10.217    operator :=(real48):  Double            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1367

             37.10.218    operator :=(real48):  extended             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1367

             37.10.219    operator :=(ShortInt):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1367

             37.10.220    operator :=(ShortInt):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1367

             37.10.221    operator :=(shortstring):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *367

             37.10.222    operator :=(shortstring):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1368

             37.10.223    operator :=(single):  olevariant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1368

             37.10.224    operator :=(single):  variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1368

             37.10.225    operator :=(SmallInt):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1368

             37.10.226    operator :=(SmallInt):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1368

             37.10.227    operator :=(TDateTime):  olevariant                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *368

             37.10.228    operator :=(TDateTime):  variant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1369

             37.10.229    operator :=(TError):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1369

             37.10.230    operator :=(TError):  variant           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1369

             37.10.231    operator :=(UCS4String):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1369

             37.10.232    operator :=(UnicodeString):  olevariant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  13*
 *69

             37.10.233    operator :=(UnicodeString):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *369

             37.10.234    operator :=(UTF8String):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1370

             37.10.235    operator :=(variant):  ansistring            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1370

             37.10.236    operator :=(variant):  Boolean             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1370

             37.10.237    operator :=(variant):  Byte           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1370

             37.10.238    operator :=(variant):  Char           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1370

             37.10.239    operator :=(variant):  comp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1370

             37.10.240    operator :=(variant):  currency            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1371

             37.10.241    operator :=(variant):  Double           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1371

             37.10.242    operator :=(variant):  DWord            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1371

             37.10.243    operator :=(variant):  extended            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1371



                                                                 77

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.244    operator :=(variant):  Int64          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1371

             37.10.245    operator :=(variant):  longbool            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1371

             37.10.246    operator :=(variant):  LongInt             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1372

             37.10.247    operator :=(variant):  olevariant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1372

             37.10.248    operator :=(variant):  QWord               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1372

             37.10.249    operator :=(variant):  Real           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1372

             37.10.250    operator :=(variant):  ShortInt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1372

             37.10.251    operator :=(variant):  shortstring              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1372

             37.10.252    operator :=(variant):  single           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1373

             37.10.253    operator :=(variant):  SmallInt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1373

             37.10.254    operator :=(variant):  TDateTime                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1373

             37.10.255    operator :=(variant):  TError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1373

             37.10.256    operator :=(variant):  unicodestring              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *373

             37.10.257    operator :=(variant):  UTF8String               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1373

             37.10.258    operator :=(variant):  WideChar              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1374

             37.10.259    operator :=(variant):  widestring            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1374

             37.10.260    operator :=(variant):  Word             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1374

             37.10.261    operator :=(variant):  wordbool              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1374

             37.10.262    operator :=(WideChar):  olevariant                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *374

             37.10.263    operator :=(WideChar):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1375

             37.10.264    operator :=(widestring):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *375

             37.10.265    operator :=(widestring):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1375

             37.10.266    operator :=(Word):  olevariant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1375

             37.10.267    operator :=(Word):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1375

             37.10.268    operator :=(wordbool):  olevariant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1376

             37.10.269    operator :=(wordbool):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1376

             37.10.270    operator <(variant, variant):  Boolean               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *376

             37.10.271    operator <=(variant, variant):  Boolean                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  13*
 *76

             37.10.272    operator =(variant, variant):  Boolean               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *377

             37.10.273    operator >(variant, variant):  Boolean               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *377

             37.10.274    operator >=(variant, variant):  Boolean                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  13*
 *77

             37.10.275    operator and(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  13*
 *78

             37.10.276    operator div(variant, variant):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *378

             37.10.277    operator mod(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  13*
 *78

             37.10.278    operator not(variant):  variant            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1379

             37.10.279    operator or(variant, variant):  variant              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *379

             37.10.280    operator shl(variant, variant):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *379

             37.10.281    operator shr(variant, variant):  variant             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *380

             37.10.282    operator xor(variant, variant):  variant               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  13*
 *80

             37.10.283    Ord   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1380



                                                                 78

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.284    Pack     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1381

             37.10.285    Paramcount        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1381

             37.10.286    ParamStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1382

             37.10.287    pi  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1382

             37.10.288    Pos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1383

             37.10.289    Pred     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1384

             37.10.290    prefetch      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1384

             37.10.291    ptr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1384

             37.10.292    RaiseList     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1385

             37.10.293    Random        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1385

             37.10.294    Randomize       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1386

             37.10.295    Read     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1386

             37.10.296    ReadBarrier       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1387

             37.10.297    ReadDependencyBarrier               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1387

             37.10.298    ReadLn     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1388

             37.10.299    ReadStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1388

             37.10.300    ReadWriteBarrier          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1389

             37.10.301    Real2Double       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1389

             37.10.302    ReAllocMem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1390

             37.10.303    ReAllocMemory          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1390

             37.10.304    ReleaseExceptionObject              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1390

             37.10.305    Rename        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1391

             37.10.306    Reset    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1391

             37.10.307    ResumeThread           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1392

             37.10.308    Rewrite    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1392

             37.10.309    rmdir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1393

             37.10.310    RolByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1394

             37.10.311    RolDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1394

             37.10.312    RolQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1394

             37.10.313    RolWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1395

             37.10.314    RorByte       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1395

             37.10.315    RorDWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1395

             37.10.316    RorQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1395

             37.10.317    RorWord       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1396

             37.10.318    round    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1396

             37.10.319    RTLEventCreate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1396

             37.10.320    RTLeventdestroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1397

             37.10.321    RTLeventResetEvent             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1397

             37.10.322    RTLeventSetEvent            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1397

             37.10.323    RTLeventsync         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1397



                                                                 79

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.324    RTLeventWaitFor           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1398

             37.10.325    RunError      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1398

             37.10.326    SarInt64      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1398

             37.10.327    SarLongint      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1399

             37.10.328    SarShortint       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1399

             37.10.329    SarSmallint       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1399

             37.10.330    Seek     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1399

             37.10.331    SeekEOF       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1400

             37.10.332    SeekEOLn        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1401

             37.10.333    Seg   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1401

             37.10.334    Setjmp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1402

             37.10.335    SetLength       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1403

             37.10.336    SetMemoryManager            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1403

             37.10.337    SetResourceManager             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1404

             37.10.338    SetString     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1404

             37.10.339    SetTextBuf      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1404

             37.10.340    SetTextLineEnding           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1405

             37.10.341    SetThreadManager            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1406

             37.10.342    SetUnicodeStringManager               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1406

             37.10.343    SetVariantManager           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1407

             37.10.344    SetWideStringManager             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1407

             37.10.345    ShortCompareText            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1407

             37.10.346    sin   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1408

             37.10.347    SizeOf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1408

             37.10.348    SizeofResource       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1409

             37.10.349    Space    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1409

             37.10.350    Sptr  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1409

             37.10.351    sqr   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1410

             37.10.352    sqrt  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1410

             37.10.353    Sseg  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1411

             37.10.354    Str   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1411

             37.10.355    StringOfChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1412

             37.10.356    StringToPPChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1412

             37.10.357    StringToUnicodeChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1413

             37.10.358    StringToWideChar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1413

             37.10.359    strlen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1413

             37.10.360    strpas   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1414

             37.10.361    Succ     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1414

             37.10.362    SuspendThread          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1414

             37.10.363    Swap     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1415



                                                                 80

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.364    SwapEndian        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1415

             37.10.365    SysAllocMem          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1416

             37.10.366    SysAssert     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1416

             37.10.367    SysBackTraceStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1416

             37.10.368    SysFlushStdIO        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1416

             37.10.369    SysFreemem        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1416

             37.10.370    SysFreememSize         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1417

             37.10.371    SysGetFPCHeapStatus              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1417

             37.10.372    SysGetHeapStatus          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1417

             37.10.373    SysGetmem         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1417

             37.10.374    SysInitExceptions         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1417

             37.10.375    SysInitFPU        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1418

             37.10.376    SysInitStdIO      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1418

             37.10.377    SysMemSize        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1418

             37.10.378    SysReAllocMem          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1418

             37.10.379    SysResetFPU          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1418

             37.10.380    SysSetCtrlBreakHandler              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1419

             37.10.381    SysTryResizeMem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1419

             37.10.382    ThreadGetPriority           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1419

             37.10.383    ThreadSetPriority         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1419

             37.10.384    ThreadSwitch         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1420

             37.10.385    trunc    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1420

             37.10.386    Truncate      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1420

             37.10.387    TryEnterCriticalsection          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1421

             37.10.388    UCS4StringToUnicodeString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1421

             37.10.389    UCS4StringToWideString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1421

             37.10.390    Unassigned      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1422

             37.10.391    UnicodeCharLenToString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1422

             37.10.392    UnicodeCharLenToStrVar                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1422

             37.10.393    UnicodeCharToString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1422

             37.10.394    UnicodeCharToStrVar              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1423

             37.10.395    UnicodeStringToUCS4String               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1423

             37.10.396    UnicodeToUtf8          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1423

             37.10.397    UniqueString      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1424

             37.10.398    UnlockResource         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1424

             37.10.399    UnPack     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1424

             37.10.400    upCase     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1424

             37.10.401    UTF8Decode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1425

             37.10.402    UTF8Encode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1425

             37.10.403    Utf8ToAnsi        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1426



                                                                 81

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.10.404    Utf8ToUnicode          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1426

             37.10.405    Val   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1426

             37.10.406    VarArrayGet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1427

             37.10.407    VarArrayPut       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1427

             37.10.408    VarArrayRedim          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1428

             37.10.409    VarCast       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1428

             37.10.410    WaitForThreadTerminate              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1428

             37.10.411    WideCharLenToString              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1428

             37.10.412    WideCharLenToStrVar              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1429

             37.10.413    WideCharToString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1429

             37.10.414    WideCharToStrVar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1429

             37.10.415    WideStringToUCS4String                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1429

             37.10.416    Write    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1430

             37.10.417    WriteBarrier      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1430

             37.10.418    WriteLn       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1430

             37.10.419    WriteStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1431

    37.11    IDispatch     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1432

             37.11.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1432

             37.11.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1432

             37.11.3      IDispatch.GetTypeInfoCount              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1432

             37.11.4      IDispatch.GetTypeInfo            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1432

             37.11.5      IDispatch.GetIDsOfNames               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1432

             37.11.6      IDispatch.Invoke       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1432

    37.12    IEnumerable        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1433

             37.12.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1433

             37.12.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1433

             37.12.3      IEnumerable.GetEnumerator               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1433

    37.13    IEnumerator        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1433

             37.13.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1433

             37.13.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1434

             37.13.3      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1434

             37.13.4      IEnumerator.GetCurrent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1434

             37.13.5      IEnumerator.MoveNext             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1434

             37.13.6      IEnumerator.Reset           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1435

             37.13.7      IEnumerator.Current            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1435

    37.14    IInvokable       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1435

             37.14.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1435

    37.15    IUnknown         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1435

             37.15.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1435

             37.15.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1435



                                                                 82

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.15.3      IUnknown.QueryInterface               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1436

             37.15.4      IUnknown._AddRef            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1436

             37.15.5      IUnknown._Release           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1436

    37.16    TAggregatedObject            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1436

             37.16.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1436

             37.16.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1436

             37.16.3      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1436

             37.16.4      TAggregatedObject.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1437

             37.16.5      TAggregatedObject.Controller               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1437

    37.17    TContainedObject           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1437

             37.17.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1437

             37.17.2      Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1437

    37.18    TInterfacedObject          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1437

             37.18.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1437

             37.18.2      Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1438

             37.18.3      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1438

             37.18.4      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1438

             37.18.5      TInterfacedObject.AfterConstruction                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *438

             37.18.6      TInterfacedObject.BeforeDestruction                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *438

             37.18.7      TInterfacedObject.NewInstance                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1438

             37.18.8      TInterfacedObject.RefCount              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1439

    37.19    TObject       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1439

             37.19.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1439

             37.19.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1440

             37.19.3      TObject.Create         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1440

             37.19.4      TObject.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1441

             37.19.5      TObject.newinstance            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1441

             37.19.6      TObject.FreeInstance           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1441

             37.19.7      TObject.SafeCallException             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1441

             37.19.8      TObject.DefaultHandler              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1442

             37.19.9      TObject.Free         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1442

             37.19.10     TObject.InitInstance           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1442

             37.19.11     TObject.CleanupInstance             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1442

             37.19.12     TObject.ClassType           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1443

             37.19.13     TObject.ClassInfo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1443

             37.19.14     TObject.ClassName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1443

             37.19.15     TObject.ClassNameIs            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1443

             37.19.16     TObject.ClassParent            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1444

             37.19.17     TObject.InstanceSize           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1444

             37.19.18     TObject.InheritsFrom           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1444



                                                                 83

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             37.19.19     TObject.StringMessageTable              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1444

             37.19.20     TObject.MethodAddress               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1445

             37.19.21     TObject.MethodName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1445

             37.19.22     TObject.FieldAddress           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1445

             37.19.23     TObject.AfterConstruction             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1445

             37.19.24     TObject.BeforeDestruction             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1446

             37.19.25     TObject.DefaultHandlerStr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1446

             37.19.26     TObject.Dispatch          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1446

             37.19.27     TObject.DispatchStr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1446

             37.19.28     TObject.GetInterface           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1447

             37.19.29     TObject.GetInterfaceByStr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1447

             37.19.30     TObject.GetInterfaceWeak              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1447

             37.19.31     TObject.GetInterfaceEntry             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1448

             37.19.32     TObject.GetInterfaceEntryByStr                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1448

             37.19.33     TObject.GetInterfaceTable             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1448

             37.19.34     TObject.UnitName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1448

             37.19.35     TObject.Equals         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1449

             37.19.36     TObject.GetHashCode              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1449

             37.19.37     TObject.ToString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1449


38   Reference for unit 'sysutils'                                                                                    1450

    38.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1450

    38.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1450

    38.3     Localization support           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1450

    38.4     Miscellaneous conversion routines                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1451

    38.5     Date/time routines           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1451

    38.6     FileName handling routines               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1452

    38.7     File input/output routines             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1453

    38.8     PChar related functions           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1454

    38.9     Date and time formatting characters                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1455

    38.10    Formatting strings         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1456

    38.11    String functions        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1456

    38.12    Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1457

             38.12.1      Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1457

             38.12.2      Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1464

             38.12.3      Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1472

    38.13    Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1476

             38.13.1      AbandonSignalHandler             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1476

             38.13.2      Abort    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1476

             38.13.3      AddDisk       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1476



                                                                 84

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.13.4      AddTerminateProc            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1477

             38.13.5      AdjustLineBreaks          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1477

             38.13.6      AnsiCompareFileName              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1478

             38.13.7      AnsiCompareStr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1478

             38.13.8      AnsiCompareText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1479

             38.13.9      AnsiDequotedStr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1480

             38.13.10     AnsiExtractQuotedStr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1480

             38.13.11     AnsiLastChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1481

             38.13.12     AnsiLowerCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1482

             38.13.13     AnsiLowerCaseFileName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1482

             38.13.14     AnsiPos       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1483

             38.13.15     AnsiQuotedStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1483

             38.13.16     AnsiSameStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1483

             38.13.17     AnsiSameText         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1483

             38.13.18     AnsiStrComp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1484

             38.13.19     AnsiStrIComp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1484

             38.13.20     AnsiStrLastChar           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1485

             38.13.21     AnsiStrLComp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1486

             38.13.22     AnsiStrLIComp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1487

             38.13.23     AnsiStrLower         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1488

             38.13.24     AnsiStrPos      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1488

             38.13.25     AnsiStrRScan         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1489

             38.13.26     AnsiStrScan       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1489

             38.13.27     AnsiStrUpper         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1489

             38.13.28     AnsiUpperCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1490

             38.13.29     AnsiUpperCaseFileName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1490

             38.13.30     AppendStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1491

             38.13.31     ApplicationName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1491

             38.13.32     AssignStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1492

             38.13.33     BCDToInt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1492

             38.13.34     Beep     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1493

             38.13.35     BoolToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1493

             38.13.36     ByteToCharIndex           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1493

             38.13.37     ByteToCharLen          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1494

             38.13.38     ByteType        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1494

             38.13.39     CallTerminateProcs          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1494

             38.13.40     ChangeFileExt        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1494

             38.13.41     CharToByteLen          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1495

             38.13.42     CompareMem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1495

             38.13.43     CompareMemRange             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1495



                                                                 85

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.13.44     CompareStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1496

             38.13.45     CompareText          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1497

             38.13.46     ComposeDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1497

             38.13.47     ConcatPaths       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1498

             38.13.48     CreateDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1498

             38.13.49     CreateGUID        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1499

             38.13.50     CurrentYear       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1499

             38.13.51     CurrToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1500

             38.13.52     CurrToStrF        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1500

             38.13.53     Date     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1500

             38.13.54     DateTimeToFileDate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1501

             38.13.55     DateTimeToStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1501

             38.13.56     DateTimeToString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1502

             38.13.57     DateTimeToSystemTime                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1503

             38.13.58     DateTimeToTimeStamp                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1503

             38.13.59     DateToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1504

             38.13.60     DayOfWeek         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1504

             38.13.61     DecodeDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1505

             38.13.62     DecodeDateFully           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1505

             38.13.63     DecodeTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1506

             38.13.64     DeleteFile      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1506

             38.13.65     DirectoryExists        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1507

             38.13.66     DiskFree      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1507

             38.13.67     DiskSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1508

             38.13.68     DisposeStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1508

             38.13.69     DoDirSeparators        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1509

             38.13.70     EncodeDate        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1509

             38.13.71     EncodeTime        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1510

             38.13.72     ExceptAddr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1511

             38.13.73     ExceptFrameCount            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1511

             38.13.74     ExceptFrames         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1511

             38.13.75     ExceptionErrorMessage            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1512

             38.13.76     ExceptObject         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1512

             38.13.77     ExcludeLeadingPathDelimiter                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1512

             38.13.78     ExcludeTrailingBackslash            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1513

             38.13.79     ExcludeTrailingPathDelimiter               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1513

             38.13.80     ExecuteProcess         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1513

             38.13.81     ExeSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1514

             38.13.82     ExpandFileName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1514

             38.13.83     ExpandUNCFileName                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1515



                                                                 86

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.13.84     ExtractFileDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1515

             38.13.85     ExtractFileDrive       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1516

             38.13.86     ExtractFileExt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1516

             38.13.87     ExtractFileName           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1516

             38.13.88     ExtractFilePath        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1517

             38.13.89     ExtractRelativepath         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1517

             38.13.90     ExtractShortPathName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1518

             38.13.91     FileAge    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1518

             38.13.92     FileClose     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1518

             38.13.93     FileCreate      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1519

             38.13.94     FileDateToDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1520

             38.13.95     FileExists      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1520

             38.13.96     FileGetAttr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1521

             38.13.97     FileGetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1522

             38.13.98     FileIsReadOnly         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1523

             38.13.99     FileOpen      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1523

             38.13.100    FileRead      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1524

             38.13.101    FileSearch      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1524

             38.13.102    FileSeek      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1525

             38.13.103    FileSetAttr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1526

             38.13.104    FileSetDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1526

             38.13.105    FileTruncate      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1527

             38.13.106    FileWrite     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1527

             38.13.107    FindClose       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1527

             38.13.108    FindCmdLineSwitch              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1528

             38.13.109    FindFirst     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1528

             38.13.110    FindNext      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1529

             38.13.111    FloattoCurr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1530

             38.13.112    FloatToDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1530

             38.13.113    FloatToDecimal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1530

             38.13.114    FloatToStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1531

             38.13.115    FloatToStrF       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1532

             38.13.116    FloatToText       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1534

             38.13.117    FloatToTextFmt         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1535

             38.13.118    FmtStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1535

             38.13.119    ForceDirectories       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1536

             38.13.120    Format     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1536

             38.13.121    FormatBuf       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1543

             38.13.122    FormatCurr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1543

             38.13.123    FormatDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1544



                                                                 87

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.13.124    FormatFloat       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1544

             38.13.125    FreeAndNil      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1546

             38.13.126    GetAppConfigDir           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1546

             38.13.127    GetAppConfigFile          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1547

             38.13.128    GetCurrentDir        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1547

             38.13.129    GetDirs    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1548

             38.13.130    GetEnvironmentString             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1548

             38.13.131    GetEnvironmentVariable              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1549

             38.13.132    GetEnvironmentVariableCount                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1549

             38.13.133    GetFileHandle        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1549

             38.13.134    GetLastOSError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1550

             38.13.135    GetLocalTime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1550

             38.13.136    GetModuleName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1550

             38.13.137    GetTempDir        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1550

             38.13.138    GetTempFileName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1551

             38.13.139    GetUserDir        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1551

             38.13.140    GuidCase      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1551

             38.13.141    GUIDToString         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1552

             38.13.142    HookSignal      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1552

             38.13.143    IncAMonth       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1552

             38.13.144    IncludeLeadingPathDelimiter                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1553

             38.13.145    IncludeTrailingBackslash            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1553

             38.13.146    IncludeTrailingPathDelimiter               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1553

             38.13.147    IncMonth        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1554

             38.13.148    InquireSignal     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1554

             38.13.149    IntToHex      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1555

             38.13.150    IntToStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1555

             38.13.151    IsDelimiter     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1556

             38.13.152    IsEqualGUID          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1556

             38.13.153    IsLeapYear      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1556

             38.13.154    IsPathDelimiter        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1557

             38.13.155    IsValidIdent      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1557

             38.13.156    LastDelimiter        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1558

             38.13.157    LeftStr    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1558

             38.13.158    LoadStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1559

             38.13.159    LowerCase       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1559

             38.13.160    MSecsToTimeStamp               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1560

             38.13.161    NewStr     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1560

             38.13.162    Now      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1561

             38.13.163    OutOfMemoryError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1561



                                                                 88

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.13.164    QuotedStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1561

             38.13.165    RaiseLastOSError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1562

             38.13.166    RemoveDir       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1562

             38.13.167    RenameFile        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1562

             38.13.168    ReplaceDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1563

             38.13.169    ReplaceTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1563

             38.13.170    RightStr      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1563

             38.13.171    SafeLoadLibrary        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1564

             38.13.172    SameFileName         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1564

             38.13.173    SameText        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1565

             38.13.174    SetCurrentDir        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1565

             38.13.175    SetDirSeparators          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1565

             38.13.176    ShowException          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1566

             38.13.177    Sleep    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1566

             38.13.178    SScanf     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1566

             38.13.179    StrAlloc      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1567

             38.13.180    StrBufSize      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1567

             38.13.181    StrByteType       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1568

             38.13.182    strcat   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1568

             38.13.183    StrCharLength        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1569

             38.13.184    strcomp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1569

             38.13.185    strcopy    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1569

             38.13.186    StrDispose      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1570

             38.13.187    strecopy      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1570

             38.13.188    strend     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1571

             38.13.189    StrFmt     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1571

             38.13.190    stricomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1572

             38.13.191    StringReplace        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1573

             38.13.192    StringToGUID         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1573

             38.13.193    strlcat    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1573

             38.13.194    strlcomp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1574

             38.13.195    strlcopy   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1575

             38.13.196    strlen   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1575

             38.13.197    StrLFmt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1576

             38.13.198    strlicomp     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1576

             38.13.199    strlower   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1577

             38.13.200    strmove    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1577

             38.13.201    strnew     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1578

             38.13.202    StrNextChar       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1578

             38.13.203    StrPas     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1579



                                                                 89

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.13.204    StrPCopy        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1579

             38.13.205    StrPLCopy       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1579

             38.13.206    strpos   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1580

             38.13.207    strrscan   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1580

             38.13.208    strscan    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1580

             38.13.209    StrToBool       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1581

             38.13.210    StrToBoolDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1581

             38.13.211    StrToCurr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1581

             38.13.212    StrToCurrDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1582

             38.13.213    StrToDate       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1582

             38.13.214    StrToDateDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1583

             38.13.215    StrToDateTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1583

             38.13.216    StrToDateTimeDef            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1584

             38.13.217    StrToFloat      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1585

             38.13.218    StrToFloatDef        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1586

             38.13.219    StrToInt      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1586

             38.13.220    StrToInt64      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1587

             38.13.221    StrToInt64Def        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1587

             38.13.222    StrToIntDef       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1587

             38.13.223    StrToQWord        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1588

             38.13.224    StrToQWordDef          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1588

             38.13.225    StrToTime       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1588

             38.13.226    StrToTimeDef         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1589

             38.13.227    strupper      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1590

             38.13.228    Supports      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1590

             38.13.229    SysErrorMessage           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1591

             38.13.230    SystemTimeToDateTime                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1591

             38.13.231    TextToFloat       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1591

             38.13.232    Time     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1592

             38.13.233    TimeStampToDateTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1593

             38.13.234    TimeStampToMSecs               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1594

             38.13.235    TimeToStr       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1594

             38.13.236    Trim     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1594

             38.13.237    TrimLeft      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1595

             38.13.238    TrimRight       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1596

             38.13.239    TryEncodeDate          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1596

             38.13.240    TryEncodeTime          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1597

             38.13.241    TryFloatToCurr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1597

             38.13.242    TryStringToGUID           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1597

             38.13.243    TryStrToBool         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1598



                                                                 90

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.13.244    TryStrToCurr         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1598

             38.13.245    TryStrToDate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1598

             38.13.246    TryStrToDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1599

             38.13.247    TryStrToFloat        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1599

             38.13.248    TryStrToInt       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1600

             38.13.249    TryStrToInt64        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1600

             38.13.250    TryStrToQWord          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1600

             38.13.251    TryStrToTime         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1601

             38.13.252    UnhookSignal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1601

             38.13.253    UpperCase       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1601

             38.13.254    VendorName        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1602

             38.13.255    WideCompareStr            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1602

             38.13.256    WideCompareText             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1603

             38.13.257    WideFmtStr        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1603

             38.13.258    WideFormat        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1603

             38.13.259    WideFormatBuf          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1604

             38.13.260    WideLowerCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1604

             38.13.261    WideSameStr          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1604

             38.13.262    WideSameText           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1604

             38.13.263    WideUpperCase          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1605

             38.13.264    WrapText        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1605

    38.14    EAbort      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  160@

             38.14.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1605

    38.15    EAbstractError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1606

             38.15.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1606

    38.16    EAccessViolation           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1606

             38.16.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1606

    38.17    EAssertionFailed        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1606

             38.17.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1606

    38.18    EBusError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1606

             38.18.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1606

    38.19    EControlC        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1606

             38.19.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1606

    38.20    EConvertError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1606

             38.20.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1606

    38.21    EDivByZero         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1606

             38.21.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1606

    38.22    EExternal        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1607

             38.22.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1607

    38.23    EExternalException           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1607



                                                                 91

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.23.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1607

    38.24    EFormatError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1607

             38.24.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1607

    38.25    EHeapMemoryError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1607

             38.25.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1607

             38.25.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1607

             38.25.3      EHeapMemoryError.FreeInstance                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1607

    38.26    EInOutError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1608

             38.26.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1608

    38.27    EInterror     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1608

             38.27.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1608

    38.28    EIntfCastError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1608

             38.28.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1608

    38.29    EIntOverflow       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1608

             38.29.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1608

    38.30    EInvalidCast       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1608

             38.30.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1608

    38.31    EInvalidContainer          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1608

             38.31.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1608

    38.32    EInvalidInsert        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1609

             38.32.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1609

    38.33    EInvalidOp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1609

             38.33.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1609

    38.34    EInvalidPointer         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1609

             38.34.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1609

    38.35    EMathError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1609

             38.35.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1609

    38.36    ENoThreadSupport             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1609

             38.36.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1609

    38.37    ENotImplemented            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1609

             38.37.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1609

    38.38    ENoWideStringSupport              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1609

             38.38.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1609

    38.39    EOSError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1610

             38.39.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1610

    38.40    EOutOfMemory            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1610

             38.40.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1610

    38.41    EOverflow        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1610

             38.41.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1610

    38.42    EPackageError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1610



                                                                 92

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.42.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1610

    38.43    EPrivilege       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1610

             38.43.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1610

    38.44    EPropReadOnly           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1610

             38.44.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1610

    38.45    EPropWriteOnly          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1610

             38.45.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1610

    38.46    ERangeError        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1611

             38.46.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1611

    38.47    ESafecallException           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1611

             38.47.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1611

    38.48    EStackOverflow          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1611

             38.48.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1611

    38.49    EUnderflow       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1611

             38.49.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1611

    38.50    EVariantError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1611

             38.50.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1611

             38.50.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1611

             38.50.3      EVariantError.CreateCode              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1611

    38.51    Exception        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1612

             38.51.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1612

             38.51.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1612

             38.51.3      Property overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1612

             38.51.4      Exception.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1612

             38.51.5      Exception.CreateFmt            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1613

             38.51.6      Exception.CreateRes            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1613

             38.51.7      Exception.CreateResFmt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1613

             38.51.8      Exception.CreateHelp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1613

             38.51.9      Exception.CreateFmtHelp               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1614

             38.51.10     Exception.CreateResHelp             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1614

             38.51.11     Exception.CreateResFmtHelp                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1614

             38.51.12     Exception.HelpContext            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1614

             38.51.13     Exception.Message           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1615

    38.52    EZeroDivide        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1615

             38.52.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1615

    38.53    IReadWriteSync          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1615

             38.53.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1615

             38.53.2      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1615

             38.53.3      IReadWriteSync.BeginRead                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1615

             38.53.4      IReadWriteSync.EndRead                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1616



                                                                 93

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             38.53.5      IReadWriteSync.BeginWrite               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1616

             38.53.6      IReadWriteSync.EndWrite               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1616

    38.54    TMultiReadExclusiveWriteSynchronizer                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1616

             38.54.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1616

             38.54.2      Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1616

             38.54.3      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1617

             38.54.4      TMultiReadExclusiveWriteSynchronizer.Create                        .  .  .  .  .  .  .  .  .  .  .  1617

             38.54.5      TMultiReadExclusiveWriteSynchronizer.Destroy                       .  .  .  .  .  .  .  .  .  .  .  1617

             38.54.6      TMultiReadExclusiveWriteSynchronizer.Beginwrite                         .  .  .  .  .  .  .  .  .  1617

             38.54.7      TMultiReadExclusiveWriteSynchronizer.Endwrite                         .  .  .  .  .  .  .  .  .  .  1618

             38.54.8      TMultiReadExclusiveWriteSynchronizer.Beginread                          .  .  .  .  .  .  .  .  .  1618

             38.54.9      TMultiReadExclusiveWriteSynchronizer.Endread                          .  .  .  .  .  .  .  .  .  .  1618

    38.55    TSimpleRWSync           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1618

             38.55.1      Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1618

             38.55.2      Interfaces overview         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1619

             38.55.3      Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1619

             38.55.4      TSimpleRWSync.Create                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1619

             38.55.5      TSimpleRWSync.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1619

             38.55.6      TSimpleRWSync.Beginwrite                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1619

             38.55.7      TSimpleRWSync.Endwrite                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1620

             38.55.8      TSimpleRWSync.Beginread                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1620

             38.55.9      TSimpleRWSync.Endread                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  1620


39   Reference for unit 'types'                                                                                       1621

    39.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1621

    39.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1621

             39.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1621

             39.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1626

    39.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1632

             39.3.1       Bounds     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1632

             39.3.2       CenterPoint       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1632

             39.3.3       EqualRect       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1633

             39.3.4       InflateRect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1633

             39.3.5       IntersectRect        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1633

             39.3.6       IsRectEmpty       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1633

             39.3.7       OffsetRect      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1634

             39.3.8       Point    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1634

             39.3.9       PtInRect      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1634

             39.3.10      Rect     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1634

             39.3.11      Size  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1635



                                                                 94

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             39.3.12      UnionRect       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1635

    39.4     IClassFactory         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1635

             39.4.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1635

             39.4.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1635

             39.4.3       IClassFactory.CreateInstance            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 1635

             39.4.4       IClassFactory.LockServer            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1636

    39.5     ISequentialStream          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1636

             39.5.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1636

             39.5.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1636

             39.5.3       ISequentialStream.Read              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1636

             39.5.4       ISequentialStream.Write             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1636

    39.6     IStream     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  163@

             39.6.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1637

             39.6.2       Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1637

             39.6.3       IStream.Seek      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1637

             39.6.4       IStream.SetSize        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1637

             39.6.5       IStream.CopyTo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1637

             39.6.6       IStream.Commit         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1638

             39.6.7       IStream.Revert         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1638

             39.6.8       IStream.LockRegion          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1638

             39.6.9       IStream.UnlockRegion             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1638

             39.6.10      IStream.Stat      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1639

             39.6.11      IStream.Clone        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1639


40   Reference for unit 'typinfo'                                                                                     1640

    40.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1640

    40.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1640

    40.3     Auxiliary functions          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1640

    40.4     Getting or setting property values               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  1641

    40.5     Examining published property information                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *1641

    40.6     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1642

             40.6.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1642

             40.6.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1643

    40.7     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1649

             40.7.1       FindPropInfo         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1649

             40.7.2       GetEnumName            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1650

             40.7.3       GetEnumNameCount               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1651

             40.7.4       GetEnumProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1651

             40.7.5       GetEnumValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1652

             40.7.6       GetFloatProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1652



                                                                 95

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             40.7.7       GetInt64Prop         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1653

             40.7.8       GetInterfaceProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1654

             40.7.9       GetMethodProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1654

             40.7.10      GetObjectProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1656

             40.7.11      GetObjectPropClass             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1657

             40.7.12      GetOrdProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1658

             40.7.13      GetPropInfo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1659

             40.7.14      GetPropInfos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1659

             40.7.15      GetPropList       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1660

             40.7.16      GetPropValue         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1662

             40.7.17      GetRawInterfaceProp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1662

             40.7.18      GetSetProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1662

             40.7.19      GetStrProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1663

             40.7.20      GetTypeData          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1664

             40.7.21      GetUnicodeStrProp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1665

             40.7.22      GetVariantProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1665

             40.7.23      GetWideStrProp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1665

             40.7.24      IsPublishedProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1666

             40.7.25      IsStoredProp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1666

             40.7.26      PropIsType        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1667

             40.7.27      PropType        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1668

             40.7.28      SetEnumProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1669

             40.7.29      SetFloatProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1669

             40.7.30      SetInt64Prop      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1670

             40.7.31      SetInterfaceProp       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1670

             40.7.32      SetMethodProp          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1671

             40.7.33      SetObjectProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1671

             40.7.34      SetOrdProp        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1672

             40.7.35      SetPropValue         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1672

             40.7.36      SetRawInterfaceProp            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1672

             40.7.37      SetSetProp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1673

             40.7.38      SetStrProp      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1673

             40.7.39      SetToString       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1674

             40.7.40      SetUnicodeStrProp           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1675

             40.7.41      SetVariantProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1675

             40.7.42      SetWideStrProp         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1675

             40.7.43      StringToSet       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1676

    40.8     EPropertyConvertError             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1676

             40.8.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1676

    40.9     EPropertyError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1676



                                                                 96

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             40.9.1       Description     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1676


41   Reference for unit 'Unix'                                                                                        1677

    41.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1677

    41.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1677

             41.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1677

             41.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1684

             41.2.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1693

    41.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1693

             41.3.1       AssignPipe      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1693

             41.3.2       AssignStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1694

             41.3.3       FpExecL       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1695

             41.3.4       FpExecLE        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1696

             41.3.5       FpExecLP        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1697

             41.3.6       FpExecLPE         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1698

             41.3.7       FpExecV       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1698

             41.3.8       FpExecVP        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1699

             41.3.9       FpExecVPE         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1700

             41.3.10      fpFlock    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1701

             41.3.11      fpfStatFS     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1701

             41.3.12      fpfsync    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1702

             41.3.13      fpgettimeofday       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1702

             41.3.14      fpStatFS      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1702

             41.3.15      fpSystem      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1703

             41.3.16      FSearch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1703

             41.3.17      fStatFS    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1704

             41.3.18      fsync    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1705

             41.3.19      GetDomainName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1706

             41.3.20      GetHostName          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1706

             41.3.21      GetLocalTimezone            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1707

             41.3.22      GetTimezoneFile           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1707

             41.3.23      PClose     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1707

             41.3.24      POpen      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1708

             41.3.25      ReadTimezoneFile          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1709

             41.3.26      SeekDir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1709

             41.3.27      SelectText      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1709

             41.3.28      Shell    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1710

             41.3.29      SigRaise      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1710

             41.3.30      StatFS     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1711

             41.3.31      TellDir    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1712



                                                                 97

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             41.3.32      WaitProcess       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1713

             41.3.33      WIFSTOPPED             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1713

             41.3.34      W_EXITCODE             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1713

             41.3.35      W_STOPCODE             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1714


42   Reference for unit 'unixtype'                                                                                    1715

    42.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1715

    42.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1715

             42.2.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1715

             42.2.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1716


43   Reference for unit 'unixutil'                                                                                    1729

    43.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1729

    43.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1729

             43.2.1       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1729

             43.2.2       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1729

    43.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1730

             43.3.1       ArrayStringToPPchar            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1730

             43.3.2       Basename        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1730

             43.3.3       Dirname       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1731

             43.3.4       EpochToLocal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1731

             43.3.5       FNMatch       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1732

             43.3.6       FSplit     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1733

             43.3.7       GetFS      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1733

             43.3.8       GregorianToJulian           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1734

             43.3.9       JulianToGregorian           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1734

             43.3.10      LocalToEpoch         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1734

             43.3.11      StringToPPChar         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1735


44   Reference for unit 'video'                                                                                       1737

    44.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1737

    44.2     Examples utility unit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1738

    44.3     Writing a custom video driver               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1739

    44.4     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1742

             44.4.1       Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1742

             44.4.2       Types    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1746

             44.4.3       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1748

    44.5     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1749

             44.5.1       ClearScreen       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1749

             44.5.2       DefaultErrorHandler            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1750

             44.5.3       DoneVideo       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1750



                                                                 98

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             44.5.4       GetCapabilities        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1751

             44.5.5       GetCursorType          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1752

             44.5.6       GetLockScreenCount             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1753

             44.5.7       GetVideoDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1753

             44.5.8       GetVideoMode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1754

             44.5.9       GetVideoModeCount              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1754

             44.5.10      GetVideoModeData            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1756

             44.5.11      InitVideo     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1756

             44.5.12      LockScreenUpdate            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1756

             44.5.13      SetCursorPos         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1757

             44.5.14      SetCursorType          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1758

             44.5.15      SetVideoDriver         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1758

             44.5.16      SetVideoMode         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1758

             44.5.17      UnlockScreenUpdate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1759

             44.5.18      UpdateScreen         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1759


45   Reference for unit 'wincrt'                                                                                      1761

    45.1     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1761

    45.2     Constants, types and variables              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  1761

             45.2.1       Variables     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1761

    45.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1761

             45.3.1       delay    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1761

             45.3.2       keypressed      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1761

             45.3.3       nosound       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1762

             45.3.4       readkey    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1762

             45.3.5       sound    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  1762

             45.3.6       textmode      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1762


46   Reference for unit 'x86'                                                                                         1763

    46.1     Used units       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1763

    46.2     Overview      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  1763

    46.3     Procedures and functions            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  1763

             46.3.1       fpIOperm        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1763

             46.3.2       fpIoPL     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1764

             46.3.3       ReadPort      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  1764

             46.3.4       ReadPortB       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1764

             46.3.5       ReadPortL       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1765

             46.3.6       ReadPortW         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1765

             46.3.7       WritePort       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1765

             46.3.8       WritePortB        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1766

             46.3.9       WritePortl      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  1766



                                                                 99

____________________________________________________________________________________________________________________CONTENTS_______*
 *___



             46.3.10      WritePortW        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  1766



                                                                 100

____________________________________________________________________________________________________________________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.



                                                                 101




Chapter   1



Reference   for   unit   'BaseUnix'



1.1         Used  units



                                   Table 1.1:  Used units by unit 'BaseUnix'


                                                  __Name____________Page_____
                                                    System          1230
                                                    unixtype        1715



1.2         Overview


The BaseUnix unit was implemented by Marco Van de Voort.  It contains basic unix function-
ality.  It supersedes the Linux unit of version 1.0.X of the compiler, but does not implement
all functionality of the linux unit.

People that have code which heavily uses the old Linux unit, must fetch this unit from the
sources or older distributions and manually compile it.  In 2.0.x and 2.2.x releases this unit
was included as oldlinux, but starting with 2.4.0 this unit has been removed \ from the release
distribution.

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



                                                             102

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  Argument list too long


ESysEACCES  =  13


System error:  Permission denied


ESysEADDRINUSE  =  98


System error:  Address already in use


ESysEADDRNOTAVAIL  =  99


System error:  Cannot assign requested address


ESysEADV  =  68


System error:  Advertise error


ESysEAFNOSUPPORT  =  97


System error:  Address family not supported by protocol


ESysEAGAIN  =  11


System error:  Try again


ESysEALREADY  =  114


System error:  Operation already in progress


ESysEBADE  =  52


System error:  Invalid exchange


ESysEBADF  =  9


System error:  Bad file number


ESysEBADFD  =  77


System error:  File descriptor in bad state


ESysEBADMSG  =  74


System error:  Not a data message


ESysEBADR  =  53


System error:  Invalid request descriptor


ESysEBADRQC  =  56



                                                                 103

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  Invalid request code


ESysEBADSLT  =  57


System error:  Invalid slot


ESysEBFONT  =  59


System error:  Bad font file format


ESysEBUSY  =  16


System error:  Device or resource busy


ESysECHILD  =  10


System error:  No child processes


ESysECHRNG  =  44


System error:  Channel number out of range


ESysECOMM  =  70


System error:  Communication error on send


ESysECONNABORTED  =  103


System error:  Software caused connection abort


ESysECONNREFUSED  =  111


System error:  Connection refused


ESysECONNRESET  =  104


System error:  Connection reset by peer


ESysEDEADLK  =  35


System error:  Resource deadlock would occur


ESysEDEADLOCK  =  58


System error:  File locking deadlock error


ESysEDESTADDRREQ  =  89


System error:  Destination address required


ESysEDOM  =  33



                                                                 104

________________________________________________________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



                                                                 105

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  I/O error


ESysEISCONN  =  106


System error:  Transport endpoint is already connected


ESysEISDIR  =  21


System error:  Is a directory


ESysEISNAM  =  120


System error:  Is a named type file


ESysEL2HLT  =  51


System error:  Level 2 halted


ESysEL2NSYNC  =  45


System error:  Level 2 not synchronized


ESysEL3HLT  =  46


System error:  Level 3 halted


ESysEL3RST  =  47


System error:  Level 3 reset


ESysELIBACC  =  79


System error:  Can not access a needed shared library


ESysELIBBAD  =  80


System error:  Accessing a corrupted shared library


ESysELIBEXEC  =  83


System error:  Cannot exec a shared library directly


ESysELIBMAX  =  82


System error:  Attempting to link in too many shared libraries


ESysELIBSCN  =  81


System error:  .lib section in a.out corrupted


ESysELNRNG  =  48



                                                                 106

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  Link number out of range


ESysELOOP  =  40


System error:  Too many symbolic links encountered


ESysEMFILE  =  24


System error:  Too many open files


ESysEMLINK  =  31


System error:  Too many links


ESysEMSGSIZE  =  90


System error:  Message too long


ESysEMULTIHOP  =  72


System error:  Multihop attempted


ESysENAMETOOLONG  =  36


System error:  File name too long


ESysENAVAIL  =  119


System error:  No XENIX semaphores available


ESysENETDOWN  =  100


System error:  Network is down


ESysENETRESET  =  102


System error:  Network dropped connection because of reset


ESysENETUNREACH  =  101


System error:  Network is unreachable


ESysENFILE  =  23


System error:  File table overflow


ESysENOANO  =  55


System error:  No anode


ESysENOBUFS  =  105



                                                                 107

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  No buffer space available


ESysENOCSI  =  50


System error:  No CSI structure available


ESysENODATA  =  61


System error:  No data available


ESysENODEV  =  19


System error:  No such device


ESysENOENT  =  2


System error:  No such file or directory


ESysENOEXEC  =  8


System error:  Exec format error


ESysENOLCK  =  37


System error:  No record locks available


ESysENOLINK  =  67


System error:  Link has been severed


ESysENOMEM  =  12


System error:  Out of memory


ESysENOMSG  =  42


System error:  No message of desired type


ESysENONET  =  64


System error:  Machine is not on the network


ESysENOPKG  =  65


System error:  Package not installed


ESysENOPROTOOPT  =  92


System error:  Protocol not available


ESysENOSPC  =  28



                                                                 108

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  No space left on device


ESysENOSR  =  63


System error:  Out of streams resources


ESysENOSTR  =  60


System error:  Device not a stream


ESysENOSYS  =  38


System error:  Function not implemented


ESysENOTBLK  =  15


System error:  Block device required


ESysENOTCONN  =  107


System error:  Transport endpoint is not connected


ESysENOTDIR  =  20


System error:  Not a directory


ESysENOTEMPTY  =  39


System error:  Directory not empty


ESysENOTNAM  =  118


System error:  Not a XENIX named type file


ESysENOTSOCK  =  88


System error:  Socket operation on non-socket


ESysENOTTY  =  25


System error:  Not a typewriter


ESysENOTUNIQ  =  76


System error:  Name not unique on network


ESysENXIO  =  6


System error:  No such device or address


ESysEOPNOTSUPP  =  95



                                                                 109

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  Operation not supported on transport endpoint


ESysEOVERFLOW  =  75


System error:  Value too large for defined data type


ESysEPERM  =  1


System error:  Operation not permitted.


ESysEPFNOSUPPORT  =  96


System error:  Protocol family not supported


ESysEPIPE  =  32


System error:  Broken pipe


ESysEPROTO  =  71


System error:  Protocol error


ESysEPROTONOSUPPORT  =  93


System error:  Protocol not supported


ESysEPROTOTYPE  =  91


System error:  Protocol wrong type for socket


ESysERANGE  =  34


System error:  Math result not representable


ESysEREMCHG  =  78


System error:  Remote address changed


ESysEREMOTE  =  66


System error:  Object is remote


ESysEREMOTEIO  =  121


System error:  Remote I/O error


ESysERESTART  =  85


System error:  Interrupted system call should be restarted


ESysEROFS  =  30



                                                                 110

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  Read-only file system


ESysESHUTDOWN  =  108


System error:  Cannot send after transport endpoint shutdown


ESysESOCKTNOSUPPORT  =  94


System error:  Socket type not supported


ESysESPIPE  =  29


System error:  Illegal seek


ESysESRCH  =  3


System error:  No such process


ESysESRMNT  =  69


System error:  Srmount error


ESysESTALE  =  116


System error:  Stale NFS file handle


ESysESTRPIPE  =  86


System error:  Streams pipe error


ESysETIME  =  62


System error:  Timer expired


ESysETIMEDOUT  =  110


System error:  Connection timed out


ESysETOOMANYREFS  =  109


System error:  Too many references:  cannot splice


ESysETXTBSY  =  26


System error:  Text (code segment) file busy


ESysEUCLEAN  =  117


System error:  Structure needs cleaning


ESysEUNATCH  =  49



                                                                 111

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



System error:  Protocol driver not attached


ESysEUSERS  =  87


System error:  Too many users


ESysEWOULDBLOCK  =  ESysEAGAIN


System error:  Operation would block


ESysEXDEV  =  18


System error:  Cross-device link


ESysEXFULL  =  54


System error:  Exchange full


FD_MAXFDSET  =  1024


Maximum elements in a TFDSet (137  ) 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



                                                                 112

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Value signalling integer overflow in case of SIGFPE signal


F_GetFd  =  1


fpFCntl (151  ) command:  Get close-on-exec flag


F_GetFl  =  3


fpFCntl (151  ) command:  Get filedescriptor flags


F_GetLk  =  5


fpFCntl (151  ) command:  Get lock


F_GetOwn  =  9


fpFCntl (151  ) command:  get owner of filedescriptor events


F_OK  =  0


fpAccess (142  ) call test:  file exists.


F_SetFd  =  2


fpFCntl (151  ) command:  Set close-on-exec flag


F_SetFl  =  4


fpFCntl (151  ) command:  Set filedescriptor flags


F_SetLk  =  6


fpFCntl (151  ) command:  Set lock


F_SetLkW  =  7


fpFCntl (151  ) command:  Test lock


F_SetOwn  =  8


fpFCntl (151  ) 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



                                                                 113

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Anonymous memory mapping (data private to application)


MAP_ANONYMOUS  =  $20


FpMMap (165  ) map type:  Don't use a file


MAP_FAILED  =  (-1)


Memory mapping failed error code


MAP_FIXED  =  $10


FpMMap (165  ) map type:  Interpret addr exactly


MAP_PRIVATE  =  $2


FpMMap (165  ) map type:  Changes are private


MAP_SHARED  =  $1


FpMMap (165  ) map type:  Share changes


MAP_TYPE  =  $f


FpMMap (165  ) map type:  Bitmask for type of mapping


NAME_MAX  =  UnixType  .  NAME_MAX


Maximum filename length.


O_APPEND  =  $400


fpOpen (168  ) file open mode:  Append to file


O_CREAT  =  $40


fpOpen (168  ) file open mode:  Create if file does not yet exist.


O_DIRECT  =  $4000


fpOpen (168  ) file open mode:  Minimize caching effects


O_DIRECTORY  =  $10000


fpOpen (168  ) file open mode:  File must be directory.


O_EXCL  =  $80


fpOpen (168  ) file open mode:  Open exclusively


O_NDELAY  =  O_NONBLOCK



                                                                 114

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



fpOpen (168  ) file open mode:  Alias for O_NonBlock (115  )


O_NOCTTY  =  $100


fpOpen (168  ) file open mode:  No TTY control.


O_NOFOLLOW  =  $20000


fpOpen (168  ) file open mode:  Fail if file is symbolic link.


O_NONBLOCK  =  $800


fpOpen (168  ) file open mode:  Open in non-blocking mode


O_RDONLY  =  0


fpOpen (168  ) file open mode:  Read only


O_RDWR  =  2


fpOpen (168  ) file open mode:  Read/Write


O_SYNC  =  $1000


fpOpen (168  ) file open mode:  Write to disc at once


O_TRUNC  =  $200


fpOpen (168  ) file open mode:  Truncate file to length 0


O_WRONLY  =  1


fpOpen (168  ) 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


Data is available for reading


POLLNVAL  =  $0020



                                                                 115

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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 (1715   )


PRIO_PROCESS  =  UnixType  .  PRIO_PROCESS


Easy access alias for unixtype.PRIO_PROCESS (1715   )


PRIO_USER  =  UnixType  .  PRIO_USER


Easy access alias for unixtype.PRIO_USER (1715   )


PROT_EXEC  =  $4


FpMMap (165  ) memory access:  page can be executed


PROT_NONE  =  $0


FpMMap (165  ) memory access:  page can not be accessed


PROT_READ  =  $1


FpMMap (165  ) memory access:  page can be read


PROT_WRITE  =  $2



                                                                 116

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



FpMMap (165  ) 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


fpAccess (142  ) call test:  read allowed


SA_INTERRUPT  =  $20000000



                                                                 117

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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  (180  )  to  indicate  the  signal  handler  must  be  called
on  an  alternate  signal  stack  provided  by  fpsigaltstack  (1230   ).  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 (162  ) option:  Set position relative to current position.


SEEK_END  =  2


fpLSeek (162  ) option:  Set position relative to end of file.



                                                                 118

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



SEEK_SET  =  0


fpLSeek (162  ) 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)


SIGKILL  =  9


Signal:  KILL (unblockable)



                                                                 119

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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)


SIGTTOU  =  22


Signal:  TTOU (Terminal output, background)



                                                                 120

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


SIG_MAXSIG  =  UnixType  .  SIG_MAXSIG


Maximum system signal number.



                                                                 121

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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 (136  ) record) mode:  Block device


S_IFCHR  =  8192


File (#rtl.baseunix.stat (136  ) record) mode:  Character device


S_IFDIR  =  16384


File (#rtl.baseunix.stat (136  ) record) mode:  Directory


S_IFIFO  =  4096


File (#rtl.baseunix.stat (136  ) record) mode:  FIFO


S_IFLNK  =  40960


File (#rtl.baseunix.stat (136  ) record) mode:  Link


S_IFMT  =  61440


File (#rtl.baseunix.stat (136  ) record) mode:  File type bit mask


S_IFREG  =  32768


File (#rtl.baseunix.stat (136  ) record) mode:  Regular file


S_IFSOCK  =  49152


File (#rtl.baseunix.stat (136  ) record) mode:  Socket


S_IRGRP  =  %0000100000


Mode flag:  Read by group.



                                                                 122

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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 (141  ) domain name.


UTSNAME_LENGTH  =  SYS_NMLN


Max length of utsname (141  ) system name, release, version, machine.



                                                                 123

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



UTSNAME_NODENAME_LENGTH  =  UTSNAME_LENGTH


Max length of utsname (141  ) node name.


WNOHANG  =  1


#rtl.baseunix.fpWaitpid (194  ) option:  Do not wait for processes to terminate.


wordsinfdset  =  FD_MAXFDSET  div  BITSINWORD


Number of words in a TFDSet (137  ) array


wordsinsigset  =  SIG_MAXSIG  div  BITSINWORD


Number of words in a signal set.


WUNTRACED  =  2


#rtl.baseunix.fpWaitpid (194  ) option:  Also report children wich were stopped but not yet
reported


W_OK  =  2


fpAccess (142  ) call test:  write allowed


X_OK  =  1


fpAccess (142  ) call test:  execute allowed


_STAT_VER  =  _STAT_VER_LINUX


Stat version number


_STAT_VER_KERNEL  =  1


Current version of stat record


_STAT_VER_LINUX  =  3


Version of linux stat record


_STAT_VER_LINUX_OLD  =  1


Old kernel definition of stat


_STAT_VER_SVR4  =  2


SVR 4 definition of stat



                                                                 124

________________________________________________________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 (1717   )


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



                                                                 125

________________________________________________________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 (125  ).


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 (126  ).


csshort  =  UnixType.csshort


Short signed integer type


cuchar  =  UnixType.cuchar


Alias for #rtl.UnixType.cuchar (1718   )


cuint  =  UnixType.cuint



                                                                 126

________________________________________________________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 (1719   )


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 (170  ) and fpReadDir (174  ) calls



                                                                 127

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Dirent  =  packed  record
   d_fileno  :  ino64_t;
   d_off  :  off_t;
   d_reclen  :  cushort;
   d_type  :  cuchar;
   d_name  :  Array[0..(255+1)-1]  of  Char;
end



Record used in the fpReadDir (174  ) 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 (151  ) lock call.


FLock64  =  record
   l_type  :  cshort;
   l_whence  :  cshort;
   l_start  :  kernel_loff_t;
   l_len  :  kernel_loff_t;
   l_pid  :  pid_t;
end



FLock64 is the record used in the FpFcntl (151  ) file locking call.  It is the same as the FLock
(128  ) type, only contains 64-bit offsets.


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 (175  ) 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.



                                                                 128

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


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 (136  ) type.


PBlkSize  =  ^Blksize_t


Pointer to TBlkSize (136  ) type.


pcbool  =  UnixType.pcbool


Pointer to boolean type cbool (125  )


pcchar  =  UnixType.pcchar


Alias for #rtl.UnixType.pcchar (1720   )


pcdouble  =  UnixType.pcdouble


Pointer to cdouble (125  ) type.


pcfloat  =  UnixType.pcfloat


Pointer to cfloat (125  ) type.



                                                                 129

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



pcint  =  UnixType.pcint


Pointer to cInt (125  ) 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 (136  ) type.


pclong  =  UnixType.pclong


Pointer to cLong (126  ) type.


pclonglong  =  UnixType.pclonglong


Pointer to longlong type.


pcschar  =  UnixType.pcschar


Pointer to character type cschar (126  ).


pcshort  =  UnixType.pcshort


Pointer to cShort (126  ) type.


pcsigned  =  UnixType.pcsigned


Pointer to signed integer type csigned (126  ).


pcsint  =  UnixType.pcsint


Pointer to signed integer type csint (126  )


pcsize_t  =  UnixType.psize_t


Pointer to csize_t



                                                                 130

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



pcslong  =  UnixType.pcslong


Pointer ot the signed long cslong (126  )


pcslonglong  =  UnixType.pcslonglong


Pointer to Signed longlong type cslonglong (126  )


pcsshort  =  UnixType.pcsshort


Pointer to short signed integer type csshort (126  )


pcuchar  =  UnixType.pcuchar


Alias for #rtl.UnixType.pcuchar (1721   )


pcuint  =  UnixType.pcuint


Pointer to cUInt (127  ) 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 (127  ) type.


pculonglong  =  UnixType.pculonglong


Unsigned longlong type


pcunsigned  =  UnixType.pcunsigned


Alias for #rtl.unixtype.pcunsigned (1722   )


pcushort  =  UnixType.pcushort


Pointer to cuShort (127  ) type.



                                                                 131

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



pDev  =  UnixType.pDev


Pointer to TDev (136  ) type.


pDir  =  ^Dir


Pointer to TDir (136  ) record


pDirent  =  ^Dirent


Pointer to TDirent (136  ) record.


pFDSet  =  ^TFDSet


Pointer to TFDSet (137  ) type.


pFilDes  =  ^TFilDes


Pointer to TFilDes (137  ) type.


pfpstate  =  ^tfpstate


Pointer to tfpstate (137  ) record.


pGid  =  UnixType.pGid


Pointer to TGid (137  ) type.


pGrpArr  =  ^TGrpArr


Pointer to TGrpArr (137  ) array.


pid_t  =  UnixType.pid_t


Process ID type.


pIno  =  UnixType.pIno


Pointer to TIno (138  ) type.


piovec  =  ^tiovec


pointer to a iovec (128  ) record


pMode  =  UnixType.pMode


Pointer to TMode (138  ) type.


pnLink  =  UnixType.pnLink


Pointer to TnLink (138  ) type.



                                                                 132

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



pOff  =  UnixType.pOff


Pointer to TOff (138  ) type.


pollfd  =  record
   fd  :  cint;
   events  :  cshort;
   revents  :  cshort;
end



pollfd is used in the fpPoll (172  ) call to describe the various actions.


pPid  =  UnixType.pPid


Pointer to TPid (138  ) type.


ppollfd  =  ^pollfd


Pointer to tpollfd.


PRLimit  =  ^TRLimit


Pointer to TRLimit (139  ) record


psigactionrec  =  ^sigactionrec


Pointer to SigActionRec (135  ) record type.


PSigContext  =  ^TSigContext


Pointer to #rtl.baseunix.TSigContext (139  ) record type.


psiginfo  =  ^tsiginfo


Pointer to #rtl.baseunix.TSigInfo (140  ) record type.


psigset  =  ^tsigset


Pointer to SigSet (136  ) type.


pSize  =  UnixType.pSize


Pointer to TSize (140  ) type.


pSize_t  =  UnixType.pSize_t


Pointer to Size_t


pSocklen  =  UnixType.pSocklen



                                                                 133

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Pointer to TSockLen (140  ) type.


psSize  =  UnixType.psSize


Pointer to TsSize (140  ) type


PStat  =  ^Stat


Pointer to TStat (140  ) type.


pstatfs  =  UnixType.PStatFs


This is an alias for the type defined in the #rtl.ctypes (438  ) 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 (140  ) type.


ptimespec  =  UnixType.ptimespec


Pointer to timespec (137  ) type.


ptimeval  =  UnixType.ptimeval


Pointer to timeval (137  ) type.


ptimezone  =  ^timezone


Pointer to TimeZone (138  ) record.


ptime_t  =  UnixType.ptime_t


Pointer to time_t (138  ) type.


PTms  =  ^tms


Pointer to TTms (141  ) type.


Pucontext  =  ^Tucontext



                                                                 134

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Pointer to TUContext (141  ) type.


pUid  =  UnixType.pUid


Pointer to TUid (141  ) type.


pUtimBuf  =  ^UTimBuf


Pointer to TUTimBuf (141  ) type.


PUtsName  =  ^TUtsName


Pointer to TUtsName (141  ) type.


rlim_t  =  culong


rlim_t is used as the type for the various fields in the TRLimit (139  ) 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)  of  object


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 (180  ) call.


signalhandler  =  signalhandler_t


Simple signal handler prototype


signalhandler_t  =  procedure(signal:  LongInt)  of  object


Standard signal handler prototype


sigrestorerhandler  =  sigrestorerhandler_t


Alias for sigrestorerhandler_t (136  ) type.


sigrestorerhandler_t  =  procedure  of  object



                                                                 135

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



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


Size specification type.


socklen_t  =  UnixType.socklen_t


Socket address length type.


ssize_t  =  UnixType.ssize_t


Small size type.


Stat  =  packed  record
end



Record describing an inode (file) in the FPFstat (153  ) call.


TBlkCnt  =  Blkcnt_t


Alias for Blkcnt_t (125  ) type.


TBlkSize  =  Blksize_t


Alias for blksize_t (125  ) type.


TClock  =  UnixType.TClock


Alias for clock_t (126  ) type.


TDev  =  UnixType.TDev


Alias for dev_t (127  ) type.


TDir  =  Dir


Alias for Dir (127  ) type.


TDirent  =  Dirent


Alias for Dirent (128  ) type.



                                                                 136

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



TFDSet  =  Array[0..(FD_MAXFDSETdivBITSINWORD)-1]  of  culong


File descriptor set for fpSelect (177  ) call.


TFilDes  =  Array[0..1]  of  cint


Array of file descriptors as used in fpPipe (171  ) 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;
   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 (128  ) type.


TGrpArr  =  Array[0..0]  of  TGid


Array of gid_t (128  ) IDs


timespec  =  UnixType.timespec


Short time specification type.


timeval  =  UnixType.timeval


Time specification type.


timezone  =  packed  record
   tz_minuteswest  :  cint;
   tz_dsttime  :  cint;
end



                                                                 137

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



Record describing a timezone


time_t  =  UnixType.time_t


Time span type


TIno  =  UnixType.TIno


Alias for ino_t (128  ) type.


TIOCtlRequest  =  UnixType.TIOCtlRequest


Easy access alias for unixtype.TIOCtlRequest (1727   )


tiovec  =  iovec


Alias for the iovec (128  ) record type.


TMode  =  UnixType.TMode


Alias for mode_t (129  ) type.


tms  =  packed  record
   tms_utime  :  clock_t;
   tms_stime  :  clock_t;
   tms_cutime  :  clock_t;
   tms_cstime  :  clock_t;
end



Record containing timings for fpTimes (191  ) call.


TnLink  =  UnixType.TnLink


Alias for nlink_t (129  ) type.


TOff  =  UnixType.TOff


Alias for off_t (129  ) type.


TPid  =  UnixType.TPid


Alias for pid_t (132  ) type.


tpollfd  =  pollfd


Alias for pollfd type


TRLimit  =  record
   rlim_cur  :  rlim_t;
   rlim_max  :  rlim_t;
end



                                                                 138

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



TRLimit is the structure used by the kernel to return resource limit information in.


tsigactionhandler  =  sigactionhandler_t


Alias for sigactionhandler_t (135  ) type.


tsigaltstack  =  record
   ss_sp  :  pointer;
   ss_flags  :  LongInt;
   ss_size  :  LongInt;
end



Provide the location of an alternate signal handler stack.


TSigContext  =  record
   gs  :  Word;
   __gsh  :  Word;
   fs  :  Word;
   __fsh  :  Word;
   es  :  Word;
   __esh  :  Word;
   ds  :  Word;
   __dsh  :  Word;
   edi  :  Cardinal;
   esi  :  Cardinal;
   ebp  :  Cardinal;
   esp  :  Cardinal;
   ebx  :  Cardinal;
   edx  :  Cardinal;
   ecx  :  Cardinal;
   eax  :  Cardinal;
   trapno  :  Cardinal;
   err  :  Cardinal;
   eip  :  Cardinal;
   cs  :  Word;
   __csh  :  Word;
   eflags  :  Cardinal;
   esp_at_signal  :  Cardinal;
   ss  :  Word;
   __ssh  :  Word;
   fpstate  :  pfpstate;
   oldmask  :  Cardinal;
   cr2  :  Cardinal;
end



This type is CPU dependent.  Cross-platform code should not use the contents of this record.


tsiginfo  =  record
   si_signo  :  LongInt;
   si_errno  :  LongInt;
   si_code  :  LongInt;



                                                                 139

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



   _sifields  :  record
   end;
end



This type describes the signal that occurred.


tsignalhandler  =  signalhandler_t


Alias for signalhandler_t (135  ) type.


tsigrestorerhandler  =  sigrestorerhandler_t


Alias for sigrestorerhandler_t (136  ) type.


tsigset  =  sigset_t


Alias for SigSet (136  ) type.


TSize  =  UnixType.TSize


Alias for size_t (136  ) type


TSocklen  =  UnixType.TSocklen


Alias for socklen_t (136  ) type.


TsSize  =  UnixType.TsSize


Alias for ssize_t (136  ) type


TStat  =  Stat


Alias for Stat (136  ) type.


tstatfs  =  UnixType.TStatFs


Record describing a file system in the baseunix.fpstatfs (1230   ) call.


TTime  =  UnixType.TTime


Alias for TTime (140  ) type.


Ttimespec  =  UnixType.Ttimespec


Alias for TimeSpec (137  ) type.


TTimeVal  =  UnixType.TTimeVal


Alias for timeval (137  ) type.



                                                                 140

________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________________________*
 *___



TTimeZone  =  timezone


Alias for TimeZone (138  ) record.


TTms  =  tms


Alias for Tms (138  ) 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 (141  ) type.


TUtimBuf  =  UTimBuf


Alias for UtimBuf (141  ) type.


TUtsName  =  UtsName


Alias for UtsName (141  ) type.


uid_t  =  UnixType.uid_t


User ID type


UTimBuf  =  record
   actime  :  time_t;
   modtime  :  time_t;
end



Record used in fpUtime (193  ) to set file access and modificaton times.


UtsName  =  record
   Sysname  :  Array[0..UTSNAME_LENGTH-1]  of  Char;
   Nodename  :  Array[0..UTSNAME_NODENAME_LENGTH-1]  of  Char;
   Release  :  Array[0..UTSNAME_LENGTH-1]  of  Char;
   Version  :  Array[0..UTSNAME_LENGTH-1]  of  Char;
   Machine  :  Array[0..UTSNAME_LENGTH-1]  of  Char;
   Domain  :  Array[0..UTSNAME_DOMAIN_LENGTH-1]  of  Char;
end



The  elements  of  this  record  are  null-terminated  C  style  strings,  you  cannot  access  them
directly.  Note that the Domain field is a GNU extension,  and may not be available on all
platforms.



                                                                 141

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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
                (149  ) and friends.

       Errors:   If no more memory is available, a heap error may occur.

    See also:    fpExecv (149  ), FreeShellArgV (195  )



                1.4.2        FpAccess

    Synopsis:    Check file access

Declaration:     function  FpAccess(pathname:  PChar;aMode:  cint)  :  cint
                function  FpAccess(pathname:  AnsiString;aMode:  cint)  :  cint

    Visibility:   default

Description:     FpAccess tests user's access rights on the specified file.  Mode is a mask existing of one or
                more of the following:


                R__OK     User has read rights.

                W__OK      User has write rights.

                X__OK     User has execute rights.

                F__OK    File exists.


                The test is done with the real user ID, instead of the effective user ID. If the user has the
                requested rights, zero is returned.  If access is denied, or an error occurred, a nonzero value
                is returned.

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).


                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 (145  ), FpChmod (144  )


                Listing:  ./bunixex/ex26.pp



                                                                                 142

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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

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 (180  ), fpPause (171  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 143

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.4        FpChdir

    Synopsis:    Change current working directory.

Declaration:     function  FpChdir(path:  PChar)  :  cint
                function  FpChdir(path:  AnsiString)  :  cint

    Visibility:   default

Description:     fpChDir sets the current working directory to Path.

                It returns zero if the call was succesful, -1 on error.

                Note:  There exist a portable alterative to fpChDir:  system.chdir.  Please use fpChDir only
                if you are writing Unix specific code.  System.chdir will work on all operating systems.

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).

    See also:    fpGetCwd (155  )



                1.4.5        FpChmod

    Synopsis:    Change file permission bits

Declaration:     function  FpChmod(path:  PChar;Mode:  TMode)  :  cint
                function  FpChmod(path:  AnsiString;Mode:  TMode)  :  cint

    Visibility:   default

Description:     fpChmod sets the Mode bits of the file in Path to Mode.  Mode can be specified by 'or'-ing
                the following values:


                S__ISUID      Set user ID on execution.

                S__ISGID      Set Group ID on execution.

                S__ISVTX       Set sticky bit.

                S__IRUSR       Read by owner.

                S__IWUSR        Write by owner.

                S__IXUSR       Execute by owner.

                S__IRGRP        Read by group.

                S__IWGRP         Write by group.

                S__IXGRP        Execute by group.

                S__IROTH        Read by others.

                S__IWOTH         Write by others.

                S__IXOTH        Execute by others.

                S__IRWXO        Read, write, execute by others.

                S__IRWXG        Read, write, execute by groups.

                S__IRWXU        Read, write, execute by user.


                If the function is successful, zero is returned.  A nonzero return value indicates an error.

       Errors:   The following error codes are returned:


                sys__eperm      The effective UID doesn't match the ownership of the file, and is not zero.  Owner
                       or group were not specified correctly.



                                                                                 144

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (145  ), fpAccess (142  )


                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
                    {   C r e a t e a   f i l e }
                    A s s i g n ( f , 't e s t e x 2 1') ;
                    R e w r i t e (F  ) ;
                    W r i t e l n ( f , '#!/  b i n/ s h ' ) ;
                    W r i t e l n ( f , 'e c h o Some      t e x t f o r  t h i s  f i l e' ) ;
                    C l o s e ( F ) ;
                    fpChmod       ( ' t e s t e x 2 1', & 7 7 7 ) ;
                    {   F i l e i s  now     e x e c u t a b l e }
                    f p e x e c l ( ' . /t e s t e x 2 1' , [ ] ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                1.4.6        FpChown

    Synopsis:    Change owner of file

Declaration:     function  FpChown(path:  PChar;owner:  TUid;group:  TGid)  :  cint
                function  FpChown(path:  AnsiString;owner:  TUid;group:  TGid)  :  cint

    Visibility:   default

Description:     fpChown sets the User ID and Group ID of the file in Path to Owner,Group.

                The function returns zero if the call was succesfull, a nonzero return value indicates an error.

       Errors:   The following error codes are returned:


                sys__eperm      The effective UID doesn't match the ownership of the file, and is not zero.  Owner
                       or group were not specified correctly.

                sys__eaccess     One of the directories in Path has no search (=execute) permission.

                sys__enoent      A  directory  entry  in  Path  does  not  exist  or  is  a  symbolic  link  pointing  to  a
                       non-existent directory.

                sys__enomem        Insufficient kernel memory.

                sys__erofs    The file is on a read-only filesystem.



                                                                                 145

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                sys__eloop    Path  has  a  reference  to  a  circular  symbolic  link,  i.e.   a  symbolic  link,  whose
                      expansion points to itself.


    See also:    fpChmod (144  ), fpAccess (142  )


                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  ) ;
                    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 (168  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).

    See also:    FpOpen (168  ), FpRead (173  ), FpWrite (195  ), FpFTruncate (154  ), FpLSeek (162  )



                1.4.8        FpClosedir

    Synopsis:    Close directory file descriptor



                                                                                 146

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (170  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).

    See also:    FpOpenDir (170  ), FpReadDir (174  )



                1.4.9        FpDup

    Synopsis:    Duplicate a file handle

Declaration:     function  FpDup(fildes:  cint)  :  cint
                function  FpDup(var  oldfile:  text;var  newfile:  text)  :  cint
                function  FpDup(var  oldfile:  File;var  newfile:  File)  :  cint

    Visibility:   default

Description:     FpDup returns a file descriptor that is a duplicate of the file descriptor fildes.

                The second and third forms make NewFile an exact copy of  OldFile, after having flushed
                the buffer of OldFile in case it is a Text file or untyped file.  Due to the buffering mechanism
                of Pascal, these calls do not have the same functionality as the dup call in C. The internal
                Pascal buffers are not the same after this call, but when the buffers are flushed (e.g.  after
                output), the output is sent to the same file.  Doing an lseek will, however, work as in C, i.e.
                doing a lseek will change the fileposition in both files.

                The function returns a negative value in case of an error,  a positive value is a file handle,
                and indicates succes.

       Errors:   A negative value can be one of the following error codes:


                sys__ebadf     OldFile hasn't been assigned.

                sys__emfile     Maximum number of open files for the process is reached.


    See also:    fpDup2 (148  )


                Listing:  ./bunixex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 1;


                {   Program       t o  d e m o n s t r a t et h e  Dup    f u n c t i o n. }


                 u s e s b a s e u n i x;


                 v a r  f  :   t e x t;


                 b e g i n
                    i f    f p d u p ( o u t p u t, f)<>0     then
                        W r i t e l n(  'Dup    F a i l e d ! ' ) ;
                    w r i t e l n ( ' T h i s i s   w r i t t e nt o   s t d o u t.' ) ;
                    w r i t e l n ( f , 'T h i s  i s  w r i t t e n t o  t h e  dup    f i l e,  and     f l u s h e d') ;f l u s *
 *h(f ) ;
                    w r i t e l n
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                 147

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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.

                The function returns the new file descriptor number, on error -1 is returned, and the error
                can be retrieved with fpgeterrno (156  )

       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 (147  )


                Listing:  ./bunixex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 1;


                {   Program       t o  d e m o n s t r a t et h e  FpDup2      f u n c t i o n.  }


                 u s e s B a s e U n i x;


                 v a r  f  :   t e x t;
                        i  :   l o n g i n t;


                 b e g i n
                    A s s i g n ( f , 't e x t. t x t' ) ;
                    R e w r i t e (F  ) ;
                    For    i : = 1  t o  1 0  do    w r i t e l n( F , 'L i n e  :   ' ,i ) ;
                    i f  f p d u p 2 ( o u t p u t, f)=-1     then
                        W r i t e l n(  'Dup2     F a i l e d ! ' ) ;
                    w r i t e l n ( ' T h i s i s   w r i t t e nt o   s t d o u t.' ) ;
                    w r i t e l n ( f , 'T h i s  i s  w r i t t e n t o  t h e  dup    f i l e,  and     f l u s h e d') ;
                    f l u s h( f) ;
                    w r i t e l n;
                    {  Remove       f i l e.  Comment       t h i s  i f  you    want     t o  c h e c k  f l u s h i n g.}
                    f p U n l i n k ( 't e x t. t x t' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                 148

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.11         FpExecv

    Synopsis:    Execute process

Declaration:     function  FpExecv(path:  PChar;argv:  PPChar)  :  cint
                function  FpExecv(path:  AnsiString;argv:  PPChar)  :  cint

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  It gives the
                program the options in argvp.  This is a pointer to an array of pointers to null-terminated
                strings.  The last pointer in this array should be nil.  The current environment is passed to
                the program.  On success, execv does not return.

       Errors:   On  error,  -1  is  returned.   Extended  error  information  can  be  retrieved  with  fpGetErrNo
                (156  )


                sys__eacces     File is not a regular file,  or has no execute permission.  A compononent of the
                       path has no search permission.

                sys__eperm      The file system is mounted \textit{noexec}.

                sys__e2big     Argument list too big.

                sys__enoexec       The magic number in the file is incorrect.

                sys__enoent      The file does not exist.

                sys__enomem        Not enough memory for kernel.

                sys__enotdir      A component of the path is not a directory.

                sys__eloop     The path contains a circular reference (via symlinks).


    See also:    fpExecve (150  ), fpFork (153  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 149

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.12         FpExecve

    Synopsis:    Execute process using environment

Declaration:     function  FpExecve(path:  PChar;argv:  PPChar;envp:  PPChar)  :  cint
                function  FpExecve(path:  AnsiString;argv:  PPChar;envp:  PPChar)  :  cint

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  It gives the
                program the options in argv, and the environment in envp.  They are pointers to an array of
                pointers to null-terminated strings.  The last pointer in this array should be nil.  On success,
                execve does not return.

       Errors:   Extended error information can be retrieved with fpGetErrno (156  ), 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.

                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 (149  ), fpFork (153  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 150

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (153  ), FpExecve (150  )



                1.4.14         FpFcntl

    Synopsis:    File control operations.

Declaration:     function  FpFcntl(fildes:  cint;cmd:  cint)  :  cint
                function  FpFcntl(fildes:  cint;cmd:  cint;arg:  cint)  :  cint
                function  FpFcntl(fildes:  cint;cmd:  cint;var  arg:  FLock)  :  cint

    Visibility:   default

Description:     Read/set a file's attributes.  Fildes a valid file descriptor.  Cmd speciefies what to do, and is
                one of the following:


                F__GetFd      Read the close_on_exec flag.  If the low-order bit is 0, then the file will remain open
                       across execve calls.

                F__GetFl     Read the descriptor's flags.

                F__GetOwn        Get the Process ID of the owner of a socket.

                F__SetFd     Set the close_on_exec flag of  fildes.  (only the least siginificant bit is used).

                F__GetLk      Return the flock record that prevents this process from obtaining the lock, or set
                       the l_type field of the lock of there is no obstruction.  Arg is the flock record.

                F__SetLk     Set the lock or clear it (depending on l_type in the flock structure).  if the lock is
                       held by another process, an error occurs.

                F__GetLkw       Same as for F__Setlk, but wait until the lock is released.

                F__SetOwn       Set the Process or process group that owns a socket.


                The function returns 0 if successful, -1 otherwise.

       Errors:   On error, -1 is returned.  Use fpGetErrno (156  ) 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.



                                                                                 151

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (177  ), FpFD_ZERO (153  ), FpFD_IsSet (152  ), FpFD_Clr (152  ), FpFD_Set (152  )



                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 (177  ).

       Errors:   None.

    See also:    FpSelect (177  ), FpFD_ZERO (153  ), FpFD_Set (152  ), FpFD_IsSet (152  )



                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 (177  ).

       Errors:   If an invald file descriptor number is passed, -1 is returned.

    See also:    FpSelect (177  ), FpFD_ZERO (153  ), FpFD_Clr (152  ), FpFD_Set (152  )



                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 (177  ).

       Errors:   None.

    See also:    FpSelect (177  ), FpFD_ZERO (153  ), FpFD_Clr (152  ), FpFD_IsSet (152  )



                                                                                 152

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (177  ).

       Errors:   None.

    See also:    FpSelect (177  ), FpFD_Clr (152  ), FpFD_Set (152  ), FpFD_IsSet (152  )



                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 (158  )).

       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 (150  ), #rtl.linux.Clone (740  )



                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 (136  ).  The function returns zero if the call was
                succesfull, a nonzero return value indicates failure.

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).


                sys__enoent      Path does not exist.


    See also:    FpStat (186  ), FpLStat (163  )


                Listing:  ./bunixex/ex28.pp



                                                                                 153

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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.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 (156  ).

    See also:    FpOpen (168  ), FpClose (146  ), FpRead (173  ), FpWrite (195  ), FpLSeek (162  )



                                                                                 154

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.23         FpGetcwd

    Synopsis:    Retrieve the current working directory.

Declaration:     function  FpGetcwd(path:  PChar;siz:  TSize)  :  PChar
                function  FpGetcwd  :  AnsiString

    Visibility:   default

Description:     fpgetCWD  returns  the  current  working  directory  of  the  running  process.  It  is  returned  in
                Path, which points to a memory location of at least siz bytes.

                If  the  function  is  succesful,  a  pointer  to  Path  is  returned,  or  a  string  with  the  result.  On
                error Nil or an empty string are returned.

       Errors:   On error Nil or an empty string are returned.

    See also:    FpGetPID (158  ), FpGetUID (160  )



                1.4.24         FpGetegid

    Synopsis:    Return effective group ID

Declaration:     function  FpGetegid  :  TGid

    Visibility:   default

Description:     FpGetegid returns the effective group ID of the currently running process.

       Errors:   None.

    See also:    FpGetGid (157  ),  FpGetUid (160  ),  FpGetEUid (156  ),  FpGetPid (158  ),  FpGetPPid (158  ),
                fpSetUID (180  ), FpSetGid (178  )


                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.



                                                                                 155

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



       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.

       Errors:   None.

    See also:    fpseterrno (178  )



                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 (160  ),  FpGetGid (157  ),  FpGetEGid (155  ),  FpGetPid (158  ),  FpGetPPid (158  ),
                fpSetUID (180  ), FpSetGid (178  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 156

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (155  ), FpGetUid (160  ), FpGetEUid (156  ), FpGetPid (158  ), FpGetPPid (158  ),
                fpSetUID (180  ), FpSetGid (178  )


                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.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
                (156  )

    See also:    FpGetpgrp (157  ), FpGetGID (157  ), FpGetEGID (155  )



                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 (158  ), fpGetPPID (158  ), FpGetGID (157  ), FpGetUID (160  )



                                                                                 157

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (158  )


                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.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 (158  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 158

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (168  ).

       Errors:   Error information is returned solely by the FpGetErrno (156  ) 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 (179  ), FpNice (168  )



                1.4.34         FpGetRLimit

    Synopsis:    Get process resource limits

Declaration:     function  FpGetRLimit(resource:  cint;rlim:  PRLimit)  :  cint

    Visibility:   default

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 (139  ) 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 (156  ) can be used to retrieve the error code.

    See also:    FpSetRLimit (179  )



                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 (157  ), FpGetpid (158  ), FpGetPpid (158  )



                                                                                 159

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (157  ), FpGetEUid (156  ), FpGetEGid (155  ), FpGetPid (158  ), FpGetPPid (158  ),
                fpSetUID (180  )


                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.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 (156  ).


                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 ) ) ;



                                                                                 160

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    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 (156  ):


                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 (180  ), FpSignal (183  )



                1.4.39         FpLink

    Synopsis:    Create a hard link to a file

Declaration:     function  FpLink(existing:  PChar;newone:  PChar)  :  cint
                function  FpLink(existing:  AnsiString;newone:  AnsiString)  :  cint

    Visibility:   default

Description:     fpLink makes NewOne point to the same file als Existing.  The two files then have the same
                inode  number.  This  is  known  as  a  'hard'  link.  The  function  returns  zero  if  the  call  was
                succesfull, and returns a non-zero value if the call failed.

       Errors:   The following error codes are returned:


                sys__exdev     Existing and NewOne are not on the same filesystem.

                sys__eperm      The filesystem containing Existing and NewOne doesn't support linking files.

                sys__eaccess     Write  access  for  the  directory  containing  NewOne  is  disallowed,  or  one  of  the
                       directories in Existing or NewOne has no search (=execute) permission.

                sys__enoent      A  directory  entry  in  Existing  or  NewOne  does  not  exist  or  is  a  symbolic  link
                       pointing to a non-existent directory.

                sys__enotdir      A directory entry in Existing or NewOne is nor a directory.

                sys__enomem        Insufficient kernel memory.

                sys__erofs    The files are on a read-only filesystem.

                sys__eexist    NewOne already exists.



                                                                                 161

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (187  ), fpUnLink (192  )


                Listing:  ./bunixex/ex21.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 1;


                {   Program       t o  d e m o n s t r a t et h e  L i n k  and    U n L i n k f u n c t i o n s. }


                Uses     B a s e U n i x;


                Var    F   :  T e x t ;
                       S   :   S t r i n g;
                 b e g i n
                    A s s i g n ( F , 't e s t. t x t' ) ;
                    R e w r i t e (F  ) ;
                    W r i t e l n (F  , 'T h i s  i s  w r i t t e n t o  t e s t. t x t' ) ;
                    C l o s e( f) ;
                    {  new   . t x t and     t e s t.t x t  a r e  now    t h e  same     f i l e }
                    i f  f p L i n k (  't e s t. t x t' , 'new   .t x t ')<>0     then
                        w r i t e l n(  'E r r o r when     l i n k i n g ! ' ) ;
                    {  Removing        t e s t. t x t  s t i l l  l e a v e snew   . t x t }
                    I f  f p U n l i n k ( ' t e s t.t x t ')<>0     then
                        W r i t e l n(  'E r r o r when     u n l i n k i n g ! ') ;
                    A s s i g n ( f , 'new   .t x t ') ;
                    R e s e t ( F ) ;
                    While     not    EOF   ( f)  do
                        b e g i n
                       Readln     (F  ,S ) ;
                        W r i t e l n(  '>   ' ,s ) ;
                       end   ;
                  C l o s e  ( f) ;
                  {   Remove      new  . t x t  a l s o }
                   I f not    F P U n l i n k ( 'new   . t x t')<>0     then
                      W r i t e l n ( 'E r r o r  when     u n l i n k i n g! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                1.4.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.



                                                                                 162

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (168  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).

    See also:    FpOpen (168  ), FpWrite (195  ), FpClose (146  ), FpRead (173  ), FpFTruncate (154  )



                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(path:  Ansistring;Info:  PStat)  :  cint
                function  fpLstat(path:  PChar;var  Info:  Stat)  :  cint
                function  fpLstat(Filename:  ansistring;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  (153  ),  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 (156  ) function.


                sys__enoent      Path does not exist.


    See also:    FpFStat (153  ), #rtl.unix.StatFS (1711   )


                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 ) ;



                                                                                 163

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    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) ;
                    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(path:  AnsiString;Mode:  TMode)  :  cint

    Visibility:   default

Description:     FpMkDir creates a new directory Path, and sets the new directory's mode to Mode.  Path can
                be an absolute path or a relative path.  Note that only the last element of the directory will
                be created, higher level directories must already exist, and must be writeable by the current
                user.

                On succes, 0 is returned.  if the function fails, -1 is returned.

                Note:  There exist a portable alterative to fpMkDir:  system.mkdir.  Please use fpMkDir only
                if you are writing Unix specific code.  System.mkdir will work on all operating systems.

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).



                                                                                 164

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



    See also:    fpGetCWD (155  ), fpChDir (144  )



                1.4.43         FpMkfifo

    Synopsis:    Create FIFO (named pipe) in file system

Declaration:     function  FpMkfifo(path:  PChar;Mode:  TMode)  :  cint
                function  FpMkfifo(path:  AnsiString;Mode:  TMode)  :  cint

    Visibility:   default

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

Description:     FpMMap maps or unmaps files or devices into memory.  The different arguments determine
                what and how the file is mapped:


                adr  Address where to mmap the device.  This address is a hint, and may not be followed.

                len  Size (in bytes) of area to be mapped.

                prot   Protection of mapped memory.  This is a OR-ed combination of the following constants:

                       PROT__EXEC            The memory can be executed.

                       PROT__READ            The memory can be read.

                       PROT__WRITE             The memory can be written.

                       PROT__NONE            The memory can not be accessed.

                flags  Contains some options for the mmap call.  It is an OR-ed combination of the following
                       constants:

                       MAP__FIXED            Do not map at another address than the given address.  If the address
                             cannot be used, MMap will fail.

                       MAP__SHARED              Share this map with other processes that map this object.

                       MAP__PRIVATE              Create a private map with copy-on-write semantics.

                       MAP__ANONYMOUS                     fd does not have to be a file descriptor.

                       One of the options MAP_SHARED and MAP_PRIVATE must be present, but not both at the
                       same time.

                fd File descriptor from which to map.

                off Offset to be used in file descriptor fd.


                The function returns a pointer to the mapped memory, or a -1 in case of en error.



                                                                                 165

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



       Errors:   On  error,  -1  is  returned  and  extended  error  information  is  returned  by  the  FpGetErrno
                (156  ) 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 (166  )


                Listing:  ./unixex/ex66.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 6;


                {   Program       t o  d e m o n s t r a t et h e  MMap     f u n c t i o n. }


                Uses     B a s e U n i x,U n i x;


                Var    S         :  S t r i n g;
                        f d      :  c i n t;
                       Len       :  l o n g i n t;
                //         a r g s  :  tmmapargs       ;
                       P         :  PChar    ;


                 b e g i n
                    s :=  'T h i s  i s  t h e  s t r i n g';
                    Len  :=  Length    ( S ) ;
                    f d:=  fpOpen    (  't e s t f i l e.t x t' ,O _wrOnly       o r  o _c r e a t ) ;
                    I f  f d=-1     then
                       H a l t ( 1 ) ;
                    I f  f p W r i t e(f d ,S [ 1 ] ,Len  )=-1     then
                       H a l t ( 2 ) ;
                    f p C l o s e(f d ) ;
                    f d:=  fpOpen    (  't e s t f i l e.t x t' ,O _r d O n l y ) ;
                    i f  f d=-1     then
                       H a l t ( 3 ) ;
                    P := P c h a r( fpmmap    ( n i l, l e n+1  ,  PROT_READ         o r PROT_WRITE        , MAP_PRIVATE        , f*
 * d , 0 ) ) ;


                    I f  l o n g i n t(P )=-1     then
                       H a l t ( 4 ) ;
                    W r i t e l n(' Read     i n memory         : ',P  ) ;
                    f p c l o s e(f d ) ;
                    i f  fpMUnMap      ( P ,Len  )<>0     Then
                       H a l t( f p g e t e r r n o) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                1.4.45         Fpmunmap

    Synopsis:    Unmap previously mapped memory block

Declaration:     function  Fpmunmap(start:  pointer;len:  size_t)  :  cint



                                                                                 166

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



    Visibility:  default

Description:     FpMUnMap unmaps the memory block of size Len, pointed to by Adr, which was previously
                allocated with FpMMap (165  ).

                The function returns True if successful, False otherwise.

                For an example, see FpMMap (165  ).

       Errors:   In case of error the function returns a nonzero value, extended error information is returned
                by the FpGetErrno (156  ) function.  See FpMMap (165  ) for possible error values.

    See also:    FpMMap (165  )



                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 (156  ).

    See also:    FpPause (171  ), FpAlarm (143  )


                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 ) ;



                                                                                 167

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                           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 (156  ) function.


                sys__eperm      A non-superuser tried to specify a negative N, i.e.  do a priority increase.


    See also:    FpGetPriority (159  ), FpSetPriority (179  )


                Listing:  ./unixex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;


                {   Program       t o  d e m o n s t r a t et h e  N i c e  and    Get  / S e t P r i o r i t yf u n c t i o n s. }


                Uses     B a s e U n i x,U n i x;


                 b e g i n
                    w r i t e l n ( ' S e t t i n g p r i o r i t yt o  5 ' ) ;
                    f p s e t p r i o r i t y(p r i o _p r o c e s s,f p g e t p i d, 5 ) ;
                    w r i t e l n ( 'New     p r i o r i t y=   ' ,f p g e t p r i o r i t y(p r i o _p r o c e s s,f p g e t p i d*
 *) ) ;
                    w r i t e l n ( 'D o i n g  n i c e 1 0 ' ) ;
                    f p n i c e ( 1 0 ) ;
                    w r i t e l n ( 'New     P r i o r i t y=   ' ,f p g e t p r i o r i t y(p r i o _p r o c e s s,f p g e t p i d*
 *) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                1.4.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(path:  AnsiString;flags:  cint)  :  cint
                function  FpOpen(path:  AnsiString;flags:  cint;Mode:  TMode)  :  cint
                function  FpOpen(path:  string;flags:  cint)  :  cint
                function  FpOpen(path:  string;flags:  cint;Mode:  TMode)  :  cint

    Visibility:   default

Description:     FpOpen opens a file in Path with flags flags and mode Mode One of the following:


                O__RdOnly        File is opened Read-only



                                                                                 168

            ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_____________________*
 *_______________



            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.

   Errors:   Extended error information can be retrieved using fpGetErrno (156  ).

See also:    FpClose (146  ), FpRead (173  ), FpWrite (195  ), FpFTruncate (154  ), FpLSeek (162  )


            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___.________________________________________________________________________________________________________________*
 *_______



                                                                             169

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.49         FpOpendir

    Synopsis:    Open a directory for reading

Declaration:     function  FpOpendir(dirname:  PChar)  :  pDir
                function  FpOpendir(dirname:  AnsiString)  :  pDir
                function  FpOpendir(dirname:  shortString)  :  pDir

    Visibility:   default

Description:     FpOpenDir opens the directory DirName, and returns a pdir pointer to a Dir (127  ) 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 (156  ).

    See also:    FpCloseDir (146  ), FpReadDir (174  )


                Listing:  ./bunixex/ex35.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 5;


                {   Program       t o  d e m o n s t r a t et h e
                    OpenDir     , R e a d D i r,  S e e k D i r and    T e l l D i r f u n c t i o n.s  }


                Uses     B a s e U n i x;


                Var    T h e D i r  :  P D i r;
                        A D i r e n t :  P D i r e n t;
                        E n t r y :   L o n g i n t;


                 b e g i n
                    T h e D i r:= f p O p e n D i r('. / . ') ;
                    Repeat
                //         E n t r y:= f p T e l l D i r(T h e D i r) ;
                        A D i r e n t:=f p R e a d D i r( T h e D i r^ ) ;
                        I f  A D i r e n<t>  N i l then
                           With     A D i r e n t^ do
                              b e g i n
                               W r i t e l n(  'E n t r y No    :  ' , E n t r y) ;
                               W r i t e l n(  'I n o d e       :  ' , d _f i l e n o) ;
                //                W r i t e l n ( ' O f f s e t    :   ' ,d _o f f ) ;
                               W r i t e l n(  'R e c l e n     :  ' , d _r e c l e n) ;
                               W r i t e l n(  'Name            :  ' , p c h a r(@d _name     [ 0 ] ) ) ;
                              end   ;
                    U n t i l  A D i r e n=t N i l;
                    Repeat
                       Write      ( ' E n t r y No  .  you    w o u l d  l i k e t o  s e e  a g a i n ( - 1   t o  s t o p) :  ' )*
 * ;
                       ReadLn       ( E n t r y) ;
                        I f  E n t r y<>-1    then
                           b e g i n
                //             f p S e e k D i r( TheDir    , E n t r y) ;                          / /  n o t  i m p l e m e n t e*
 * df o r  v a r i o u s p l a t@
                           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) ;



                                                                                 170

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                                  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 (143  ).



                1.4.51         FpPipe

    Synopsis:    Create a set of pipe file handlers

Declaration:     function  FpPipe(var  fildes:  TFilDes)  :  cint

    Visibility:   default

Description:     FpPipe creates a pipe, i.e.  two file objects, one for input, one for output.  The filehandles
                are returned in the array fildes.  The input handle is in the 0-th element of the array, the
                output handle is in the 1-st element.

                The function returns zero if everything went succesfully, a nonzero return value indicates an
                error.

       Errors:   In case the function fails, the following return values are possible:


                sys__emfile     Too many file descriptors for this process.

                sys__enfile    The system file table is full.


    See also:    #rtl.unix.POpen (1708   ), fpMkFifo (165  )


                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;



                                                                                 171

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    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 (138  )



                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 (175  ), FpPWrite (172  )



                1.4.54         FppWrite

    Synopsis:    Positional write:  write to file descriptor at a certain position.



                                                                                 172

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (172  ), FpWriteV (195  )



                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 (156  ).

    See also:    FpOpen (168  ), FpClose (146  ), FpWrite (195  ), FpFTruncate (154  ), FpLSeek (162  )


                Listing:  ./bunixex/ex20.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 0;


                {   Program       t o  d e m o n s t r a t et h e  f d R e a d and    f d T r u n c a t e f u n c t i o n.s }


                Uses     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 ) ;



                                                                                 173

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                       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 (128  ) record describing the entry.  If the next entry can't be read, Nil is
                returned.

                For an example, see FpOpenDir (170  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).

    See also:    FpCloseDir (146  ), FpOpenDir (170  )



                1.4.57         fpReadLink

    Synopsis:    Read destination of symbolic link

Declaration:     function  fpReadLink(name:  PChar;linkname:  PChar;maxlen:  size_t)  :  cint
                function  fpReadLink(Name:  ansistring)  :  ansistring

    Visibility:   default

Description:     FpReadLink  returns  the  file  the  symbolic  link  name  is  pointing  to.  The  first  form  of  this
                function accepts a buffer linkname of length maxlen where the filename will be stored.  It
                returns the actual number of characters stored in the buffer.

                The second form of the function returns simply the name of the file.

       Errors:   On error, the first form of the function returns -1; the second one returns an empty string.
                Extended error information is returned by the FpGetErrno (156  ) function.



                                                                                 174

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                SYS__ENOTDIR             A part of the path in Name is not a directory.

                SYS__EINVAL          maxlen is not positive, or the file is not a symbolic link.

                SYS__ENAMETOOLONG                       A pathname, or a component of a pathname, was too long.

                SYS__ENOENT            the link name does not exist.

                SYS__EACCES           No permission to search a directory in the path

                SYS__ELOOP          Too many symbolic links were encountered in translating the pathname.

                SYS__EIO      An I/O error occurred while reading from the file system.

                SYS__EFAULT           The buffer is not part of the the process's memory space.

                SYS__ENOMEM              Not enough kernel memory was available.

    See also:    FpSymLink (187  )


                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
                        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 (138  ) buffers pointed to by iov.  It works like fpRead (173  ) only on multiple buffers.

       Errors:   On error, -1 is returned.

    See also:    FpWriteV (195  ), FpPWrite (172  ), FpPRead (172  )



                                                                                 175

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.59         FpRename

    Synopsis:    Rename file

Declaration:     function  FpRename(old:  PChar;newpath:  PChar)  :  cint
                function  FpRename(old:  AnsiString;newpath:  AnsiString)  :  cint

    Visibility:   default

Description:     FpRename renames the file Old to NewPath.  NewPath can be in a different directory than
                Old, but it cannot be on another partition (device).  Any existing file on the new location
                will be replaced.

                If the operation fails, then the Old file will be preserved.

                The function returns zero on succes, a nonzero value indicates failure.

                Note:  There exist a portable alterative to fpRename:  system.rename.  Please use fpRename
                only if you are writing Unix specific code.  System.rename will work on all operating systems.

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).


                sys__eisdir    NewPath exists and is a directory, but Old is not a directory.

                sys__exdev     NewPath and Old are on different devices.

                sys__enotempty or sys__eexist               NewPath is an existing, non-empty directory.

                sys__ebusy     Old or NewPath is a directory and is in use by another process.

                sys__einval    NewPath is part of  Old.

                sys__emlink      OldPath  or  NewPath  already  have  tha  maximum  amount  of  links  pointing  to
                       them.

                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 (192  )



                1.4.60         FpRmdir

    Synopsis:    Remove a directory.

Declaration:     function  FpRmdir(path:  PChar)  :  cint
                function  FpRmdir(path:  AnsiString)  :  cint

    Visibility:   default



                                                                                 176

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (156  ).



                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
                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 (153  ), fpFD_Clr (152  ), fpFD_Set (152  ) or fpFD_IsSet
                (152  ) 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 (156  ).



                                                                                 177

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (153  ), fpFD_Clr (152  ), fpFD_Set (152  ), fpFD_IsSet (152  )


                Listing:  ./bunixex/ex33.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   Program       t o  d e m o n s t r a t et h e  S e l e c t f u n c t i o n.  }


                Uses     B a s e U n i x;


                Var    FDS     :  T f d s e t;


                 b e g i n
                    f p f d _z e r o(FDS   ) ;
                    f p f d _s e t( 0 ,FDS   ) ;
                    W r i t e l n ( ' P r e s s t h e < ENTER    >   t o  c o n t i n u e t h e  p r o g r a m.' ) ;
                    {  Wait     u n t i l  F i l e  d e s c r i p t o r0  ( = I n p u t)  c h a n g e s }
                    f p S e l e c t ( 1 ,@FDS   , n i l, n i l, n i l) ;
                    {  Get     r i d  o f < ENTER    >   i n  b u f f e r }
                    r e a d l n;
                    W r i t e l n ( ' P r e s s< ENTER    >   k e y  i n  l e s s  t h a n 2   s e c o n d s. . .') ;
                    F p f d _z e r o(FDS   ) ;
                    F p F d _s e t  ( 0 ,FDS  ) ;
                    i f  f p S e l e c t ( 1 ,@FDS   , n i l, n i l, 2 0 0 0 ) > 0 then
                        W r i t e l n(  'Thank     you    ! ' )
                       {   FD _ISSET     ( 0 ,FDS   )  w o u l d be    t r u e h e r e .  }
                    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 (156  )



                1.4.63         FpSetgid

    Synopsis:    Set the current group ID

Declaration:     function  FpSetgid(gid:  TGid)  :  cint

    Visibility:   default



                                                                                 178

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (156  ).

    See also:    FpSetUid  (180  ),  FpGetGid  (157  ),  FpGetUid  (160  ),  FpGetEUid  (156  ),  FpGetEGid  (155  ),
                FpGetPid (158  ), FpGetPPid (158  )



                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 (168  ).

                The function returns zero on success, -1 on failure

       Errors:   Extended error information is returned by the FpGetErrno (156  ) 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 (159  ), FpNice (168  )



                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 (139  ) 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 (156  ) can be used to retrieve the error code.

    See also:    FpGetRLimit (159  )



                                                                                 179

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (157  ).  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
                (156  )



                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 (1702   )



                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 (156  ).

    See also:    FpGetGid (157  ), FpGetUid (160  ), FpGetEUid (156  ), FpGetEGid (155  ), FpGetPid (158  ),
                FpGetPPid (158  ), FpSetGid (178  )



                1.4.69         FPSigaction

    Synopsis:    Install signal handler

Declaration:     function  FPSigaction(sig:  cint;act:  psigactionrec;oact:  psigactionrec)
                                                   :  cint

    Visibility:   default



                                                                                 180

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



Description:     FPSigaction changes the action to take upon receipt of a signal.  Act and Oact are pointers
                to  a  SigActionRec  (135  )  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 (156  ).


                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 (184  ), FpSigPending (184  ), FpSigSuspend (185  ), FpKill (161  )


                Listing:  ./bunixex/ex57.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 5 7;


                {   Program       t o  d e m o n s t r a t et h e  S i g A c t i o n f u n c t i o n.}


                {
                do    a   k i l l- USR1      p i d f r o m  a n o t h e r t e r m i n a l t o  s e e  what     h a p p e n s.
                 r e p l a c e p i d  w i t h t h e  r e a l  p i d  o f  t h i s  p r o g r a m.
                You    c a n   g e t  t h i s p i d  by   r u n n i n g  'ps  ' .
                }


                 u s e s B a s e U n i x;


                Var
                      oa , na   :   P S i g A c t i o n R e;c


                 P r o c e d u r eDoSig    ( s i g  :  c i n t) ;c d e c l;


                 b e g i n
                      w r i t e l n(' R e c e i v i n gs i g n a l:  ' , s i g) ;
                end   ;


                 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



                                                                                 181

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                         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 (182  ), FpSigFillSet (183  ), FpSigDelSet (182  ), FpSigIsMember (183  )



                1.4.71         FpSigDelSet

    Synopsis:    Remove a signal from a signal set.

Declaration:     function  FpSigDelSet(var  nset:  tsigset;signo:  cint)  :  cint

    Visibility:   default

Description:     FpSigDelSet removes signal Signo to the signal set nset.  The function returns 0 on success.

       Errors:   If an invalid signal number is given, -1 is returned.

    See also:    FpSigEmptySet (182  ), FpSigFillSet (183  ), FpSigAddSet (182  ), FpSigIsMember (183  )



                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 (183  ), FpSigAddSet (182  ), FpSigDelSet (182  ), FpSigIsMember (183  )



                                                                                 182

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (182  ), FpSigAddSet (182  ), FpSigDelSet (182  ), FpSigIsMember (183  )



                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 (182  ), FpSigFillSet (183  ), FpSigAddSet (182  ), FpSigDelSet (182  )



                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 (180  ) call.  The return
                value for FpSignal is the old signal handler, or nil on error.

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).


                SIG__ERR        An error occurred.


    See also:    FpSigAction (180  ), FpKill (161  )


                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  ' .
                }



                                                                                 183

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                 u s e s B a s e U n i x;


                 P r o c e d u r eDoSig    ( s i g  :  c i n t) ;c d e c l;


                 b e g i n
                      w r i t e l n(' R e c e i v i n gs i g n a l:  ' , s i g) ;
                end   ;


                 b e g i n
                      i f  f p S i g n a l(S i g U s r 1,S i g n a l H a n d l e(r@DoSig   ))=   s i g n a l h a n d l e(rSIG _ERR *
 *  )   then
                         b e g i n
                         w r i t e l n( 'E r r o r:  ' , f p G e t E r r n,o' . ') ;
                         h a l t( 1 ) ;
                         end   ;
                      W r i t e l n ( 'Send     USR1     s i g n a l o r  p r e s s < ENTER    >  t o   e x i t' ) ;
                      r e a d l n;
                end___.____________________________________________________________________________________________________________*
 *___________



                1.4.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.

       Errors:   None

    See also:    fpSigAction (180  ), fpSigProcMask (184  ), fpSigSuspend (185  ), fpSignal (183  ), fpKill (161  )



                1.4.77         FpSigProcMask

    Synopsis:    Set list of blocked signals

Declaration:     function  FpSigProcMask(how:  cint;nset:  psigset;oset:  psigset)  :  cint
                function  FpSigProcMask(how:  cint;const  nset:  tsigset;var  oset:  tsigset)
                                                      :  cint

    Visibility:   default

Description:     Changes the list of currently blocked signals.  The behaviour of the call depends on How :

                SIG__BLOCK           The set of blocked signals is the union of the current set and the nset argu-
                       ment.

                SIG__UNBLOCK              The signals in nset are removed from the set of currently blocked signals.

                SIG__SETMASK              The list of blocked signals is set so nset.

                If  oset is non-nil, then the old set is stored in it.

       Errors:   Errno is used to report errors.

                sys__efault    oset or nset point to an adress outside the range of the process.

                sys__eintr    System call was interrupted.

    See also:    fpSigAction (180  ), fpSigPending (184  ), fpSigSuspend (185  ), fpKill (161  )



                                                                                 184

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (180  ), fpSigProcMask (184  ), fpSigPending (184  ), fpSignal (183  ), fpKill (161  )



                1.4.79         FpSigTimedWait

    Synopsis:    Wait for signal, with timeout

Declaration:     function  FpSigTimedWait(const  sigset:  tsigset;info:  psiginfo;
                                                      timeout:  ptimespec)  :  cint

    Visibility:   default

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 (185  )



                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 (171  ), fpAlarm (143  ), fpNanoSleep (167  )


                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;



                                                                                 185

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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(path:  AnsiString;var  buf:  Stat)  :  cint
                function  FpStat(path:  string;var  buf:  Stat)  :  cint

    Visibility:   default

Description:     FpFStat gets information about the file specified in Path, and stores it in Info, which is of
                type stat (136  ).  The function returns zero if the call was succesfull, a nonzero return value
                indicates failure.

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).


                sys__enoent      Path does not exist.


    See also:    FpStat (186  ), FpLStat (163  )


                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;



                                                                                 186

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    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

    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 (156  ) 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 (161  ), FpUnLink (192  ), FpReadLink (174  )


                Listing:  ./unixex/ex22.pp



                                                                                 187

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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+ }
                    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 (153  ), FpS_ISLNK (189  ), FpS_ISREG (190  ), FpS_ISDIR (189  ), FpS_ISCHR (188  ),
                FpS_ISFIFO (189  ), FpS_ISSOCK (190  )



                1.4.84         fpS__ISCHR

    Synopsis:    Is file a character device

Declaration:     function  fpS_ISCHR(m:  TMode)  :  Boolean

    Visibility:   default



                                                                                 188

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (153  ), FpS_ISLNK (189  ), FpS_ISREG (190  ), FpS_ISDIR (189  ), FpS_ISBLK (188  ),
                FpS_ISFIFO (189  ), FpS_ISSOCK (190  )



                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 (153  ), FpS_ISLNK (189  ), FpS_ISREG (190  ), FpS_ISCHR (188  ), FpS_ISBLK (188  ),
                fpS_ISFIFO (189  ), FpS_ISSOCK (190  )



                1.4.86         fpS__ISFIFO

    Synopsis:    Is file a FIFO

Declaration:     function  fpS_ISFIFO(m:  TMode)  :  Boolean

    Visibility:   default

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 (153  ), FpS_ISLNK (189  ), FpS_ISREG (190  ), FpS_ISCHR (188  ), FpS_ISBLK (188  ),
                FpS_ISDIR (189  ), FpS_ISSOCK (190  )



                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 (153  ), FpS_ISFIFO (189  ), FpS_ISREG (190  ), FpS_ISCHR (188  ), FpS_ISBLK (188  ),
                FpS_ISDIR (189  ), FpS_ISSOCK (190  )


                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



                                                                                 189

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                    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

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 (153  ), FpS_ISFIFO (189  ), FpS_ISLNK (189  ), FpS_ISCHR (188  ), FpS_ISBLK (188  ),
                FpS_ISDIR (189  ), FPS_ISSOCK (190  )



                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 (153  ), FpS_ISFIFO (189  ), FpS_ISLNK (189  ), FpS_ISCHR (188  ), FpS_ISBLK (188  ),
                FpS_ISDIR (189  ), FpS_ISREG (190  )



                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.



                                                                                 190

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



       Errors:   On  error,  -1  is  returned.   Extended  error  information  can  be  retrieved  using  fpGetErrno
                (156  ).


                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

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 (156  ).

    See also:    fpUTime (193  )



                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 (144  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 191

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (156  ).

    See also:    FpUTime (193  )



                1.4.94         FpUnlink

    Synopsis:    Unlink (i.e.  remove) a file.

Declaration:     function  FpUnlink(path:  PChar)  :  cint
                function  FpUnlink(path:  AnsiString)  :  cint

    Visibility:   default

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 (161  ).

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).


                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 (161  ), FpSymLink (187  )



                                                                                 192

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                1.4.95         FpUtime

    Synopsis:    Set access and modification times of a file (touch).

Declaration:     function  FpUtime(path:  PChar;times:  pUtimBuf)  :  cint
                function  FpUtime(path:  AnsiString;times:  pUtimBuf)  :  cint

    Visibility:   default

Description:     FpUtime  sets  the  access  and  modification  times  of  the  file  specified  in  Path.   the  times
                record contains 2 fields, actime, and modtime, both of type time_t (commonly a longint).
                They should be filled with an epoch-like time, specifying, respectively, the last access time,
                and  the  last  modification  time.  For  some  filesystem  (most  notably,  FAT),  these  times  are
                the same.

                The function returns zero on success, a nonzero return value indicates failure.

       Errors:   Extended error information can be retrieved using fpGetErrno (156  ).


                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 (190  ), FpChown (145  ), FpAccess (142  )


                Listing:  ./bunixex/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  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.



                                                                                 193

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



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 (156  ).

    See also:    fpFork (153  ), fpExecve (150  ), fpWaitPid (194  )



                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.

                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
                       (740  ) 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 (153  ).

       Errors:   Extended error information can be retrieved using fpgetErrno (156  ).

    See also:    fpFork (153  ), fpExecve (150  ), fpWait (193  )



                                                                                 194

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (156  ).

    See also:    FpOpen (168  ), FpClose (146  ), FpRead (173  ), FpFTruncate (154  ), FpLSeek (162  )



                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 (138  ) buffers pointed to by iov.  It works like fpWrite (195  ) only from multiple
                buffers.

       Errors:   On error, -1 is returned.

    See also:    FpReadV (175  ), FpPWrite (172  ), FpPRead (172  )



                1.4.100          FreeShellArgV

    Synopsis:    Free the result of a CreateShellArgV (142  ) 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 (142  ).

       Errors:   None.

    See also:    CreateShellArgV (142  )



                1.4.101          wexitStatus

    Synopsis:    Extract the exit status from the fpWaitPID (194  ) 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 (194  ) call.

    See also:    FpWaitPID (194  ), WTERMSIG (196  ), WSTOPSIG (196  ), WIFEXITED (196  ), WIFSIG-
                NALED (196  )



                                                                                 195

                ________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASEUNIX'_________________*
 *___________________



                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 (194  ), WTERMSIG (196  ), WSTOPSIG (196  ), WIFSIGNALED (196  ), WEX-
                ITSTATUS (195  )



                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 (194  ),  WTERMSIG (196  ),  WSTOPSIG (196  ),  WIFEXITED (196  ),  WEXIT-
                STATUS (195  )



                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 (195  ).

    See also:    FpWaitPID (194  ), WTERMSIG (196  ), WIFEXITED (196  ), WIFSIGNALED (196  ), WEX-
                ITSTATUS (195  )



                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 (194  ), WSTOPSIG (196  ), WIFEXITED (196  ), WIFSIGNALED (196  ), WEX-
                ITSTATUS (195  )



                                                                                 196




Chapter   2



Reference   for   unit   'Classes'



2.1         Used  units



                                     Table 2.1:  Used units by unit 'Classes'


                                                  __Name____________Page____
                                                    rtlconsts            1
                                                    System          1230
                                                    sysutils        1450
                                                    types           1621
                                                    typinfo         1640



2.2         Overview


This documentation describes the FPC classes unit.  The Classes unit contains basic classes
for the Free Component Library (FCL):


     o  a TList (328  ) class for maintaining lists of pointers,

     o  TStringList (378  ) for lists of strings,

     o  TCollection (279  ) to manage collections of objects

     o  TStream (364  ) classes to support streaming.


Furthermore  it  introduces  methods  for  object  persistence,  and  classes  that  understand  an
owner-owned relationship, with automatic memory management.



2.3         Constants,  types  and  variables



2.3.1        Constants

BITSHIFT  =  5


Used to calculate the size of a bits array



                                                             197

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



dupAccept  =  Types  .  dupAccept


Duplicate values can be added to the list.


dupError  =  Types  .  dupError


If an attempt is made to add a duplicate value to the list, an EStringListError (230  ) exception
is raised.


dupIgnore  =  Types  .  dupIgnore


Duplicate values will not be be added to the list, but no error will be triggered.


FilerSignature  :  Array[1..4]  of  Char  =  'TPF0'


Constant that is found at the start of a binary stream containing a streamed component.


fmCreate  =  $FF00


TFileStream.Create (1 ) creates a new file if needed.


fmOpenRead  =  0


TFileStream.Create (1 ) opens a file with read-only access.


fmOpenReadWrite  =  2


TFileStream.Create (1 ) opens a file with read-write access.


fmOpenWrite  =  1


TFileStream.Create (1 ) 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 (328  ).


scAlt  =  $8000



                                                                 198

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



Indicates ALT key in a keyboard shortcut.


scCtrl  =  $4000


indicates CTRL key in a keyboard shortcut.


scNone  =  0


Indicates no special key is presed in a keyboard shortcut.


scShift  =  $2000


Indicates Shift key in a keyboard shortcut.


soFromBeginning  =  0


Seek (1 ) starts relative to the stream origin.


soFromCurrent  =  1


Seek (1 ) starts relative to the current position in the stream.


soFromEnd  =  2


Seek (1 ) starts relative to the stream end.


toEOF  =  (0)


Value returned by TParser.Token (1 ) when the end of the input stream was reached.


toFloat  =  (4)


Value  returned  by  TParser.Token  (1 )  when  a  floating  point  value  was  found  in  the  input
stream.


toInteger  =  (3)


Value returned by TParser.Token (1 ) when an integer was found in the input stream.


toString  =  (2)


Value returned by TParser.Token (1 ) when a string was found in the input stream.


toSymbol  =  (1)


Value returned by TParser.Token (1 ) when a symbol was found in the input stream.


toWString  =  (5)


Value returned by TParser.Token (1 ) when a widestring was found in the input stream.



                                                                 199

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



2.3.2        Types

  =  -MaxLongint..MaxLongint


This documentation describes the FPC classes unit.  The Classes unit contains basic classes
for the Free Component Library (FCL):


     o  a TList (328  ) class for maintaining lists of pointers,

     o  TStringList (378  ) for lists of strings,

     o  TCollection (279  ) to manage collections of objects

     o  TStream (364  ) classes to support streaming.


Furthermore  it  introduces  methods  for  object  persistence,  and  classes  that  understand  an
owner-owned relationship, with automatic memory management.


HMODULE  =  PtrInt


FPC doesn't support modules yet, so this is a dummy type.


HRSRC  =  TFPResourceHandle


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 (210  ) record.


PStringItemList  =  ^TStringItemList


Pointer to a TStringItemList (210  ).


TActiveXRegType  =  (axrComponentOnly,axrIncludeDescendants)



                      Table 2.2:  Enumeration values for type TActiveXRegType


                                   __Value______________________________Explanation________
                                     axrComponentOnly
                                     axrIncludeDescendants



This type is provided for compatibility only, and is currently not used in Free Pascal.


TAlignment  =  (taLeftJustify,taRightJustify,taCenter)



                                                                 200

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



                           Table 2.3:  Enumeration values for type TAlignment


                        __Value__________________Explanation___________________________________________
                          taCenter                Text is displayed centered.
                          taLeftJustify           Text is displayed aligned to the left
                          taRightJustify          Text is displayed aligned to the right.



The TAlignment type is used to specify the alignment of the text in controls that display a
text.


TAncestorNotFoundEvent  =  procedure(Reader:  TReader;
                                                         const  ComponentName:  string;
                                                         ComponentClass:  TPersistentClass;
                                                         var  Component:  TComponent)  of  object


This event occurs when an ancestor component cannot be found.


TBasicActionClass  =  Class  of  TBasicAction


TBasicAction (254  ) class reference.


TBasicActionLinkClass  =  Class  of  TBasicActionLink


TBasicActionLink (258  ) class reference.


TBiDiMode  =  (bdLeftToRight,bdRightToLeft,bdRightToLeftNoAlign,
                     bdRightToLeftReadingOnly)



                           Table 2.4:  Enumeration values for type TBiDiMode


     __Value_____________________________________Explanation_____________________________________________________________
       bdLeftToRight                             Texts read from left to right.
       bdRightToLeft                             Texts read from right to left.
       bdRightToLeftNoAlign                      Texts read from right to left, but not right-aligned
       bdRightToLeftReadingOnly                  Texts read from right to left



TBiDiMode describes bi-directional support for displaying texts.


TBitArray  =  Array[0..MaxBitRec-1]  of  Cardinal


Array to store bits.


TCollectionItemClass  =  Class  of  TCollectionItem


TCollectionItemClass  is  used  by  the  TCollection.ItemClass  (1 )  property  of  TCollection
(279  ) to identify the descendent class of TCollectionItem (286  ) which should be created and
managed.



                                                                 201

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



TCollectionNotification  =  (cnAdded,cnExtracting,cnDeleting)



                   Table 2.5:  Enumeration values for type TCollectionNotification


                      __Value_________________Explanation_______________________________________________
                        cnAdded               An item is added to the collection.
                        cnDeleting            An item is deleted from the collection.
                        cnExtracting          An item is extracted from the collection.



TCollectionNotification is used in the TCollection (279  ) class to send notifications about
changes to the collection.


TCollectionSortCompare  =  function(Item1:  TCollectionItem;
                                                        Item2:  TCollectionItem)  :  Integer


TCollectionSortCompare is the prototype for a callback used in the TCollection.Sort (1 )
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  (289  )  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)


Indicates the state of the component during the streaming process.


TComponentStyle=  Set  of  (csInheritable,csCheckPropAvail,csSubComponent,
                                         csTransient)


Describes the style of the component.


TCreateComponentEvent  =  procedure(Reader:  TReader;
                                                        ComponentClass:  TComponentClass;
                                                        var  Component:  TComponent)  of  object


Event handler type, occurs when a component instance must be created when a component
is read from a stream.



                                                                 202

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



TDataModuleClass  =  Class  of  TDataModule


TDataModuleClass defines the class pointer for TDataModule (303  ).


TDuplicates  =  Types.TDuplicates


Type to describe what to do with duplicate values in a TStringlist (378  ).


TExceptionClass  =  Class  of  Exception


TExceptionClass is the class pointer for the Exception (1612   ) class, defined in the SysUtils
(1450   ) unit.


TFilerFlag  =  (ffInherited,ffChildPos,ffInline)



                            Table 2.6:  Enumeration values for type TFilerFlag


                 __Value_____________Explanation_____________________________________________________________
                   ffChildPos        The position of the child on it's parent is included.
                   ffInherited       Stored object is an inherited object.
                   ffInline          Used for frames.



The  TFiler  class  uses  this  enumeration  type  to  decide  whether  the  streamed  object  was
streamed as part of an inherited form or not.


TFilerFlags  =  Set  of  TFilerFlag


Set of TFilerFlag (203  )


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 (215  ) 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.



                                                                 203

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



TFindMethodEvent  =  procedure(Reader:  TReader;const  MethodName:  string;
                                               var  Address:  Pointer;var  Error:  Boolean)
                                                 of  object


If a TReader (349  ) instance needs to locate a method and it doesn't find it in the streamed
form, then the OnFindMethod (1 ) event handler will be called, if one is installed.  This event
can be assigned in order to use different locating methods.  If a method is found,  then its
address should be returned in Address.  The Error should be set to True if the reader should
raise  an  exception  after  the  event  was  handled.  If  it  is  set  to  False  no  exception  will  be
raised, even if no method was found.  On entry, Error will be set to True.


TGetChildProc  =  procedure(Child:  TComponent)  of  object


Callback used when obtaining child components.


TGetStrProc  =  procedure(const  S:  string)  of  object


This event is used as a callback to retrieve string values.  It is used, among other things, to
pass along string properties in property editors.


THandle  =  System.THandle


This type is used as the handle for THandleStream (318  ) stream descendents


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 2.7:  Enumeration values for type THelpType


                                __Value______________Explanation______________________________
                                  htContext          Help type:  Context ID help.
                                  htKeyword          Help type:  Keyword help



Enumeration type specifying the kind of help requested.


TIdentMapEntry  =  record
   Value  :  Integer;
   Name  :  string;
end



TIdentMapEntry  is  used  internally  by  the  IdentToInt  (218  )  and  IntToIdent  (219  )  calls  to
store the mapping between the identifiers and the integers they represent.


TIdentToInt  =  function(const  Ident:  string;var  Int:  LongInt)  :  Boolean



                                                                 204

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



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 (224  ) call.


TInitComponentHandler  =  function(Instance:  TComponent;
                                                      RootAncestor:  TClass)  :  Boolean


TInitComponentHandler is a callback type.  It is used in the InitInheritedComponent (219  )
call  to  initialize  a  component.  Callbacks  of  this  type  are  registered  with  the  RegisterInit-
ComponentHandler (224  ) 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 (224  ) call.


TLeftRight  =  taLeftJustify..taRightJustify


TLeftRight is a subrange type based on the TAlignment (201  ) enumerated type.  It contains
only the left and right alignment constants.


TListAssignOp  =  (laCopy,laAnd,laOr,laXor,laSrcUnique,laDestUnique)



                         Table 2.8:  Enumeration values for type TListAssignOp



__Value_________________Explanation________________________________________________________________________________________________*
 *________
  laAnd                 Remove all elements not first second list
  laCopy                Clear list and copy all strings from second list.
  laDestUnique          Keep all elements that exists only in list2
  laOr                  Add all elements from second (and optional third) list, eliminate duplicates
  laSrcUnique           Just keep all elements that exist only in source list
  laXor                 Remove elements in second lists, Add all elements from second list not in first list



This type determines what operation TList.Assign (1 ) or TFPList.assign (1 ) performs.


TListCallback  =  Types.TListCallback


TListCallback  is  the  method  callback  prototype  for  the  function  that  is  passed  to  the
TFPList.ForEachCall (1 ) 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)



                                                                 205

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



                       Table 2.9:  Enumeration values for type TListNotification


            __Value_______________Explanation______________________________________________________________________
              lnAdded             List change notification:  Element added to the list.
              lnDeleted           List change notification:  Element deleted from the list.
              lnExtracted         List change notification:  Element extracted from the list.



Kind of list notification event.


TListSortCompare  =  function(Item1:  Pointer;Item2:  Pointer)  :  Integer


Callback type for the list sort algorithm.


TListStaticCallback  =  Types.TListStaticCallback


TListCallback is the procedurald callback prototype for the function that is passed to the
TFPList.ForEachCall (1 ) 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 2.10:  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)



                          Table 2.11:  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.



                                                                 206

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



TPersistentClass  =  Class  of  TPersistent


TPersistentClass is the class reference type for the TPersistent (347  ) class.


TPoint  =  Types.TPoint


This record describes a coordinate.  It is used to handle the Top (1 ) and Left (1 ) properties
of TComponent (289  ).

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 (1 ) 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 (347  ) descendent to read user properties from a stream during the streaming process.
The Reader argument is the writer object which can be used read properties from the stream.


TReadWriteStringPropertyEvent  =  procedure(Sender:  TObject;
                                                                     const  Instance:  TPersistent;
                                                                     PropInfo:  PPropInfo;
                                                                     var  Content:  string)  of  object


TReadWriteStringPropertyEvent is the prototype for the TReader.OnReadStringProperty
(1 ) 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.



                                                                 207

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



TRect  =  Types.TRect


TRect describes a rectangle in space with its upper-left (in (Top,Left>)) and lower-right (in
(Bottom ,Right)) corners.


TReferenceNameEvent  =  procedure(Reader:  TReader;var  Name:  string)
                                                      of  object


Occurs when a named object needs to be looked up.


TSeekOrigin  =  (soBeginning,soCurrent,soEnd)



                          Table 2.12:  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 (1 ) 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  (1 )
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


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)



                                                                 208

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



                      Table 2.13:  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  =  Low(Word)..High(Word)


Enumeration type to identify shortcut key combinations.


TSmallPoint  =  record
   x  :  SmallInt;
   y  :  SmallInt;
end



Same  as  TPoint  (207  ),  only  the  X  and  Y  ranges  are  limited  to  2-byte  integers  instead  of
4-byte integers.


TStreamOwnership  =  (soReference,soOwned)



                     Table 2.14:  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 (373  ) acts, when the adapter is freed.


TStreamProc  =  procedure(Stream:  TStream)  of  object



                                                                 209

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



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 (378  ) string
list instance.  It should never be used directly.


TStringItemList  =  Array[0..MaxListSize]  of  TStringItem


This declaration is provided for Delphi compatibility, it is not used in Free Pascal.


TStringListSortCompare  =  function(List:  TStringList;Index1:  Integer;
                                                        Index2:  Integer)  :  Integer


Callback type used in stringlist compares.


TSynchronizeProcVar  =  procedure


Synchronize callback type


TThreadMethod  =  procedure  of  object


Procedure variable used when synchronizing threads.


TThreadPriority  =  (tpIdle,tpLowest,tpLower,tpNormal,tpHigher,tpHighest,
                               tpTimeCritical)



                       Table 2.15:  Enumeration values for type TThreadPriority


                __Value___________________Explanation_________________________________________________________
                  tpHigher                Thread runs at high priority
                  tpHighest               Thread runs at highest possible priority.
                  tpIdle                  Thread only runs when other processes are idle.
                  tpLower                 Thread runs at a lower priority.
                  tpLowest                Thread runs at the lowest priority.
                  tpNormal                Thread runs at normal process priority.
                  tpTimeCritical          Thread runs at realtime priority.



Enumeration specifying the priority at which a thread runs.


TValueType  =  (vaNull,vaList,vaInt8,vaInt16,vaInt32,vaExtended,vaString,
                       vaIdent,vaFalse,vaTrue,vaBinary,vaSet,vaLString,vaNil,
                       vaCollection,vaSingle,vaCurrency,vaDate,vaWString,vaInt64,
                       vaUTF8String,vaUString,vaQWord)



                                                                 210

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



                          Table 2.16:  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
(1 )  event.    Writer  is  the  sender  of  the  event,  Instance  is  the  instance  that  is  being
streamed.  PropInfo is a pointer to the RTTI information for the property being written, and
MethodValue is the value of the method that the property was set to.  DefMethodCodeValue
is set to the default value of the property (Nil or the parent value).  Handled should be set
to True if the handler set the property succesfully.


TWriterProc  =  procedure(Writer:  TWriter)  of  object


The TWriterProc writer procedure is a callback procedure which will be used by a TPersis-
tent (347  ) descendent to write user properties from a stream during the streaming process.
The Writer argument is the writer object which can be used write properties to the stream.



2.3.3        Variables

AddDataModule  :  procedure(DataModule:  TDataModule)  of  object



                                                                 211

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



AddDataModule can be set by an IDE or a streaming mechanism to receive notification when
a new instance of a TDataModule (303  ) 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 (303  ) 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 (303  ) descendent is freed.


WakeMainThread  :  TNotifyEvent  =  nil


WakeMainThread  is  called  by  the  TThread.synchronize  (1 )  call.   It  should  alert  the  main
program  thread  that  a  thread  is  waiting  for  synchronization.  The  call  is  executed  by  the
thread, and should therefore NOT synchronize the thread, but should somehow signal the
main thread that a thread is waiting for synchronization.  For example, by sending a message.



                                                                 212

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.4         Procedures  and  functions



                2.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 (226  ), GroupDescendentsWith (217  ), ClassGroupOf (214  )



                2.4.2        BeginGlobalLoading

    Synopsis:    Not yet implemented

Declaration:     procedure  BeginGlobalLoading

    Visibility:   default

Description:     Not yet implemented



                2.4.3        BinToHex

    Synopsis:    Convert a binary buffer to a hexadecimal string

Declaration:     procedure  BinToHex(BinValue:  PChar;HexValue:  PChar;BinBufSize:  Integer)

    Visibility:   default

Description:     BinToHex converts the byte values in BinValue to a string consisting of 2-charachter hex-
                adecimal strings in HexValue.  BufSize specifies the length of  BinValue, which means that
                HexValue must have size 2*BufSize.

                For example a buffer containing the byte values 255 and 0 will be converted to FF00.

       Errors:   No length checking is done, so if an invalid size is specified, an exception may follow.

    See also:    HexToBin (218  )



                2.4.4        Bounds

    Synopsis:    Returns a TRect structure with the bounding rect of the given location and size.

Declaration:     function  Bounds(ALeft:  Integer;ATop:  Integer;AWidth:  Integer;
                                         AHeight:  Integer)  :  TRect

    Visibility:   default



                                                                                 213

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     Bounds returns a TRect (208  ) 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 (222  )



                2.4.5        CheckSynchronize

    Synopsis:    Check whether there are any synchronize calls in the synchronize queue.

Declaration:     function  CheckSynchronize(timeout:  LongInt)  :  Boolean

    Visibility:   default

Description:     CheckSynchronize should be called regularly by the main application thread to handle any
                TThread.synchronize (1 ) calls that may be waiting for execution by the main thread.

    See also:    TThread.synchronize (1 )



                2.4.6        ClassGroupOf

    Synopsis:    Returns the class group to which an instance or class belongs

Declaration:     function  ClassGroupOf(AClass:  TPersistentClass)  :  TPersistentClass
                function  ClassGroupOf(Instance:  TPersistent)  :  TPersistentClass

    Visibility:   default

Description:     ClassGroupOf returns the class group to which AClass or Instance belongs.

       Errors:   The result is Nil if no matching class group is found.

    See also:    StartClassGroup (226  ), ActivateClassGroup (213  ), GroupDescendentsWith (217  )



                2.4.7        CollectionsEqual

    Synopsis:    Returns True if two collections are equal.

Declaration:     function  CollectionsEqual(C1:  TCollection;C2:  TCollection)  :  Boolean
                function  CollectionsEqual(C1:  TCollection;C2:  TCollection;
                                                         Owner1:  TComponent;Owner2:  TComponent)
                                                           :  Boolean

    Visibility:   default

Description:     CollectionsEqual is not yet implemented.  It simply returns False



                2.4.8        EndGlobalLoading

    Synopsis:    Not yet implemented.

Declaration:     procedure  EndGlobalLoading

    Visibility:   default

Description:     Not yet implemented.



                                                                                 214

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.4.9        ExtractStrings

    Synopsis:    Split a string in different words.

Declaration:     function  ExtractStrings(Separators:  TSysCharSet;WhiteSpace:  TSysCharSet;
                                                      Content:  PChar;Strings:  TStrings)  :  Integer

    Visibility:   default

Description:     ExtractStrings splits Content (a null-terminated string) into words, and adds the words
                to  the  Strings  stringlist.  The  words  are  separated  by  Separators  and  any  characters  in
                whitespace  are  stripped  from  the  strings.   The  space  and  CR/LF  characters  are  always
                considered whitespace.

       Errors:   No length checking is performed on Content.  If no null-termination character is present, an
                access violation may occur.  Likewise, if Strings is not valid, an access violation may occur.



                2.4.10         FindClass

    Synopsis:    Returns the class pointer of a class with given name.

Declaration:     function  FindClass(const  AClassName:  string)  :  TPersistentClass

    Visibility:   default

Description:     FindClass  searches  for  the  class  named  ClassName  in  the  list  of  registered  classes  and
                returns a class pointer to the definition.  If no class with the given name could be found, an
                exception is raised.

                The GetClass (216  ) function does not raise an exception when it does not find the class, but
                returns a Nil pointer instead.

    See also:    RegisterClass (222  ), GetClass (216  )



                2.4.11         FindGlobalComponent

    Synopsis:    Callback used when a component must be found.

Declaration:     function  FindGlobalComponent(const  Name:  string)  :  TComponent

    Visibility:   default

Description:     FindGlobalComponent is a callback of type TFindGlobalComponent (203  ).  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 (203  )



                2.4.12         FindIdentToInt

    Synopsis:    Return the string to integer converter for an integer type

Declaration:     function  FindIdentToInt(AIntegerType:  Pointer)  :  TIdentToInt

    Visibility:   default



                                                                                 215

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     FindIdentToInt returns the handler that handles the conversion of a string representation
                to an integer that can be used in component streaming, when IdentToInt (218  ) is called.

       Errors:   Nil is returned if no handler is registered for the given type.



                2.4.13         FindIntToIdent

    Synopsis:    Return the integer to string converter for an integer type

Declaration:     function  FindIntToIdent(AIntegerType:  Pointer)  :  TIntToIdent

    Visibility:   default

Description:     FindIntToIdent returns the handler that handles the conversion of an integer to a string
                representation that can be used in component streaming, when IntToIdent (219  ) is called.

       Errors:   Nil is returned if no handler is registered for the given type.

    See also:    IntToIdent (219  ), TIntToIdent (205  ), FindIdentToInt (215  )



                2.4.14         FindNestedComponent

    Synopsis:    Finds the component with name path starting at the indicated root component.

Declaration:     function  FindNestedComponent(Root:  TComponent;APath:  string;
                                                              CStyle:  Boolean)  :  TComponent

    Visibility:   default

Description:     FindNestedComponent will descend through the list of owned components (starting at Root)
                and will return the component whose name path matches NamePath.  As a path separator
                the characters .  (dot), - (dash) and > (greater than) can be used

    See also:    GlobalFixupReferences (217  )



                2.4.15         GetClass

    Synopsis:    Returns the class pointer of a class with given name.

Declaration:     function  GetClass(const  AClassName:  string)  :  TPersistentClass

    Visibility:   default

Description:     GetClass searches for the class named ClassName in the list of registered classes and returns
                a  class  pointer  to  the  definition.   If  no  class  with  the  given  name  could  be  found,  Nil  is
                returned.

                The FindClass (215  ) function will raise an exception if the does not find the class.

    See also:    RegisterClass (222  ), GetClass (216  )



                                                                                 216

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.4.16         GetFixupInstanceNames

    Synopsis:    Returns  the  names  of  elements  that  need  to  be  resolved  for  the  root  component,  whose
                reference contains ReferenceRootName

Declaration:     procedure  GetFixupInstanceNames(Root:  TComponent;
                                                                   const  ReferenceRootName:  string;
                                                                   Names:  TStrings)

    Visibility:   default

Description:     GetFixupInstanceNames examines the list of unresolved references and returns the names
                of classes that contain unresolved references to the Root component in the list Names.  The
                list is not cleared prior to filling it.

    See also:    GetFixupReferenceNames (217  ), GlobalFixupReferences (217  )



                2.4.17         GetFixupReferenceNames

    Synopsis:    Returns the names of elements that need to be resolved for the root component.

Declaration:     procedure  GetFixupReferenceNames(Root:  TComponent;Names:  TStrings)

    Visibility:   default

Description:     GetFixupReferenceNames examines the list of unresolved references and returns the names
                of properties that must be resolved for the component Root in the list Names.  The list is not
                cleared prior to filling it.

    See also:    GetFixupInstanceNames (217  ), GlobalFixupReferences (217  )



                2.4.18         GlobalFixupReferences

    Synopsis:    Called to resolve unresolved references after forms are loaded.

Declaration:     procedure  GlobalFixupReferences

    Visibility:   default

Description:     GlobalFixupReferences  runs  over  the  list  of  unresolved  references  and  tries  to  resolve
                them.   This  routine  should  under  normal  circumstances  not  be  called  in  an  application
                programmer's code.  It is called automatically by the streaming system after a component
                has  been  instantiated  and  its  properties  read  from  a  stream.   It  will  attempt  to  resolve
                references to other global components.

    See also:    GetFixupReferenceNames (217  ), GetFixupInstanceNames (217  )



                2.4.19         GroupDescendentsWith

    Synopsis:    Add class to the group of another class.

Declaration:     procedure  GroupDescendentsWith(AClass:  TPersistentClass;
                                                                  AClassGroup:  TPersistentClass)

    Visibility:   default



                                                                                 217

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     GroupDescendentsWith adds AClass to the group that AClassGroup belongs to.  If AClassGroup
                belongs to more than 1 group, then it is added to the group which contains the nearest an-
                cestor.

                The  class  registration  and  streaming  mechanism  allows  to  organize  the  classes  in  groups.
                This allows an IDE to form groups of classes,  which can be enabled or disabled.  It is not
                needed at Run-Time.

    See also:    StartClassGroup (226  ), ActivateClassGroup (213  ), ClassGroupOf (214  )



                2.4.20         HexToBin

    Synopsis:    Convert a hexadecimal string to a binary buffer

Declaration:     function  HexToBin(HexValue:  PChar;BinValue:  PChar;BinBufSize:  Integer)
                                              :  Integer

    Visibility:   default

Description:     HexToBin scans the hexadecimal string representation in HexValue and transforms every 2
                character hexadecimal number to a byte and stores it in BinValue.  The buffer size is the
                size  of  the  binary  buffer.  Scanning  will  stop  if  the  size  of  the  binary  buffer  is  reached  or
                when an invalid character is encountered.  The return value is the number of stored bytes.

       Errors:   No length checking is done, so if an invalid size is specified, an exception may follow.

    See also:    BinToHex (213  )



                2.4.21         IdentToInt

    Synopsis:    Looks up an integer value in a integer-to-identifier map list.

Declaration:     function  IdentToInt(const  Ident:  string;var  Int:  LongInt;
                                                const  Map:  Array  of  TIdentMapEntry)  :  Boolean

    Visibility:   default

Description:     IdentToInt searches Map for an entry whose Name field matches Ident and returns the cor-
                responding integer value in Int.  If a match was found, the function returns True, otherwise,
                False is returned.

    See also:    TIdentToInt (205  ), TIntToIdent (205  ), IntToIdent (219  ), TIdentMapEntry (204  )



                2.4.22         InitComponentRes

    Synopsis:    Provided for Delphi compatibility only

Declaration:     function  InitComponentRes(const  ResName:  string;Instance:  TComponent)
                                                           :  Boolean

    Visibility:   default

Description:     This function is provided for Delphi compatibility.  It always returns false.

    See also:    ReadComponentRes (221  )



                                                                                 218

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.4.23         InitInheritedComponent

    Synopsis:    Initializes a component descending from RootAncestor

Declaration:     function  InitInheritedComponent(Instance:  TComponent;
                                                                   RootAncestor:  TClass)  :  Boolean

    Visibility:   default

Description:     InitInheritedComponent  should  be  called  from  a  constructor  to  read  properties  of  the
                component Instance from the streaming system.  The RootAncestor class is the root class
                from which Instance is a descendent.  This must be one of  TDatamodule, TCustomForm or
                TFrame.

                The function returns True if the properties were successfully read from a stream or False if
                some error occurred.

    See also:    ReadComponentRes (221  ), ReadComponentResEx (221  ), ReadComponentResFile (222  )



                2.4.24         IntToIdent

    Synopsis:    Looks up an identifier for an integer value in a identifier-to-integer map list.

Declaration:     function  IntToIdent(Int:  LongInt;var  Ident:  string;
                                                const  Map:  Array  of  TIdentMapEntry)  :  Boolean

    Visibility:   default

Description:     IdentToInt  searches  Map  for  an  entry  whose  Value  field  matches  Int  and  returns  the
                corresponding identifier in Ident.  If a match was found, the function returns True, otherwise,
                False is returned.

    See also:    TIdentToInt (205  ), TintToIdent (205  ), IdentToInt (218  ), TIdentMapEntry (204  )



                2.4.25         InvalidPoint

    Synopsis:    Check whether a point is invalid.

Declaration:     function  InvalidPoint(X:  Integer;Y:  Integer)  :  Boolean
                function  InvalidPoint(const  At:  TPoint)  :  Boolean
                function  InvalidPoint(const  At:  TSmallPoint)  :  Boolean

    Visibility:   default

Description:     InvalidPoint  returns  True  if  the  X  and  Y  coordinates  (of  the  TPoint  or  TSmallPoint
                records, if one of these versions is used) are -1.

    See also:    TPoint (207  ), TSmallPoint (209  ), PointsEqual (221  )



                2.4.26         LineStart

    Synopsis:    Finds the start of a line in Buffer before BufPos.

Declaration:     function  LineStart(Buffer:  PChar;BufPos:  PChar)  :  PChar

    Visibility:   default

Description:     LineStart reversely scans Buffer starting at BufPos for a linefeed character.  It returns a
                pointer at the linefeed character.



                                                                                 219

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.4.27         NotifyGlobalLoading

    Synopsis:    Not yet implemented.

Declaration:     procedure  NotifyGlobalLoading

    Visibility:   default

Description:     Not yet implemented.



                2.4.28         ObjectBinaryToText

    Synopsis:    Converts an object stream from a binary to a text format.

Declaration:     procedure  ObjectBinaryToText(Input:  TStream;Output:  TStream;
                                                              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 (220  )



                2.4.29         ObjectResourceToText

    Synopsis:    Converts an object stream from a (windows) resource to a text format.

Declaration:     procedure  ObjectResourceToText(Input:  TStream;Output:  TStream)

    Visibility:   default

Description:     ObjectResourceToText reads the resource header from the Input stream and then passes
                the streams to ObjectBinaryToText (220  )

    See also:    ObjectBinaryToText (220  ), ObjectTextToResource (220  )



                2.4.30         ObjectTextToBinary

    Synopsis:    Converts an object stream from a text to a binary format.

Declaration:     procedure  ObjectTextToBinary(Input:  TStream;Output:  TStream)

    Visibility:   default

Description:     Converts an object stream from a text to a binary format.



                2.4.31         ObjectTextToResource

    Synopsis:    Converts an object stream from a text to a (windows) resource format.

Declaration:     procedure  ObjectTextToResource(Input:  TStream;Output:  TStream)

    Visibility:   default



                                                                                 220

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (220  ), ObjectResourceToText (220  )



                2.4.32         Point

    Synopsis:    Returns a TPoint record with the given coordinates.

Declaration:     function  Point(AX:  Integer;AY:  Integer)  :  TPoint

    Visibility:   default

Description:     Point returns a TPoint (207  ) record with the given coordinates AX and AY filled in.

    See also:    TPoint (207  ), SmallPoint (225  ), Rect (222  ), Bounds (213  )



                2.4.33         PointsEqual

    Synopsis:    Check whether two TPoint variables are equal.

Declaration:     function  PointsEqual(const  P1:  TPoint;const  P2:  TPoint)  :  Boolean
                function  PointsEqual(const  P1:  TSmallPoint;const  P2:  TSmallPoint)
                                                   :  Boolean

    Visibility:   default

Description:     PointsEqual compares the P1 and P2 points (of type TPoint (207  ) or TSmallPoint (209  ))
                and returns True if the X and Y coordinates of the points are equal, or False otherwise.

    See also:    TPoint (207  ), TSmallPoint (209  ), InvalidPoint (219  )



                2.4.34         ReadComponentRes

    Synopsis:    Read component properties from a resource in the current module

Declaration:     function  ReadComponentRes(const  ResName:  string;Instance:  TComponent)
                                                           :  TComponent

    Visibility:   default

Description:     This function is provided for Delphi compatibility.  It always returns Nil.



                2.4.35         ReadComponentResEx

    Synopsis:    Read component properties from a resource in the specified module

Declaration:     function  ReadComponentResEx(HInstance:  THandle;const  ResName:  string)
                                                              :  TComponent

    Visibility:   default

Description:     This function is provided for Delphi compatibility.  It always returns Nil.



                                                                                 221

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.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  (1 )
                method to read the state of the component from the stream.

    See also:    TStream.ReadComponentRes (1 ), WriteComponentResFile (227  )



                2.4.37         Rect

    Synopsis:    Returns a TRect record with the given coordinates.

Declaration:     function  Rect(ALeft:  Integer;ATop:  Integer;ARight:  Integer;
                                      ABottom:  Integer)  :  TRect

    Visibility:   default

Description:     Rect returns a TRect (208  ) 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 (208  ), Point (221  ), SmallPoint (225  ), Bounds (213  )



                2.4.38         RedirectFixupReferences

    Synopsis:    Redirects references under the root object from OldRootName to NewRootName

Declaration:     procedure  RedirectFixupReferences(Root:  TComponent;
                                                                       const  OldRootName:  string;
                                                                       const  NewRootName:  string)

    Visibility:   default

Description:     RedirectFixupReferences  examines  the  list  of  unresolved  references  and  replaces  refer-
                ences to a root object named OldRootName with references to root object NewRootName.

                An  application  programmer  should  never  need  to  call  RedirectFixupReferences.   This
                function can be used by an IDE to support redirection of broken component links.

    See also:    RemoveFixupReferences (225  )



                2.4.39         RegisterClass

    Synopsis:    Registers a class with the streaming system.

Declaration:     procedure  RegisterClass(AClass:  TPersistentClass)

    Visibility:   default

Description:     RegisterClass registers the class AClass in the streaming system.  After the class has been
                registered, it can be read from a stream when a reference to this class is encountered.

    See also:    RegisterClasses (223  ), RegisterClassAlias (223  ), RegisterComponents (223  ), UnregisterClass
                (226  )



                                                                                 222

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.4.40         RegisterClassAlias

    Synopsis:    Registers a class alias with the streaming system.

Declaration:     procedure  RegisterClassAlias(AClass:  TPersistentClass;
                                                              const  Alias:  string)

    Visibility:   default

Description:     RegisterClassAlias  registers  a  class  alias  in  the  streaming  system.   If  a  reference  to  a
                class Alias is encountered in a stream, then an instance of the class AClass will be created
                instead by the streaming code.

    See also:    RegisterClass (222  ), RegisterClasses (223  ), RegisterComponents (223  ), UnregisterClass (226  )



                2.4.41         RegisterClasses

    Synopsis:    Registers multiple classes with the streaming system.

Declaration:     procedure  RegisterClasses(AClasses:  Array  of  TPersistentClass)

    Visibility:   default

Description:     RegisterClasses registers the specified classes AClass in the streaming system.  After the
                classes have been registered, they can be read from a stream when a reference to this class
                is encountered.

    See also:    RegisterClass (222  ), RegisterClassAlias (223  ), RegisterComponents (223  ), UnregisterClass
                (226  )



                2.4.42         RegisterComponents

    Synopsis:    Registers components for the component palette.

Declaration:     procedure  RegisterComponents(const  Page:  string;
                                                              ComponentClasses:  Array  of  TComponentClass)

    Visibility:   default

Description:     RegisterComponents  registers  the  component  on  the  appropriate  component  page.   The
                component pages can be used by an IDE to display the known components so an application
                programmer may pick and use the components in his programs.

                Registercomponents  inserts  the  component  class  in  the  correct  component  page.   If  the
                RegisterComponentsProc procedure is set, this is called as well.  Note that this behaviour is
                different from Delphi's behaviour where an exception will be raised if the procedural variable
                is not set.

    See also:    RegisterClass (222  ), RegisterNoIcon (224  )



                2.4.43         RegisterFindGlobalComponentProc

    Synopsis:    Register a component searching handler

Declaration:     procedure  RegisterFindGlobalComponentProc
                                                                                    (AFindGlobalComponent:  TFindGlobalComponent)

    Visibility:   default



                                                                                 223

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     RegisterFindGlobalComponentProc registers a global component search callback AFindGlobalComponent.
                When FindGlobalComponent (215  ) is called, then this callback will be used to search for the
                component.

       Errors:   None.

    See also:    FindGlobalComponent (215  ), UnRegisterFindGlobalComponentProc (226  )



                2.4.44         RegisterInitComponentHandler

    Synopsis:    Register a component initialization handler

Declaration:     procedure  RegisterInitComponentHandler(ComponentClass:  TComponentClass;
                                                                               Handler:  TInitComponentHandler)

    Visibility:   default

Description:     RegisterInitComponentHandler registers a component initialization handler Handler for
                the  component  ComponentClass.   This  handler  will  be  used  to  initialize  descendents  of
                ComponentClass in the InitInheritedComponent (219  ) call.

    See also:    InitInheritedComponent (219  ), TInitComponentHandler (205  )



                2.4.45         RegisterIntegerConsts

    Synopsis:    Registers some integer-to-identifier mappings.

Declaration:     procedure  RegisterIntegerConsts(IntegerType:  Pointer;
                                                                   IdentToIntFn:  TIdentToInt;
                                                                   IntToIdentFn:  TIntToIdent)

    Visibility:   default

Description:     RegisterIntegerConsts  registers  a  pair  of  callbacks  to  be  used  when  an  integer  of  type
                IntegerType must be mapped to an identifier (using IntToIdentFn) or when an identifier
                must be mapper to an integer (using IdentToIntFn).

                Component programmers can use RegisterIntegerConsts to associate a series of identifier
                strings with integer values for a property.  A necessary condition is that the property should
                have a separate type declared using the type  integer syntax.  If a type of integer is defined
                in this way, an IDE can show symbolic names for the values of these properties.

                The  IntegerType  should  be  a  pointer  to  the  type  information  of  the  integer  type.   The
                IntToIdentFn and IdentToIntFn are two callbacks that will be used when converting be-
                tween the identifier and integer value and vice versa.  The functions IdentToInt (218  ) and
                IntToIdent (219  ) can be used to implement these callback functions.

    See also:    TIdentToInt (205  ), TIntToIdent (205  ), IdentToInt (218  ), IntToIdent (219  )



                2.4.46         RegisterNoIcon

    Synopsis:    Registers components that have no icon on the component palette.

Declaration:     procedure  RegisterNoIcon(ComponentClasses:  Array  of  TComponentClass)

    Visibility:   default

Description:     RegisterNoIcon performs the same function as RegisterComponents (223  ) except that it
                calls RegisterNoIconProc (212  ) instead of RegisterComponentsProc (212  )

    See also:    RegisterNoIconProc (212  ), RegisterComponents (223  )



                                                                                 224

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.4.47         RegisterNonActiveX

    Synopsis:    Register non-activex component.

Declaration:     procedure  RegisterNonActiveX(ComponentClasses:  Array  of  TComponentClass;
                                                              AxRegType:  TActiveXRegType)

    Visibility:   default

Description:     Not yet implemented in Free Pascal



                2.4.48         RemoveFixupReferences

    Synopsis:    Removes references to rootname from the fixup list.

Declaration:     procedure  RemoveFixupReferences(Root:  TComponent;const  RootName:  string)

    Visibility:   default

Description:     RemoveFixupReferences examines the list of unresolved references and removes references
                to a root object pointing at Root or a root component named RootName.

                An application programmer should never need to call RemoveFixupReferences.  This func-
                tion can be used by an IDE to support removal of broken component links.

    See also:    RedirectFixupReferences (222  )



                2.4.49         RemoveFixups

    Synopsis:    Removes Instance from the fixup list.

Declaration:     procedure  RemoveFixups(Instance:  TPersistent)

    Visibility:   default

Description:     RemoveFixups removes all entries for component Instance from the list of unresolved ref-
                erences.a

    See also:    RedirectFixupReferences (222  ), RemoveFixupReferences (225  )



                2.4.50         SmallPoint

    Synopsis:    Returns a TSmallPoint record with the given coordinates.

Declaration:     function  SmallPoint(AX:  SmallInt;AY:  SmallInt)  :  TSmallPoint

    Visibility:   default

Description:     SmallPoint returns a TSmallPoint (209  ) record with the given coordinates AX and AY filled
                in.

    See also:    TSmallPoint (209  ), Point (221  ), Rect (222  ), Bounds (213  )



                                                                                 225

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.4.51         StartClassGroup

    Synopsis:    Start new class group.

Declaration:     procedure  StartClassGroup(AClass:  TPersistentClass)

    Visibility:   default

Description:     StartClassGroup starts a new class group and adds AClass to it.

                The  class  registration  and  streaming  mechanism  allows  to  organize  the  classes  in  groups.
                This allows an IDE to form groups of classes,  which can be enabled or disabled.  It is not
                needed at Run-Time.

    See also:    GroupDescendentsWith (217  ), ActivateClassGroup (213  ), ClassGroupOf (214  )



                2.4.52         UnRegisterClass

    Synopsis:    Unregisters a class from the streaming system.

Declaration:     procedure  UnRegisterClass(AClass:  TPersistentClass)

    Visibility:   default

Description:     UnregisterClass  removes  the  class  AClass  from  the  class  definitions  in  the  streaming
                system.

    See also:    UnRegisterClasses (226  ), UnRegisterModuleClasses (227  ), RegisterClass (222  )



                2.4.53         UnRegisterClasses

    Synopsis:    Unregisters multiple classes from the streaming system.

Declaration:     procedure  UnRegisterClasses(AClasses:  Array  of  TPersistentClass)

    Visibility:   default

Description:     UnregisterClasses  removes  the  classes  in  AClasses  from  the  class  definitions  in  the
                streaming system.



                2.4.54         UnregisterFindGlobalComponentProc

    Synopsis:    Remove a previously registered component searching handler.

Declaration:     procedure  UnregisterFindGlobalComponentProc
                                                                                       (AFindGlobalComponent:  TFindGlobalComponent)

    Visibility:   default

Description:     UnRegisterFindGlobalComponentProc unregisters the previously registered global compo-
                nent search callback AFindGlobalComponent.  After this call, when FindGlobalComponent
                (215  ) is called, then this callback will be no longer be used to search for the component.

       Errors:   None.

    See also:    FindGlobalComponent (215  ), RegisterFindGlobalComponentProc (223  )



                                                                                 226

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.4.55         UnRegisterModuleClasses

    Synopsis:    Unregisters classes registered by module.

Declaration:     procedure  UnRegisterModuleClasses(Module:  HMODULE)

    Visibility:   default

Description:     UnRegisterModuleClasses unregisters all classes which reside in the module Module.  For
                each registered class, the definition pointer is checked to see whether it resides in the module,
                and if it does, the definition is removed.

    See also:    UnRegisterClass (226  ), UnRegisterClasses (226  ), RegisterClasses (223  )



                2.4.56         WriteComponentResFile

    Synopsis:    Write component properties to a specified resource file

Declaration:     procedure  WriteComponentResFile(const  FileName:  string;
                                                                   Instance:  TComponent)

    Visibility:   default

Description:     WriteComponentResFile  starts  writing  properties  of  Instance  to  the  file  FileName.   It
                creates a filestream from FileName and then calls TStream.WriteComponentRes (1 ) method
                to write the state of the component to the stream.

    See also:    TStream.WriteComponentRes (1 ), ReadComponentResFile (222  )



                2.5         EBitsError



                2.5.1        Description

                When  an  index  of  a  bit  in  a  TBits  (272  )  is  out  of  the  valid  range  (0  to  Count-1)  then  a
                EBitsError exception is raised.



                2.6         EClassNotFound



                2.6.1        Description

                When  the  streaming  system  needs  to  create  a  component,  it  looks  for  the  class  pointer
                (VMT)  in  the  list  of  registered  classes  by  its  name.   If  this  name  is  not  found,  then  an
                EClassNotFound is raised.


    See also:    EFilerError (228  )



                2.7         EComponentError



                2.7.1        Description

                When an error occurs during the registration of a component, or when naming a component,
                then a EComponentError is raised.  Possible causes are:


                    1.  An name with an illegal character was assigned to a component.



                                                                                 227

            __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



                2.  A component with the same name and owner already exists.

                3.  The component registration system isn't set up properly.


See also:    TComponent (289  ), TComponent.Name (1 )



            2.8         EFCreateError



            2.8.1        Description

            When the operating system reports an error during creation of a new file in the Filestream
            Constructor (1 ), a EFCreateError is raised.


See also:    EStreamError (230  ), EFOpenError (228  )



            2.9         EFilerError



            2.9.1        Description

            This  class  serves  as  an  ancestor  class  for  exceptions  that  are  raised  when  an  error  occurs
            during component streaming.  A EFilerError exception is raised when a class is registered
            twice.


See also:    EStreamError (230  ), EReadError (229  )



            2.10          EFOpenError



            2.10.1         Description

            When the operating system reports an error during the opening of a file in the Filestream
            Constructor (1 ), a EFOpenError is raised.


See also:    EStreamError (230  ), EFCreateError (228  )



            2.11          EInvalidImage



            2.11.1         Description

            This exception is not used by Free Pascal but is provided for Delphi compatibility.



            2.12          EInvalidOperation



            2.12.1         Description

            This exception is not used in Free Pascal, it is defined for Delphi compatibiliy purposes only.



                                                                             228

            __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



            2.13          EListError



            2.13.1         Description

            If an error occurs in one of the TList (328  ) or TStrings (383  ) 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 (328  ), TStrings (383  )



            2.14          EMethodNotFound



            2.14.1         Description

            This  exception  is  no  longer  used  in  the  streaming  system.   This  error  is  replaced  by  a
            EReadError (229  ).


See also:    EFilerError (228  ), EReadError (229  )



            2.15          EOutOfResources



            2.15.1         Description

            This exception is not used in Free Pascal, it is defined for Delphi compatibiliy purposes only.



            2.16          EParserError



            2.16.1         Description

            When an error occurs during the parsing of a stream, an EParserError is raised.  Usually
            this indicates that an invalid token was found on the input stream, or the token read from
            the stream wasn't the expected token.


See also:    TParser (340  )



            2.17          EReadError



            2.17.1         Description

            If an error occurs when reading from a stream, a EReadError exception is raised.  Possible
            causes for this are:



                                                                             229

            __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



                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 (228  ), EWriteError (231  )



            2.18          EResNotFound



            2.18.1         Description

            This exception is not used by Free Pascal but is provided for Delphi compatibility.



            2.19          EStreamError



            2.19.1         Description

            An EStreamError is raised when an error occurs during reading from or writng to a stream:
            Possible causes are


                1.  Not enough data is available in the stream.

                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 (228  )



            2.20          EStringListError



            2.20.1         Description

            When an error occurs in one of the methods of TStrings (383  ) 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 (378  ) when TStringList.AllowDuplicates
                    (1 ) is False.


See also:    TStrings (383  ), TStringList (378  )



            2.21          EThread



            2.21.1         Description

            Thread error exception.



                                                                             230

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.22          EThreadDestroyCalled



                2.22.1         Description

                Exception raised when a thread is destroyed illegally.



                2.23          EWriteError



                2.23.1         Description

                If  an  error  occurs  when  writing  to  a  stream,  a  EWriteError  exception  is  raised.  Possible
                causes for this are:


                    1.  The stream doesn't allow writing.

                    2.  An error occurred when writing a property to a stream.


    See also:    EFilerError (228  ), EReadError (229  )



                2.24          IDesignerNotify



                2.24.1         Description

                IDesignerNotify  is  an  interface  that  can  be  used  to  communicate  changes  to  a  designer
                mechanism.  It offers functionality for detecting changes, and notifications when the compo-
                nent is destroyed.



                2.24.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  231       Modified            Notify that the component is modified.
                __231_______Notification________Notification_of_owner_changes______________________________________________________*
 *___________



                2.24.3         IDesignerNotify.Modified

    Synopsis:    Notify that the component is modified.

Declaration:     procedure  Modified

    Visibility:   default

Description:     Modified can be used to notify a designer of changes, indicating that components should
                be streamed.



                2.24.4         IDesignerNotify.Notification

    Synopsis:    Notification of owner changes

Declaration:     procedure  Notification(AnObject:  TPersistent;Operation:  TOperation)

    Visibility:   default

Description:     Notification is the interface counterpart of TComponent.Notification (1 ) which is used to
                communicate adds to the components.



                                                                                 231

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    See also:    TComponent.Notification (1 )



                2.25          IInterfaceComponentReference



                2.25.1         Description

                IInterfaceComponentReference is an interface to return the component that implements
                a given interface.  It is implemented by TComponent (289  ).


    See also:    TComponent (289  )



                2.25.2         Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                __232_______GetComponent_____________Return_component_instance_____________________________________________________*
 *___________



                2.25.3         IInterfaceComponentReference.GetComponent

    Synopsis:    Return component instance

Declaration:     function  GetComponent  :  TComponent

    Visibility:   default

Description:     GetComponent returns the component instance.

       Errors:   None.

    See also:    TComponent (289  )



                2.26          IInterfaceList



                2.26.1         Description

                IInterfaceList is an interface for maintaining a list of interfaces, strongly resembling the
                standard  TList  (328  )  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 (328  )



                                                                                 232

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.26.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  236       Add                   Add an interface to the list
                  235       Clear                 Clear the list
                  235       Delete                Remove an interface from the list
                  235       Exchange              Exchange 2 interfaces in the list
                  235       First                 Return the first non-empty interface in the list.
                  233       Get                   Retrieve an interface pointer from the list.
                  233       GetCapacity           Return the capacity of the list.
                  234       GetCount              Return the current number of elements in the list.
                  236       IndexOf               Return the index of an interface.
                  236       Insert                Insert an interface in the list.
                  236       Last                  Returns the last non-nil interface in the list.
                  237       Lock                  Lock the list
                  234       Put                   Write an item to the list
                  236       Remove                Remove an interface from the list
                  234       SetCapacity           Set the capacity of the list
                  234       SetCount              Set the number of items in the list
                __237_______Unlock________________Unlock_the_list._________________________________________________________________*
 *___________



                2.26.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  237       Capacity        rw           Capacity of the list
                  237       Count           rw           Current number of elements in the list.
                  238       Items           rw           Provides Index-based, sequential, access to the interfaces in
                _________________________________________the_list._________________________________________________________________*
 *___________



                2.26.4         IInterfaceList.Get

    Synopsis:    Retrieve an interface pointer from the list.

Declaration:     function  Get(i:  Integer)  :  IUnknown

    Visibility:   default

Description:     Get returns the interface pointer at position i in the list.  It serves as the Read method for
                the Items (1 ) property.

    See also:    IInterfaceList.Items (1 ), TList.Items (1 )



                2.26.5         IInterfaceList.GetCapacity

    Synopsis:    Return the capacity of the list.

Declaration:     function  GetCapacity  :  Integer

    Visibility:   default

Description:     GetCapacity returns the current capacity of the list.  It serves as the Read method for the
                Capacity (1 ) property.

    See also:    IInterfaceList.Capacity (1 ), TList.Capacity (1 )



                                                                                 233

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.26.6         IInterfaceList.GetCount

    Synopsis:    Return the current number of elements in the list.

Declaration:     function  GetCount  :  Integer

    Visibility:   default

Description:     It serves as the Read method for the Count (1 ) property.

    See also:    IInterfaceList.Count (1 ), TList.Count (1 )



                2.26.7         IInterfaceList.Put

    Synopsis:    Write an item to the list

Declaration:     procedure  Put(i:  Integer;item:  IUnknown)

    Visibility:   default

Description:     Put writes the interface Item at position I in the list.  It servers as the Write method for
                the Items (1 ) property.

    See also:    IInterfaceList.Items (1 ), TList.Items (1 )



                2.26.8         IInterfaceList.SetCapacity

    Synopsis:    Set the capacity of the list

Declaration:     procedure  SetCapacity(NewCapacity:  Integer)

    Visibility:   default

Description:     SetCapacity sets the capacity of the list to NewCapacity.  It serves as the Write method
                for the Capacity (1 ) property.

    See also:    IInterfaceList.Capacity (1 ), TList.Capacity (1 )



                2.26.9         IInterfaceList.SetCount

    Synopsis:    Set the number of items in the list

Declaration:     procedure  SetCount(NewCount:  Integer)

    Visibility:   default

Description:     SetCount  sets  the  count  of  the  list  to  NewCount.  It  serves  as  the  Write  method  for  the
                Capacity (1 )

    See also:    IInterfaceList.Count (1 ), TList.Count (1 )



                                                                                 234

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.26.10          IInterfaceList.Clear

    Synopsis:    Clear the list

Declaration:     procedure  Clear

    Visibility:   default

Description:     Clear removes all interfaces from the list.  All interfaces in the list will be cleared (i.e.  their
                reference count will decrease with 1)

    See also:    TList.Clear (1 )



                2.26.11          IInterfaceList.Delete

    Synopsis:    Remove an interface from the list

Declaration:     procedure  Delete(index:  Integer)

    Visibility:   default

Description:     Delete  removes  the  interface  at  position  Index  from  the  list.   It  does  this  by  explicitly
                clearing the interface and then removing the slot.

    See also:    TList.Clear (1 ), IInterfaceList.Add (1 ), IInterfaceList.Delete (1 ), IInterfaceList.Insert (1 )



                2.26.12          IInterfaceList.Exchange

    Synopsis:    Exchange 2 interfaces in the list

Declaration:     procedure  Exchange(index1:  Integer;index2:  Integer)

    Visibility:   default

Description:     Exchange exchanges 2 interfaces in the list at locations index1 and Index2.

    See also:    TList.Exchange  (1 ),  IInterfaceList.Add  (1 ),  IInterfaceList.Delete  (1 ),  IInterfaceList.Insert
                (1 )



                2.26.13          IInterfaceList.First

    Synopsis:    Return the first non-empty interface in the list.

Declaration:     function  First  :  IUnknown

    Visibility:   default

Description:     First returns the first non-empty interface in the list.

    See also:    TList.First (1 ), IInterfaceList.IndexOf (1 ), IInterfaceList.Last (1 )



                                                                                 235

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.26.14          IInterfaceList.IndexOf

    Synopsis:    Return the index of an interface.

Declaration:     function  IndexOf(item:  IUnknown)  :  Integer

    Visibility:   default

Description:     IndexOf returns the location in the list of the interface Item.  If there is no such interface
                in the list, then -1 is returned.

    See also:    TList.IndexOf (1 ), IInterfaceList.First (1 ), IInterfaceList.Last (1 )



                2.26.15          IInterfaceList.Add

    Synopsis:    Add an interface to the list

Declaration:     function  Add(item:  IUnknown)  :  Integer

    Visibility:   default

Description:     Add adds the interface Item to the list, and returns the position at which it has been added.

    See also:    TList.Add (1 ), IInterfaceList.Insert (1 ), IInterfaceList.Delete (1 )



                2.26.16          IInterfaceList.Insert

    Synopsis:    Insert an interface in the list.

Declaration:     procedure  Insert(i:  Integer;item:  IUnknown)

    Visibility:   default

Description:     Insert inserts the interface Item in the list, at position I, shifting all items one position.

    See also:    TList.Insert (1 ), IInterfaceList.Add (1 ), IInterfaceList.Delete (1 )



                2.26.17          IInterfaceList.Last

    Synopsis:    Returns the last non-nil interface in the list.

Declaration:     function  Last  :  IUnknown

    Visibility:   default

Description:     Last returns the last non-empty interface in the list.

    See also:    TList.Last (1 ), IInterfaceList.First (1 ), IInterfaceList.IndexOf (1 )



                2.26.18          IInterfaceList.Remove

    Synopsis:    Remove an interface from the list

Declaration:     function  Remove(item:  IUnknown)  :  Integer

    Visibility:   default

Description:     Remove searches for the first occurrence of  Item in the list and deletes it.

    See also:    TList.Remove (1 ), IInterfaceList.Delete (1 ), IInterfaceList.IndexOf (1 )



                                                                                 236

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.26.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 (1 ) is called.

    See also:    TList.Lock (1 ), IInterfaceList.Unlock (1 )



                2.26.20          IInterfaceList.Unlock

    Synopsis:    Unlock the list.

Declaration:     procedure  Unlock

    Visibility:   default

Description:     Unlock unlocks a locked list.  After a call to UnLock, other threads are again able to access
                the list.

    See also:    TList.UnLock (1 ), IInterfaceList.Lock (1 )



                2.26.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 (1 ), IInterfaceList.Count (1 )



                2.26.22          IInterfaceList.Count

    Synopsis:    Current number of elements in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   default

      Access:    Read,Write

Description:     Count  is  the  current  number  of  elements  in  the  list.   Setting  it  to  a  larger  number  will
                allocate empty slots.  Setting it to a smaller number will clear any interfaces that fall outside
                the new border.

    See also:    IInterfaceList.Capacity (1 ), TList.Count (1 )



                                                                                 237

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.26.23          IInterfaceList.Items

    Synopsis:    Provides Index-based, sequential, access to the interfaces in the list.

Declaration:     Property  Items[index:  Integer]:  IUnknown;  default

    Visibility:   default

      Access:    Read,Write

Description:     Items is the default property of the interface list and provides index-based array access to
                the interfaces in the list.  Allowed values for Index include 0 to Count-1

    See also:    IInterfaceList.Count (1 ), TList.Items (1 )



                2.27          IStreamPersist



                2.27.1         Description

                IStreamPersist defines an interface for object persistence streaming to a stream.  Any class
                implementing  this  interface  is  expected  to  be  able  to  save  or  load  it's  state  from  or  to  a
                stream.


    See also:    TPersistent (347  ), TComponent (289  ), TStream (364  )



                2.27.2         Method  overview

                __Page______Property____________________Description________________________________________________________________*
 *___________
                  238       LoadFromStream              Load persistent data from stream.
                __238_______SaveToStream________________Save_persistent_data_to_stream.____________________________________________*
 *___________



                2.27.3         IStreamPersist.LoadFromStream

    Synopsis:    Load persistent data from stream.

Declaration:     procedure  LoadFromStream(Stream:  TStream)

    Visibility:   default

Description:     LoadFromStream is the method called when the object should load it's state from the stream
                stream.   It  should  be  able  to  read  the  data  which  was  written  using  the  SavetoStream
                method.

    See also:    TPersistent (347  ), TComponent (289  ), TStream (364  ), IStreamPersist.SaveToStream (1 )



                2.27.4         IStreamPersist.SaveToStream

    Synopsis:    Save persistent data to stream.

Declaration:     procedure  SaveToStream(Stream:  TStream)

    Visibility:   default

Description:     SaveFromStream is the method called when the object should load it's state from the stream
                stream.   The  data  written  by  this  method  should  be  readable  by  the  LoadFromStream
                method.

    See also:    TPersistent (347  ), TComponent (289  ), TStream (364  ), IStreamPersist.LoadFromStream (1 )



                                                                                 238

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.28          IStringsAdapter



                2.28.1         Description

                Is not yet supported in Free Pascal.


    See also:    TStrings (383  )



                2.28.2         Method  overview

                __Page______Property___________________Description_________________________________________________________________*
 *___________
                  239       ReferenceStrings           Add a reference to the indicated strings.
                __239_______ReleaseStrings_____________Release_the_reference_to_the_strings._______________________________________*
 *___________



                2.28.3         IStringsAdapter.ReferenceStrings

    Synopsis:    Add a reference to the indicated strings.

Declaration:     procedure  ReferenceStrings(S:  TStrings)

    Visibility:   default



                2.28.4         IStringsAdapter.ReleaseStrings

    Synopsis:    Release the reference to the strings.

Declaration:     procedure  ReleaseStrings

    Visibility:   default



                2.29          IVCLComOb ject



                2.29.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 (1 )



                2.29.2         Method  overview

                __Page______Property______________________Description______________________________________________________________*
 *___________
                  241       FreeOnRelease                 Is called by TComponent.FreeOnRelease
                  240       GetIDsOfNames                 The IDispatch:GetIDsOfNames call for automation servers.
                  240       GetTypeInfo                   The IDispatch:GetTypeInfo call for automation servers
                  240       GetTypeInfoCount              The   IDispatch:GetTypeInfoCount   call   for   automation
                                                          servers
                  240       Invoke                        The IDispatch:Invoke call for automation servers.
                  241       SafeCallException             This  method  can  be  invoked  if  an  exception  occurs  during
                __________________________________________Invoke___________________________________________________________________*
 *___________



                                                                                 239

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.29.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 (1 )



                2.29.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 (1 )



                2.29.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 (1 )



                2.29.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



                                                                                 240

                __________________________________________________________CHAPTER_2.___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 (1 )



                2.29.7         IVCLComObject.SafeCallException

    Synopsis:    This method can be invoked if an exception occurs during Invoke

Declaration:     function  SafeCallException(ExceptObject:  TObject;ExceptAddr:  Pointer)
                                                             :  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 (1 )



                2.29.8         IVCLComObject.FreeOnRelease

    Synopsis:    Is called by TComponent.FreeOnRelease

Declaration:     procedure  FreeOnRelease

    Visibility:   default

Description:     FreeOnRelease is called by TComponent.FreeOnRelease (1 ) for the IVCLComObject inter-
                face implemented by TComponent.

    See also:    TComponent.FreeOnRelease (1 )



                2.30          TAbstractOb jectReader



                2.30.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 (261  ) 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 (261  )



                                                                                 241

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.30.2         Method  overview

                __Page______Property___________________________Description_________________________________________________________*
 *___________
                  243       BeginComponent                     Marks the reading of a new component.
                  243       BeginProperty                      Marks the reading of a property value.
                  243       BeginRootComponent                 Starts the reading of the root component.
                  242       NextValue                          Returns the type of the next value in the stream.
                  243       Read                               Read raw data from stream
                  244       ReadBinary                         Read binary data from the stream.
                  245       ReadCurrency                       Read a currency value from the stream.
                  245       ReadDate                           Read a date value from the stream.
                  244       ReadFloat                          Read a float value from the stream.
                  245       ReadIdent                          Read an identifier from the stream.
                  246       ReadInt16                          Read a 16-bit integer from the stream.
                  246       ReadInt32                          Read a 32-bit integer from the stream.
                  247       ReadInt64                          Read a 64-bit integer from the stream.
                  246       ReadInt8                           Read an 8-bit integer from the stream.
                  247       ReadSet                            Reads a set from the stream.
                  244       ReadSingle                         Read a single (real-type) value from the stream.
                  247       ReadStr                            Read a shortstring from the stream
                  248       ReadString                         Read a string of type StringType from the stream.
                  248       ReadUnicodeString                  Read a unicode string value
                  242       ReadValue                          Reads the type of the next value.
                  248       ReadWideString                     Read a widestring value from the stream.
                  249       SkipComponent                      Skip till the end of the component.
                __249_______SkipValue__________________________Skip_the_current_value._____________________________________________*
 *___________



                2.30.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 (1 )



                2.30.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 (1 )



                                                                                 242

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.30.5         TAbstractObjectReader.BeginRootComponent

    Synopsis:    Starts the reading of the root component.

Declaration:     procedure  BeginRootComponent;    Virtual;    Abstract

    Visibility:   public

Description:     This  function  can  be  used  to  initialize  the  driver  class  for  reading  a  component.   It  is
                called  once  at  the  beginning  of  the  read  process,  and  is  immediatly  followed  by  a  call  to
                BeginComponent (1 ).

    See also:    TAbstractObjectReader.BeginComponent (1 )



                2.30.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 (1 ), TAbstractObjectReader.BeginProperty
                (1 )



                2.30.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 (1 )



                2.30.8         TAbstractObjectReader.Read

    Synopsis:    Read raw data from stream

Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Virtual;    Abstract

    Visibility:   public



                                                                                 243

                __________________________________________________________CHAPTER_2.___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 (1 ), TReader.Read (1 )



                2.30.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
                (1 ) returned a valuetype of vaBinary).  The data should be stored in the DestData memory
                stream by descendent classes.

    See also:    TAbstractObjectReader.ReadFloat  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8
                (1 ),  TAbstractObjectReader.ReadInt16  (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAb-
                stractObjectReader.ReadInt64 (1 ), TabstractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr
                (1 ), TabstractObjectReader.ReadString (1 )



                2.30.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 (1 ) returned a valuetype of  vaExtended).  The return value should be
                the value of the float.

    See also:    TAbstractObjectReader.ReadFloat  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8
                (1 ),  TAbstractObjectReader.ReadInt16  (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAb-
                stractObjectReader.ReadInt64 (1 ), TabstractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr
                (1 ), TabstractObjectReader.ReadString (1 )



                2.30.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 (1 ) returned a valuetype of  vaSingle).  The return value
                should be the value of the float.

    See also:    TAbstractObjectReader.ReadFloat  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8
                (1 ),  TAbstractObjectReader.ReadInt16  (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAb-
                stractObjectReader.ReadInt64 (1 ), TabstractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr
                (1 ), TabstractObjectReader.ReadString (1 )



                                                                                 244

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.30.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  (1 )  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 (1 ), TAbstractObjectReader.ReadSingle (1 ), TAbstrac-
                tObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8 (1 ), TAbstractObjectReader.ReadInt16
                (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAbstractObjectReader.ReadInt64  (1 ),  Tab-
                stractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr (1 ), TabstractObjectReader.ReadString
                (1 )



                2.30.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 (1 )



                2.30.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 (1 ) 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 2.17:

                                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.



                                                                                 245

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    See also:    TAbstractObjectReader.ReadFloat  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadInt8 (1 ), TAbstractObjectReader.ReadInt16
                (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAbstractObjectReader.ReadInt64  (1 ),  Tab-
                stractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr (1 ), TabstractObjectReader.ReadString
                (1 )



                2.30.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 (1 ) 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  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt16
                (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAbstractObjectReader.ReadInt64  (1 ),  Tab-
                stractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr (1 ), TabstractObjectReader.ReadString
                (1 )



                2.30.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 (1 ) 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  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8
                (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAbstractObjectReader.ReadInt64  (1 ),  Tab-
                stractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr (1 ), TabstractObjectReader.ReadString
                (1 )



                2.30.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 (1 ) 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.



                                                                                 246

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    See also:    TAbstractObjectReader.ReadFloat  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8
                (1 ),  TAbstractObjectReader.ReadInt16  (1 ),  TAbstractObjectReader.ReadInt64  (1 ),  Tab-
                stractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr (1 ), TabstractObjectReader.ReadString
                (1 )



                2.30.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 (1 ) 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  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8
                (1 ),  TAbstractObjectReader.ReadInt16  (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  Tab-
                stractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr (1 ), TabstractObjectReader.ReadString
                (1 )



                2.30.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 (1 ) 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  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8
                (1 ),  TAbstractObjectReader.ReadInt16  (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAb-
                stractObjectReader.ReadInt64 (1 ), TabstractObjectReader.ReadStr (1 ), TabstractObjectReader.ReadString
                (1 )



                2.30.20          TAbstractObjectReader.ReadStr

    Synopsis:    Read a shortstring from the stream

Declaration:     function  ReadStr  :  string;    Virtual;    Abstract

    Visibility:   public

Description:     ReadStr  is  called  by  the  streaming  system  if  it  expects  to  read  a  string  from  the  stream
                (i.e.  after ReadValue (1 ) returned a valuetype of  vaLString,vaWstring or vaString).  The
                return value is the string.



                                                                                 247

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    See also:    TAbstractObjectReader.ReadFloat  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8
                (1 ),  TAbstractObjectReader.ReadInt16  (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAb-
                stractObjectReader.ReadInt64 (1 ), TabstractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadString
                (1 )



                2.30.21          TAbstractObjectReader.ReadString

    Synopsis:    Read a string of type StringType from the stream.

Declaration:     function  ReadString(StringType:  TValueType)  :  string;    Virtual
                                                ;    Abstract

    Visibility:   public

Description:     ReadStr  is  called  by  the  streaming  system  if  it  expects  to  read  a  string  from  the  stream
                (i.e.  after ReadValue (1 ) returned a valuetype of  vaLString,vaWstring or vaString).  The
                return value is the string.

    See also:    TAbstractObjectReader.ReadFloat  (1 ),  TAbstractObjectReader.ReadDate  (1 ),  TAbstrac-
                tObjectReader.ReadSingle (1 ), TAbstractObjectReader.ReadIdent (1 ), TAbstractObjectReader.ReadInt8
                (1 ),  TAbstractObjectReader.ReadInt16  (1 ),  TAbstractObjectReader.ReadInt32  (1 ),  TAb-
                stractObjectReader.ReadInt64 (1 ), TabstractObjectReader.ReadSet (1 ), TabstractObjectReader.ReadStr
                (1 )



                2.30.22          TAbstractObjectReader.ReadWideString

    Synopsis:    Read a widestring value from the stream.

Declaration:     function  ReadWideString  :  WideString;    Virtual;    Abstract

    Visibility:   public

Description:     ReadWideString is called when a widestring-typed value should be read from the stream.
                This abstract method should be overidden by descendent classes.

    See also:    TAbstractObjectWriter.WriteWideString (1 )



                2.30.23          TAbstractObjectReader.ReadUnicodeString

    Synopsis:    Read a unicode string value

Declaration:     function  ReadUnicodeString  :  UnicodeString;    Virtual;    Abstract

    Visibility:   public

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 (1 ), TAbstractObjectReader.ReadWideString (1 )



                                                                                 248

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.30.24          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 (1 ), TAbstractObjectReader.SkipValue (1 )



                2.30.25          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 (1 )



                2.31          TAbstractOb jectWriter



                2.31.1         Description

                Abstract driver class for writing component data.



                                                                                 249

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.31.2         Method  overview

                __Page______Property_______________________Description_____________________________________________________________*
 *___________
                  250       BeginCollection                Start writing a collection.
                  250       BeginComponent                 Start writing a component
                  250       BeginList                      Start writing a list.
                  251       BeginProperty                  Start writing a property
                  251       EndList                        Mark the end of a list.
                  251       EndProperty                    Marks the end of writing of a property.
                  251       Write                          Write raw data to stream
                  251       WriteBinary                    Writes binary data to the stream.
                  252       WriteBoolean                   Writes a boolean value to the stream.
                  252       WriteCurrency                  Write a currency value to the stream
                  252       WriteDate                      Writes a date type to the stream.
                  252       WriteFloat                     Writes a float value to the stream.
                  253       WriteIdent                     Writes an identifier to the stream.
                  253       WriteInteger                   Writes an integer value to the stream
                  253       WriteMethodName                Writes a methodname to the stream.
                  254       WriteSet                       Writes a set value to the stream.
                  252       WriteSingle                    Writes a single-type real value to the stream.
                  254       WriteString                    Writes a string value to the stream.
                  253       WriteUInt64                    Write an unsigned 64-bit integer
                  254       WriteUnicodeString             Write a unicode string to the stream.
                  253       WriteVariant                   Write a variant to the stream
                __254_______WriteWideString________________Write_a_widestring_value_to_the_stream__________________________________*
 *___________



                2.31.3         TAbstractObjectWriter.BeginCollection

    Synopsis:    Start writing a collection.

Declaration:     procedure  BeginCollection;    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a collection.



                2.31.4         TAbstractObjectWriter.BeginComponent

    Synopsis:    Start writing a component

Declaration:     procedure  BeginComponent(Component:  TComponent;Flags:  TFilerFlags;
                                                        ChildPos:  Integer);    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a component



                2.31.5         TAbstractObjectWriter.BeginList

    Synopsis:    Start writing a list.

Declaration:     procedure  BeginList;    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a list.



                                                                                 250

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.31.6         TAbstractObjectWriter.EndList

    Synopsis:    Mark the end of a list.

Declaration:     procedure  EndList;    Virtual;    Abstract

    Visibility:   public

Description:     Mark the end of a list.



                2.31.7         TAbstractObjectWriter.BeginProperty

    Synopsis:    Start writing a property

Declaration:     procedure  BeginProperty(const  PropName:  string);    Virtual;    Abstract

    Visibility:   public

Description:     Start writing a property



                2.31.8         TAbstractObjectWriter.EndProperty

    Synopsis:    Marks the end of writing of a property.

Declaration:     procedure  EndProperty;    Virtual;    Abstract

    Visibility:   public

Description:     Marks the end of writing of a property.



                2.31.9         TAbstractObjectWriter.Write

    Synopsis:    Write raw data to stream

Declaration:     procedure  Write(const  Buffer;Count:  LongInt);    Virtual;    Abstract

    Visibility:   public

Description:     Write is introduced for Delphi compatibility to write raw data to the component stream.
                This should not be used in new production code as it will totally mess up the streaming.

    See also:    TBinaryObjectWriter.Write (1 ), TWriter.Write (1 )



                2.31.10          TAbstractObjectWriter.WriteBinary

    Synopsis:    Writes binary data to the stream.

Declaration:     procedure  WriteBinary(const  Buffer;Count:  LongInt);    Virtual;    Abstract

    Visibility:   public

Description:     Writes binary data to the stream.



                                                                                 251

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.31.11          TAbstractObjectWriter.WriteBoolean

    Synopsis:    Writes a boolean value to the stream.

Declaration:     procedure  WriteBoolean(Value:  Boolean);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a boolean value to the stream.



                2.31.12          TAbstractObjectWriter.WriteFloat

    Synopsis:    Writes a float value to the stream.

Declaration:     procedure  WriteFloat(const  Value:  Extended);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a float value to the stream.



                2.31.13          TAbstractObjectWriter.WriteSingle

    Synopsis:    Writes a single-type real value to the stream.

Declaration:     procedure  WriteSingle(const  Value:  Single);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a single-type real value to the stream.



                2.31.14          TAbstractObjectWriter.WriteDate

    Synopsis:    Writes a date type to the stream.

Declaration:     procedure  WriteDate(const  Value:  TDateTime);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a date type to the stream.



                2.31.15          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 (1 )



                                                                                 252

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.31.16          TAbstractObjectWriter.WriteIdent

    Synopsis:    Writes an identifier to the stream.

Declaration:     procedure  WriteIdent(const  Ident:  string);    Virtual;    Abstract

    Visibility:   public

Description:     Writes an identifier to the stream.



                2.31.17          TAbstractObjectWriter.WriteInteger

    Synopsis:    Writes an integer value to the stream

Declaration:     procedure  WriteInteger(Value:  Int64);    Virtual;    Abstract

    Visibility:   public

Description:     Writes an integer value to the stream



                2.31.18          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 (1 )



                2.31.19          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 (1 )



                2.31.20          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.



                                                                                 253

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.31.21          TAbstractObjectWriter.WriteSet

    Synopsis:    Writes a set value to the stream.

Declaration:     procedure  WriteSet(Value:  LongInt;SetType:  Pointer);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a set value to the stream.



                2.31.22          TAbstractObjectWriter.WriteString

    Synopsis:    Writes a string value to the stream.

Declaration:     procedure  WriteString(const  Value:  string);    Virtual;    Abstract

    Visibility:   public

Description:     Writes a string value to the stream.



                2.31.23          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 (1 )



                2.31.24          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 (1 )



                2.32          TBasicAction



                2.32.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 (258  ), TComponent (289  )



                                                                                 254

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.32.2         Method  overview

                __Page______Property_______________________Description_____________________________________________________________*
 *___________
                  255       Create                         Creates a new instance of a TBasicAction (254  ) class.
                  255       Destroy                        Destroys the action.
                  256       Execute                        Triggers the OnExecute (1 ) event
                  256       ExecuteTarget                  Executes the action on the Target object
                  255       HandlesTarget                  Determines whether Target can be handled by this action
                  257       RegisterChanges                Registers a new client with the action.
                  257       UnRegisterChanges              Unregisters a client from the list of clients
                  257       Update                         Triggers the OnUpdate (1 ) event
                __256_______UpdateTarget___________________Notify_client_controls_when_the_action_updates_itself.__________________*
 *___________



                2.32.3         Property  overview

                __Page______Property_____________________Access_______Description__________________________________________________*
 *___________
                  257       ActionComponent              rw           Returns the component that initiated the action.
                  258       OnExecute                    rw           Event triggered when the action executes.
                __258_______OnUpdate_____________________rw___________Event_trigged_when_the_application_is_idle.__________________*
 *___________



                2.32.4         TBasicAction.Create

    Synopsis:    Creates a new instance of a TBasicAction (254  ) 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 (1 ), AssignClient (1 )



                2.32.5         TBasicAction.Destroy

    Synopsis:    Destroys the action.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the list of client controls and then calls the inherited destructor.

                An application programmer should not call Destroy directly; Instead Free should be called,
                if it needs to be called at all.  Normally the controlling class (e.g.  a TActionList) will destroy
                the action.



                2.32.6         TBasicAction.HandlesTarget

    Synopsis:    Determines whether Target can be handled by this action

Declaration:     function  HandlesTarget(Target:  TObject)  :  Boolean;    Virtual

    Visibility:   public



                                                                                 255

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (1 ), ExecuteTarget (1 )



                2.32.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 (1 ), ExecuteTarget (1 )



                2.32.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 (1 ), UpdateTarget (1 ), Execute (1 )



                2.32.9         TBasicAction.Execute

    Synopsis:    Triggers the OnExecute (1 ) 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.



                                                                                 256

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.32.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 (1 )



                2.32.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 (1 ), Destroy (1 )



                2.32.12          TBasicAction.Update

    Synopsis:    Triggers the OnUpdate (1 ) 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 (1 ) event, and perform any checks
                in that handler.

    See also:    OnUpdate (1 ), Execute (1 ), UpdateTarget (1 )



                2.32.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 (1 ), OnExecute (1 )



                                                                                 257

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.32.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 (1 ) 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 (1 ), OnUpdate (1 )



                2.32.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 (1 ), OnExecute (1 )



                2.33          TBasicActionLink



                2.33.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 (254  )



                                                                                 258

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.33.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  259       Create          Creates a new instance of the TBasicActionLink class
                  259       Destroy         Destroys the TBasicActionLink instance.
                  259       Execute         Calls the action's Execute method.
                __260_______Update__________Calls_the_action's_Update_method_______________________________________________________*
 *___________



                2.33.3         Property  overview

                __Page______Property___________Access_______Description____________________________________________________________*
 *___________
                  260       Action             rw           The action to which the link was assigned.
                __260_______OnChange___________rw___________Event_handler_triggered_when_the_action's_properties_change____________*
 *___________



                2.33.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 (1 )



                2.33.5         TBasicActionLink.Destroy

    Synopsis:    Destroys the TBasicActionLink instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  unregisters  the  TBasicActionLink  with  the  action,  and  then  calls  the  inherited
                destructor.

                Application programmers should never call Destroy directly.  If a link should be destroyed
                at all, the Free method should be called instead.

    See also:    Create (1 )



                2.33.6         TBasicActionLink.Execute

    Synopsis:    Calls the action's Execute method.

Declaration:     function  Execute(AComponent:  TComponent)  :  Boolean;    Virtual

    Visibility:   public



                                                                                 259

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     Execute sets the ActionComponent (1 ) property of the associated Action (1 ) to AComponent
                and then calls the Action's execute (1 ) 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 (1 ), TBasicAction.ActionComponent (1 ), TBasicAction.Execute (1 ), TBasicAction.onExecute
                (1 )



                2.33.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 (1 ) methoda.

                Component programmers can override the Update method to provide additional processing
                when the Update method occurs.



                2.33.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 (254  ) 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 (254  )



                2.33.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 (1 ), TBasicAction.Change (1 )



                                                                                 260

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.34          TBinaryOb jectReader



                2.34.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  (241  ).
                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 (1 ) call should be used.


    See also:    TAbstractObjectReader (241  ), TBinaryObjectWriter (267  )



                2.34.2         Method  overview

                __Page______Property___________________________Description_________________________________________________________*
 *___________
                  263       BeginComponent                     Start reading a component.
                  263       BeginProperty                      Start reading a property.
                  262       BeginRootComponent                 Start reading the root component.
                  261       Create                             Creates a new binary data reader instance.
                  262       Destroy                            Destroys the binary data reader.
                  262       NextValue                          Return the type of the next value.
                  263       Read                               Read raw data from stream
                  263       ReadBinary                         Start reading a binary value.
                  264       ReadCurrency                       Read a currency value from the stream.
                  264       ReadDate                           Read a date.
                  263       ReadFloat                          Read a float value
                  264       ReadIdent                          Read an identifier
                  265       ReadInt16                          Read a 16-bits integer.
                  265       ReadInt32                          Read a 32-bits integer.
                  265       ReadInt64                          Read a 64-bits integer.
                  264       ReadInt8                           Read an 8-bits integer.
                  265       ReadSet                            Read a set
                  264       ReadSingle                         Read a single-size float value
                  266       ReadStr                            Read a short string
                  266       ReadString                         Read a string
                  266       ReadUnicodeString                  Read a unicode string value
                  262       ReadValue                          Read the next value in the stream
                  266       ReadWideString                     Read a widestring value from the stream.
                  267       SkipComponent                      Skip a component's data
                __267_______SkipValue__________________________Skip_a_value's_data_________________________________________________*
 *___________



                2.34.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 (241  )



                                                                                 261

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.34.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 (1 )



                2.34.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 (241  )



                2.34.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 (241  )



                2.34.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 (241  )



                                                                                 262

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.34.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 (241  )



                2.34.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 (241  )



                2.34.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 (1 ), TReader.Read (1 )



                2.34.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 (241  )



                2.34.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 (241  )



                                                                                 263

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.34.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 (241  )



                2.34.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 (241  )



                2.34.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 (241  ).

    See also:    TAbstractObjectReader.ReadCurrency (1 ), TBinaryObjectWriter.WriteCurrency (1 )



                2.34.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 (241  )



                2.34.17          TBinaryObjectReader.ReadInt8

    Synopsis:    Read an 8-bits integer.

Declaration:     function  ReadInt8  :  ShortInt;    Override

    Visibility:   public



                                                                                 264

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (241  )



                2.34.18          TBinaryObjectReader.ReadInt16

    Synopsis:    Read a 16-bits integer.

Declaration:     function  ReadInt16  :  SmallInt;    Override

    Visibility:   public

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 (241  )



                2.34.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 (241  )



                2.34.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 (241  )



                2.34.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 (241  )



                                                                                 265

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.34.22          TBinaryObjectReader.ReadStr

    Synopsis:    Read a short string

Declaration:     function  ReadStr  :  string;    Override

    Visibility:   public

Description:     ReadStr reads a short string from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (241  )



                2.34.23          TBinaryObjectReader.ReadString

    Synopsis:    Read a string

Declaration:     function  ReadString(StringType:  TValueType)  :  string;    Override

    Visibility:   public

Description:     ReadStr reads a string of type StringType from a binary stream.

                This method is simply the implementation for a binary stream of the abstract method in-
                troduced in TAbstractObjectReader (241  )



                2.34.24          TBinaryObjectReader.ReadWideString

    Synopsis:    Read a widestring value from the stream.

Declaration:     function  ReadWideString  :  WideString;    Override

    Visibility:   public

Description:     var>ReadWideString reads a widestring-typed value from a binary stream.  It is the imple-
                mentation of the method introduced in TAbstractObjectReader (241  ).

    See also:    TAbstractObjectReader.ReadWideString (1 ), TBinaryObjectWriter.WriteWideString (1 )



                2.34.25          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 (1 )



                                                                                 266

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.34.26          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 (241  ).



                2.34.27          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 (241  )



                2.35          TBinaryOb jectWriter



                2.35.1         Description

                Driver class which stores component data in binary form.



                                                                                 267

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.35.2         Method  overview

                __Page______Property_______________________Description_____________________________________________________________*
 *___________
                  268       BeginCollection                Start writing a collection.
                  269       BeginComponent                 Start writing a component
                  269       BeginList                      Start writing a list.
                  269       BeginProperty                  Start writing a property
                  268       Create                         Creates a new instance of a binary object writer.
                  268       Destroy                        Destroys an instance of the binary object writer.
                  269       EndList                        Mark the end of a list.
                  269       EndProperty                    Marks the end of writing of a property.
                  269       Write                          Write raw data to stream
                  270       WriteBinary                    Writes binary data to the stream.
                  270       WriteBoolean                   Writes a boolean value to the stream.
                  270       WriteCurrency                  Write a currency-valued type to a stream
                  270       WriteDate                      Writes a date type to the stream.
                  270       WriteFloat                     Writes a float value to the stream.
                  271       WriteIdent                     Writes an identifier to the stream.
                  271       WriteInteger                   Writes an integer value to the stream.
                  271       WriteMethodName                Writes a methodname to the stream.
                  271       WriteSet                       Writes a set value to the stream.
                  270       WriteSingle                    Writes a single-type real value to the stream.
                  271       WriteString                    Writes a string value to the stream.
                  271       WriteUInt64                    Write an unsigned 64-bit integer
                  272       WriteUnicodeString             Write a unicode string to the stream.
                  272       WriteVariant                   Write a variant to the stream
                __272_______WriteWideString________________Write_a_widestring-valued_type_to_a_stream______________________________*
 *___________



                2.35.3         TBinaryObjectWriter.Create

    Synopsis:    Creates a new instance of a binary object writer.

Declaration:     constructor  Create(Stream:  TStream;BufSize:  Integer)

    Visibility:   public

Description:     Creates a new instance of a binary object writer.



                2.35.4         TBinaryObjectWriter.Destroy

    Synopsis:    Destroys an instance of the binary object writer.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys an instance of the binary object writer.



                2.35.5         TBinaryObjectWriter.BeginCollection

    Synopsis:    Start writing a collection.

Declaration:     procedure  BeginCollection;    Override

    Visibility:   public



                                                                                 268

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.35.6         TBinaryObjectWriter.BeginComponent

    Synopsis:    Start writing a component

Declaration:     procedure  BeginComponent(Component:  TComponent;Flags:  TFilerFlags;
                                                        ChildPos:  Integer);    Override

    Visibility:   public



                2.35.7         TBinaryObjectWriter.BeginList

    Synopsis:    Start writing a list.

Declaration:     procedure  BeginList;    Override

    Visibility:   public



                2.35.8         TBinaryObjectWriter.EndList

    Synopsis:    Mark the end of a list.

Declaration:     procedure  EndList;    Override

    Visibility:   public



                2.35.9         TBinaryObjectWriter.BeginProperty

    Synopsis:    Start writing a property

Declaration:     procedure  BeginProperty(const  PropName:  string);    Override

    Visibility:   public



                2.35.10          TBinaryObjectWriter.EndProperty

    Synopsis:    Marks the end of writing of a property.

Declaration:     procedure  EndProperty;    Override

    Visibility:   public



                2.35.11          TBinaryObjectWriter.Write

    Synopsis:    Write raw data to stream

Declaration:     procedure  Write(const  Buffer;Count:  LongInt);    Override

    Visibility:   public

Description:     Write is introduced for Delphi compatibility to write raw data to the component stream.
                This should not be used in new production code as it will totally mess up the streaming.

    See also:    TAbstractObjectWriter.Write (1 ), TWriter.Write (1 )



                                                                                 269

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.35.12          TBinaryObjectWriter.WriteBinary

    Synopsis:    Writes binary data to the stream.

Declaration:     procedure  WriteBinary(const  Buffer;Count:  LongInt);    Override

    Visibility:   public



                2.35.13          TBinaryObjectWriter.WriteBoolean

    Synopsis:    Writes a boolean value to the stream.

Declaration:     procedure  WriteBoolean(Value:  Boolean);    Override

    Visibility:   public



                2.35.14          TBinaryObjectWriter.WriteFloat

    Synopsis:    Writes a float value to the stream.

Declaration:     procedure  WriteFloat(const  Value:  Extended);    Override

    Visibility:   public



                2.35.15          TBinaryObjectWriter.WriteSingle

    Synopsis:    Writes a single-type real value to the stream.

Declaration:     procedure  WriteSingle(const  Value:  Single);    Override

    Visibility:   public



                2.35.16          TBinaryObjectWriter.WriteDate

    Synopsis:    Writes a date type to the stream.

Declaration:     procedure  WriteDate(const  Value:  TDateTime);    Override

    Visibility:   public



                2.35.17          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 (249  ).

    See also:    TAbstractObjectWriter.WriteCurrency (1 )



                                                                                 270

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.35.18          TBinaryObjectWriter.WriteIdent

    Synopsis:    Writes an identifier to the stream.

Declaration:     procedure  WriteIdent(const  Ident:  string);    Override

    Visibility:   public



                2.35.19          TBinaryObjectWriter.WriteInteger

    Synopsis:    Writes an integer value to the stream.

Declaration:     procedure  WriteInteger(Value:  Int64);    Override

    Visibility:   public



                2.35.20          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 (1 )



                2.35.21          TBinaryObjectWriter.WriteMethodName

    Synopsis:    Writes a methodname to the stream.

Declaration:     procedure  WriteMethodName(const  Name:  string);    Override

    Visibility:   public



                2.35.22          TBinaryObjectWriter.WriteSet

    Synopsis:    Writes a set value to the stream.

Declaration:     procedure  WriteSet(Value:  LongInt;SetType:  Pointer);    Override

    Visibility:   public



                2.35.23          TBinaryObjectWriter.WriteString

    Synopsis:    Writes a string value to the stream.

Declaration:     procedure  WriteString(const  Value:  string);    Override

    Visibility:   public



                                                                                 271

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.35.24          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 (249  ).

    See also:    TAbstractObjectWriter.WriteWidestring (1 )



                2.35.25          TBinaryObjectWriter.WriteUnicodeString

    Synopsis:    Write a unicode string to the stream.

Declaration:     procedure  WriteUnicodeString(const  Value:  UnicodeString);    Override

    Visibility:   public

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 (1 )



                2.35.26          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.



                2.36          TBits



                2.36.1         Description

                TBits can be used to store collections of bits in an indexed array.  This is especially useful
                for storing collections of booleans:  Normally the size of a boolean is the size of the smallest
                enumerated type, i.e.  1 byte.  Since a bit can take 2 values it can be used to store a boolean
                as well.  Since TBits can store 8 bits in a byte, it takes 8 times less space to store an array
                of booleans in a TBits class then it would take to stoe them in a conventional array.

                TBits introduces methods to store and retrieve bit values, apply masks, and search for bits.



                                                                                 272

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.36.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  275       AndBits               Performs an and operation on the bits.
                  274       Clear                 Clears a particular bit.
                  274       Clearall              Clears all bits in the array.
                  273       Create                Creates a new bits collection.
                  273       Destroy               Destroys a bit collection
                  276       Equals                Determines whether the bits of 2 arrays are equal.
                  277       FindFirstBit          Find first bit with a particular value
                  277       FindNextBit           Searches the next bit with a particular value.
                  278       FindPrevBit           Searches the previous bit with a particular value.
                  276       Get                   Retrieve the value of a particular bit
                  274       GetFSize              Returns the number of records used to store the bits.
                  276       Grow                  Expands the bits array to the requested size.
                  276       NotBits               Performs a not operation on the bits.
                  278       OpenBit               Returns the position of the first bit that is set to False.
                  275       OrBits                Performs an or operation on the bits.
                  277       SetIndex              Sets the start position for FindNextBit (1 ) and FindPrevBit (1 )
                  274       SetOn                 Turn a particular bit on.
                __275_______XorBits_______________Performs_a_xor_operation_on_the_bits.____________________________________________*
 *___________



                2.36.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  278       Bits            rw           Access to all bits in the array.
                __279_______Size____________rw___________Current_size_of_the_array_of_bits.________________________________________*
 *___________



                2.36.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 (1 )



                2.36.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 (1 )



                                                                                 273

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.36.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 (1 )



                2.36.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 (1 ).

       Errors:   If  bit  is  larger  than  the  maximum  allowed  bits  array  size  or  is  negative,  an  EBitsError
                (227  ) exception is raised.

    See also:    Bits (1 ), Clear (1 )



                2.36.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 (1 ).

       Errors:   If  bit  is  larger  than  the  maximum  allowed  bits  array  size  or  is  negative,  an  EBitsError
                (227  ) exception is raised.

    See also:    Bits (1 ), seton (1 )



                2.36.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 (1 ), clear (1 )



                                                                                 274

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.36.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 (1 ), OrBits (1 ), XOrBits (1 ), NotBits (1 )



                2.36.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 (1 ), andBits (1 ), XOrBits (1 ), NotBits (1 )



                2.36.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 (1 ), andBits (1 ), OrBits (1 ), NotBits (1 )



                                                                                 275

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.36.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 (1 ), andBits (1 ), OrBits (1 ), XOrBits (1 )



                2.36.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 (227  ) exception is raised.

    See also:    Bits (1 ), FindFirstBit (1 ), seton (1 )



                2.36.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 (227  )is raised.

    See also:    Size (1 )



                2.36.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:   default

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 (1 ), andBits (1 ), OrBits (1 ), XOrBits (1 )



                                                                                 276

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.36.17          TBits.SetIndex

    Synopsis:    Sets the start position for FindNextBit (1 ) and FindPrevBit (1 )

Declaration:     procedure  SetIndex(Index:  LongInt)

    Visibility:   public

Description:     SetIndex sets the search start position forFindNextBit (1 ) and FindPrevBit (1 ) to Index.
                This means that these calls will start searching from position Index.

                This mechanism provides an alternative to FindFirstBit (1 ) which can also be used to position
                for the FindNextBit and FindPrevBit calls.

       Errors:   None.

    See also:    FindNextBit (1 ), FindPrevBit (1 ), FindFirstBit (1 ), OpenBit (1 )



                2.36.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 (1 ) and FindPrevBit (1 ) 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 (1 ) instead.

       Errors:   None.

    See also:    FindNextBit (1 ), FindPrevBit (1 ), OpenBit (1 ), SetIndex (1 )



                2.36.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 (1 ).  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
                (1 ).

                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 (1 ), FindPrevBit (1 ), OpenBit (1 ), SetIndex (1 )



                                                                                 277

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.36.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  (1 ).   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 (1 ).

                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 (1 ), FindNextBit (1 ), OpenBit (1 ), SetIndex (1 )



                2.36.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 (1 ), FindPrevBit (1 ), FindFirstBit (1 ), SetIndex (1 )



                2.36.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 (227  ) exception
                is raised.

    See also:    Size (1 )



                                                                                 278

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.36.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 (227  ) exception is raised.

    See also:    Bits (1 )



                2.37          TCollection



                2.37.1         Description

                TCollection  implements  functionality  to  manage  a  collection  of  named  objects.  Each  of
                these objects needs to be a descendent of the TCollectionItem (286  ) class.  Exactly which
                type of object is managed can be seen from the TCollection.ItemClass (1 ) property.

                Normally, no TCollection is created directly.  Instead, a descendents of  TCollection and
                TCollectionItem (286  ) are created as a pair.


    See also:    TCollectionItem (286  )



                2.37.2         Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  280       Add                       Creates and adds a new item to the collection.
                  281       Assign                    Assigns one collection to another.
                  281       BeginUpdate               Start an update batch.
                  281       Clear                     Removes all items from the collection.
                  280       Create                    Creates a new collection.
                  282       Delete                    Delete an item from the collection.
                  280       Destroy                   Destroys the collection and frees all the objects it manages.
                  282       EndUpdate                 Ends an update batch.
                  283       Exchange                  Exchange 2 items in the collection
                  283       FindItemID                Searches for an Item in the collection, based on its TCollection-
                                                      Item.ID (1 ) property.
                  282       GetEnumerator             Create an IEnumerator instance
                  282       GetNamePath               Overrides  TPersistent.GetNamePath  (1 )  to  return  a  proper
                                                      pathname.
                  283       Insert                    Insert an item in the collection.
                  280       Owner                     Owner of the collection.
                __284_______Sort______________________Sort_the_items_in_the_collection_____________________________________________*
 *___________



                2.37.3         Property  overview

                __Page______Property__________Access_______Description_____________________________________________________________*
 *___________
                  284       Count             r            Number of items in the collection.
                  284       ItemClass         r            Class pointer for each item in the collection.
                __284_______Items_____________rw___________Indexed_array_of_items_in_the_collection._______________________________*
 *___________



                                                                                 279

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.37.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 (1 ), TCollection.Destroy (1 )



                2.37.5         TCollection.Destroy

    Synopsis:    Destroys the collection and frees all the objects it manages.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy first clears the collection, and then frees all memory allocated to this instance.

                Don't call Destroy directly, call Free instead.

    See also:    TCollection.Create (1 )



                2.37.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.



                2.37.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 (1 ) and adds it to the list.  The
                newly created object is returned.

    See also:    TCollection.ItemClass (1 ), TCollection.Clear (1 )



                                                                                 280

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.37.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 (1 ), TCollectionItem (286  )



                2.37.9         TCollection.BeginUpdate

    Synopsis:    Start an update batch.

Declaration:     procedure  BeginUpdate;    Virtual

    Visibility:   public

Description:     BeginUpdate is called at the beginning of a batch update.  It raises the update count with
                1.

                Call BeginUpdate at the beginning of a series of operations that will change the state of the
                collection.  This will avoid the call to TCollection.Update (1 ) 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 (1 ), even in case of an exception.

    See also:    TCollection.EndUpdate (1 ), TCollection.Changed (1 ), TCollection.Update (1 )



                2.37.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 (1 ), TCollectionItem.Destroy (1 ), TCollection.Destroy (1 )



                                                                                 281

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.37.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 (1 ) it should always be used in conjunction with TCollec-
                tion.BeginUpdate (1 ), preferably in the Finally section of a Try  ...    Finally block.

    See also:    TCollection.BeginUpdate (1 ), TCollection.Changed (1 ), TCollection.Update (1 )



                2.37.12          TCollection.Delete

    Synopsis:    Delete an item from the collection.

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete deletes the item at (zero based) position Index from the collection.  This will result
                in a cnDeleted notification.

       Errors:   If an invalid index is specified, an EListError exception is raised.

    See also:    TCollection.Items (1 ), TCollection.Insert (1 ), TCollection.Clear (1 )



                2.37.13          TCollection.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TCollectionEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1433   ) interface for TCollection.
                It creates a TCollectionEnumerator (285  ) instance and returns it's IEnumerator (1433   ) in-
                terface.

    See also:    TCollectionEnumerator (285  ), IEnumerator (1433   ), IEnumerable (1433   )



                2.37.14          TCollection.GetNamePath

    Synopsis:    Overrides TPersistent.GetNamePath (1 ) 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 (1 ) property is not empty



                                                                                 282

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                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 (1 ), TCollection.Propname (1 )



                2.37.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 (1 ) adds a new item at the end.

       Errors:   None.

    See also:    TCollection.Add (1 ), TCollection.Delete (1 ), TCollection.Items (1 )



                2.37.16          TCollection.FindItemID

    Synopsis:    Searches for an Item in the collection, based on its TCollectionItem.ID (1 ) 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 (1 ) 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 (1 ), TCollectionItem.ID (1 )



                2.37.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 (1 ), TCollectionItem.Index (1 )



                                                                                 283

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.37.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 (202  ) type.

    See also:    TCollectionSortCompare (202  )



                2.37.19          TCollection.Count

    Synopsis:    Number of items in the collection.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read

Description:     Count contains the number of items in the collection.

 Remark:         The items in the collection are identified by their TCollectionItem.Index (1 ) property, which
                is  a  zero-based  index,  meaning  that  it  can  take  values  between  0  and  Count-1,  borders
                included.

    See also:    TCollectionItem.Index (1 ), TCollection.Items (1 )



                2.37.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 (286  ), TCollection.Items (1 )



                2.37.21          TCollection.Items

    Synopsis:    Indexed array of items in the collection.

Declaration:     Property  Items[Index:  Integer]:  TCollectionItem

    Visibility:   public

      Access:    Read,Write



                                                                                 284

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (1 ) property.

                Adding  an  element  to  the  array  can  be  done  with  the  TCollection.Add  (1 )  method.  The
                array can be cleared with the TCollection.Clear (1 ) method.  Removing an element of the
                array should be done by freeing that element.

    See also:    TCollection.Count (1 ), TCollection.ItemClass (1 ), TCollection.Clear (1 ), TCollection.Add
                (1 )



                2.38          TCollectionEnumerator



                2.38.1         Description

                TCollectionEnumerator implements the #rtl.system.IEnumerator (1433   ) interface for the
                TCollection (279  ) class, so the TCollection class can be used in a for  ...    in loop.  It is
                returned by the TCollection.GetEnumerator (1 ) method of  TCollection.


    See also:    TCollection (279  ), TCollection.GetEnumerator (1 ), #rtl.system.IEnumerator (1433   )



                2.38.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  285       Create              Initialize a new instance of  TCollectionEnumerator
                  285       GetCurrent          Return the current pointer in the list
                  286       MoveNext            Move  the  position  of  the  enumerator  to  the  next  position  in  the
                ________________________________collection.________________________________________________________________________*
 *___________



                2.38.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __286_______Current_________r____________Current_pointer_in_the_list_______________________________________________*
 *___________



                2.38.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 (279  )



                2.38.5         TCollectionEnumerator.GetCurrent

    Synopsis:    Return the current pointer in the list

Declaration:     function  GetCurrent  :  TCollectionItem



                                                                                 285

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    Visibility:  public

Description:     GetCurrent returns the current TCollectionItem (286  ) instance in the enumerator.

       Errors:   No checking is done on the validity of the current position.

    See also:    MoveNext (1 ), TCollectionItem (286  )



                2.38.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 (1 )



                2.38.7         TCollectionEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  TCollectionItem

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (1 ) as a property.

    See also:    GetCurrent (1 )



                2.39          TCollectionItem



                2.39.1         Description

                TCollectionItem and TCollection (279  ) 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 (1 ), TCollection.Index (1 ) and TCollectionItem.ID (1 ).

                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 (279  ) 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 (279  )



                                                                                 286

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.39.2         Method  overview

                __Page______Property________________Description____________________________________________________________________*
 *___________
                  287       Create                  Creates a new instance of this collection item.
                  287       Destroy                 Destroyes this collection item.
                __287_______GetNamePath_____________Returns_the_namepath_of_this_collection_item.__________________________________*
 *___________



                2.39.3         Property  overview

                __Page______Property______________Access_______Description_________________________________________________________*
 *___________
                  288       Collection            rw           Pointer to the collection managing this item.
                  289       DisplayName           rw           Name of the item, displayed in the object inspector.
                  288       ID                    r            Initial index of this item.
                  288       Index                 rw           Index  of  the  item  in  its  managing  collection  TCollec-
                _______________________________________________tion.Items_(1_)_property.___________________________________________*
 *___________



                2.39.4         TCollectionItem.Create

    Synopsis:    Creates a new instance of this collection item.

Declaration:     constructor  Create(ACollection:  TCollection);    Virtual

    Visibility:   public

Description:     Create instantiates a new item in a TCollection (279  ).  It is called by the TCollection.Add
                (1 ) function and should under normal circumstances never be called directly.  called

    See also:    TCollectionItem.Destroy (1 )



                2.39.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 (1 )



                2.39.6         TCollectionItem.GetNamePath

    Synopsis:    Returns the namepath of this collection item.

Declaration:     function  GetNamePath  :  string;    Override

    Visibility:   public

Description:     GetNamePath overrides the TPersistent.GetNamePath (1 ) method to return the name of the
                managing collection and appends its TCollectionItem.Index (1 ) property.

    See also:    TCollectionItem.Collection (1 ), TPersistent.GetNamePath (1 ), TCollectionItem.Index (1 )



                                                                                 287

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.39.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 (279  )



                2.39.8         TCollectionItem.ID

    Synopsis:    Initial index of this item.

Declaration:     Property  ID  :  Integer

    Visibility:   public

      Access:    Read

Description:     ID is the initial value of TCollectionItem.Index (1 ); 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  (1 )  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 (1 ), TCollectionItem.Index (1 )



                2.39.9         TCollectionItem.Index

    Synopsis:    Index of the item in its managing collection TCollection.Items (1 ) 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  (1 )
                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 (1 ) property does not form a continuous series, but can
                also be used to identify an item.

    See also:    TCollectionItem.ID (1 ), TCollection.Items (1 )



                                                                                 288

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.39.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  TCol-
                lectionItem.SetDisplayName  (1 )  and  TCollectionItem.GetDisplayName  (1 )  to  add  storage
                functionality.

    See also:    TCollectionItem.Index (1 ), TCollectionItem.ID (1 ), TCollectionItem.GetDisplayName (1 ),
                TCollectionItem.SetDisplayName (1 )



                2.40          TComponent



                2.40.1         Description

                TComponent  is  the  base  class  for  any  set  of  classes  that  needs  owner-owned  functionality,
                and which needs support for property streaming.  All classes that should be handled by an
                IDE (Integrated Development Environment) must descend from TComponent, as it includes
                all support for streaming all its published properties.

                Components can 'own' other components.  TComponent introduces methods for enumerating
                the child components.  It also allows to name the owned components with a unique name.
                Furthermore, functionality for sending notifications when a component is removed from the
                list or removed from memory alltogether is also introduced in TComponent

                TComponent  introduces  a  form  of  automatic  memory  management:  When  a  component  is
                destroyed, all its child components will be destroyed first.



                2.40.2         Interfaces  overview

                __Page______Property_______________________________________Description_____________________________________________*
 *___________
                  232       IInterfaceComponentReference                   Interface for checking component references
                __1435______IUnknown_______________________________________Basic_interface_for_all_COM-based_interfaces____________*
 *___________



                                                                                 289

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.40.3         Method  overview

                __Page______Property_____________________________Description_______________________________________________________*
 *___________
                  291       BeforeDestruction                    Overrides standard BeforeDestruction.
                  291       Create                               Creates a new instance of the component.
                  291       Destroy                              Destroys the instance of the component.
                  292       DestroyComponents                    Destroy child components.
                  292       Destroying                           Called when the component is being destroyed
                  292       ExecuteAction                        Standard action execution method.
                  292       FindComponent                        Finds and returns the named component in the owned
                                                                 components.
                  293       FreeNotification                     Ask  the  component  to  notify  called  when  it  is  being
                                                                 destroyed.
                  293       FreeOnRelease                        Part of the IVCLComObject interface.
                  293       GetEnumerator                        Create an IEnumerator instance
                  294       GetNamePath                          Returns the name path of this component.
                  294       GetParentComponent                   Returns the parent component.
                  294       HasParent                            Does the component have a parent ?
                  294       InsertComponent                      Insert the given component in the list of owned compo-
                                                                 nents.
                  296       IsImplementorOf                      Checks if the current component is the implementor of
                                                                 the interface
                  296       ReferenceInterface                   Interface implementation of Notification
                  295       RemoveComponent                      Remove  the  given  component  from  the  list  of  owned
                                                                 components.
                  293       RemoveFreeNotification               Remove a component from the Free Notification list.
                  295       SafeCallException                    Part of the IVCLComObject Interface.
                  295       SetSubComponent                      Sets the csSubComponent style.
                  295       UpdateAction                         Updates the state of an action.
                __290_______WriteState___________________________Writes_the_component_to_a_stream._________________________________*
 *___________



                2.40.4         Property  overview

                __Page______Property_____________________Access______Description___________________________________________________*
 *___________
                  296       ComObject                    r           Interface reference implemented by the component
                  297       ComponentCount               r           Count of owned components
                  297       ComponentIndex               rw          Index of component in it's owner's list.
                  296       Components                   r           Indexed list (zero-based) of all owned components.
                  297       ComponentState               r           Current component's state.
                  298       ComponentStyle               r           Current component's style.
                  298       DesignInfo                   rw          Information for IDE designer.
                  299       Name                         rws         Name of the component.
                  298       Owner                        r           Owner of this component.
                  299       Tag                          rw          Tag value of the component.
                __298_______VCLComObject_________________rw__________Not_implemented.______________________________________________*
 *___________



                2.40.5         TComponent.WriteState

    Synopsis:    Writes the component to a stream.

Declaration:     procedure  WriteState(Writer:  TWriter);    Virtual

    Visibility:   public



                                                                                 290

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     WriteState  writes  the  component's  current  state  to  a  stream  through  the  writer  (409  )
                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 (289  ) implementation of WriteState simply calls TWriter.WriteData (1 ).
                Descendent  classes  can,  however,  override  WriteStateto  provide  additional  processing  of
                stream data.

    See also:    ReadState (1 ), TStream.WriteComponent (1 ), TWriter.WriteData (1 )



                2.40.6         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 (1 ), Owner (1 )



                2.40.7         TComponent.Destroy

    Synopsis:    Destroys the instance of the component.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy sends a opRemove notification to all components in the free-notification list.  After
                that,  all  owned  components  are  destroyed  by  calling  DestroyComponents  (1 )  (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 (1 ), Owner (1 ), DestroyComponents (1 ), Components (1 )



                2.40.8         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 (1 )

    See also:    TComponent.ComponentState (1 )



                                                                                 291

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.40.9         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 (1 ) 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  ex-
                ception, it's TComponent.Destroy (1 ) destructor will not be called, which may result in an
                endless loop.

    See also:    Destroy (1 ), Components (1 )



                2.40.10          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 (1 ) property, and does the
                same for all owned components.

                It  is  not  necessary  to  call  Destroying  directly,  the  destructor  Destroy  (1 )  does  this  auto-
                matically.

    See also:    State (1 ), Destroy (1 )



                2.40.11          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 (254  ), TBasicAction.ExecuteAction (1 ), TBasicAction.HandlesTarget (1 ), TCom-
                ponent.UpdateAction (1 )



                2.40.12          TComponent.FindComponent

    Synopsis:    Finds and returns the named component in the owned components.

Declaration:     function  FindComponent(const  AName:  string)  :  TComponent

    Visibility:   public



                                                                                 292

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (1 ), Name (1 )



                2.40.13          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 (1 ) method is called for all components in the freenotification
                list.

    See also:    Components (1 ), Notification (1 ), TComponent.RemoveFreeNotification (1 )



                2.40.14          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 (1 )



                2.40.15          TComponent.FreeOnRelease

    Synopsis:    Part of the IVCLComObject interface.

Declaration:     procedure  FreeOnRelease

    Visibility:   public

Description:     Provided for Delphi compatibility, but is not yet impltmentedd.



                2.40.16          TComponent.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TComponentEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1433   ) interface for TComponent.
                It  creates  a  TComponentEnumerator  (299  )  instance  and  returns  it's  IEnumerator  (1433   )
                interface.  The enumerator enumerates all child components of the component instance.

    See also:    TComponentEnumerator (299  ), IEnumerator (1433   ), IEnumerable (1433   )



                                                                                 293

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.40.17          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 (1 ) property of the component.

    See also:    Name (1 ), TPersistent.GetNamePath (1 )



                2.40.18          TComponent.GetParentComponent

    Synopsis:    Returns the parent component.

Declaration:     function  GetParentComponent  :  TComponent;    Dynamic

    Visibility:   public

Description:     GetParentComponent can be implemented to return the parent component of this compo-
                nent.  The implementation of this method in TComponent always returns Nil.  Descendent
                classes must override this method to return the visual parent of the component.

    See also:    HasParent (1 ), Owner (1 )



                2.40.19          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 (1 ) will return the parent component.

    See also:    HasParent (1 ), Owner (1 )



                2.40.20          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 (289  ) to see whether the component can be inserted.  It then
                checks whether there are no name conflicts by calling ValidateRename (1 ).  If neither of these
                checks have raised an exception the component is inserted, and notified of the insert.

    See also:    RemoveComponent (1 ), Insert (1 ), ValidateContainer (1 ), ValidateRename (1 ), Notification
                (1 )



                                                                                 294

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.40.21          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 (1 ), Remove (1 ), ValidateRename (1 ), Notification (1 )



                2.40.22          TComponent.SafeCallException

    Synopsis:    Part of the IVCLComObject Interface.

Declaration:     function  SafeCallException(ExceptObject:  TObject;ExceptAddr:  Pointer)
                                                             :  HRESULT;    Override

    Visibility:   public

Description:     Provided for Delphi compatibility, but not implemented.



                2.40.23          TComponent.SetSubComponent

    Synopsis:    Sets the csSubComponent style.

Declaration:     procedure  SetSubComponent(ASubComponent:  Boolean)

    Visibility:   public

Description:     SetSubComponent includes csSubComponent in the ComponentStyle (1 ) property if ASubComponent
                is True, and excludes it again if  ASubComponent is False.

    See also:    TComponent.ComponentStyle (1 )



                2.40.24          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 (254  ), TBasicAction.UpdateTarget (1 ), TBasicAction.HandlesTarget (1 ), TBa-
                sicAction.ExecuteAction (1 )



                                                                                 295

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.40.25          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 (232  ) and the GetComponent
                method should return the current instance.

    See also:    IInterfaceComponentReference (232  )



                2.40.26          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  (1 )  method  of  TComponent  for  interfaces.
                If the interface implements IInterfaceComponentReference (232  ), then the component that
                implements the interface is notified of the given operation Op.

       Errors:   None.

    See also:    TComponent.Notification (1 ), IInterfaceComponentReference (232  )



                2.40.27          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
                (227  ).

    See also:    EComponentError (227  )



                2.40.28          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 (1 ).

    See also:    ComponentCount (1 ), Owner (1 )



                                                                                 296

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.40.29          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 (1 ) array.

    See also:    Components (1 ), Owner (1 )



                2.40.30          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 (1 ), ComponentCount (1 ), Owner (1 )



                2.40.31          TComponent.ComponentState

    Synopsis:    Current component's state.

Declaration:     Property  ComponentState  :  TComponentState

    Visibility:   public

      Access:    Read

Description:     ComponentState  indicates  the  current  state  of  the  component.  It  is  a  set  of  flags  which
                indicate the various stages in the lifetime of a component.  The following values can occur in
                this set:



                                                          Table 2.18:  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.



                                                                                 297

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                The component state is set by various actions such as reading it from stream, destroying it
                etc.

    See also:    SetAncestor (1 ), SetDesigning (1 ), SetInline (1 ), SetDesignInstance (1 ), Updating (1 ), Up-
                dated (1 ), Loaded (1 )



                2.40.32          TComponent.ComponentStyle

    Synopsis:    Current component's style.

Declaration:     Property  ComponentStyle  :  TComponentStyle

    Visibility:   public

      Access:    Read

Description:     Current component's style.



                2.40.33          TComponent.DesignInfo

    Synopsis:    Information for IDE designer.

Declaration:     Property  DesignInfo  :  LongInt

    Visibility:   public

      Access:    Read,Write

Description:     DesignInformation can be used by an IDE to store design information in the component.
                It should not be used by an application programmer.

    See also:    Tag (1 )



                2.40.34          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 compo-
                nent's InsertComponent (1 ) method, or by removing the component from it's owner's owned
                component list using the RemoveComponent (1 ) method.

    See also:    Components (1 ), InsertComponent (1 ), RemoveComponent (1 )



                2.40.35          TComponent.VCLComObject

    Synopsis:    Not implemented.

Declaration:     Property  VCLComObject  :  Pointer

    Visibility:   public

      Access:    Read,Write

Description:     VCLComObject is not yet implemented in Free Pascal.



                                                                                 298

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.40.36          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 (1 ), Owner (1 )



                2.40.37          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 (1 )



                2.41          TComponentEnumerator



                2.41.1         Description

                TComponentEnumerator  implements  the  #rtl.system.IEnumerator  (1433   )  interface  for  the
                TComponent (289  ) class, so the TComponent class can be used in a for  ...    in loop over
                the TComponent.Components (1 ) child components of the component.  It is returned by the
                TComponent.GetEnumerator (1 ) method of  TComponent.


    See also:    TComponent (289  ), TComponent.GetEnumerator (1 ), #rtl.system.IEnumerator (1433   )



                2.41.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  300       Create              Initialize a new instance of  TComponentEnumerator
                  300       GetCurrent          Return the current pointer in the list
                  300       MoveNext            Move  the  position  of  the  enumerator  to  the  next  position  in  the
                ________________________________children_of_the_component._________________________________________________________*
 *___________



                                                                                 299

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.41.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __300_______Current_________r____________Current_pointer_in_the_list_______________________________________________*
 *___________



                2.41.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 (289  )



                2.41.5         TComponentEnumerator.GetCurrent

    Synopsis:    Return the current pointer in the list

Declaration:     function  GetCurrent  :  TComponent

    Visibility:   public

Description:     GetCurrent returns the current TComponent (289  ) child component instance in the enu-
                merator.

       Errors:   No checking is done on the validity of the current position.

    See also:    MoveNext (1 ), TComponent.Components (1 )



                2.41.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 (1 )



                2.41.7         TComponentEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  TComponent

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (1 ) as a property.

    See also:    GetCurrent (1 )



                                                                                 300

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.42          TCustomMemoryStream



                2.42.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 (1 ) 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 (336  ).  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 (336  ).


    See also:    TMemoryStream (336  ), TStream (364  )



                2.42.2         Method  overview

                __Page______Property________________Description____________________________________________________________________*
 *___________
                  301       Read                    Reads Count bytes from the stream into buffer.
                  302       SaveToFile              Writes the contents of the stream to a file.
                  302       SaveToStream            Writes the contents of the memory stream to another stream.
                __301_______Seek____________________Sets_a_new_position_in_the_stream._____________________________________________*
 *___________



                2.42.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __303_______Memory__________r____________Pointer_to_the_data_kept_in_the_memory_stream.____________________________*
 *___________



                2.42.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 (1 ) method of TStream (364  ).  It will read as much
                bytes as are still available in the memory area pointer to by Memory (1 ).  After the bytes
                are read, the internal stream position is updated.

    See also:    TCustomMemoryStream.Memory (1 ), TStream.Read (1 )



                2.42.5         TCustomMemoryStream.Seek

    Synopsis:    Sets a new position in the stream.

Declaration:     function  Seek(const  Offset:  Int64;Origin:  TSeekOrigin)  :  Int64
                                      ;    Override



                                                                                 301

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    Visibility:  public

Description:     Seek overrides the abstract TStream.Seek (1 ) 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 (1 ), TStream.Size (1 ), TCustomMemoryStream.Memory (1 )



                2.42.6         TCustomMemoryStream.SaveToStream

    Synopsis:    Writes the contents of the memory stream to another stream.

Declaration:     procedure  SaveToStream(Stream:  TStream)

    Visibility:   public

Description:     SaveToStream writes the contents of the memory stream to Stream.  The content of Stream
                is not cleared first.  The current position of the memory stream is not changed by this action.

 Remark:         This method will work much faster than the use of the TStream.CopyFrom (1 ) 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 (230  ) exception will be raised.

    See also:    TCustomMemoryStream.SaveToFile (1 ), TStream.CopyFrom (1 )



                2.42.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 (1 ).

 Remark:         This method will work much faster than the use of the TStream.CopyFrom (1 ) 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  (230  )  exception
                may occur.

    See also:    TCustomMemoryStream.SaveToStream (1 ), TFileStream (308  ), TStream.CopyFrom (1 )



                                                                                 302

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.42.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 (1 )



                2.43          TDataModule



                2.43.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 (1 )



                2.43.2         Method  overview

                __Page______Property_____________________Description_______________________________________________________________*
 *___________
                  304       AfterConstruction            Overrides standard TObject (1439   ) behaviour.
                  305       BeforeDestruction
                  304       Create                       Create a new instance of a TDataModule.
                  304       CreateNew
                __304_______Destroy______________________Destroys_the_TDataModule_instance.________________________________________*
 *___________



                2.43.3         Property  overview

                __Page______Property__________________Access_______Description_____________________________________________________*
 *___________
                  305       DesignOffset              rw           Position property needed for manipulation in an IDE.
                  305       DesignSize                rw           Size property needed for manipulation in an IDE.
                  306       OldCreateOrder            rw           Determines when OnCreate and OnDestroy are trig-
                                                                   gered.
                  305       OnCreate                  rw           Event handler, called when the datamodule is created.
                  306       OnDestroy                 rw           Event  handler,  called  when  the  datamodule  is  de-
                ___________________________________________________stroyed.________________________________________________________*
 *___________



                                                                                 303

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.43.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 (1 ).
                After  that  it  reads  the  published  properties  from  a  stream  using  InitInheritedComponent
                (219  ) if a descendent class is instantiated.  If the OldCreateOrder (1 ) property is True, the
                TDataModule.OnCreate (1 ) event is called.

       Errors:   An exception can be raised during the streaming operation.

    See also:    TDataModule.CreateNew (1 )



                2.43.5         TDataModule.CreateNew

    Synopsis:

Declaration:     constructor  CreateNew(AOwner:  TComponent)
                constructor  CreateNew(AOwner:  TComponent;CreateMode:  Integer);    Virtual

    Visibility:   default

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
                (212  ) handler is set, then it is called, with the newly created instance as an argument.

    See also:    TDataModule.Create (1 ), AddDataModule (212  ), TDataModule.OnCreate (1 )



                2.43.6         TDataModule.Destroy

    Synopsis:    Destroys the TDataModule instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy destroys the TDataModule instance.  If the OldCreateOrder (1 ) property is True
                the OnDestroy (1 ) event handler is called prior to destroying the data module.

                Before calling the inherited destroy, the RemoveDataModule (212  ) 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 (1 ), RemoveDataModule (212  )



                2.43.7         TDataModule.AfterConstruction

    Synopsis:    Overrides standard TObject (1439   ) behaviour.

Declaration:     procedure  AfterConstruction;    Override

    Visibility:   public

Description:     AfterConstruction calls the OnCreate (1 ) handler if the OldCreateOrder (1 ) property is
                False.

    See also:    TDataModule.OldCreateOrder (1 ), TDataModule.OnCreate (1 )



                                                                                 304

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.43.8         TDataModule.BeforeDestruction

    Synopsis:

Declaration:     procedure  BeforeDestruction;    Override

    Visibility:   public

Description:     BeforeDestruction calls the OnDestroy (1 ) handler if the OldCreateOrder (1 ) property is
                False.

    See also:    TDataModule.OldCreateOrder (1 ), TDataModule.OnDestroy (1 )



                2.43.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 (1 )



                2.43.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 (1 )



                2.43.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 (1 ) property.

    See also:    TDataModule.Create (1 ), TDataModule.CreateNew (1 ), TDataModule.OldCreateOrder (1 )



                                                                                 305

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.43.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 (1 ) property.

    See also:    TDataModule.Destroy (1 ), TDataModule.OnCreate (1 ), TDataModule.Create (1 ), TData-
                Module.CreateNew (1 ), TDataModule.OldCreateOrder (1 )



                2.43.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 (1 ) and OnDestroy (1 ) event han-
                dlers 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 (1 ), TDataModule.OnCreate (1 ), TDataModule.Destroy (1 ), TData-
                Module.Create (1 ), TDataModule.CreateNew (1 ), TDataModule.OldCreateOrder (1 )



                2.44          TFiler



                2.44.1         Description

                Class responsible for streaming of components.



                2.44.2         Method  overview

                __Page______Property__________________________Description__________________________________________________________*
 *___________
                  307       DefineBinaryProperty
                __307_______DefineProperty_________________________________________________________________________________________*
 *___________



                                                                                 306

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.44.3         Property  overview

                __Page______Property_________________Access_______Description______________________________________________________*
 *___________
                  308       Ancestor                 rw           Ancestor component from which an inherited compo-
                                                                  nent is streamed.
                  308       IgnoreChildren           rw           Determines whether children will be streamed as well.
                  307       LookupRoot               r            Component used to look up ancestor components.
                  307       Root                     rw           The root component is the initial component which is
                __________________________________________________being_streamed.__________________________________________________*
 *___________



                2.44.4         TFiler.DefineProperty

    Synopsis:

Declaration:     procedure  DefineProperty(const  Name:  string;ReadData:  TReaderProc;
                                                        WriteData:  TWriterProc;HasData:  Boolean)
                                                        ;    Virtual;    Abstract

    Visibility:   public

Description:



                2.44.5         TFiler.DefineBinaryProperty

    Synopsis:

Declaration:     procedure  DefineBinaryProperty(const  Name:  string;ReadData:  TStreamProc;
                                                                  WriteData:  TStreamProc;HasData:  Boolean)
                                                                  ;    Virtual;    Abstract

    Visibility:   public

Description:



                2.44.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 (1 )



                2.44.7         TFiler.LookupRoot

    Synopsis:    Component used to look up ancestor components.

Declaration:     Property  LookupRoot  :  TComponent

    Visibility:   public

      Access:    Read



                                                                                 307

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (1 ).

    See also:    Root (1 )



                2.44.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 (1 ), LookupRoot (1 )



                2.44.9         TFiler.IgnoreChildren

    Synopsis:    Determines whether children will be streamed as well.

Declaration:     Property  IgnoreChildren  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     By default, all children (i.e.  owned objects) will also be streamed when streaming a com-
                ponent.  This property can be used to prevent owned objects from being streamed.



                2.45          TFileStream



                2.45.1         Description

                TFileStream is a TStream (364  ) 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 (1 ) property to the list of public properties.


    See also:    TFileStream.Create (1 ), TStream (364  )



                2.45.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  309       Create          Creates a file stream.
                __309_______Destroy_________Destroys_the_file_stream.______________________________________________________________*
 *___________



                2.45.3         Property  overview

                __Page______Property_________Access_______Description______________________________________________________________*
 *___________
                __309_______FileName_________r____________The_filename_of_the_stream.______________________________________________*
 *___________



                                                                                 308

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.45.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:   default

Description:     Create  creates  a  new  instance  of  a  TFileStream  class.  It  opens  the  file  AFileName  with
                mode Mode, which can have one of the following values:



                                                                       Table 2.19:

                        fmCreate                     TFileStream.Create (1 ) creates a new file if needed.
                        fmOpenRead                   TFileStream.Create (1 ) opens a file with read-only access.
                        fmOpenWrite                  TFileStream.Create (1 ) opens a file with write-only access.
                        fmOpenReadWrite              TFileStream.Create (1 ) opens a file with read-write access.



                After the file has been opened in the requested mode and a handle has been obtained from
                the operating system, the inherited constructor is called.

       Errors:   If the file could not be opened in the requested mode, an EFOpenError (228  ) exception is
                raised.

    See also:    TStream (364  ), TFileStream.FileName (1 ), THandleStream.Create (1 )



                2.45.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 (1 )



                2.45.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 (1 )



                                                                                 309

            __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



            2.46          TFPList



            2.46.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 (328  ), 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  (383  )  descendent  such  as
            TStringList (378  ).  To manage general objects, a TCollection (279  ) class exists, from which
            a descendent can be made to manage collections of various kinds.


See also:    TStrings (383  ), TCollection (279  )



            2.46.2         Method  overview

            __Page______Property__________________Description______________________________________________________________________*
 *_______
              311       Add                       Adds a new pointer to the list.
              311       AddList                   Add all pointers from another list
              314       Assign                    Assign performs the given operation on the list.
              311       Clear                     Clears the pointer list.
              311       Delete                    Removes a pointer from the list.
              310       Destroy                   Destroys the list and releases the memory used to store the list
                                                  elements.
              312       Error                     Raises an EListError (229  ) exception.
              312       Exchange                  Exchanges two pointers in the list.
              312       Expand                    Increases the capacity of the list if needed.
              312       Extract                   Remove the first occurrence of a pointer from the list.
              313       First                     Returns the first non-nil pointer in the list.
              315       ForEachCall               Call a procedure or method for each pointer in the list.
              313       GetEnumerator             Create an IEnumerator instance
              313       IndexOf                   Returns the index of a given pointer.
              313       Insert                    Inserts a new pointer in the list at a given position.
              314       Last                      Returns the last non-nil pointer in the list.
              314       Move                      Moves a pointer from one position in the list to another.
              315       Pack                      Removes Nil pointers from the list and frees unused memory.
              314       Remove                    Removes a value from the list.
            __315_______Sort______________________Sorts_the_pointers_in_the_list.__________________________________________________*
 *_______



            2.46.3         Property  overview

            __Page______Property________Access_______Description___________________________________________________________________*
 *_______
              315       Capacity        rw           Current capacity (i.e.  number of pointers that can be stored)
                                                     of the list.
              316       Count           rw           Current number of pointers in the list.
              316       Items           rw           Provides access to the pointers in the list.
            __316_______List____________r____________Memory_array_where_pointers_are_stored._______________________________________*
 *_______



            2.46.4         TFPList.Destroy

Synopsis:    Destroys the list and releases the memory used to store the list elements.



                                                                             310

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Declaration:     destructor  Destroy;    Override

    Visibility:  public

Description:     Destroy  destroys  the  list  and  releases  the  memory  used  to  store  the  list  elements.   The
                elements themselves are in no way touched, i.e.  any meomory they point to must be explicitly
                released before calling the destructor.



                2.46.5         TFPList.AddList

    Synopsis:    Add all pointers from another list

Declaration:     procedure  AddList(AList:  TFPList)

    Visibility:   public

Description:     AddList adds all pointers from AList to the list.  If a pointer is already present, it is added
                a second time.

    See also:    TFPList.Assign (1 ), TList.AddList (1 )



                2.46.6         TFPList.Add

    Synopsis:    Adds a new pointer to the list.

Declaration:     function  Add(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Add  adds  a  new  pointer  to  the  list  after  the  last  pointer  (i.e.   at  position  Count,  thus
                increasing  the  item  count  with  1.  If  the  list  is  at  full  capacity,  the  capacity  of  the  list  is
                expanded, using the Grow (1 ) method.

                To insert a pointer at a certain position in the list, use the Insert (1 ) method instead.

    See also:    Delete (1 ), Grow (1 ), Insert (1 )



                2.46.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 (1 )



                2.46.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.



                                                                                 311

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.46.9         TFPList.Error

    Synopsis:    Raises an EListError (229  ) exception.

Declaration:     class  procedure  Error(const  Msg:  string;Data:  PtrInt)

    Visibility:   public

Description:     Error raises an EListError (229  ) exception, with a message formatted with Msg and Data.



                2.46.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 (229  ) exception will be raised.



                2.46.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 (1 )



                2.46.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 (1 )



                                                                                 312

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.46.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 (1 )



                2.46.14          TFPList.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TFPListEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1433   ) interface for TFPList.  It
                creates a TFPListEnumerator (317  ) instance and returns it's IEnumerator (1433   ) interface.

    See also:    TFPListEnumerator (317  ), IEnumerator (1433   ), IEnumerable (1433   )



                2.46.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.



                2.46.16          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 (229  ) exception is raised.

    See also:    Add (1 ), Delete (1 )



                                                                                 313

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.46.17          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 (1 )



                2.46.18          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  (229  )
                exception is raised.

    See also:    Exchange (1 )



                2.46.19          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 (205  ) type.

    See also:    TFPList.Add (1 ), TFPList.Clear (1 )



                2.46.20          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 (1 ), IndexOf (1 ), Insert (1 )



                                                                                 314

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.46.21          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 (1 )



                2.46.22          TFPList.Sort

    Synopsis:    Sorts the pointers in the list.

Declaration:     procedure  Sort(Compare:  TListSortCompare)

    Visibility:   public

Description:     Sort>  sorts  the  pointers  in  the  list.  Two  pointers  are  compared  by  passing  them  to  the
                Compare function.  The result of this function determines how the pointers will be sorted:


                      oIf the result of this function is negative,  the first pointer is assumed to be 'less' than
                       the second and will be moved before the second in the list.

                      oIf the function result is positive,  the first pointer is assumed to be 'greater than' the
                       second and will be moved after the second in the list.

                      oif the function result is zero, the pointers are assumed to be 'equal' and no moving will
                       take place.


                The sort is done using a quicksort algorithm.



                2.46.23          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:   default

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 (206  ), TListCallback (205  )



                2.46.24          TFPList.Capacity

    Synopsis:    Current capacity (i.e.  number of pointers that can be stored) of the list.

Declaration:     Property  Capacity  :  Integer

    Visibility:   public



                                                                                 315

                __________________________________________________________CHAPTER_2.___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  (1 )  or  insert  (1 ),  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 (1 ), Count (1 )



                2.46.25          TFPList.Count

    Synopsis:    Current number of pointers in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Count is the current number of (possibly Nil) pointers in the list.  Since the list is zero-based,
                the index of the largest pointer is Count-1.



                2.46.26          TFPList.Items

    Synopsis:    Provides access to the pointers in the list.

Declaration:     Property  Items[Index:  Integer]:  Pointer;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items is used to access the pointers in the list.  It is the default property of the TFPList
                class, so it can be omitted.

                The list is zero-based, so Index must be in the range 0 to Count-1.



                2.46.27          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.



                                                                                 316

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.47          TFPListEnumerator



                2.47.1         Description

                TFPListEnumerator implements the #rtl.system.IEnumerator (1433   ) interface for the TF-
                PList (310  ) class, so the TFPList class can be used in a for  ...    in loop.  It is returned
                by the TFPList.GetEnumerator (1 ) method of  TFPList.


    See also:    TFPList (310  ), TFPList.GetEnumerator (1 ), #rtl.system.IEnumerator (1433   )



                2.47.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  317       Create              Initialize a new instance of  TFPListEnumerator
                  317       GetCurrent          Return the current pointer in the list
                __317_______MoveNext____________Move_the_position_of_the_enumerator_to_the_next_position_in_the_list.______________*
 *___________



                2.47.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __318_______Current_________r____________Current_pointer_in_the_list_______________________________________________*
 *___________



                2.47.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 (310  )



                2.47.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 (1 )



                2.47.6         TFPListEnumerator.MoveNext

    Synopsis:    Move the position of the enumerator to the next position in the list.

Declaration:     function  MoveNext  :  Boolean

    Visibility:   public



                                                                                 317

                __________________________________________________________CHAPTER_2.___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 (1 )



                2.47.7         TFPListEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  Pointer

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (1 ) as a property.

    See also:    GetCurrent (1 )



                2.48          THandleStream



                2.48.1         Description

                THandleStream  is  an  abstract  descendent  of  the  TStream  (364  )  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 (1 ) and Write (1 ) 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 (364  ), TFileStream (308  )



                2.48.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  319       Create          Create a handlestream from an OS Handle.
                  319       Read            Overrides standard read method.
                  320       Seek            Overrides the Seek method.
                  319       SetSize
                __319_______Write___________Overrides_standard_write_method._______________________________________________________*
 *___________



                2.48.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __320_______Handle__________r____________The_OS_handle_of_the_stream.______________________________________________*
 *___________



                                                                                 318

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.48.4         THandleStream.SetSize

Declaration:     procedure  SetSize(NewSize:  LongInt);    Override
                procedure  SetSize(const  NewSize:  Int64);    Override

    Visibility:   default



                2.48.5         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 (364  )



                2.48.6         THandleStream.Read

    Synopsis:    Overrides standard read method.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read overrides the Read (1 ) method of  TStream.  It uses the Handle (1 ) 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 (1 ), THandleStream.Write (1 ), THandleStream.Handle (1 )



                2.48.7         THandleStream.Write

    Synopsis:    Overrides standard write method.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write overrides the Write (1 ) method of TStream.  It uses the Handle (1 ) 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 (1 ), THandleStream.Write (1 ), THandleStream.Handle (1 )



                                                                                 319

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.48.8         THandleStream.Seek

    Synopsis:    Overrides the Seek method.

Declaration:     function  Seek(const  Offset:  Int64;Origin:  TSeekOrigin)  :  Int64
                                      ;    Override

    Visibility:   public

Description:     seek uses the FileSeek (1525   ) method to position the stream on the desired position.  Note
                that handle stream descendents (notably pipes) can override the method to prevent the seek.



                2.48.9         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 (1 )

    See also:    THandleStream (318  ), THandleStream.Create (1 )



                2.49          TInterfacedPersistent



                2.49.1         Description

                TInterfacedPersistent is a direct descendent of TPersistent (347  ) which implements the
                #rtl.system.IInterface (1258   ) interface.  In particular, it implements the QueryInterface as
                a public method.


    See also:    IInterface (1258   )



                2.49.2         Interfaces  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                __1258______IInterface_______Basic_interface_for_all_COM_based_interfaces__________________________________________*
 *___________



                2.49.3         Method  overview

                __Page______Property_____________________Description_______________________________________________________________*
 *___________
                  321       AfterConstruction            Overrides the standard AfterConstruction method.
                __320_______QueryInterface_______________Implementation_of__IInterface.QueryInterface______________________________*
 *___________



                2.49.4         TInterfacedPersistent.QueryInterface

    Synopsis:    Implementation of  IInterface.QueryInterface

Declaration:     function  QueryInterface(const  IID:  TGuid;out  Obj)  :  HRESULT;    Virtual

    Visibility:   public



                                                                                 320

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     QueryInterface simply calls GetInterface using the specified IID, and returns the correct
                values.

    See also:    TObject.GetInterface (1447   )



                2.49.5         TInterfacedPersistent.AfterConstruction

    Synopsis:    Overrides the standard AfterConstruction method.

Declaration:     procedure  AfterConstruction;    Override

    Visibility:   public

Description:     AfterConstruction is overridden to do some extra interface housekeeping:  a reference to
                the IInterface interface of the owning class is obtained (if it exists).



                2.50          TInterfaceList



                2.50.1         Description

                TInterfaceList is a standard implementation of the IInterfaceList (232  ) interface.  It uses
                a TThreadList (407  ) instance to store the list of interfaces.


    See also:    IInterfaceList (232  ), TList (328  )



                2.50.2         Interfaces  overview

                __Page______Property_______________Description_____________________________________________________________________*
 *___________
                __232_______IInterfaceList_________Interface_for_maintaining_a_list_of_interfaces._________________________________*
 *___________



                2.50.3         Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  324       Add                       Add an interface to the list
                  322       Clear                     Removes all interfaces from the list.
                  322       Create                    Create a new instance of  TInterfaceList
                  322       Delete                    Delete an interface from the list.
                  322       Destroy                   Destroys the list of interfaces
                  323       Exchange                  Exchange 2 interfaces in the list
                  325       Expand                    Expands the list
                  323       First                     Returns the first non-Nil element in the list.
                  323       GetEnumerator             Create an IEnumerator instance
                  323       IndexOf                   Returns the index of an interface.
                  324       Insert                    Insert an interface to the list
                  324       Last                      Returns the last non-Nil element in the list.
                  325       Lock                      Lock the list
                  324       Remove                    Remove an interface from the list
                __325_______Unlock____________________UnLocks_a_locked_list________________________________________________________*
 *___________



                                                                                 321

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.50.4         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  325       Capacity        rw           The current capacity of the list.
                  326       Count           rw           The current number of elements in the list.
                __326_______Items___________rw___________Array-based_access_to_the_list's_items.___________________________________*
 *___________



                2.50.5         TInterfaceList.Create

    Synopsis:    Create a new instance of  TInterfaceList

Declaration:     constructor  Create

    Visibility:   public

Description:     Create creates a new instance of the TInterfaceList class.  It sets up the internal structures
                needed to store the list of interfaces.

    See also:    Destroy (1 )



                2.50.6         TInterfaceList.Destroy

    Synopsis:    Destroys the list of interfaces

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy first calls Clear (1 ) and then frees the TInterfaceList instance from memory.

                Note that the Clear method decreases the reference count of all interfaces.

    See also:    Create (1 ), Clear (1 )



                2.50.7         TInterfaceList.Clear

    Synopsis:    Removes all interfaces from the list.

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear is the implementation of the IInterfaceList.Clear (1 ) method.  It removes all interfaces
                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 (1 ), Add (1 ), Destroy (1 ), TList.Clear (1 ), TFPList.Clear (1 )



                2.50.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 (1 ) method.  It clears the slot first
                and then removes the element from the list.

    See also:    IInterfaceList.Delete (1 ),  TInterfaceList.Remove (1 ),  TInterfaceList.Add (1 ),  TList.Delete
                (1 ), TFPList.Delete (1 )



                                                                                 322

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.50.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 (1 ) method.  It exchanges
                the position of 2 interfaces in the list.

    See also:    IInterfaceList.Exchange (1 ), TInterfaceList.Delete (1 ), TInterfaceList.Add (1 ), TList.Exchange
                (1 ), TFPList.Exchange (1 )



                2.50.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  (1 )  method.   It  returns  the  first
                non-Nil element from the list.

    See also:    IInterfaceList.First (1 ), TList.First (1 )



                2.50.11          TInterfaceList.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TInterfaceListEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1433   ) interface for TInterfaceList.
                It  creates  a  TInterfaceListEnumerator  (326  )  instance  and  returns  it's  IEnumerator  (1433   )
                interface.  The enumerator enumerates all interfaces in the list.

    See also:    TInterfaceListEnumerator (326  ), IEnumerator (1433   ), IEnumerable (1433   )



                2.50.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  (1 )  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 (1 ), TList.IndexOf (1 )



                                                                                 323

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.50.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 (1 ) 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 (1 ), TInterfaceList.Delete (1 ), TInterfaceList.Insert (1 ), TList.Add (1 ),
                TFPList.Add (1 )



                2.50.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 (1 ) method.  It inserts an interface
                in the list at the indicated position.  This operation will increment the reference count of the
                interface.

    See also:    IInterfaceList.Insert (1 ), TInterfaceList.Delete (1 ), TInterfaceList.Add (1 ), TList.Insert (1 ),
                TFPList.Insert (1 )



                2.50.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 (1 ) method.  It returns the last non-Nil
                element from the list.

    See also:    IInterfaceList.Last (1 ), TInterfaceList.First (1 ), TList.Last (1 ), TFPList.Last (1 )



                2.50.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 (1 ) method.  It removes the first
                occurrence of the interface from the list.

    See also:    IInterfaceList.Remove (1 ), TInterfaceList.Delete (1 ), TInterfaceList.IndexOf (1 ), TList.Remove
                (1 ), TFPList.Remove (1 )



                                                                                 324

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.50.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 (1 ) method.  It limits
                access to the list to the current thread.

    See also:    IInterfaceList.Lock (1 ), TInterfaceList.UnLock (1 ), TThreadList.LockList (1 )



                2.50.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 (1 ) method.
                After a call to unlock, the current thread releases the list for manipulation by other threads.

    See also:    IInterfaceList.UnLock (1 ), TInterfaceList.Lock (1 ), TThreadList.UnLockList (1 )



                2.50.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 (1 )



                2.50.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 (1 ), TInterfaceList.Count (1 ), TList.Capacity (1 ), TFPList.Capacity
                (1 )



                                                                                 325

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.50.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 (1 ), TInterfaceList.Items (1 ), TInterfaceList.Capacity (1 ), TList.Count
                (1 ), TFPList.Count (1 )



                2.50.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 (1 ).

    See also:    IInterfaceList.Items (1 ), TInterfaceList.Count (1 ), TList.Items (1 ), TFPList.Items (1 )



                2.51          TInterfaceListEnumerator



                2.51.1         Description

                TInterfaceListEnumerator implements the #rtl.system.IEnumerator (1433   ) interface for
                the TInterfaceList (321  ) class, so the TInterfaceList class can be used in a for  ...    in
                loop  over  the  TInterfaceList.Components  (1 )  child  components  of  the  component.   It  is
                returned by the TInterfaceList.GetEnumerator (1 ) method of  TInterfaceList.


    See also:    TInterfaceList (321  ), TInterfaceList.GetEnumerator (1 ), #rtl.system.IEnumerator (1433   )



                2.51.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  327       Create              Initialize a new instance of  TInterfaceListEnumerator
                  327       GetCurrent          Return the current pointer in the list
                  327       MoveNext            Move  the  position  of  the  enumerator  to  the  next  position  in  the
                ________________________________children_of_the_component._________________________________________________________*
 *___________



                2.51.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __327_______Current_________r____________Current_pointer_in_the_list_______________________________________________*
 *___________



                                                                                 326

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.51.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 (321  )



                2.51.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 (321  ) list.

       Errors:   No checking is done on the validity of the current position.

    See also:    MoveNext (1 ), TInterfaceList.Components (1 )



                2.51.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 (1 )



                2.51.7         TInterfaceListEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  IUnknown

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (1 ) as a property.

    See also:    GetCurrent (1 )



                                                                                 327

            __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



            2.52          TList



            2.52.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 (310  ) may be used instead.

            To  manage  collections  of  strings,  it  is  better  to  use  a  TStrings  (383  )  descendent  such  as
            TStringList (378  ).  To manage general objects, a TCollection (279  ) class exists, from which
            a descendent can be made to manage collections of various kinds.


See also:    TStrings (383  ), TCollection (279  )



            2.52.2         Method  overview

            __Page______Property__________________Description______________________________________________________________________*
 *_______
              329       Add                       Adds a new pointer to the list.
              329       AddList                   Add all pointers from another list
              332       Assign                    Copy the contents of other lists.
              329       Clear                     Clears the pointer list.
              328       Create                    Class to manage collections of pointers.
              330       Delete                    Removes a pointer from the list.
              329       Destroy                   Destroys the list and releases the memory used to store the list
                                                  elements.
              330       Error                     Raises an EListError (229  ) exception.
              330       Exchange                  Exchanges two pointers in the list.
              330       Expand                    Increases the capacity of the list if needed.
              331       Extract                   Remove the first occurrence of a pointer from the list.
              331       First                     Returns the first non-nil pointer in the list.
              331       GetEnumerator             Create an IEnumerator instance
              331       IndexOf                   Returns the index of a given pointer.
              332       Insert                    Inserts a new pointer in the list at a given position.
              332       Last                      Returns the last non-nil pointer in the list.
              332       Move                      Moves a pointer from one position in the list to another.
              333       Pack                      Removes Nil pointers from the list and frees unused memory.
              333       Remove                    Removes a value from the list.
            __333_______Sort______________________Sorts_the_pointers_in_the_list.__________________________________________________*
 *_______



            2.52.3         Property  overview

            __Page______Property________Access_______Description___________________________________________________________________*
 *_______
              333       Capacity        rw           Current capacity (i.e.  number of pointers that can be stored)
                                                     of the list.
              334       Count           rw           Current number of pointers in the list.
              334       Items           rw           Provides access to the pointers in the list.
            __334_______List____________r____________Memory_array_where_pointers_are_stored._______________________________________*
 *_______



            2.52.4         TList.Create

Synopsis:    Class to manage collections of pointers.



                                                                             328

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (328  ), TList.Destroy (1 )



                2.52.5         TList.Destroy

    Synopsis:    Destroys the list and releases the memory used to store the list elements.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  destroys  the  list  and  releases  the  memory  used  to  store  the  list  elements.   The
                elements themselves are in no way touched, i.e.  any meomory they point to must be explicitly
                released before calling the destructor.



                2.52.6         TList.AddList

    Synopsis:    Add all pointers from another list

Declaration:     procedure  AddList(AList:  TList)

    Visibility:   public

Description:     AddList adds all pointers from AList to the list.  If a pointer is already present, it is added
                a second time.

    See also:    TList.Assign (1 ), TFPList.AddList (1 )



                2.52.7         TList.Add

    Synopsis:    Adds a new pointer to the list.

Declaration:     function  Add(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Add  adds  a  new  pointer  to  the  list  after  the  last  pointer  (i.e.   at  position  Count,  thus
                increasing  the  item  count  with  1.  If  the  list  is  at  full  capacity,  the  capacity  of  the  list  is
                expanded, using the Grow (1 ) method.

                To insert a pointer at a certain position in the list, use the Insert (1 ) method instead.

    See also:    Delete (1 ), Grow (1 ), Insert (1 )



                2.52.8         TList.Clear

    Synopsis:    Clears the pointer list.

Declaration:     procedure  Clear;    Virtual

    Visibility:   public

Description:     Clear removes all pointers from the list, and sets the capacity to 0, thus freeing any memory
                allocated to maintain the list.

    See also:    Destroy (1 )



                                                                                 329

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.52.9         TList.Delete

    Synopsis:    Removes a pointer from the list.

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete removes the pointer at position Index from the list, shifting all following pointers
                one position up (or to the left).

                The memory the pointer is pointing to is not  deallocated.



                2.52.10          TList.Error

    Synopsis:    Raises an EListError (229  ) exception.

Declaration:     class  procedure  Error(const  Msg:  string;Data:  PtrInt);    Virtual

    Visibility:   public

Description:     Error raises an EListError (229  ) exception, with a message formatted with Msg and Data.



                2.52.11          TList.Exchange

    Synopsis:    Exchanges two pointers in the list.

Declaration:     procedure  Exchange(Index1:  Integer;Index2:  Integer)

    Visibility:   public

Description:     Exchange exchanges the pointers at positions Index1 and Index2.  Both pointers must be
                withing the current range of the list, or an EListError (229  ) exception will be raised.



                2.52.12          TList.Expand

    Synopsis:    Increases the capacity of the list if needed.

Declaration:     function  Expand  :  TList

    Visibility:   public

Description:     Expand increases the capacity of the list if the current element count matches the current
                list capacity.

                The capacity is increased according to the following algorithm:


                     1.If the capacity is less than 3, the capacity is increased with 4.

                     2.If the capacity is larger than 3 and less than 8, the capacity is increased with 8.

                     3.If the capacity is larger than 8, the capacity is increased with 16.


                The return value is Self.

    See also:    Capacity (1 )



                                                                                 330

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.52.13          TList.Extract

    Synopsis:    Remove the first occurrence of a pointer from the list.

Declaration:     function  Extract(item:  Pointer)  :  Pointer

    Visibility:   public

Description:     Extract searched for an occurence of  item, and if a match is found, the match is deleted
                from the list.  If no match is found, nothing is deleted.  If Item was found, the result is Item.
                If Item was not found, the result is Nil.  A lnExtracted notification event is triggered if an
                element is extracted from the list.

    See also:    TList.Delete (1 ), TList.IndexOf (1 ), TList.Remove (1 )



                2.52.14          TList.First

    Synopsis:    Returns the first non-nil pointer in the list.

Declaration:     function  First  :  Pointer

    Visibility:   public

Description:     First returns the value of the first non-nil pointer in the list.

                If there are no pointers in the list or all pointers equal Nil, then Nil is returned.

    See also:    Last (1 )



                2.52.15          TList.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TListEnumerator

    Visibility:   public

Description:     GetEnumerator  is  the  implementation  of  the  IEnumerable  (1433   )  interface  for  TList.  It
                creates a TListEnumerator (335  ) instance and returns it's IEnumerator (1433   ) interface.

    See also:    TListEnumerator (335  ), IEnumerator (1433   ), IEnumerable (1433   )



                2.52.16          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.



                                                                                 331

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.52.17          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 (229  ) exception is raised.

    See also:    Add (1 ), Delete (1 )



                2.52.18          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 (1 )



                2.52.19          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  (229  )
                exception is raised.

    See also:    Exchange (1 )



                2.52.20          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 (205  ) type.

    See also:    TList.Clear (1 )



                                                                                 332

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.52.21          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 (1 ), IndexOf (1 ), Insert (1 )



                2.52.22          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 (1 )



                2.52.23          TList.Sort

    Synopsis:    Sorts the pointers in the list.

Declaration:     procedure  Sort(Compare:  TListSortCompare)

    Visibility:   public

Description:     Sort>  sorts  the  pointers  in  the  list.  Two  pointers  are  compared  by  passing  them  to  the
                Compare function.  The result of this function determines how the pointers will be sorted:


                      oIf the result of this function is negative,  the first pointer is assumed to be 'less' than
                       the second and will be moved before the second in the list.

                      oIf the function result is positive,  the first pointer is assumed to be 'greater than' the
                       second and will be moved after the second in the list.

                      oif the function result is zero, the pointers are assumed to be 'equal' and no moving will
                       take place.


                The sort is done using a quicksort algorithm.



                2.52.24          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



                                                                                 333

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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  (1 )  or  insert  (1 ),  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 (1 ), Count (1 )



                2.52.25          TList.Count

    Synopsis:    Current number of pointers in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Count is the current number of (possibly Nil) pointers in the list.  Since the list is zero-based,
                the index of the largest pointer is Count-1.



                2.52.26          TList.Items

    Synopsis:    Provides access to the pointers in the list.

Declaration:     Property  Items[Index:  Integer]:  Pointer;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items is used to access the pointers in the list.  It is the default property of the TList class,
                so it can be omitted.

                The list is zero-based, so Index must be in the range 0 to Count-1.



                2.52.27          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.



                                                                                 334

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.53          TListEnumerator



                2.53.1         Description

                TListEnumerator  implements  the  #rtl.system.IEnumerator  (1433   )  interface  for  the  TList
                (328  )  class,  so  the  TList  class  can  be  used  in  a  for  ...    in  loop.  It  is  returned  by  the
                TList.GetEnumerator (1 ) method of  TList.


    See also:    TList (328  ), TList.GetEnumerator (1 ), #rtl.system.IEnumerator (1433   )



                2.53.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  335       Create              Initialize a new instance of  TListEnumerator
                  335       GetCurrent          Return the current pointer in the list
                __335_______MoveNext____________Move_the_position_of_the_enumerator_to_the_next_position_in_the_list.______________*
 *___________



                2.53.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __336_______Current_________r____________Current_pointer_in_the_list_______________________________________________*
 *___________



                2.53.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 (328  )



                2.53.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 (1 )



                2.53.6         TListEnumerator.MoveNext

    Synopsis:    Move the position of the enumerator to the next position in the list.

Declaration:     function  MoveNext  :  Boolean

    Visibility:   public



                                                                                 335

                __________________________________________________________CHAPTER_2.___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 (1 )



                2.53.7         TListEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  Pointer

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (1 ) as a property.

    See also:    GetCurrent (1 )



                2.54          TMemoryStream



                2.54.1         Description

                TMemoryStream is a TStream (364  ) descendent that stores it's data in memory.  It descends
                directly from TCustomMemoryStream (301  ) and implements the necessary to allocate and
                de-allocate memory directly from the heap.  It implements the Write (1 ) 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 (301  ), TStream (364  )



                2.54.2         Method  overview

                __Page______Property____________________Description________________________________________________________________*
 *___________
                  337       Clear                       Zeroes the position, capacity and size of the stream.
                  336       Destroy                     Frees any allocated memory and destroys the memory stream.
                  337       LoadFromFile                Loads the contents of a file into memory.
                  337       LoadFromStream              Loads the contents of a stream into memory.
                  338       SetSize                     Sets the size for the memory stream.
                __338_______Write_______________________Writes_data_to_the_stream's_memory.________________________________________*
 *___________



                2.54.3         TMemoryStream.Destroy

    Synopsis:    Frees any allocated memory and destroys the memory stream.

Declaration:     destructor  Destroy;    Override

    Visibility:   public



                                                                                 336

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     Destroy clears the memory stream, thus in effect freeing any memory allocated for it, and
                then frees the memory stream.



                2.54.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 (1 ), TStream.Position (1 ), TCustomMemoryStream.Memory (1 )



                2.54.5         TMemoryStream.LoadFromStream

    Synopsis:    Loads the contents of a stream into memory.

Declaration:     procedure  LoadFromStream(Stream:  TStream)

    Visibility:   public

Description:     LoadFromStream loads the contents of  Stream into the memorybuffer of the stream.  Any
                previous contents of the memory stream are overwritten.  Memory is allocated as needed.

 Remark:         The LoadFromStream uses the Size (1 ) 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 (1 ) 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 (230  ) may occur.

    See also:    TStream.CopyFrom (1 ), TMemoryStream.LoadFromFile (1 )



                2.54.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
                (1 ) method.

    See also:    TMemoryStream.LoadFromStream (1 )



                                                                                 337

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.54.7         TMemoryStream.SetSize

    Synopsis:    Sets the size for the memory stream.

Declaration:     procedure  SetSize(NewSize:  PtrInt);    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 (1 ), TStream.Size (1 )



                2.54.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 (1 ) method.

       Errors:   If no more memory could be allocated, then an exception will be raised.

    See also:    TCustomMemoryStream.Read (1 )



                2.55          TOwnedCollection



                2.55.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 (279  )



                2.55.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __338_______Create__________Create_a_new_TOwnerCollection_instance.________________________________________________*
 *___________



                2.55.3         TOwnedCollection.Create

    Synopsis:    Create a new TOwnerCollection instance.

Declaration:     constructor  Create(AOwner:  TPersistent;AItemClass:  TCollectionItemClass)

    Visibility:   public



                                                                                 338

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     Create  creates  a  new  instance  of  TOwnedCollection  and  stores  the  AOwner  references.
                It  will  the  value  returned  in  the  TCollection.Owner  (1 )  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 (1 ) and Add (1 ) methods.

    See also:    TCollection.Create (1 ), TCollection.Owner (1 )



                2.56          TOwnerStream



                2.56.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 (1 ) property is set to True).


    See also:    TStream (364  ), TOwnerStream.Source (1 ), TOwnerStream.SourceOwner (1 )



                2.56.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  339       Create          Create a new instance of  TOwnerStream.
                __339_______Destroy_________Destroys_the_TOwnerStream_instance_and_the_source_stream.______________________________*
 *___________



                2.56.3         Property  overview

                __Page______Property______________Access_______Description_________________________________________________________*
 *___________
                  340       Source                r            Reference to the source stream.
                __340_______SourceOwner___________rw___________Indicates_whether_the_ownerstream_owns_it's_source__________________*
 *___________



                2.56.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 (1 ), TOwnerStream.Source (1 ), TOwnerStream.SourceOwner (1 )



                2.56.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 (1 ), TOwnerStream.Source (1 ), TOwnerStream.SourceOwner (1 )



                                                                                 339

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.56.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 (1 )



                2.56.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 (1 ), TOwnerStream.Destroy (1 )



                2.57          TParser



                2.57.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 (1 )
                property.  Various methods are provided to obtain the token value in the desired format.

                To advance to the next token, invoke NextToken (1 ) method.


    See also:    TParser.Token (1 ), TParser.NextToken (1 )



                                                                                 340

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.57.2         Method  overview

                __Page______Property____________________________Description________________________________________________________*
 *___________
                  342       CheckToken                          Checks whether the token if of the given type.
                  342       CheckTokenSymbol                    Checks whether the token equals the given symbol
                  341       Create                              Creates a new parser instance.
                  341       Destroy                             Destroys the parser instance.
                  342       Error                               Raises an EParserError (229  ) exception with the given
                                                                message
                  342       ErrorFmt                            Raises an EParserError (229  ) exception and formats the
                                                                message.
                  342       ErrorStr                            Raises an EParserError (229  ) exception with the given
                                                                message
                  343       HexToBinary                         Writes hexadecimal data to a stream.
                  343       NextToken                           Reads the next token and returns its type.
                  343       SourcePos                           Returns the current position in the stream.
                  344       TokenComponentIdent                 Returns the path of a subcomponent starting from the
                                                                current token.
                  344       TokenFloat                          Returns the current token as a float.
                  344       TokenInt                            Returns the current token as an integer.
                  345       TokenString                         Returns the current token as a string.
                  345       TokenSymbolIs                       Returns True if the token equals the given symbol.
                __345_______TokenWideString_____________________Returns_the_current_token_as_a_widestring__________________________*
 *___________



                2.57.3         Property  overview

                __Page______Property___________Access_______Description____________________________________________________________*
 *___________
                  346       FloatType          r            The type of a float token.
                  346       SourceLine         r            Current source line number.
                __346_______Token______________r____________The_type_of_the_current_token._________________________________________*
 *___________



                2.57.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 (229  ) exception is raised.

    See also:    TParser.NextToken (1 ), TParser.Token (1 )



                2.57.5         TParser.Destroy

    Synopsis:    Destroys the parser instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the parser instance.

       Errors:   None.



                                                                                 341

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.57.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 (229  ) exception is raised.

    See also:    TParser.Token (1 )



                2.57.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 (199  ), otherwise an EParserError (229  ) exception
                is raised.

       Errors:   If the comparison fails, or current token isn't a symbol, an EParserError (229  ) exception is
                raised.

    See also:    TParser.TokenSymbolIs (1 ), toSymbol (199  )



                2.57.8         TParser.Error

    Synopsis:    Raises an EParserError (229  ) exception with the given message

Declaration:     procedure  Error(const  Ident:  string)

    Visibility:   public

Description:     Raises an EParserError (229  ) exception with the given message



                2.57.9         TParser.ErrorFmt

    Synopsis:    Raises an EParserError (229  ) exception and formats the message.

Declaration:     procedure  ErrorFmt(const  Ident:  string;const  Args:  Array  of  const)

    Visibility:   public

Description:     Raises an EParserError (229  ) exception and formats the message.



                2.57.10          TParser.ErrorStr

    Synopsis:    Raises an EParserError (229  ) exception with the given message

Declaration:     procedure  ErrorStr(const  Message:  string)

    Visibility:   public

Description:     Raises an EParserError (229  ) exception with the given message



                                                                                 342

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.57.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 (229  ) exception is raised.



                2.57.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 (1 ) property.

                If the end of the stream is reached, toEOF (199  ) is returned.

                For details about token types, see TParser.Token (1 )

       Errors:   If an error occours while parsing the token, an EParserError (229  ) exception is raised.

    See also:    TParser.Token (1 )



                2.57.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 (1 )



                                                                                 343

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.57.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 (199  ), 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 (1 ) or TokenWideString
                (1 ) 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 (1 ) isn't toSymbol (199  ), or no valid symbol is found after a dot, an EParserError
                (229  ) exception is raised.

    See also:    TParser.NextToken (1 ), TParser.Token (1 ), TParser.TokenString (1 ), TParser.TokenWideString
                (1 ), toSymbol (199  )



                2.57.15          TParser.TokenFloat

    Synopsis:    Returns the current token as a float.

Declaration:     function  TokenFloat  :  Extended

    Visibility:   public

Description:     If current token type is toFloat (199  ), 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 (1 ) for further information.

 Remark:         In the input stream the decimal separator, if present, must be a dot (.).

       Errors:   If Token (1 ) isn't toFloat (199  ), an EParserError (229  ) exception is raised.

    See also:    TParser.FloatType (1 ), TParser.NextToken (1 ), TParser.Token (1 ), toFloat (199  )



                2.57.16          TParser.TokenInt

    Synopsis:    Returns the current token as an integer.

Declaration:     function  TokenInt  :  Int64

    Visibility:   public

Description:     If current token type is toInteger (199  ), 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 (1 ) isn't toInteger (199  ), an EConvertError (1 ) exception is raised.

    See also:    TParser.NextToken (1 ), TParser.Token (1 ), toInteger (199  )



                                                                                 344

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.57.17          TParser.TokenString

    Synopsis:    Returns the current token as a string.

Declaration:     function  TokenString  :  string

    Visibility:   public

Description:     If current token type is toString (199  ) or toWString (199  ), 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 (1 ).

 Remark:         If Token (1 ) is toWString (199  ), TokenWideString (1 ) should be used instead.

       Errors:   None.

    See also:    TParser.NextToken (1 ), TParser.TokenWideString (1 ), TParser.Token (1 ), toString (199  ),
                toWString (199  )



                2.57.18          TParser.TokenWideString

    Synopsis:    Returns the current token as a widestring

Declaration:     function  TokenWideString  :  WideString

    Visibility:   public

Description:     If  current  token  type  is  toWString  (199  ),  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
                (1 ).

       Errors:   None.

    See also:    TParser.NextToken (1 ), TokenString (1 ), TParser.Token (1 ), toWString (199  )



                2.57.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 (199  ), or comparison fails, False is returned.

       Errors:   None.

    See also:    TParser.CheckTokenSymbol (1 ), TParser.Token (1 )



                                                                                 345

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.57.20          TParser.FloatType

    Synopsis:    The type of a float token.

Declaration:     Property  FloatType  :  Char

    Visibility:   public

      Access:    Read

Description:     Floating  point  numbers  can  be  postfixed  with  a  character  specifying  the  type  of  floating
                point value.  When specified, this property holds the character postfixed to the number.

                It can be one of the following values:



                                                                       Table 2.20:

                                                            s or S      Value is a single.
                                                            c or C      Value is a currency.
                                                            d or D      Value is a date.



                If Token (1 ) isn't toFloat (199  ) or one of the above characters wasn't specified, FloatType
                is the null character (zero).

    See also:    TParser.NextToken (1 ), TParser.Token (1 ), TParser.TokenFloat (1 ), toFloat (199  )



                2.57.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 (1 )



                2.57.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:



                                                                                 346

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                                                                       Table 2.21:



                  toEOF (199  )              Value returned by TParser.Token (1 ) when the end of the input stream was reached.
                  toSymbol (199  )           Value returned by TParser.Token (1 ) when a symbol was found in the input stream.
                  toString (199  )           Value returned by TParser.Token (1 ) when a string was found in the input stream.
                  toInteger (199  )          Value returned by TParser.Token (1 ) when an integer was found in the input stream.
                  toFloat (199  )            Value returned by TParser.Token (1 ) when a floating point value was found in the inpu*
 *t stream.
                  toWString (199  )          Value returned by TParser.Token (1 ) when a widestring was found in the input stream.



                To advance to the next token, use NextToken (1 ) method.

    See also:    TParser.CheckToken (1 ), TParser.NextToken (1 ), TParser.TokenComponentIdent (1 ), TParser.TokenFloat
                (1 ), TParser.TokenInt (1 ), TParser.TokenString (1 ), TParser.TokenWideString (1 )



                2.58          TPersistent



                2.58.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.


    See also:    TComponent (289  )



                2.58.2         Method  overview

                __Page______Property________________Description____________________________________________________________________*
 *___________
                  347       Assign                  Assign the contents of one class to another.
                  347       Destroy                 Destroys the TPersistent instance.
                __348_______GetNamePath_____________Returns_a_string_that_can_be_used_to_identify_the_class_instance.______________*
 *___________



                2.58.3         TPersistent.Destroy

    Synopsis:    Destroys the TPersistent instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  disposes  of  the  persistent  object.   This  method  should  never  be  called  directly.
                Instead the Free method should be used.



                2.58.4         TPersistent.Assign

    Synopsis:    Assign the contents of one class to another.

Declaration:     procedure  Assign(Source:  TPersistent);    Virtual

    Visibility:   public



                                                                                 347

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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  (1 )
                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;


                (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 (1 )



                2.58.5         TPersistent.GetNamePath

    Synopsis:    Returns a string that can be used to identify the class instance.

Declaration:     function  GetNamePath  :  string;    Virtual

    Visibility:   public

Description:     GetNamePath returns a string that can be used to identify the class instance.  This can be
                used to display a name for this instance in a Object designer.

                GetNamePath  constructs  a  name  by  recursively  prepending  the  Classname  of  the  Owner
                instance to the Classname of this instance, separated by a dot.

    See also:    TPersistent.GetOwner (1 )



                2.59          TProxyStream



                2.59.1         Description

                TProxyStream is a proxy class for the #rtl.types.IStream (1637   ) interface.  It implements all
                stream methods by relaying them to the IStream interface.


    See also:    #rtl.types.IStream (1637   ), TStreamAdapter (373  )



                2.59.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  349       Check           Check errors
                  349       Create          Create a new instance of the TProxyStream class.
                  349       Read
                  349       Seek
                __349_______Write__________________________________________________________________________________________________*
 *___________



                                                                                 348

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.59.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 (1637   )



                2.59.4         TProxyStream.Read

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public



                2.59.5         TProxyStream.Write

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public



                2.59.6         TProxyStream.Seek

Declaration:     function  Seek(const  Offset:  Int64;Origin:  TSeekOrigin)  :  Int64
                                      ;    Override

    Visibility:   public



                2.59.7         TProxyStream.Check

    Synopsis:    Check errors

Declaration:     procedure  Check(err:  LongInt);    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 (1637   )



                2.60          TReader



                2.60.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 (241  ) 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.



                                                                                 349

            __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'____________________*
 *_______________



            It  should  never  be  necessary  to  create  an  instance  of  this  class  directly.    Instead,  the
            TStream.ReadComponent (1 ) call should be used.


See also:    TFiler (306  ), TWriter (409  ), TAbstractObjectReader (241  )



            2.60.2         Method  overview

            __Page______Property__________________________Description______________________________________________________________*
 *_______
              351       BeginReferences                   Initializes the component referencing mechanism.
              352       CheckValue                        Raises an exception if the next value in the stream is not
                                                          of type Value
              358       CopyValue                         Copy a value to a writer.
              351       Create                            Creates a new reader class
              352       DefineBinaryProperty              Reads a user-defined binary property from the stream.
              352       DefineProperty                    Reads a user-defined property from the stream.
              351       Destroy                           Destroys a reader class.
              352       EndOfList                         Returns true if the stream contains an end-of-list marker.
              352       EndReferences                     Finalizes the component referencing mechanism.
              353       FixupReferences                   Tries to resolve all unresolved component references.
              353       NextValue                         Returns the type of the next value.
              353       Read                              Read raw data from stream
              353       ReadBoolean                       Reads a boolean from the stream.
              353       ReadChar                          Reads a character from the stream.
              354       ReadCollection                    Reads a collection from the stream.
              354       ReadComponent                     Starts reading a component from the stream.
              354       ReadComponents                    Starts reading child components from the stream.
              355       ReadCurrency                      Read a currency value from the stream.
              355       ReadDate                          Reads a date from the stream
              355       ReadFloat                         Reads a float from the stream.
              355       ReadIdent                         Reads an identifier from the stream.
              356       ReadInt64                         Reads a 64-bit integer from the stream.
              356       ReadInteger                       Reads an integer from the stream
              356       ReadListBegin                     Checks for the beginning of a list.
              356       ReadListEnd                       Checks for the end of a list.
              357       ReadRootComponent                 Starts reading a root component.
              356       ReadSet                           Read a set value from the stream
              355       ReadSingle                        Reads a single-type real from the stream.
              357       ReadString                        Reads a string from the stream.
              354       ReadUnicodeChar                   Read unicode character
              357       ReadUnicodeString                 Read a UnicodeString value from the stream
              358       ReadValue                         Reads the next value type from the stream.
              357       ReadVariant                       Read a variant from the stream
              354       ReadWideChar                      Read widechar from the stream
            __357_______ReadWideString____________________Read_a_WideString_value_from_the_stream._________________________________*
 *_______



                                                                             350

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.3         Property  overview

                __Page______Property______________________________Access_______Description_________________________________________*
 *___________
                  358       Driver                                r            The driver in use for streaming the data.
                  360       OnAncestorNotFound                    rw           Handler called when the ancestor component
                                                                               cannot be found.
                  360       OnCreateComponent                     rw           Handler  called  when  a  component  needs  to
                                                                               be created.
                  359       OnError                               rw           Handler called when an error occurs.
                  360       OnFindComponentClass                  rw           Handler called when a component class refer-
                                                                               ence needs to be found.
                  359       OnFindMethod                          rw           Handler to find or change a method address.
                  359       OnPropertyNotFound                    rw           Handler for treating missing properties.
                  361       OnReadStringProperty                  rw           Handler  for  translating  strings  when  read
                                                                               from the stream.
                  360       OnReferenceName                       rw           Handler  called  when  another  component  is
                                                                               referenced.
                  359       OnSetMethodProperty                   rw           Handler for setting method properties.
                  360       OnSetName                             rw           Handler  called  when  setting  a  component
                                                                               name.
                  358       Owner                                 rw           Owner of the component being read
                __358_______Parent________________________________rw___________Parent_of_the_component_being_read._________________*
 *___________



                2.60.4         TReader.Create

    Synopsis:    Creates a new reader class

Declaration:     constructor  Create(Stream:  TStream;BufSize:  Integer)

    Visibility:   public

Description:     Creates a new reader class



                2.60.5         TReader.Destroy

    Synopsis:    Destroys a reader class.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys a reader class.



                2.60.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.



                                                                                 351

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.7         TReader.CheckValue

    Synopsis:    Raises an exception if the next value in the stream is not of type Value

Declaration:     procedure  CheckValue(Value:  TValueType)

    Visibility:   public

Description:     Raises an exception if the next value in the stream is not of type Value



                2.60.8         TReader.DefineProperty

    Synopsis:    Reads a user-defined property from the stream.

Declaration:     procedure  DefineProperty(const  Name:  string;AReadData:  TReaderProc;
                                                        WriteData:  TWriterProc;HasData:  Boolean)
                                                        ;    Override

    Visibility:   public

Description:     Reads a user-defined property from the stream.



                2.60.9         TReader.DefineBinaryProperty

    Synopsis:    Reads a user-defined binary property from the stream.

Declaration:     procedure  DefineBinaryProperty(const  Name:  string;
                                                                  AReadData:  TStreamProc;
                                                                  WriteData:  TStreamProc;HasData:  Boolean)
                                                                  ;    Override

    Visibility:   public

Description:     Reads a user-defined binary property from the stream.



                2.60.10          TReader.EndOfList

    Synopsis:    Returns true if the stream contains an end-of-list marker.

Declaration:     function  EndOfList  :  Boolean

    Visibility:   public

Description:     Returns true if the stream contains an end-of-list marker.



                2.60.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.



                                                                                 352

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.12          TReader.FixupReferences

    Synopsis:    Tries to resolve all unresolved component references.

Declaration:     procedure  FixupReferences

    Visibility:   public

Description:     Tries to resolve all unresolved component references.



                2.60.13          TReader.NextValue

    Synopsis:    Returns the type of the next value.

Declaration:     function  NextValue  :  TValueType

    Visibility:   public

Description:     Returns the type of the next value.



                2.60.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 (1 ), TBinaryObjectReader.Read (1 )



                2.60.15          TReader.ReadBoolean

    Synopsis:    Reads a boolean from the stream.

Declaration:     function  ReadBoolean  :  Boolean

    Visibility:   public

Description:     Reads a boolean from the stream.



                2.60.16          TReader.ReadChar

    Synopsis:    Reads a character from the stream.

Declaration:     function  ReadChar  :  Char

    Visibility:   public

Description:     Reads a character from the stream.



                                                                                 353

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.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 (1 ), TWriter.WriteWideChar (1 )



                2.60.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 (1 )



                2.60.19          TReader.ReadCollection

    Synopsis:    Reads a collection from the stream.

Declaration:     procedure  ReadCollection(Collection:  TCollection)

    Visibility:   public

Description:     Reads a collection from the stream.



                2.60.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.



                2.60.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.



                                                                                 354

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.22          TReader.ReadFloat

    Synopsis:    Reads a float from the stream.

Declaration:     function  ReadFloat  :  Extended

    Visibility:   public

Description:     Reads a float from the stream.



                2.60.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.



                2.60.24          TReader.ReadDate

    Synopsis:    Reads a date from the stream

Declaration:     function  ReadDate  :  TDateTime

    Visibility:   public

Description:     Reads a date from the stream



                2.60.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 (1 )



                2.60.26          TReader.ReadIdent

    Synopsis:    Reads an identifier from the stream.

Declaration:     function  ReadIdent  :  string

    Visibility:   public

Description:     Reads an identifier from the stream.



                                                                                 355

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.27          TReader.ReadInteger

    Synopsis:    Reads an integer from the stream

Declaration:     function  ReadInteger  :  LongInt

    Visibility:   public

Description:     Reads an integer from the stream



                2.60.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.



                2.60.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 (1 )



                2.60.30          TReader.ReadListBegin

    Synopsis:    Checks for the beginning of a list.

Declaration:     procedure  ReadListBegin

    Visibility:   public

Description:     Checks for the beginning of a list.



                2.60.31          TReader.ReadListEnd

    Synopsis:    Checks for the end of a list.

Declaration:     procedure  ReadListEnd

    Visibility:   public

Description:     Checks for the end of a list.



                                                                                 356

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.32          TReader.ReadRootComponent

    Synopsis:    Starts reading a root component.

Declaration:     function  ReadRootComponent(ARoot:  TComponent)  :  TComponent

    Visibility:   public

Description:     Starts reading a root component.



                2.60.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 (1 )



                2.60.34          TReader.ReadString

    Synopsis:    Reads a string from the stream.

Declaration:     function  ReadString  :  string

    Visibility:   public

Description:     Reads a string from the stream.



                2.60.35          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 (1 )



                2.60.36          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 (1 ), TWriter.WriteUnicodeString (1 )



                                                                                 357

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.37          TReader.ReadValue

    Synopsis:    Reads the next value type from the stream.

Declaration:     function  ReadValue  :  TValueType

    Visibility:   public

Description:     Reads the next value type from the stream.



                2.60.38          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.



                2.60.39          TReader.Driver

    Synopsis:    The driver in use for streaming the data.

Declaration:     Property  Driver  :  TAbstractObjectReader

    Visibility:   public

      Access:    Read

Description:     The driver in use for streaming the data.



                2.60.40          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



                2.60.41          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.



                                                                                 358

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.42          TReader.OnError

    Synopsis:    Handler called when an error occurs.

Declaration:     Property  OnError  :  TReaderError

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when an error occurs.



                2.60.43          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 (207  ).

    See also:    TPropertyNotFoundEvent (207  ), TReader.OnSetMethodProperty (1 ), TReader.OnReadStringProperty
                (1 )



                2.60.44          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.



                2.60.45          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 (1 ), TReader.OnPropertyNotFound (1 )



                                                                                 359

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.46          TReader.OnSetName

    Synopsis:    Handler called when setting a component name.

Declaration:     Property  OnSetName  :  TSetNameEvent

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when setting a component name.



                2.60.47          TReader.OnReferenceName

    Synopsis:    Handler called when another component is referenced.

Declaration:     Property  OnReferenceName  :  TReferenceNameEvent

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when another component is referenced.



                2.60.48          TReader.OnAncestorNotFound

    Synopsis:    Handler called when the ancestor component cannot be found.

Declaration:     Property  OnAncestorNotFound  :  TAncestorNotFoundEvent

    Visibility:   public

      Access:    Read,Write

Description:     Handler called when the ancestor component cannot be found.



                2.60.49          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.



                2.60.50          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.



                                                                                 360

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.60.51          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 (207  ) for a description of the various
                parameters.

    See also:    TReader.OnPropertyNotFound (1 ), TReader.OnSetMethodProperty (1 ), TReadWriteString-
                PropertyEvent (207  )



                2.61          TRecall



                2.61.1         Description

                TRecall is a helper class used to copy published properties of a class (the reference object)
                in  another  class  (the  storage  object).   The  reference  object  and  storage  object  must  be
                assignable to each other.

                The  TRecall  can  be  used  to  store  the  state  of  a  persistent  class,  and  restore  it  at  a  later
                time.

                When a TRecall object is created, it gets passed a reference instance and a storage instance.
                It immediatly stores the properties of the reference object in the storage object.

                The Store (1 ) 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 (1 ) can be called.


    See also:    TRecall.Create  (1 ),  TRecall.Destroy  (1 ),  TRecall.Forget  (1 ),  TRecall.Store  (1 ),  TPersis-
                tent.Assign (1 )



                2.61.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  362       Create          Creates a new instance of  TRecall.
                  362       Destroy         Copies the stored properties to the reference object and destroys the
                                            TRecall instance.
                  362       Forget          Clear the reference property.
                __362_______Store___________Assigns_the_reference_instance_to_the_storage_instance.________________________________*
 *___________



                2.61.3         Property  overview

                __Page______Property_________Access_______Description______________________________________________________________*
 *___________
                __363_______Reference________r____________The_reference_object.____________________________________________________*
 *___________



                                                                                 361

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.61.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 (1 ) to assign the reference object properties to the storage instance.

    See also:    TRecall.Store (1 ), TRecall.Destroy (1 )



                2.61.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  (1 )  instance  is  still  valid.  If  the  reference
                pointer was invalidated, call TRecall.Forget (1 ) to clear the reference instance.

    See also:    TRecall.Store (1 ), TRecall.Forget (1 )



                2.61.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 (1 ) instance is still valid.  If the reference pointer
                was invalidated, call TRecall.Forget (1 ) to clear the reference instance.



                2.61.7         TRecall.Forget

    Synopsis:    Clear the reference property.

Declaration:     procedure  Forget

    Visibility:   public

Description:     Forget sets the Reference (1 ) 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 (1 ) has no effect.

       Errors:   None.

    See also:    TRecall.Reference (1 ), TRecall.Store (1 ), TRecall.Destroy (1 )



                                                                                 362

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.61.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 (1 ) to clear the reference and then free the reference object.

    See also:    TRecall.Forget (1 )



                2.62          TResourceStream



                2.62.1         Description

                Stream that reads its data from a resource object.



                2.62.2         Method  overview

                __Page______Property________________Description____________________________________________________________________*
 *___________
                  363       Create                  Creates a new instance of a resource stream.
                  363       CreateFromID            Creates a new instance of a resource stream with a resource
                __364_______Destroy_________________Destroys_the_instance_of_the_resource_stream.__________________________________*
 *___________



                2.62.3         TResourceStream.Create

    Synopsis:    Creates a new instance of a resource stream.

Declaration:     constructor  Create(Instance:  THandle;const  ResName:  string;
                                              ResType:  PChar)

    Visibility:   public

Description:     Creates a new instance of a resource stream.



                2.62.4         TResourceStream.CreateFromID

    Synopsis:    Creates a new instance of a resource stream with a resource

Declaration:     constructor  CreateFromID(Instance:  THandle;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.



                                                                                 363

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.62.5         TResourceStream.Destroy

    Synopsis:    Destroys the instance of the resource stream.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the instance of the resource stream.



                2.63          TStream



                2.63.1         Description

                TStream is the base class for all streaming classes.  It defines methods for reading (1 ), writing
                (1 ) 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 (336  ) or TFileStream (308  ) then override these
                methods to write streams to memory or file.


    See also:    TMemoryStream (336  ), TFileStream (308  ), TStringStream (401  )



                2.63.2         Method  overview

                __Page______Property__________________________Description__________________________________________________________*
 *___________
                  367       CopyFrom                          Copy data from one stream to another
                  369       FixupResourceHeader               Not implemented in FPC
                  365       Read                              Reads data from the stream to a buffer and returns the
                                                              number of bytes read.
                  371       ReadAnsiString                    Read an ansistring from the stream and return its value.
                  366       ReadBuffer                        Reads data from the stream to a buffer
                  370       ReadByte                          Read a byte from the stream and return its value.
                  367       ReadComponent                     Reads component data from a stream
                  368       ReadComponentRes                  Reads component data and resource header from a stream
                  370       ReadDWord                         Read a DWord from the stream and return its value.
                  371       ReadQWord                         Read a QWord value from the stream and return its value
                  370       ReadResHeader                     Read a resource header from the stream.
                  370       ReadWord                          Read a word from the stream and return its value.
                  366       Seek                              Sets the current position in the stream
                  365       SetSize                           Sets the size of the stream
                  365       Write                             Writes data from a buffer to the stream and returns the
                                                              number of bytes written.
                  372       WriteAnsiString                   Write an ansistring to the stream.
                  367       WriteBuffer                       Writes data from the stream to the buffer
                  371       WriteByte                         Write a byte to the stream.
                  368       WriteComponent                    Write component data to the stream
                  368       WriteComponentRes                 Write resource header and component data to a stream
                  368       WriteDescendent                   Write component data to a stream, relative to an ancestor
                  369       WriteDescendentRes                Write resource header and component data to a stream,
                                                              relative to an ancestor
                  372       WriteDWord                        Write a DWord to the stream.
                  372       WriteQWord                        Write a QWord value to the stream
                  369       WriteResourceHeader               Write resource header to the stream
                __372_______WriteWord_________________________Write_a_word_to_the_stream.__________________________________________*
 *___________



                                                                                 364

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.63.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  373       Position        rw           The current position in the stream.
                __373_______Size____________rw___________The_current_size_of_the_stream.___________________________________________*
 *___________



                2.63.4         TStream.SetSize

    Synopsis:    Sets the size of the stream

Declaration:     procedure  SetSize(NewSize:  LongInt);    Virtual;    Overload
                procedure  SetSize(const  NewSize:  Int64);    Virtual;    Overload

    Visibility:   default

Description:     SetSize is the write handler for the TStream.Size (1 ) property.  The TStream implemen-
                tation of  SetSize does nothing, but descendent classes may override this methods to allow
                programmers to set the size of the stream.

    See also:    TStream.GetSize (1 ), TStream.Size (1 )



                2.63.5         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 (1 ) instead.

                As implemented in TStream, Read does nothing but raises an EStreamError (230  ) exception
                to indicate that reading is not supported.  Descendent classes that allow reading must override
                this method to do the actual reading.

       Errors:   In case a descendent class does not allow reading from the stream, an exception is raised.

    See also:    TStream.Write (1 ), TStream.ReadBuffer (1 )



                2.63.6         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  (1 )
                instead.

                As implemented in TStream, Write does nothing but raises EStreamError (230  ) exception to
                indicate that writing is not supported.  Descendent classes that allow writing must override
                this method to do the actual writing.



                                                                                 365

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



       Errors:   In case a descendent class does not allow writing to the stream, an exception is raised.

    See also:    TStream.Read (1 ), TStream.WriteBuffer (1 )



                2.63.7         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:   default

Description:     Seek sets the position of the stream to Offset bytes from Origin.  Origin can have one of
                the following values:



                                                                       Table 2.22:

                       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.



                Offset should be negative when the origin is SoFromEnd.  It should be positive for soFromBeginning
                and can have both signs for soFromCurrent

                This  is  an  abstract  method,  which  must  be  overridden  by  descendent  classes.   They  may
                choose not to implement this method for all values of  Origin and Offset.

       Errors:   An exception may be raised if this method is called with an invalid pair of  Offset,Origin
                values.  e.g.  a negative offset for soFromBeginning.

    See also:    TStream.Position (1 )



                2.63.8         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
                (1 ) 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 (1 ), TStream.WriteBuffer (1 )



                                                                                 366

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.63.9         TStream.WriteBuffer

    Synopsis:    Writes data from the stream to the buffer

Declaration:     procedure  WriteBuffer(const  Buffer;Count:  LongInt)

    Visibility:   public

Description:     WriteBuffer writes Count bytes to the stream from Buffer.  If the stream does not allow
                Count bytes to be written, then an exception is raised.

                WriteBuffer should be used to read in a fixed number of bytes, such as when writing struc-
                tures or the content of variables.  If the number of bytes is not determined, use TStream.Write
                (1 ) instead.  WriteBuffer uses Write internally to do the actual reading.

       Errors:   If the stream does not allow to write Count bytes, then an exception is raised.

    See also:    TStream.Write (1 ), TStream.ReadBuffer (1 )



                2.63.10          TStream.CopyFrom

    Synopsis:    Copy data from one stream to another

Declaration:     function  CopyFrom(Source:  TStream;Count:  Int64)  :  Int64

    Visibility:   public

Description:     CopyFrom  reads  Count  bytes  from  Source  and  writes  them  to  the  current  stream.   This
                updates  the  current  position  in  the  stream.  After  the  action  is  completed,  the  number  of
                bytes copied is returned.

                This  can  be  used  to  quickly  copy  data  from  one  stream  to  another  or  to  copy  the  whole
                contents of the stream.

    See also:    TStream.Read (1 ), TStream.Write (1 )



                2.63.11          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  (349  )  object  and  calls  its  ReadRootComponent
                (1 ) method.

       Errors:   If an error occurs during the reading of the component, an EFilerError (228  ) exception is
                raised.

    See also:    TStream.WriteComponent (1 ), TStream.ReadComponentRes (1 ), TReader.ReadRootComponent
                (1 )



                                                                                 367

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.63.12          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
                (1 ) to read the component state from the stream into Instance.

                This  method  is  usually  called  by  the  global  streaming  method  when  instantiating  forms
                and  datamodules  as  created  by  an  IDE.  It  should  be  used  mainly  on  Windows,  to  store
                components in Windows resources.

       Errors:   If an error occurs during the reading of the component, an EFilerError (228  ) exception is
                raised.

    See also:    TStream.ReadComponent (1 ), TStream.WriteComponentRes (1 )



                2.63.13          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 (1 ).  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 (1 ) with Nil ancestor.

    See also:    TStream.ReadComponent (1 ), TStream.WriteComponentRes (1 )



                2.63.14          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 (1 ) 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 (1 ), TStream.ReadComponentRes (1 )



                2.63.15          TStream.WriteDescendent

    Synopsis:    Write component data to a stream, relative to an ancestor

Declaration:     procedure  WriteDescendent(Instance:  TComponent;Ancestor:  TComponent)

    Visibility:   public



                                                                                 368

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



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 (409  ) object and calls its WriteDescendent (1 ) object.
                The writer is passed a binary driver object (267  ) by default.



                2.63.16          TStream.WriteDescendentRes

    Synopsis:    Write resource header and component data to a stream, relative to an ancestor

Declaration:     procedure  WriteDescendentRes(const  ResName:  string;Instance:  TComponent;
                                                              Ancestor:  TComponent)

    Visibility:   public

Description:     WriteDescendentRes  writes  a  ResName  resource  header,  and  then  calls  WriteDescendent
                (1 ) to write the state of  Instance to the stream where it differs from Ancestor, i.e.  only
                the changed properties are written to the stream.

                This method is intened for use by an IDE that can use it to store forms or datamodules as
                designed in a Windows resource stream.



                2.63.17          TStream.WriteResourceHeader

    Synopsis:    Write resource header to the stream

Declaration:     procedure  WriteResourceHeader(const  ResName:  string;
                                                                var  FixupInfo:  Integer)

    Visibility:   public

Description:     WriteResourceHeader writes a resource-file header for a resource called ResName.  It returns
                in FixupInfo the argument that should be passed on to TStream.FixupResourceHeader (1 ).

                WriteResourceHeader should not be used directly.  It is called by the TStream.WriteComponentRes
                (1 ) and TStream.WriteDescendentRes (1 ) methods.

    See also:    TStream.FixupResourceHeader (1 ), TStream.WriteComponentRes (1 ), TStream.WriteDescendentRes
                (1 )



                2.63.18          TStream.FixupResourceHeader

    Synopsis:    Not implemented in FPC

Declaration:     procedure  FixupResourceHeader(FixupInfo:  Integer)

    Visibility:   public

Description:     FixupResourceHeader is used to write the size of the resource after a component was written
                to  stream.  The  size  is  determined  from  the  current  position,  and  it  is  written  at  position
                FixupInfo.  After that the current position is restored.

                FixupResourceHeader should never be called directly; it is handled by the streaming system.

    See also:    TStream.WriteResourceHeader (1 ), TStream.WriteComponentRes (1 ), TStream.WriteDescendentRes
                (1 )



                                                                                 369

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.63.19          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 (228  ) exception is raised.

    See also:    TStream.ReadComponentRes (1 ), EInvalidImage (228  )



                2.63.20          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 (230  ) exception will be raised.  This is a utility
                function which symply calls the Read (1 ) function.

    See also:    TStream.Read (1 ), TStream.WriteByte (1 ), TStream.ReadWord (1 ), TStream.ReadDWord
                (1 ), TStream.ReadAnsiString (1 )



                2.63.21          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 (1 ) function.

       Errors:   If the word cannot be read, a EStreamError (230  ) exception will be raised.

    See also:    TStream.Read (1 ), TStream.WriteWord (1 ), TStream.ReadByte (1 ), TStream.ReadDWord
                (1 ), TStream.ReadAnsiString (1 )



                2.63.22          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 (1 ) function.



                                                                                 370

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



       Errors:   If the DWord cannot be read, a EStreamError (230  ) exception will be raised.

    See also:    TStream.Read (1 ), TStream.WriteDWord (1 ), TStream.ReadByte (1 ), TStream.ReadWord
                (1 ), TStream.ReadAnsiString (1 )



                2.63.23          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 (230  ) exception will be
                raised.

    See also:    TStream.Read (1 ), TStream.WriteByte (1 ), TStream.ReadWord (1 ), TStream.ReadDWord
                (1 ), TStream.ReadAnsiString (1 )



                2.63.24          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 (1 ) function writes an ansistring in such a format.

       Errors:   If the AnsiString cannot be read, a EStreamError (230  ) exception will be raised.

    See also:    TStream.Read (1 ), TStream.WriteAnsiString (1 ), TStream.ReadByte (1 ), TStream.ReadWord
                (1 ), TStream.ReadDWord (1 )



                2.63.25          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 (1 ) function.  The byte can be read from the stream using the ReadByte (1 ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (230  ) exception will be raised.

    See also:    TStream.Write (1 ), TStream.ReadByte (1 ), TStream.WriteWord (1 ), TStream.WriteDWord
                (1 ), TStream.WriteAnsiString (1 )



                                                                                 371

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.63.26          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 (1 ) function.  The word can be read from the stream using the Read-
                Word (1 ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (230  ) exception will be raised.

    See also:    TStream.Write (1 ), TStream.ReadWord (1 ), TStream.WriteByte (1 ), TStream.WriteDWord
                (1 ), TStream.WriteAnsiString (1 )



                2.63.27          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 (1 ) function.  The DWord can be read from the stream using
                the ReadDWord (1 ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (230  ) exception will be raised.

    See also:    TStream.Write (1 ), TStream.ReadDWord (1 ), TStream.WriteByte (1 ), TStream.WriteWord
                (1 ), TStream.WriteAnsiString (1 )



                2.63.28          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 (1 ) function.  The word can be read from the stream using the
                ReadQWord (1 ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (230  ) exception will be raised.

    See also:    TStream.Write (1 ), TStream.ReadByte (1 ), TStream.WriteWord (1 ), TStream.WriteDWord
                (1 ), TStream.WriteAnsiString (1 )



                2.63.29          TStream.WriteAnsiString

    Synopsis:    Write an ansistring to the stream.

Declaration:     procedure  WriteAnsiString(const  S:  string)

    Visibility:   public



                                                                                 372

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     WriteAnsiString  writes  the  AnsiString  S  (i.e.  4  bytes)  to  the  stream.  This  is  a  utility
                function  which  simply  calls  the  Write  (1 )  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 (1 ) function.

       Errors:   If an error occurs when attempting to write, an EStreamError (230  ) exception will be raised.

    See also:    TStream.Write (1 ), TStream.ReadAnsiString (1 ), TStream.WriteByte (1 ), TStream.WriteWord
                (1 ), TStream.WriteDWord (1 )



                2.63.30          TStream.Position

    Synopsis:    The current position in the stream.

Declaration:     Property  Position  :  Int64

    Visibility:   public

      Access:    Read,Write

Description:     Position can be read to determine the current position in the stream.  It can be written to
                to set the (absolute) position in the stream.  The position is zero-based, so to set the position
                at the beginning of the stream, the position must be set to zero.

 Remark:         Not all TStream descendants support setting the position in the stream, so this should be
                used with care.

       Errors:   Some descendents may raise an EStreamError (230  ) exception if they do not support setting
                the stream position.

    See also:    TStream.Size (1 ), TStream.Seek (1 )



                2.63.31          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 (1 ), TStream.Seek (1 )



                2.64          TStreamAdapter



                2.64.1         Description

                Implements IStream for TStream (364  ) descendents



                2.64.2         Interfaces  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __1637______IStream_________COM_stream_abstraction_________________________________________________________________*
 *___________



                                                                                 373

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.64.3         Method  overview

                __Page______Property_______________Description_____________________________________________________________________*
 *___________
                  377       Clone                  Clone the stream
                  376       Commit                 Commit data to the stream
                  376       CopyTo                 Copy data to destination stream
                  374       Create                 Create a new instance of  TStreamAdapter
                  374       Destroy                Free the TStreamAdapter instance
                  376       LockRegion             Lock a region of the stream
                  374       Read                   Read from the stream.
                  376       Revert                 Revert operations on the stream
                  375       Seek                   Set the stream position
                  375       SetSize                Set the stream size
                  377       Stat                   Return statistical data about the stream
                  377       UnlockRegion           Unlock a region of the stream
                __375_______Write__________________Write_to_the_stream_____________________________________________________________*
 *___________



                2.64.4         Property  overview

                __Page______Property_____________________Access_______Description__________________________________________________*
 *___________
                  377       Stream                       r            Stream on which adaptor works
                  378       StreamOwnership              rw           Determines what happens with the stream when the
                ______________________________________________________adaptor_is_freed_____________________________________________*
 *___________



                2.64.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
                (1 ) with Stream and initializes StreamOwnerShip (1 ) with Ownership.

                TStreamAdapter is an abstract class:  descendents must be created that implement the actual
                functionality.

    See also:    StreamOwnerShip (1 ), TStreamAdapter.Stream (1 )



                2.64.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.



                2.64.7         TStreamAdapter.Read

    Synopsis:    Read from the stream.

Declaration:     function  Read(pv:  Pointer;cb:  DWORD;pcbRead:  PDWord)  :  HRESULT;    Virtual



                                                                                 374

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



    Visibility:  public

Description:     Read  implements  #rtl.types.ISequentialStream.Read  (1636   )  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 (1636   )



                2.64.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 (1636   ) 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 (1636   )



                2.64.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 (1637   ) 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 (1637   )



                2.64.10          TStreamAdapter.SetSize

    Synopsis:    Set the stream size

Declaration:     function  SetSize(libNewSize:  Largeint)  :  HRESULT;    Virtual

    Visibility:   public

Description:     SetSize  implements  #rtl.types.IStream.Setsize  (1637   )  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 (1637   )



                                                                                 375

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.64.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 (1637   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.



                2.64.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 (1638   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.Commit (1638   )



                2.64.13          TStreamAdapter.Revert

    Synopsis:    Revert operations on the stream

Declaration:     function  Revert  :  HRESULT;    Virtual

    Visibility:   public

Description:     Revert implements #rtl.types.IStream.Revert (1638   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.Revert (1638   )



                2.64.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 (1638   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.LockRegion (1638   )



                                                                                 376

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.64.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 (1638   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.UnLockRegion (1638   )



                2.64.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 (1639   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.Stat (1639   )



                2.64.17          TStreamAdapter.Clone

    Synopsis:    Clone the stream

Declaration:     function  Clone(out  stm:  IStream)  :  HRESULT;    Virtual

    Visibility:   public

Description:     Clone implements #rtl.types.IStream.Clone (1639   ).

       Errors:   This function must be overridden and will raise a runerror 217 when called directly.

    See also:    #rtl.types.IStream.Clone (1639   )



                2.64.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.



                                                                                 377

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.64.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



                2.65          TStringList



                2.65.1         Description

                TStringList  is  a  descendent  class  of  TStrings  (383  )  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 (383  ), TStrings.Duplicates (1 ), TStrings.Sorted (1 )



                2.65.2         Method  overview

                __Page______Property_____________Description_______________________________________________________________________*
 *___________
                  379       Add                  Implements the TStrings.Add (1 ) function.
                  379       Clear                Implements the TStrings.Clear (1 ) function.
                  381       CustomSort           Sort the stringlist using a custom sort algorithm
                  379       Delete               Implements the TStrings.Delete (1 ) function.
                  379       Destroy              Destroys the stringlist.
                  380       Exchange             Implements the TStrings.Exchange (1 ) function.
                  380       Find                 Locates the index for a given string in sorted lists.
                  380       IndexOf              Overrides the TStrings.IndexOf (1 ) property.
                  380       Insert               Overrides the TStrings.Insert (1 ) method.
                  379       InsertItem
                __381_______Sort_________________Sorts_the_strings_in_the_list.____________________________________________________*
 *___________



                2.65.3         Property  overview

                __Page______Property_______________Access_______Description________________________________________________________*
 *___________
                  382       CaseSensitive          rw
                  381       Duplicates             rw           Describes the behaviour of a sorted list with respect to
                                                                duplicate strings.
                  382       OnChange               rw           Event triggered after the list was modified.
                  383       OnChanging             rw           Event triggered when the list is about to be modified.
                  383       OwnsObjects            rw           Determines  whether  the  stringlist  owns  it's  objects  or
                                                                not.
                __382_______Sorted_________________rw___________Determines_whether_the_list_is_sorted_or_not.______________________*
 *___________



                                                                                 378

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.65.4         TStringList.InsertItem

Declaration:     procedure  InsertItem(Index:  Integer;const  S:  string);    Virtual
                procedure  InsertItem(Index:  Integer;const  S:  string;O:  TObject)
                                                 ;    Virtual

    Visibility:   default



                2.65.5         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.



                2.65.6         TStringList.Add

    Synopsis:    Implements the TStrings.Add (1 ) 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 (1 ) is dupError then an EStringListError (230  ) exception is
                raised.  If  Duplicates is set to dupIgnore then the return value is underfined.

                If the list is sorted, new strings will not necessarily be added to the end of the list, rather
                they will be inserted at their alphabetical position.

       Errors:   If the list is sorted and the string S is already present in the list and TStringList.Duplicates
                (1 ) is dupError then an EStringListError (230  ) exception is raised.

    See also:    TStringList.Insert (1 ), TStringList.Duplicates (1 )



                2.65.7         TStringList.Clear

    Synopsis:    Implements the TStrings.Clear (1 ) function.

Declaration:     procedure  Clear;    Override

    Visibility:   public

Description:     Implements the TStrings.Clear (1 ) function.



                2.65.8         TStringList.Delete

    Synopsis:    Implements the TStrings.Delete (1 ) function.

Declaration:     procedure  Delete(Index:  Integer);    Override

    Visibility:   public

Description:     Implements the TStrings.Delete (1 ) function.



                                                                                 379

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.65.9         TStringList.Exchange

    Synopsis:    Implements the TStrings.Exchange (1 ) 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 (1 ).

 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 (1 ), TStrings.Exchange (1 )



                2.65.10          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 (1 )
                       instead.

                     2.Find uses a binary search method to locate the string



                2.65.11          TStringList.IndexOf

    Synopsis:    Overrides the TStrings.IndexOf (1 ) property.

Declaration:     function  IndexOf(const  S:  string)  :  Integer;    Override

    Visibility:   public

Description:     IndexOf overrides the ancestor method TStrings.indexOf (1 ).  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 (1 ), TStringList.Find (1 )



                2.65.12          TStringList.Insert

    Synopsis:    Overrides the TStrings.Insert (1 ) 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 (230  ) exception will be raised instead.  Index is a zero-based position.



                                                                                 380

                __________________________________________________________CHAPTER_2.___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 (230  ) exception will be raised.

    See also:    TStringList.Add (1 ), TStrings.Insert (1 ), TStringList.InsertObject (1 )



                2.65.13          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 (1 ) property set to True then nothing will be done.

    See also:    TStringList.Sorted (1 )



                2.65.14          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 (1 ), TStringList.Sort (1 )



                2.65.15          TStringList.Duplicates

    Synopsis:    Describes the behaviour of a sorted list with respect to duplicate strings.

Declaration:     Property  Duplicates  :  TDuplicates

    Visibility:   public

      Access:    Read,Write

Description:     Duplicates describes what to do in case a duplicate value is added to the list:



                                                                       Table 2.23:



                  dupIgnore          Duplicate values will not be be added to the list, but no error will be triggered.
                  dupError           If an attempt is made to add a duplicate value to the list, an EStringListError (230  ) except*
 *ion is raised.
                  dupAccept          Duplicate values can be added to the list.



                If the stringlist is not sorted, the Duplicates setting is ignored.



                                                                                 381

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.65.16          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 (1 ) cannot be used.  For sorted lists, TStringList.Add
                       (1 ) should be used instead.

                     2.If  Sorted  is  True,  the  TStringList.Duplicates  (1 )  setting  has  effect.   This  setting  is
                       ignored when Sorted is False.

    See also:    TStringList.Sort  (1 ),  TStringList.Duplicates  (1 ),  TStringList.Add  (1 ),  TstringList.Insert
                (1 )



                2.65.17          TStringList.CaseSensitive

    Synopsis:

Declaration:     Property  CaseSensitive  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Indicates whether locating strings happens in a case sensitive manner.



                2.65.18          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 (1 ) event occurs.

    See also:    TStringList.OnChanging (1 )



                                                                                 382

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.65.19          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 (1 ) event occurs.

    See also:    TStringList.OnChange (1 )



                2.65.20          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 (1 )



                2.66          TStrings



                2.66.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
                (378  ) 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 (378  ).


    See also:    TStringList (378  )



                                                                                 383

__________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________________________*
 *___



2.66.2         Method  overview

__Page______Property____________________Description___________________________________________________________________________
  386       Add                         Add a string to the list
  386       AddObject                   Add a string and associated object to the list.
  386       AddStrings                  Add contents of another stringlist to this list.
  386       Append                      Add a string to the list.
  387       Assign                      Assign the contents of another stringlist to this one.
  387       BeginUpdate                 Mark the beginning of an update batch.
  387       Clear                       Removes all strings and associated objects from the list.
  388       Delete                      Delete a string from the list.
  385       Destroy                     Frees all strings and objects, and removes the list from mem-
                                        ory.
  388       EndUpdate                   Mark the end of an update batch.
  388       Equals                      Compares the contents of two stringlists.
  385       Error                       Raises an EStringListError (230  ) exception.
  389       Exchange                    Exchanges two strings in the list.
  393       ExtractName                 Extract the name part of a string
  389       GetEnumerator               Create an IEnumerator instance
  393       GetNameValue                Return  both  name  and  value  of  a  name,value  pair  based  on
                                        it's index.
  389       GetText                     Returns the contents as a PChar
  389       IndexOf                     Find a string in the list and return its position.
  390       IndexOfName                 Finds the index of a name in the name-value pairs.
  390       IndexOfObject               Finds an object in the list and returns its index.
  390       Insert                      Insert a string in the list.
  391       InsertObject                Insert a string and associated object in the list.
  391       LoadFromFile                Load the contents of a file as a series of strings.
  391       LoadFromStream              Load the contents of a stream as a series of strings.
  391       Move                        Move a string from one place in the list to another.
  392       SaveToFile                  Save the contents of the list to a file.
  392       SaveToStream                Save the contents of the string to a stream.
__393_______SetText_____________________Set_the_contents_of_the_list_from_a_PChar.____________________________________________



                                                                 384

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.66.3         Property  overview

                __Page______Property_________________________Access_______Description______________________________________________*
 *___________
                  396       Capacity                         rw           Capacity of the list, i.e.  number of strings that
                                                                          the list can currently hold before it tries to ex-
                                                                          pand.
                  396       CommaText                        rw           Contents of the list as a comma-separated string.
                  397       Count                            r            Number of strings in the list.
                  394       DelimitedText                    rw           Get  or  set  all  strings  in  the  list  in  a  delimit*
 *ed
                                                                          form.
                  394       Delimiter                        rw           Delimiter character used in DelimitedText (394  ).
                  397       Names                            r            Name parts of the name-value pairs in the list.
                  395       NameValueSeparator               rw           Value   of   the   character   used   to   separate
                                                                          name,value pairs
                  397       Objects                          rw           Indexed access to the objects associated with the
                                                                          strings in the list.
                  395       QuoteChar                        rw           Quote character used in DelimitedText (394  ).
                  395       StrictDelimiter                  rw           Should  only  the  delimiter  character  be  consid-
                                                                          ered a delimiter
                  398       Strings                          rw           Indexed access to the strings in the list.
                  399       StringsAdapter                   rw           Not implemented in Free Pascal.
                  399       Text                             rw           Contents of the list as one big string.
                  393       TextLineBreakStyle               rw           Determines which line breaks to use in the Text
                                                                          (399  ) property
                  395       ValueFromIndex                   rw           Return  the  value  part  of  a  string  based  on  it's
                                                                          index.
                __398_______Values___________________________rw___________Value_parts_of_the_name-value_pairs_in_the_list._________*
 *___________



                2.66.4         TStrings.Error

    Synopsis:    Raises an EStringListError (230  ) exception.

Declaration:     procedure  Error(const  Msg:  string;Data:  Integer)
                procedure  Error(const  Msg:  PString;Data:  Integer)

    Visibility:   default

Description:     Error raises an EStringListError (230  ) exception.  It passes Msg as a format with Data as
                the only argument.

                This method can be used by descendent objects to raise an error.

    See also:    EStringListError (230  )



                2.66.5         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.



                                                                                 385

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.66.6         TStrings.Add

    Synopsis:    Add a string to the list

Declaration:     function  Add(const  S:  string)  :  Integer;    Virtual

    Visibility:   public

Description:     Add adds S at the end of the list and returns the index of  S in the list (which should equal
                Tstrings.Count (1 )

    See also:    TStrings.Items (1 ), TStrings.AddObject (1 ), TStrings.Insert (1 ), TStrings.Delete (1 ), TStrings.Strings
                (1 ), TStrings.Count (1 )



                2.66.7         TStrings.AddObject

    Synopsis:    Add a string and associated object to the list.

Declaration:     function  AddObject(const  S:  string;AObject:  TObject)  :  Integer;    Virtual

    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 (1 ), Tstrings.Items (1 ), TStrings.Objects (1 ), Tstrings.InsertObject (1 )



                2.66.8         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 (1 ), only it does not return the index of the inserted
                string.

    See also:    TStrings.Add (1 )



                2.66.9         TStrings.AddStrings

    Synopsis:    Add contents of another stringlist to this list.

Declaration:     procedure  AddStrings(TheStrings:  TStrings);    Virtual

    Visibility:   public

Description:     AddStrings adds the contents of  TheStrings to the stringlist.  Any associated objects are
                added as well.

    See also:    TStrings.Add (1 ), TStrings.Assign (1 )



                                                                                 386

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.66.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 (1 ), TStrings.AddStrings (1 ), TPersistent.Assign (1 )



                2.66.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
                (1 )  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 (1 ) 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 (1 )



                2.66.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 (1 ) is zero.

                Since  it  is  an  abstract  method,  TStrings  itself  does  not  implement  Clear.   Descendent
                classes such as TStringList (378  ) implement this method.

    See also:    TStrings.Items (1 ), TStrings.Delete (1 ), TStrings.Count (1 )



                                                                                 387

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.66.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 (378  ) implement this method.

       Errors:   If  Index is not in the allowed range, an EStringListError (230  ) is raised.

    See also:    TStrings.Insert (1 ), TStrings.Items (1 ), TStrings.Clear (1 )



                2.66.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 (1 ).

    See also:    TStrings.BeginUpdate (1 )



                2.66.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:   default

Description:     Equals  compares  the  contents  of  the  stringlist  with  the  contents  of  TheStrings.   If  the
                contents match, i.e.  the stringlist contain an equal amount of strings, and all strings match,
                then True is returned.  If the number of strings in the lists is is unequal, or they contain one
                or more different strings, False is returned.

 Remark:

                     1.The strings are compared case-insensitively.

                     2.The associated objects are not compared

    See also:    Tstrings.Items (1 ), TStrings.Count (1 ), TStrings.Assign (1 )



                                                                                 388

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.66.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 (230  )
                exception is raised.

    See also:    TStrings.Move (1 ), TStrings.Strings (1 ), TStrings.Count (1 )



                2.66.17          TStrings.GetEnumerator

    Synopsis:    Create an IEnumerator instance

Declaration:     function  GetEnumerator  :  TStringsEnumerator

    Visibility:   public

Description:     GetEnumerator is the implementation of the IEnumerable (1433   ) interface for TStrings.  It
                creates a TStringsEnumerator (399  ) instance and returns it's IEnumerator (1433   ) interface.

    See also:    TStringsEnumerator (399  ), IEnumerator (1433   ), IEnumerable (1433   )



                2.66.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.



                2.66.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 (1 ), TStrings.IndexOfName (1 ), TStrings.Strings (1 )



                                                                                 389

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.66.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 (1 ), TStrings.IndexOfObject (1 ), TStrings.Strings (1 )



                2.66.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.



                2.66.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 (1 ) instead.

       Errors:   If  Index is less than zero or larger than Count then an EStringListError (230  ) exception is
                raised.

    See also:    TStrings.Add (1 ), TStrings.InsertObject (1 ), TStrings.Append (1 ), TStrings.Delete (1 )



                                                                                 390

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.66.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 (230  ) exception is
                raised.

    See also:    TStrings.Insert (1 ), TStrings.AddObject (1 ), TStrings.Append (1 ), TStrings.Delete (1 )



                2.66.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 (308  ) with the given filename, and then executes
                TStrings.LoadfromStream (1 ); after that the file stream object is destroyed again.

    See also:    TStrings.LoadFromStream (1 ), TStrings.SaveToFile (1 ), Tstrings.SaveToStream (1 )



                2.66.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 (1 ), TStrings.SaveToFile (1 ), Tstrings.SaveToStream (1 )



                2.66.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



                                                                                 391

                __________________________________________________________CHAPTER_2.___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 (230  ) is
                raised.

    See also:    TStrings.Exchange (1 )



                2.66.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 (308  ) with name FileName, calls TStrings.SaveToStream
                (1 ) and then destroys the file stream object.

       Errors:   An EStreamError (230  ) exception can be raised if the file FileName cannot be opened, or
                if it cannot be written to.

    See also:    TStrings.SaveToStream (1 ), Tstrings.LoadFromStream (1 ), TStrings.LoadFromFile (1 )



                2.66.28          TStrings.SaveToStream

    Synopsis:    Save the contents of the string to a stream.

Declaration:     procedure  SaveToStream(Stream:  TStream);    Virtual



                                                                                 392

                __________________________________________________________CHAPTER_2.___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 (230  ) exception can be raised if the stream cannot be written to.

    See also:    TStrings.SaveToFile (1 ), Tstrings.LoadFromStream (1 ), TStrings.LoadFromFile (1 )



                2.66.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 (1 )



                2.66.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.



                2.66.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 (1 ) character)
                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 (1 )



                2.66.32          TStrings.TextLineBreakStyle

    Synopsis:    Determines which line breaks to use in the Text (399  ) property

Declaration:     Property  TextLineBreakStyle  :  TTextLineBreakStyle

    Visibility:   public

      Access:    Read,Write



                                                                                 393

                __________________________________________________________CHAPTER_2.___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 (399  )



                2.66.33          TStrings.Delimiter

    Synopsis:    Delimiter character used in DelimitedText (394  ).

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 (1 ) property.

    See also:    TStrings.DelimitedText (1 )



                2.66.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 (1 ) and separated by
                the Delimiter (1 ) character.

                Strings are quoted if they contain a space or any character with ASCII value less than 32.

                The CommaText (1 ) property is a special case of delimited text where the delimiter character
                is a comma and the quote character is a double quote.

                If StrictDelimiter (1 ) is set to True, then no quoting is done (The QuoteChar property is dis-
                regarded 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, again disregarding the QuoteChar property.

    See also:    TStrings.Delimiter  (1 ),  TStrings.Text  (1 ),  TStrings.QuoteChar  (1 ),  TStrings.CommaText
                (1 )



                                                                                 394

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.66.35          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  (1 ):  under  normal  circumstances,  quotes
                and  spaces  are  considered  specially  (see  the  TStrings.CommaText  (1 )  property  for  more
                information).  When  StrictDelimiter  is  set  to  True  then  only  the  Delimiter  (1 )  charac-
                ter is considered when splitting the text in items:  no quoting whatsoever is performed (or
                expected) when writing the DelimitedText property.

    See also:    DelimitedText (1 ), CommaText (1 ), Delimiter (1 )



                2.66.36          TStrings.QuoteChar

    Synopsis:    Quote character used in DelimitedText (394  ).

Declaration:     Property  QuoteChar  :  Char

    Visibility:   public

      Access:    Read,Write

Description:     QuoteChar is the character used by the DelimitedText (1 ) property to quote strings that
                have a space or non-printing character in it.



                2.66.37          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.



                2.66.38          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

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 (1 ) character, or all characters
                if the NameValueSeparator character is not present.



                                                                                 395

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.66.39          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 (1 ) when read.  Trying to set the capacity has no effect.
                Descendent classes such as TStringlist (378  ) can override this property such that it actually
                sets the new capacity.

    See also:    TStringList (378  ), TStrings.Count (1 )



                2.66.40          TStrings.CommaText

    Synopsis:    Contents of the list as a comma-separated string.

Declaration:     Property  CommaText  :  string

    Visibility:   public

      Access:    Read,Write

Description:     CommaText  represents  the  stringlist  as  a  single  string,  consisting  of  a  comma-separated
                concatenation  of  the  strings  in  the  list.  If  one  of  the  strings  contains  spaces,  comma's  or
                quotes it will be enclosed by double quotes.  Any double quotes in a string will be doubled.
                For instance the following strings:


                Comma,string
                Quote"string
                Space  string
                NormalSttring


                is converted to


                "Comma,string","Quote""String","Space  string",NormalString


                Conversely, when setting the CommaText property, the text will be parsed according to the
                rules outlined above,  and the strings will be set accordingly.  Note that spaces will in this
                context be regarded as string separators, unless the string as a whole is contained in double
                quotes.  Spaces that occur next to a delimiter will be ignored.  The following string:


                "Comma,string"  ,  "Quote""String",Space  string,,  NormalString


                Will be converted to


                Comma,String
                Quote"String
                Space
                String


                NormalString



                                                                                 396

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                This is a special case of the TStrings.DelimitedText (1 ) property where the quote character
                is always the double quote, and the delimiter is always the colon.

    See also:    TStrings.Text (1 ), TStrings.SetText (1 )



                2.66.41          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 (1 ), TStrings.Objects (1 ), TStrings.Capacity (1 )



                2.66.42          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 (1 ), TStrings.IndexOfName (1 )



                2.66.43          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



                                                                                 397

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



Description:     Objects provides indexed access to the objects associated to the strings in the list.  Index
                is a zero-based index and must be in the range of  0 to Count-1.

                Setting the objects property will not free the previously associated object, if there was one.
                The caller is repsonsible for freeing the object that was previously associated to the string.

                TStrings does not implement any storage for objects.  Reading the Objects property will
                always return Nil,  Setting the property will have no effect.  It is the responsability of the
                descendent classes to provide storage for the associated objects.

       Errors:   If an Index outside the valid range is specified, an EStringListError (230  ) exception will be
                raised.

    See also:    TStrings.Strings (1 ), TStrings.IndexOfObject (1 ), TStrings.Names (1 ), TStrings.Values (1 )



                2.66.44          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 (1 ), TStrings.Strings (1 ), TStrings.Objects (1 )



                2.66.45          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.



                                                                                 398

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                To  access  the  objects  associated  with  the  strings  in  the  list,  use  the  TStrings.Objects  (1 )
                property.  The name parts of name-value pairs can be accessed with the TStrings.Names (1 )
                property, and the values can be set or read through the TStrings.Values (1 ) property.

                Searching through the list can be done using the TStrings.IndexOf (1 ) method.

       Errors:   If  Index is outside the allowed range, an EStringListError (230  ) exception is raised.

    See also:    TStrings.Count (1 ), TStrings.Objects (1 ), TStrings.Names (1 ), TStrings.Values (1 ), TStrings.IndexOf
                (1 )



                2.66.46          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 (1 ) property instead.

    See also:    TStrings.Strings (1 ), TStrings.Count (1 ), TStrings.CommaText (1 )



                2.66.47          TStrings.StringsAdapter

    Synopsis:    Not implemented in Free Pascal.

Declaration:     Property  StringsAdapter  :  IStringsAdapter

    Visibility:   public

      Access:    Read,Write

Description:     Not implemented in Free Pascal.



                2.67          TStringsEnumerator



                2.67.1         Description

                TStringsEnumerator implements the #rtl.system.IEnumerator (1433   ) interface for the TStrings
                (383  ) class, so the TStrings class can be used in a for  ...    in loop.  It is returned by the
                TStrings.GetEnumerator (1 ) method of  TStrings.


    See also:    TStrings (383  ), TStrings.GetEnumerator (1 ), #rtl.system.IEnumerator (1433   )



                                                                                 399

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.67.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  400       Create              Initialize a new instance of  TStringsEnumerator
                  400       GetCurrent          Return the current pointer in the list
                __400_______MoveNext____________Move_the_position_of_the_enumerator_to_the_next_position_in_the_list.______________*
 *___________



                2.67.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __401_______Current_________r____________Current_pointer_in_the_list_______________________________________________*
 *___________



                2.67.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 (383  )



                2.67.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 (1 ), TStringItem (210  )



                2.67.6         TStringsEnumerator.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  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 (1 )



                                                                                 400

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.67.7         TStringsEnumerator.Current

    Synopsis:    Current pointer in the list

Declaration:     Property  Current  :  string

    Visibility:   public

      Access:    Read

Description:     Current redefines GetCurrent (1 ) as a property.

    See also:    GetCurrent (1 )



                2.68          TStringStream



                2.68.1         Description

                TStringStream stores its data in an ansistring.  The contents of this string is available as
                the DataString (1 ) 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 (364  ), TStringStream.DataString (1 ), TStringStream.ReadString (1 ), TStringStream.WriteString
                (1 )



                2.68.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  401       Create              Creates a new stringstream and sets its initial content.
                  402       Read                Reads from the stream.
                  402       ReadString          Reads a string of length Count
                  402       Seek                Sets the position in the stream.
                  402       Write               Write overries the TStream.Write (1 ) method.
                __402_______WriteString_________WriteString_writes_a_string_to_the_stream._________________________________________*
 *___________



                2.68.3         Property  overview

                __Page______Property___________Access_______Description____________________________________________________________*
 *___________
                __403_______DataString_________r____________Contains_the_contents_of_the_stream_in_string_form_____________________*
 *___________



                2.68.4         TStringStream.Create

    Synopsis:    Creates a new stringstream and sets its initial content.

Declaration:     constructor  Create(const  AString:  string)

    Visibility:   public

Description:     Create creates a new TStringStream instance and sets its initial content to Astring.  The
                position is still 0 but the size of the stream will equal the length of the string.

    See also:    TStringStream.DataString (1 )



                                                                                 401

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.68.5         TStringStream.Read

    Synopsis:    Reads from the stream.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read overrides the Read (1 ) from TStream (364  ).  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
                (1 ), then the reading stops, i.e.  it is not possible to read beyond the end of the datastring.

    See also:    TStream.Read (1 ), TStringStream.Write (1 ), TStringStream.DataString (1 )



                2.68.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  (1 )  method.   It  does  not  do  the
                same stringas the TStream.ReadAnsiString (1 ) method, which first reads a length integer to
                determine the length of the string to be read.

    See also:    TStringStream.Read (1 ), TStream.ReadAnsiString (1 )



                2.68.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 (1 ) method.



                2.68.8         TStringStream.Write

    Synopsis:    Write overries the TStream.Write (1 ) method.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write overries the TStream.Write (1 ) method.



                2.68.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.



                                                                                 402

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.68.10          TStringStream.DataString

    Synopsis:    Contains the contents of the stream in string form

Declaration:     Property  DataString  :  string

    Visibility:   public

      Access:    Read

Description:     Contains the contents of the stream in string form



                2.69          TTextOb jectWriter



                2.69.1         Description

                Not yet implemented.



                2.70          TThread



                2.70.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 (1 ) 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 (230  ), TThread.Execute (1 )



                2.70.2         Method  overview

                __Page______Property_____________________Description_______________________________________________________________*
 *___________
                  404       AfterConstruction            Code to be executed after construction but before execute.
                  404       Create                       Creates a new thread.
                  404       Destroy                      Destroys the thread object.
                  405       Resume                       Resumes the thread's execution.
                  404       Start                        Starts a thread thread that was created in a suspended state.
                  405       Suspend                      Suspends the thread's execution.
                  404       Synchronize                  Synchronizes the thread by executing the method in the main
                                                         thread.
                  405       Terminate                    Signals the thread it should terminate.
                __405_______WaitFor______________________Waits_for_the_thread_to_terminate_and_returns_the_exit_status.____________*
 *___________



                2.70.3         Property  overview

                __Page______Property____________________Access_______Description___________________________________________________*
 *___________
                  407       FatalException              r            Exception that occured during thread execution
                  405       FreeOnTerminate             rw           Indicates whether the thread should free itself when
                                                                     it stops executing.
                  406       Handle                      r            Returns the thread handle.
                  406       OnTerminate                 rw           Event called when the thread terminates.
                  406       Priority                    rw           Returns the thread priority.
                  406       Suspended                   rw           Indicates whether the thread is suspended.
                __406_______ThreadID____________________r____________Returns_the_thread_ID.________________________________________*
 *___________



                                                                                 403

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.70.4         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:   default

Description:     Synchronizes the thread by executing the method in the main thread.



                2.70.5         TThread.Create

    Synopsis:    Creates a new thread.

Declaration:     constructor  Create(CreateSuspended:  Boolean;const  StackSize:  SizeUInt)

    Visibility:   public

Description:     Creates a new thread.



                2.70.6         TThread.Destroy

    Synopsis:    Destroys the thread object.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the thread object.



                2.70.7         TThread.AfterConstruction

    Synopsis:    Code to be executed after construction but before execute.

Declaration:     procedure  AfterConstruction;    Override

    Visibility:   public

Description:     AfterConstruction is overridden in TThread but currently does not do anything useful.



                2.70.8         TThread.Start

    Synopsis:    Starts a thread 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 (1 )



                                                                                 404

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.70.9         TThread.Resume

    Synopsis:    Resumes the thread's execution.

Declaration:     procedure  Resume

    Visibility:   public

Description:     Resumes the thread's execution.

    See also:    TThread.Start (1 ), TThread.Suspend (1 )



                2.70.10          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.Resume.

    See also:    TThread.Resume (1 )



                2.70.11          TThread.Terminate

    Synopsis:    Signals the thread it should terminate.

Declaration:     procedure  Terminate

    Visibility:   public

Description:     Signals the thread it should terminate.



                2.70.12          TThread.WaitFor

    Synopsis:    Waits for the thread to terminate and returns the exit status.

Declaration:     function  WaitFor  :  Integer

    Visibility:   public

Description:     Waits for the thread to terminate and returns the exit status.



                2.70.13          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.



                                                                                 405

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.70.14          TThread.Handle

    Synopsis:    Returns the thread handle.

Declaration:     Property  Handle  :  TThreadID

    Visibility:   public

      Access:    Read

Description:     Returns the thread handle.



                2.70.15          TThread.Priority

    Synopsis:    Returns the thread priority.

Declaration:     Property  Priority  :  TThreadPriority

    Visibility:   public

      Access:    Read,Write

Description:     Returns the thread priority.



                2.70.16          TThread.Suspended

    Synopsis:    Indicates whether the thread is suspended.

Declaration:     Property  Suspended  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     Indicates whether the thread is suspended.



                2.70.17          TThread.ThreadID

    Synopsis:    Returns the thread ID.

Declaration:     Property  ThreadID  :  TThreadID

    Visibility:   public

      Access:    Read

Description:     Returns the thread ID.



                2.70.18          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.



                                                                                 406

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.70.19          TThread.FatalException

    Synopsis:    Exception that occured during thread execution

Declaration:     Property  FatalException  :  TObject

    Visibility:   public

      Access:    Read

Description:     FatalException contains the exception that occurred during the thread's execution.



                2.71          TThreadList



                2.71.1         Description

                TThreadList is a thread-safe Tlist (328  ) 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 (328  )



                2.71.2         Method  overview

                __Page______Property___________Description_________________________________________________________________________*
 *___________
                  408       Add                Adds an element to the list.
                  408       Clear              Removes all emements from the list.
                  407       Create             Creates a new thread-safe list.
                  408       Destroy            Destroys the list instance.
                  408       LockList           Locks the list for exclusive access.
                  409       Remove             Removes an item from the list.
                __409_______UnlockList_________Unlocks_the_list_after_it_was_locked._______________________________________________*
 *___________



                2.71.3         Property  overview

                __Page______Property___________Access______Description_____________________________________________________________*
 *___________
                __409_______Duplicates_________rw__________Describes_what_to_do_with_duplicates____________________________________*
 *___________



                2.71.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 (1 )



                                                                                 407

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.71.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 (1 )



                2.71.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 (1 ), Clear (1 ), Remove (1 ), UnlockList (1 )



                2.71.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 (1 ), Add (1 ), Remove (1 ), UnlockList (1 )



                2.71.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 (1 ), Add (1 ), Remove (1 ), UnlockList (1 )



                                                                                 408

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.71.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 (1 ), Add (1 ), Clear (1 ), UnlockList (1 )



                2.71.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 (1 ), Add (1 ), Remove (1 ), lockList (1 )



                2.71.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 (1 ) property of TStringList (378  ).

    See also:    TDuplicates (203  )



                2.72          TWriter



                2.72.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 (249  ) 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 (1 ) call should be used.


    See also:    TFiler (306  ), TWriter (409  ), TAbstractObjectReader (241  )



                                                                                 409

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.72.2         Method  overview

                __Page______Property___________________________Description_________________________________________________________*
 *___________
                  410       Create                             Creates a new Writer with a stream and bufsize.
                  411       DefineBinaryProperty               Callback used when defining and streaming custom prop-
                                                               erties.
                  411       DefineProperty                     Callback used when defining and streaming custom prop-
                                                               erties.
                  411       Destroy                            Destroys the writer instance.
                  411       Write                              Write raw data to stream
                  411       WriteBoolean                       Write boolean value to the stream.
                  412       WriteChar                          Write a character to the stream.
                  412       WriteCollection                    Write a collection to the stream.
                  412       WriteComponent                     Stream a component to the stream.
                  413       WriteCurrency                      Write a currency value to the stream
                  413       WriteDate                          Write a date to the stream.
                  412       WriteDescendent                    Write a descendent component to the stream.
                  413       WriteFloat                         Write a float to the stream.
                  413       WriteIdent                         Write an identifier to the stream.
                  414       WriteInteger                       Write an integer to the stream.
                  414       WriteListBegin                     Write a start-of-list marker to the stream.
                  414       WriteListEnd                       Write an end-of-list marker to the stream.
                  414       WriteRootComponent                 Write a root component to the stream.
                  414       WriteSet                           Write a set value to the stream
                  413       WriteSingle                        Write a single-type real to the stream.
                  415       WriteString                        Write a string to the stream.
                  415       WriteUnicodeString                 Write a unicode string to the stream.
                  415       WriteVariant                       Write a variant to the stream
                  412       WriteWideChar                      Write widechar to stream
                __415_______WriteWideString____________________Write_a_widestring_value_to_the_stream______________________________*
 *___________



                2.72.3         Property  overview

                __Page______Property_______________________________Access_______Description________________________________________*
 *___________
                  416       Driver                                 r            Driver used when writing to the stream.
                  416       OnFindAncestor                         rw           Event  occurring  when  an  ancestor  compo-
                                                                                nent must be found.
                  416       OnWriteMethodProperty                  rw           Handler from writing method properties.
                  416       OnWriteStringProperty                  rw           Event handler for translating strings written
                                                                                to stream.
                  417       PropertyPath                           r            Path to the property that is currently being
                                                                                written
                __415_______RootAncestor___________________________rw___________Ancestor_of_root_component.________________________*
 *___________



                2.72.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:   default

Description:     Creates a new Writer with a stream and bufsize.



                                                                                 410

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.72.5         TWriter.Destroy

    Synopsis:    Destroys the writer instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroys the writer instance.



                2.72.6         TWriter.DefineProperty

    Synopsis:    Callback used when defining and streaming custom properties.

Declaration:     procedure  DefineProperty(const  Name:  string;ReadData:  TReaderProc;
                                                        AWriteData:  TWriterProc;HasData:  Boolean)
                                                        ;    Override

    Visibility:   public

Description:     Callback used when defining and streaming custom properties.



                2.72.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.



                2.72.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 (1 ), TAbstractObjectWriter.Write (1 )



                2.72.9         TWriter.WriteBoolean

    Synopsis:    Write boolean value to the stream.

Declaration:     procedure  WriteBoolean(Value:  Boolean)

    Visibility:   public

Description:     Write boolean value to the stream.



                                                                                 411

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.72.10          TWriter.WriteCollection

    Synopsis:    Write a collection to the stream.

Declaration:     procedure  WriteCollection(Value:  TCollection)

    Visibility:   public

Description:     Write a collection to the stream.



                2.72.11          TWriter.WriteComponent

    Synopsis:    Stream a component to the stream.

Declaration:     procedure  WriteComponent(Component:  TComponent)

    Visibility:   public

Description:     Stream a component to the stream.



                2.72.12          TWriter.WriteChar

    Synopsis:    Write a character to the stream.

Declaration:     procedure  WriteChar(Value:  Char)

    Visibility:   public

Description:     Write a character to the stream.



                2.72.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 (1 ), TWriter.WriteWideString (1 )



                2.72.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.



                                                                                 412

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.72.15          TWriter.WriteFloat

    Synopsis:    Write a float to the stream.

Declaration:     procedure  WriteFloat(const  Value:  Extended)

    Visibility:   public

Description:     Write a float to the stream.



                2.72.16          TWriter.WriteSingle

    Synopsis:    Write a single-type real to the stream.

Declaration:     procedure  WriteSingle(const  Value:  Single)

    Visibility:   public

Description:     Write a single-type real to the stream.



                2.72.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.



                2.72.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 (1 )



                2.72.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.



                                                                                 413

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.72.20          TWriter.WriteInteger

    Synopsis:    Write an integer to the stream.

Declaration:     procedure  WriteInteger(Value:  LongInt);    Overload
                procedure  WriteInteger(Value:  Int64);    Overload

    Visibility:   default

Description:     Write an integer to the stream.



                2.72.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 (1 )



                2.72.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.



                2.72.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.



                2.72.24          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.



                                                                                 414

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.72.25          TWriter.WriteString

    Synopsis:    Write a string to the stream.

Declaration:     procedure  WriteString(const  Value:  string)

    Visibility:   public

Description:     Write a string to the stream.



                2.72.26          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 (1 )



                2.72.27          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 (1 ), TReader.ReadUnicodeString (1 )



                2.72.28          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 (1 ), TReader.ReadVariant (1 )



                2.72.29          TWriter.RootAncestor

    Synopsis:    Ancestor of root component.

Declaration:     Property  RootAncestor  :  TComponent

    Visibility:   public

      Access:    Read,Write

Description:     Ancestor of root component.



                                                                                 415

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.72.30          TWriter.OnFindAncestor

    Synopsis:    Event occurring when an ancestor component must be found.

Declaration:     Property  OnFindAncestor  :  TFindAncestorEvent

    Visibility:   public

      Access:    Read,Write

Description:     Event occurring when an ancestor component must be found.



                2.72.31          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 (211  )
                for a description of the arguments.

    See also:    TWriteMethodPropertyEvent (211  ), TReader.OnSetMethodProperty (1 )



                2.72.32          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 (207  ) for a description of the various
                parameters.

    See also:    TReader.OnPropertyNotFound (1 ), TReader.OnSetMethodProperty (1 ), TReadWriteString-
                PropertyEvent (207  )



                2.72.33          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.



                                                                                 416

                __________________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'CLASSES'________________*
 *___________________



                2.72.34          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 (347  ) descendent class properties are written.



                                                                                 417




Chapter   3



Reference   for   unit   'clocale'



3.1         Overview


The clocale offers no API by itself:  it just initializes the internationalization settings of the
sysutils (1450   ) 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;



                                                             418




                Chapter   4



                Reference   for   unit   'cmem'



                4.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 (420  ), Free (420  ) and ReAlloc (420  ).  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.



                4.2         Constants,  types  and  variables



                4.2.1        Constants

                LibName  =  'c'


                LibName is the name of the library that is actually used.  On most systems, this is simply
                "libc.so".



                4.3         Procedures  and  functions



                4.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 (420  ), Free (420  ), Realloc (420  )



                                                                             419

                ______________________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CMEM'_______________*
 *___________________



                4.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 (420  ), ReAlloc (420  )



                4.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 (420  ), ReAlloc (420  )



                4.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 (420  ), Free (420  )



                                                                                 420




Chapter   5



Reference   for   unit   'Crt'



5.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.



5.2         Constants,  types  and  variables



5.2.1        Constants

Black  =  0


Black color attribute


Blink  =  128


Blink attribute


Blue  =  1



                                                             421

__________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________________________*
 *___



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


Green  =  2



                                                                 422

__________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________________________*
 *___



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



                                                                 423

__________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________________________*
 *___



5.2.2        Types

  =  1..255


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.


PConsoleBuf  =  ^TConsoleBuf



TCharAttr  =  packed  record
    ch  :  Char;
    attr  :  Byte;
end



TConsoleBuf  =  Array[0..ConsoleMaxX*ConsoleMaxY-1]  of  TCharAttr



5.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



                                                                 424

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



                DirectVideo  :  Boolean


                The DirectVideo variable controls the writing to the screen.  If it is True, the the cursor is
                set via direct port access.  If  False, then the BIOS is used.  This is defined under dos only.


                LastMode  :  Word  =  3


                The Lastmode variable tells you which mode was last selected for the screen.  It is defined
                on DOS only.


                TextAttr  :  Byte  =  $07


                The TextAttr variable controls the attributes with which characters are written to screen.


                WindMax  :  Word  =  $184f


                The upper byte of  WindMax contains the Y coordinate while the lower byte contains the X
                coordinate.  The use of this variable is deprecated, use WindMaxX and WindMaxY instead.


                WindMaxX  :  DWord


                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



                5.3         Procedures  and  functions



                5.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.



                                                                                 425

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



       Errors:   None.

    See also:    Window (436  )


                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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (428  ), InsLine (430  ), ClrScr (427  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 426

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



                5.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 (436  )


                Listing:  ./crtex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (428  ), CursorOff (427  )



                5.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 (428  ), CursorBig (427  )



                                                                                 427

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



                5.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 (427  ), CursorOff (427  )



                5.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 (433  ), NoSound (432  )


                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___.____________________________________________________________________________________________________________*
 *___________



                5.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.



                                                                                 428

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



    See also:    ClrEol (426  ), InsLine (430  ), ClrScr (427  )


                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  ') ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (435  ), WhereY (435  ), Window (436  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 429

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



                5.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.

    See also:    TextColor (434  ), TextBackground (433  ), LowVideo (431  ), NormVideo (432  )


                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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (426  ), DelLine (428  ), ClrScr (427  )


                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  ') ;



                                                                                 430

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (432  )


                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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (430  )

       Errors:   None.

    See also:    TextColor (434  ), TextBackground (433  ), HighVideo (430  ), NormVideo (432  )



                                                                                 431

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



                5.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 (430  )

       Errors:   None.

    See also:    TextColor (434  ), TextBackground (433  ), LowVideo (431  ), HighVideo (430  )



                5.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 (433  )


                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___.____________________________________________________________________________________________________________*
 *___________



                5.3.16         ReadKey

    Synopsis:    Read key from keybuffer

Declaration:     function  ReadKey  :  Char

    Visibility:   default



                                                                                 432

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



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 (431  )


                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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (432  )



                5.3.18         TextBackground

    Synopsis:    Set text background

Declaration:     procedure  TextBackground(Color:  Byte)



                                                                                 433

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



    Visibility:  default

Description:     TextBackground  sets  the  background  color  to  CL.  CL  can  be  one  of  the  predefined  color
                constants.

       Errors:   None.

    See also:    TextColor (434  ), HighVideo (430  ), LowVideo (431  ), NormVideo (432  )


                Listing:  ./crtex/ex13.pp
                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (433  ), HighVideo (430  ), LowVideo (431  ), NormVideo (432  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 434

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



                5.3.20         TextMode

    Synopsis:    Set screen mode.

Declaration:     procedure  TextMode(Mode:  Word)

    Visibility:   default

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 (436  )



                5.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 (429  ), WhereY (435  ), Window (436  )


                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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (429  ), WhereX (435  ), Window (436  )


                Listing:  ./crtex/ex7.pp



                                                                                 435

                __________________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CRT'____________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                5.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 (429  ), WhereX (435  ), WhereY (435  ), ClrScr (427  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 436




                Chapter   6



                Reference   for   unit   'cthreads'



                6.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 (1230   ) unit.  This is done using the SetCThreadMan-
                ager (437  ) 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.



                6.2         Procedures  and  functions



                6.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.



                                                                             437




Chapter   7



Reference   for   unit   'ctypes'



7.1         Used  units



                                     Table 7.1:  Used units by unit 'ctypes'


                                                  __Name____________Page_____
                                                    System          1230
                                                    unixtype        1715



7.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.



7.3         Constants,  types  and  variables



7.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)



                                                             438

___________________________________________________________CHAPTER_7.___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)



                                                                 439

___________________________________________________________CHAPTER_7.___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



                                                                 440

___________________________________________________________CHAPTER_7.___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 (438  ) type.


pcchar  =  UnixType.pcchar


Pointer to cchar (438  ) type.


pcdouble  =  UnixType.pcdouble


Pointer to cdouble (438  ) type.


pcfloat  =  UnixType.pcfloat


Pointer to cfloat (439  ) type.


pcint  =  UnixType.pcint


Pointer to cint (439  ) type.


pcint16  =  UnixType.pcint16


Pointer to cint16 (439  ) type.


pcint32  =  UnixType.pcint32


Pointer to cint32 (439  ) type.


pcint64  =  UnixType.pcint64


Pointer to cint64 (439  ) type.


pcint8  =  UnixType.pcint8


Pointer to cint8 (439  ) type.


pclong  =  UnixType.pclong


Pointer to clong (439  ) type.


Pclongdouble  =  ^clongdouble


Pointer to clongdouble (439  ) type.



                                                                 441

___________________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'CTYPES'________________________________*
 *___



pclonglong  =  UnixType.pclonglong


Pointer to clonglong (439  ) type.


pcschar  =  UnixType.pcschar


Pointer to cschar (439  ) type.


pcshort  =  UnixType.pcshort


Pointer to cshort (439  ) type.


pcsigned  =  UnixType.pcsigned


Pointer to csigned (439  ) type.


pcsint  =  UnixType.pcsint


Pointer to csint (440  ) type.


pcsize_t  =  UnixType.psize_t


Pointer to generic size type


pcslong  =  UnixType.pcslong


Pointer to cslong (440  ) type.


pcslonglong  =  UnixType.pcslonglong


Pointer to cslonglong (440  ) type.


pcsshort  =  UnixType.pcsshort


Pointer to csshort (440  ) type.


pcuchar  =  UnixType.pcuchar


Pointer to cuchar (440  ) type.


pcuint  =  UnixType.pcuint


Pointer to cuint (440  ) type.


pcuint16  =  UnixType.pcuint16


Pointer to cuint16 (440  ) type.


pcuint32  =  UnixType.pcuint32


Pointer to cuint32 (440  ) type.



                                                                 442

                ___________________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                pcuint64  =  UnixType.pcuint64


                Pointer to cuint64 (440  ) type.


                pcuint8  =  UnixType.pcuint8


                Pointer to cuint8 (440  ) type.


                pculong  =  UnixType.pculong


                Pointer to culong (440  ) type.


                pculonglong  =  UnixType.pculonglong


                Pointer to culonglong (440  ) type.


                pcunsigned  =  UnixType.pcunsigned


                Pointer to cunsigned (441  ) type.


                pcushort  =  UnixType.pcushort


                Pointer to cushort (441  ) type.



                7.4         Procedures  and  functions



                7.4.1        operator  *(clongdouble,  Double):  Double

    Synopsis:    Implement multiplication of  clongdouble and double.

Declaration:     operator  operator  *(clongdouble,  Double):  Double(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.



                7.4.2        operator  *(Double,  clongdouble):  Double

    Synopsis:    Implement multiplication of  double and clongdouble.

Declaration:     operator  operator  *(Double,  clongdouble):  Double(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.



                                                                                 443

                ___________________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                7.4.3        operator  +(clongdouble,  Double):  Double

    Synopsis:

Declaration:     operator  operator  +(clongdouble,  Double):  Double(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.



                7.4.4        operator  +(Double,  clongdouble):  Double

    Synopsis:    Implement addition of  clongdouble and double.

Declaration:     operator  operator  +(Double,  clongdouble):  Double(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.



                7.4.5        operator  -(clongdouble,  Double):  Double

    Synopsis:    Implement subtraction of  double and clongdouble.

Declaration:     operator  operator  -(clongdouble,  Double):  Double(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.



                7.4.6        operator  -(Double,  clongdouble):  Double

    Synopsis:    Implement subtraction of  clongdouble and double.

Declaration:     operator  operator  -(Double,  clongdouble):  Double(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.



                                                                                 444

                ___________________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                7.4.7        operator  /(clongdouble,  Double):  Double

    Synopsis:    Implement division of  double and clongdouble.

Declaration:     operator  operator  /(clongdouble,  Double):  Double(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.



                7.4.8        operator  /(Double,  clongdouble):  Double

    Synopsis:    Implement division of  clongdouble and double.

Declaration:     operator  operator  /(Double,  clongdouble):  Double(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.



                7.4.9        operator  :=(clongdouble):  Double

    Synopsis:    Implement assignment of a clongdouble to a double type.

Declaration:     operator  operator  :=(clongdouble):  Double(const  v:  clongdouble)  :  Double

    Visibility:   default

Description:     This operator allows to assign a clongdouble to a Double type.



                7.4.10         operator  :=(Double):  clongdouble

    Synopsis:    Implement assignment of a double to a clongdouble type.

Declaration:     operator  operator  :=(Double):  clongdouble(const  v:  Double)  :  clongdouble

    Visibility:   default

Description:     This operator allows to assign a double to a clongdouble type.



                7.4.11         operator  <(clongdouble,  Double):  Boolean

    Synopsis:    Implement less than comparison between double and clongdouble.

Declaration:     operator  operator  <(clongdouble,  Double):  Boolean(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.



                                                                                 445

                ___________________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                7.4.12         operator  <(Double,  clongdouble):  Boolean

    Synopsis:    Implement less than comparison between clongdouble and double.

Declaration:     operator  operator  <(Double,  clongdouble):  Boolean(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.



                7.4.13         operator  <=(clongdouble,  Double):  Boolean

    Synopsis:    Implement greater than or equal comparison between double and clongdouble.

Declaration:     operator  operator  <=(clongdouble,  Double):  Boolean(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.



                7.4.14         operator  <=(Double,  clongdouble):  Boolean

    Synopsis:    Implement less than or equal comparison between clongdouble and double.

Declaration:     operator  operator  <=(Double,  clongdouble):  Boolean(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.



                7.4.15         operator  =(clongdouble,  Double):  Boolean

    Synopsis:    Implement equality of  clongdouble and double.

Declaration:     operator  operator  =(clongdouble,  Double):  Boolean(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).



                                                                                 446

                ___________________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                7.4.16         operator  =(Double,  clongdouble):  Boolean

    Synopsis:    Implement equality of  double and clongdouble.

Declaration:     operator  operator  =(Double,  clongdouble):  Boolean(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).



                7.4.17         operator  >(clongdouble,  Double):  Boolean

    Synopsis:    Implement greater than comparison between double and clongdouble.

Declaration:     operator  operator  >(clongdouble,  Double):  Boolean(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.



                7.4.18         operator  >(Double,  clongdouble):  Boolean

    Synopsis:    Implement greater than comparison between clongdouble and double.

Declaration:     operator  operator  >(Double,  clongdouble):  Boolean(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.



                7.4.19         operator  >=(clongdouble,  Double):  Boolean

    Synopsis:    Implement greater than or equal comparison between double and clongdouble.

Declaration:     operator  operator  >=(clongdouble,  Double):  Boolean(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.



                                                                                 447

                ___________________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'CTYPES'________________*
 *___________________



                7.4.20         operator  >=(Double,  clongdouble):  Boolean

    Synopsis:    Implement greater than or equal comparison between clongdouble and double.

Declaration:     operator  operator  >=(Double,  clongdouble):  Boolean(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.



                                                                                 448




                Chapter   8



                Reference   for   unit   'cwstring'



                8.1         Overview


                The cwstring unit offers no API by itself:  it just initializes the widestring manager record
                of the system (1230   ) 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;



                8.2         Procedures  and  functions



                8.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.



                                                                             449




Chapter   9



Reference   for   unit   'dateutils'



9.1         Used  units



                                    Table 9.1:  Used units by unit 'dateutils'


                                                   __Name__________Page_____
                                                     math            765
                                                     System        1230
                                                     sysutils      1450



9.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.



9.3         Constants,  types  and  variables



9.3.1        Constants

ApproxDaysPerMonth  :  Double  =  30.4375


Average number of days in a month, measured over a year.  Used in MonthsBetween (497  ).


ApproxDaysPerYear  :  Double  =  365.25


Average number of days in a year, measured over 4 years.  Used in YearsBetween (538  ).


DayFriday  =  5


ISO day number for Friday


DayMonday  =  1



                                                             450

______________________________________________________CHAPTER_9.___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)



                                                                 451

                ______________________________________________________CHAPTER_9.___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



                9.4         Procedures  and  functions



                9.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 (454  ),  CompareDateTime (453  ),  SameDate (507  ),  SameTime (509  ),  Same-
                DateTime (508  )


                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        ) ;



                                                                                 452

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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  (454  ),  CompareDate  (452  ),  SameDate  (507  ),  SameTime  (509  ),  SameDate-
                Time (508  )


                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;



                                                                                 453

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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  (453  ),  CompareDate  (452  ),  SameDate  (507  ),  SameTime  (509  ),  Same-
                DateTime (508  )


                Listing:  ./datutex/ex100.pp



                                                                                 454

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (518  ), YearOf (538  ), MonthOf (497  ), DayOf (457  ), HourOf (472  ), MinuteOf (493  ),
                SecondOf (510  ), MilliSecondOf (488  )


                Listing:  ./datutex/ex1.pp



                                                                                 455

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (465  )



                9.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  (488  ),  TryJulianDateToDateTime  (523  ),  DateTimeToModifiedJu-
                lianDate (457  ), TryModifiedJulianDateToDateTime (524  )



                9.4.7        DateTimeToMac

    Synopsis:    Convert a TDateTime timestamp to a Mac timestamp

Declaration:     function  DateTimeToMac(const  AValue:  TDateTime)  :  Int64

    Visibility:   default



                                                                                 456

                ______________________________________________________CHAPTER_9.___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 (525  ), MacToDateTime (488  ), MacTimeStampToUnix (488  )



                9.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  (456  ),  JulianDateToDateTime  (488  ),  TryJulianDateToDateTime
                (523  ), TryModifiedJulianDateToDateTime (524  )



                9.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 time elapsed since
                1/1/1970).

    See also:    UnixToDateTime (525  )



                9.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 (538  )

    See also:    YearOf  (538  ),  WeekOf  (525  ),  MonthOf  (497  ),  HourOf  (472  ),  MinuteOf  (493  ),  SecondOf
                (510  ), MilliSecondOf (488  )



                                                                                 457

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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 (526  ) function.

    See also:    DayOfTheYear  (458  ),  WeekOfTheMonth  (526  ),  HourOfTheMonth  (473  ),  MinuteOfThe-
                Month (494  ), SecondOfTheMonth (511  ), MilliSecondOfTheMonth (490  )



                9.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 (458  ),  DayOfTheMonth (458  ),  HourOfTheWeek (474  ),  MinuteOfTheWeek
                (494  ), SecondOfTheWeek (511  ), MilliSecondOfTheWeek (490  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.13         DayOfTheYear

    Synopsis:    Extracts the day of the year from a TDateTime value

Declaration:     function  DayOfTheYear(const  AValue:  TDateTime)  :  Word



                                                                                 458

                ______________________________________________________CHAPTER_9.___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 (526  ) function.

    See also:    WeekOfTheYear (526  ), HourOfTheYear (474  ), MinuteOfTheYear (494  ), SecondOfTheYear
                (512  ), MilliSecondOfTheYear (491  )



                9.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  (538  ),  MonthsBetween  (497  ),  WeeksBetween  (527  ),  HoursBetween  (474  ),
                MinutesBetween (495  ), SecondsBetween (512  ), MilliSecondsBetween (491  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 459

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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 (528  ),  WeeksInYear (528  ),  DaysInYear (461  ),  DaysInAYear (460  ),  DaysIn-
                Month (461  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (528  ), WeeksInYear (528  ), DaysInYear (461  ), DaysInMonth (461  ), DaysInA-
                Month (460  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 460

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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 (528  ), WeeksInYear (528  ), DaysInYear (461  ), DaysInAYear (460  ), DaysInA-
                Month (460  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (528  ), WeeksInYear (528  ), DaysInAYear (460  ), DaysInMonth (461  ), DaysI-
                nAMonth (460  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 461

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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 (539  ),  MonthSpan (498  ),  WeekSpan (529  ),  HourSpan (475  ),  MinuteSpan (496  ),
                SecondSpan (513  ), MilliSecondSpan (492  ), DaysBetween (459  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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



                                                                                 462

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



Description:     DecodeDateDay decomposes the date indication in AValue and returns the various compo-
                nents in AYear, ADayOfYear.

    See also:    EncodeDateTime  (466  ),  EncodeDateMonthWeek  (466  ),  EncodeDateWeek  (467  ),  Encode-
                DateDay  (466  ),  DecodeDateTime  (464  ),  DecodeDateWeek  (464  ),  DecodeDateMonthWeek
                (463  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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  (466  ),  EncodeDateMonthWeek  (466  ),  EncodeDateWeek  (467  ),  Encode-
                DateDay (466  ), DecodeDateTime (464  ), DecodeDateWeek (464  ), DecodeDateDay (462  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 463

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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  (466  ),  EncodeDateMonthWeek  (466  ),  EncodeDateWeek  (467  ),  Encode-
                DateDay  (466  ),  DecodeDateWeek  (464  ),  DecodeDateDay  (462  ),  DecodeDateMonthWeek
                (463  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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  (466  ),  EncodeDateMonthWeek  (466  ),  EncodeDateWeek  (467  ),  Encode-
                DateDay  (466  ),  DecodeDateTime  (464  ),  DecodeDateDay  (462  ),  DecodeDateMonthWeek
                (463  )


                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}



                                                                                 464

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (499  ), EncodeDateMonthWeek (466  ), #rtl.sysutils.DayOfWeek (1504   ), En-
                codeDayOfWeekInMonth (467  ), TryEncodeDayOfWeekInMonth (522  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.25         DosDateTimeToDateTime

    Synopsis:    Convert DOS date/time format to TDateTime format

Declaration:     function  DosDateTimeToDateTime(AValue:  LongInt)  :  TDateTime

    Visibility:   default



                                                                                 465

                ______________________________________________________CHAPTER_9.___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 (456  )
                function.

    See also:    DateTimeToDosDateTime (456  )



                9.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 (462  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    EncodeDateMonthWeek  (466  ),  DecodeDateDay  (462  ),  EncodeDateTime  (466  ),  Encode-
                DateWeek (467  ), TryEncodeDateTime (521  ), TryEncodeDateMonthWeek (520  ), TryEncode-
                DateWeek (522  )



                9.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 (463  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    DecodeDateMonthWeek  (463  ),  EncodeDateTime  (466  ),  EncodeDateWeek  (467  ),  Encode-
                DateDay  (466  ),  TryEncodeDateTime  (521  ),  TryEncodeDateWeek  (522  ),  TryEncodeDate-
                MonthWeek (520  ), TryEncodeDateDay (520  ), NthDayOfWeek (499  )



                9.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



                                                                                 466

                ______________________________________________________CHAPTER_9.___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 (464  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    DecodeDateTime  (464  ),  EncodeDateMonthWeek  (466  ),  EncodeDateWeek  (467  ),  Encode-
                DateDay (466  ), TryEncodeDateTime (521  ), TryEncodeDateWeek (522  ), TryEncodeDateDay
                (520  ), TryEncodeDateMonthWeek (520  )



                9.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 (464  ).

       Errors:   If any of the arguments is not valid, then an EConvertError exception is raised.

    See also:    EncodeDateMonthWeek  (466  ),  DecodeDateWeek  (464  ),  EncodeDateTime  (466  ),  Encode-
                DateDay  (466  ),  TryEncodeDateTime  (521  ),  TryEncodeDateWeek  (522  ),  TryEncodeDate-
                MonthWeek (520  )



                9.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 (465  ).

       Errors:   If any of the values is not in range, then an EConvertError exception will be raised.

    See also:    NthDayOfWeek (499  ), EncodeDateMonthWeek (466  ), #rtl.sysutils.DayOfWeek (1504   ), De-
                codeDayOfWeekInMonth (465  ), TryEncodeDayOfWeekInMonth (522  )



                                                                                 467

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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 (??  )



                9.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  (516  ),  StartOfADay  (514  ),  StartOfTheWeek  (517  ),  StartOfAWeek  (515  ),
                StartOfAMonth (515  ), StartOfTheMonth (517  ), EndOfTheWeek (471  ), EndOfAWeek (469  ),
                EndOfTheYear  (472  ),  EndOfAYear  (470  ),  EndOfTheMonth  (471  ),  EndOfAMonth  (469  ),
                EndOfTheDay (470  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 468

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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  (517  ),  StartOfAMonth  (515  ),  EndOfTheMonth  (471  ),  EndOfTheYear
                (472  ), EndOfAYear (470  ), StartOfAWeek (515  ), StartOfTheWeek (517  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (517  ), EndOfTheWeek (471  ), EndOfAWeek (469  ), StartOfAMonth (515  ),
                EndOfTheYear (472  ), EndOfAYear (470  ), EndOfTheMonth (471  ), EndOfAMonth (469  )


                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;



                                                                                 469

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (518  ),  EndOfTheYear (472  ),  EndOfAYear (470  ),  EndOfTheMonth (471  ),
                EndOfAMonth (469  ), StartOfAWeek (515  ), StartOfTheWeek (517  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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.



                                                                                 470

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    See also:    StartOftheDay  (516  ),  StartOfADay  (514  ),  StartOfTheWeek  (517  ),  StartOfAWeek  (515  ),
                StartOfAMonth (515  ), StartOfTheMonth (517  ), EndOfTheWeek (471  ), EndOfAWeek (469  ),
                EndOfTheYear  (472  ),  EndOfAYear  (470  ),  EndOfTheMonth  (471  ),  EndOfAMonth  (469  ),
                EndOfADay (468  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (469  ) function.

    See also:    StartOfAMonth (515  ), StartOfTheMonth (517  ), EndOfAMonth (469  ), EndOfTheYear (472  ),
                EndOfAYear (470  ), StartOfAWeek (515  ), StartOfTheWeek (517  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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



                                                                                 471

                ______________________________________________________CHAPTER_9.___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 (469  ) function.

    See also:    StartOfAWeek  (515  ),  StartOfTheWeek  (517  ),  EndOfAWeek  (469  ),  StartOfAMonth  (515  ),
                EndOfTheYear (472  ), EndOfAYear (470  ), EndOfTheMonth (471  ), EndOfAMonth (469  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (470  ) function.

    See also:    StartOfAYear (516  ), StartOfTheYear (518  ), EndOfTheMonth (471  ), EndOfAMonth (469  ),
                StartOfAWeek (515  ), StartOfTheWeek (517  ), EndOfAYear (470  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.40         HourOf

    Synopsis:    Extract the hour part from a DateTime value.



                                                                                 472

                ______________________________________________________CHAPTER_9.___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 (538  )

    See also:    YearOf (538  ), WeekOf (525  ), MonthOf (497  ), DayOf (457  ), MinuteOf (493  ), SecondOf (510  ),
                MilliSecondOf (488  )



                9.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 (474  ), HourOfTheMonth (473  ), HourOfTheWeek (474  ), MinuteOfTheDay
                (493  ), SecondOfTheDay (510  ), MilliSecondOfTheDay (489  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (526  ) function.



                                                                                 473

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    See also:    WeekOfTheMonth (526  ), DayOfTheMonth (458  ), MinuteOfTheMonth (494  ), SecondOfThe-
                Month (511  ), MilliSecondOfTheMonth (490  )



                9.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 (458  ) function.

    See also:    HourOfTheYear (474  ), HourOfTheMonth (473  ), HourOfTheDay (473  ), DayOfTheWeek (458  ),
                MinuteOfTheWeek (494  ), SecondOfTheWeek (511  ), MilliSecondOfTheWeek (490  )



                9.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 (526  ) function.

    See also:    WeekOfTheYear  (526  ),  DayOfTheYear  (458  ),  MinuteOfTheYear  (494  ),  SecondOfTheYear
                (512  ), MilliSecondOfTheYear (491  )



                9.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 (538  ), MonthsBetween (497  ), WeeksBetween (527  ), DaysBetween (459  ), Min-
                utesBetween (495  ), SecondsBetween (512  ), MilliSecondsBetween (491  )


                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;



                                                                                 474

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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  (539  ),  MonthSpan  (498  ),  WeekSpan  (529  ),  DaySpan  (462  ),  MinuteSpan  (496  ),
                SecondSpan (513  ), MilliSecondSpan (492  ), HoursBetween (474  )


                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   ;



                                                                                 475

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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  (479  ),  #rtl.sysutils.IncMonth  (1554   ),  IncWeek  (479  ),  IncHour  (476  ),  IncMinute
                (477  ), IncSecond (478  ), IncMilliSecond (477  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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



                                                                                 476

                ______________________________________________________CHAPTER_9.___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  (479  ),  #rtl.sysutils.IncMonth  (1554   ),  IncWeek  (479  ),  IncDay  (476  ),  IncMinute
                (477  ), IncSecond (478  ), IncMilliSecond (477  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (479  ), #rtl.sysutils.IncMonth (1554   ), IncWeek (479  ), IncDay (476  ), IncHour (476  ),
                IncSecond (478  ), IncMilliSecond (477  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.50         IncMinute

    Synopsis:    Increase a DateTime value with a number of minutes.



                                                                                 477

                ______________________________________________________CHAPTER_9.___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 (479  ), #rtl.sysutils.IncMonth (1554   ), IncWeek (479  ), IncDay (476  ), IncHour (476  ),
                IncSecond (478  ), IncMilliSecond (477  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (479  ), #rtl.sysutils.IncMonth (1554   ), IncWeek (479  ), IncDay (476  ), IncHour (476  ),
                IncSecond (478  ), IncMilliSecond (477  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 478

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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  (479  ),  #rtl.sysutils.IncMonth  (1554   ),  IncDay  (476  ),  IncHour  (476  ),  IncMinute
                (477  ), IncSecond (478  ), IncMilliSecond (477  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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  (1554   ),  IncWeek  (479  ),  IncDay  (476  ),  IncHour  (476  ),  IncMinute
                (477  ), IncSecond (478  ), IncMilliSecond (477  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 479

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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  (1606   )  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 (481  ), InvalidDateTimeError (480  ), InvalidDateMonthWeekError (480  ),
                InvalidDayOfWeekInMonthError (481  )



                9.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  (1606   )  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 (481  ), InvalidDateTimeError (480  ), InvalidDateDayError (480  ), In-
                validDayOfWeekInMonthError (481  )



                9.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  (1606   )  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.



                                                                                 480

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    See also:    InvalidDateWeekError (481  ), InvalidDateDayError (480  ), InvalidDateMonthWeekError (480  ),
                InvalidDayOfWeekInMonthError (481  )



                9.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  (1606   )  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 (480  ), InvalidDateDayError (480  ), InvalidDateMonthWeekError (480  ),
                InvalidDayOfWeekInMonthError (481  )



                9.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  (1606   )  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 (481  ), InvalidDateTimeError (480  ), InvalidDateDayError (480  ), In-
                validDateMonthWeekError (480  )



                9.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 (538  ), IsPM (482  ), IsToday (483  ), IsSameDay (482  )


                Listing:  ./datutex/ex3.pp



                                                                                 481

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (538  ), IsInLeapYear (481  ), IsToday (483  ), IsSameDay (482  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (519  ), Yesterday (540  ), Tomorrow (519  ), IsToday (483  )


                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;



                                                                                 482

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (482  ), IsToday (483  ), SameDate (507  )



                9.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 (519  ), Yesterday (540  ), Tomorrow (519  ), IsSameDay (482  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 483

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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 (487  ), IsValidDateTime (486  ), IsValidDateDay (484  ), IsValidDateWeek (487  ),
                IsValidDateMonthWeek (485  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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 (484  ), IsValidTime (487  ), IsValidDateTime (486  ), IsValidDateWeek (487  ), Is-
                ValidDateMonthWeek (485  )


                Listing:  ./datutex/ex9.pp



                                                                                 484

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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  (484  ),  IsValidTime  (487  ),  IsValidDateTime  (486  ),  IsValidDateDay  (484  ),  Is-
                ValidDateWeek (487  )


                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



                                                                                 485

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.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  (484  ),  IsValidTime  (487  ),  IsValidDateDay  (484  ),  IsValidDateWeek  (487  ),  Is-
                ValidDateMonthWeek (485  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 486

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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  (484  ),  IsValidTime  (487  ),  IsValidDateTime  (486  ),  IsValidDateDay  (484  ),  Is-
                ValidDateMonthWeek (485  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.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.



                                                                                 487

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.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  (456  ),  TryJulianDateToDateTime  (523  ),  DateTimeToModifiedJu-
                lianDate (457  ), TryModifiedJulianDateToDateTime (524  )



                9.4.71         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 (525  ), DateTimeToMac (456  ), MacToDateTime (488  )



                9.4.72         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 (525  ), DateTimeToMac (456  ), MacTimeStampToUnix (488  )



                9.4.73         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 (538  )

    See also:    YearOf (538  ), WeekOf (525  ), MonthOf (497  ), DayOf (457  ), HourOf (472  ), MinuteOf (493  ),
                MilliSecondOf (488  )



                                                                                 488

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.74         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 (473  ) function.

    See also:    MilliSecondOfTheYear (491  ), MilliSecondOfTheMonth (490  ), MilliSecondOfTheWeek (490  ),
                MilliSecondOfTheHour (489  ), MilliSecondOfTheMinute (489  ), MilliSecondOfTheSecond (490  ),
                HourOfTheDay (473  ), MinuteOfTheDay (493  ), SecondOfTheDay (510  )



                9.4.75         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 (493  ) function.

    See also:    MilliSecondOfTheYear (491  ), MilliSecondOfTheMonth (490  ), MilliSecondOfTheWeek (490  ),
                MilliSecondOfTheDay (489  ), MilliSecondOfTheMinute (489  ), MilliSecondOfTheSecond (490  ),
                MinuteOfTheHour (493  ), SecondOfTheHour (510  )



                9.4.76         MilliSecondOfTheMinute

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the minute

Declaration:     function  MilliSecondOfTheMinute(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

Description:     MilliSecondOfTheMinute  returns  the  number  of  milliseconds  that  have  passed  since  the
                start of the Minute (HH:MM:00.000) till the moment indicated by AValue.  This is a zero-
                based number, i.e.  HH:MM:00.000 will return 0.

                For an example, see the SecondOfTheMinute (511  ) function.

    See also:    MilliSecondOfTheYear (491  ), MilliSecondOfTheMonth (490  ), MilliSecondOfTheWeek (490  ),
                MilliSecondOfTheDay (489  ), MilliSecondOfTheHour (489  ), MilliSecondOfTheMinute (489  ),
                MilliSecondOfTheSecond (490  ), SecondOfTheMinute (511  )



                                                                                 489

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.77         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 (526  ) function.

    See also:    WeekOfTheMonth (526  ),  DayOfTheMonth (458  ),  HourOfTheMonth (473  ),  MinuteOfThe-
                Month (494  ), SecondOfTheMonth (511  ), MilliSecondOfTheMonth (490  )



                9.4.78         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 (491  ), MilliSecondOfTheMonth (490  ), MilliSecondOfTheWeek (490  ),
                MilliSecondOfTheDay (489  ), MilliSecondOfTheHour (489  ), MilliSecondOfTheMinute (489  ),
                SecondOfTheMinute (511  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.79         MilliSecondOfTheWeek

    Synopsis:    Calculate the number of milliseconds elapsed since the start of the week

Declaration:     function  MilliSecondOfTheWeek(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default



                                                                                 490

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



Description:     MilliSecondOfTheWeek returns the number of milliseconds that have passed since the start
                of the Week (00:00:00.000) till the moment indicated by AValue.  This is a zero-based number,
                i.e.  00:00:00.000 on the first of the Week will return 0.

                For an example, see the DayOfTheWeek (458  ) function.

    See also:    MilliSecondOfTheYear (491  ), MilliSecondOfTheMonth (490  ), MilliSecondOfTheDay (489  ),
                MilliSecondOfTheHour (489  ), MilliSecondOfTheMinute (489  ), MilliSecondOfTheSecond (490  ),
                DayOfTheWeek (458  ), HourOfTheWeek (474  ), MinuteOfTheWeek (494  ), SecondOfTheWeek
                (511  )



                9.4.80         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 (526  ) function.

    See also:    WeekOfTheYear  (526  ),  DayOfTheYear  (458  ),  HourOfTheYear  (474  ),  MinuteOfTheYear
                (494  ), SecondOfTheYear (512  ), MilliSecondOfTheYear (491  )



                9.4.81         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 (538  ), MonthsBetween (497  ), WeeksBetween (527  ), DaysBetween (459  ), Hours-
                Between (474  ), MinutesBetween (495  ), SecondsBetween (512  )


                Listing:  ./datutex/ex62.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e M i l l i S e c o n d s B e t w e efnu n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  m i l l i s e c o n d sb e t w e e n ') ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', M i l l i S e c o n d s B e t w e(eAnNow  ,AThen    ) ) ;
                end   ;



                                                                                 491

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 - ( 0 . 9 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 1 . 0 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 1 . 1 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.82         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 (539  ), MonthSpan (498  ), WeekSpan (529  ), DaySpan (462  ), HourSpan (475  ), Min-
                uteSpan (496  ), SecondSpan (513  ), MilliSecondsBetween (491  )


                Listing:  ./datutex/ex70.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e M i l l i S e c o n d S p a nf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  m i l l i s e c o n d sb e t w e e n ') ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', M i l l i S e c o n d S p a(nANow  ,AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 - ( 0 . 9 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 1 . 0 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 1 . 1 *O n e M i l l i S e c o n)d;



                                                                                 492

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.83         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 (538  )

    See also:    YearOf (538  ), WeekOf (525  ), MonthOf (497  ), DayOf (457  ), HourOf (472  ), SecondOf (510  ),
                MilliSecondOf (488  )



                9.4.84         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 (473  ) function.

    See also:    MinuteOfTheYear (494  ), MinuteOfTheMonth (494  ), MinuteOfTheWeek (494  ), MinuteOfThe-
                Hour (493  ), HourOfTheDay (473  ), SecondOfTheDay (510  ), MilliSecondOfTheDay (489  )



                9.4.85         MinuteOfTheHour

    Synopsis:    Calculate the number of minutes elapsed since the start of the hour

Declaration:     function  MinuteOfTheHour(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     MinuteOfTheHour  returns  the  number  of  minutes  that  have  passed  since  the  start  of  the
                Hour  (HH:00:00)  till  the  moment  indicated  by  AValue.  This  is  a  zero-based  number,  i.e.
                HH:00:59 will return 0.

    See also:    MinuteOfTheYear (494  ), MinuteOfTheMonth (494  ), MinuteOfTheWeek (494  ), MinuteOfThe-
                Day (493  ), SecondOfTheHour (510  ), MilliSecondOfTheHour (489  )


                Listing:  ./datutex/ex44.pp



                                                                                 493

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e MinuteOfTheHour             f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    N   :  TDateTime       ;


                Begin
                    N := Now   ;
                    W r i t e l n(' M i n u t e o f  t h e  Hour              :  ' ,MinuteOfTheHour            (N ) ) ;
                    W r i t e l n(' S e c o n d o f  t h e  Hour              :  ' ,SecondOfTheHour            (N ) ) ;
                    W r i t e l n(' M i l l i S e c o n do f  t h e  Hour     :  ' ,
                                  M i l l i S e c o n d O f T h e H o(uNr) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.86         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 (526  ) function.

    See also:    WeekOfTheMonth (526  ),  DayOfTheMonth (458  ),  HourOfTheMonth (473  ),  MinuteOfThe-
                Month (494  ), SecondOfTheMonth (511  ), MilliSecondOfTheMonth (490  )



                9.4.87         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 (458  ) function.

    See also:    MinuteOfTheYear (494  ), MinuteOfTheMonth (494  ), MinuteOfTheDay (493  ), MinuteOfThe-
                Hour  (493  ),  DayOfTheWeek  (458  ),  HourOfTheWeek  (474  ),  SecondOfTheWeek  (511  ),  Mil-
                liSecondOfTheWeek (490  )



                9.4.88         MinuteOfTheYear

    Synopsis:    Calculate the number of minutes elapsed since the start of the year

Declaration:     function  MinuteOfTheYear(const  AValue:  TDateTime)  :  LongWord



                                                                                 494

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    Visibility:  default

Description:     MinuteOfTheYear returns the number of minutes that have passed since the start of the year
                (January 1, 00:00:00) till the moment indicated by AValue.  This is a zero-based number, i.e.
                January 1 00:00:59 will return 0.

                For an example, see the WeekOfTheYear (526  ) function.

    See also:    WeekOfTheYear  (526  ),  DayOfTheYear  (458  ),  HourOfTheYear  (474  ),  MinuteOfTheYear
                (494  ), SecondOfTheYear (512  ), MilliSecondOfTheYear (491  )



                9.4.89         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 (538  ), MonthsBetween (497  ), WeeksBetween (527  ), DaysBetween (459  ), Hours-
                Between (474  ), SecondsBetween (512  ), MilliSecondsBetween (491  )


                Listing:__./datutex/ex60.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 6 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e M i n u t e s B e t w e e nf u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  m i n u t e s b e t w e e n ' ) ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', M i n u t e s B e t w e e(nANow  ,AThen     ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(59*    OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(61*    OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(122*     OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(306*     OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 5 . 4 *OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *OneMinute       ) ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 495

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.90         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 (539  ), MonthSpan (498  ), WeekSpan (529  ), DaySpan (462  ), HourSpan (475  ), Sec-
                ondSpan (513  ), MilliSecondSpan (492  ), MinutesBetween (495  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.91         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.



                                                                                 496

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



       Errors:   Currently, trying to use this function will raise an exception.

    See also:    DateTimeToJulianDate  (456  ),  JulianDateToDateTime  (488  ),  TryJulianDateToDateTime
                (523  ), DateTimeToModifiedJulianDate (457  ), TryModifiedJulianDateToDateTime (524  )



                9.4.92         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 (538  )

    See also:    YearOf (538  ), DayOf (457  ), WeekOf (525  ), HourOf (472  ), MinuteOf (493  ), SecondOf (510  ),
                MilliSecondOf (488  )



                9.4.93         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
                (497  ),  and  is  provided  for  completeness  only,  corresponding  to  the  other  PartOfTheYear
                functions.

                For an example, see the WeekOfTheYear (526  ) function.

    See also:    MonthOf (497  ), WeekOfTheYear (526  ), DayOfTheYear (458  ), HourOfTheYear (474  ), Min-
                uteOfTheYear (494  ), SecondOfTheYear (512  ), MilliSecondOfTheYear (491  )



                9.4.94         MonthsBetween

    Synopsis:    Calculate the number of whole months between two DateTime values

Declaration:     function  MonthsBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                      :  Integer

    Visibility:   default

Description:     MonthsBetween returns the number of whole months between ANow and AThen.  This number
                is an approximation, based on an average number of days of 30.4375 per month (average over
                4 years).  This means the fractional part of a month is dropped.

    See also:    YearsBetween (538  ), WeeksBetween (527  ), DaysBetween (459  ), HoursBetween (474  ), Min-
                utesBetween (495  ), SecondsBetween (512  ), MilliSecondsBetween (491  )


                Listing:  ./datutex/ex56.pp



                                                                                 497

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e MonthsBetween            f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  months      b e t w e e n ' ) ;
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', MonthsBetween         ( ANow   , AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -364;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -365;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -366;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -390;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -368;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -1000;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.95         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  (539  ),  WeekSpan  (529  ),  DaySpan  (462  ),  HourSpan  (475  ),  MinuteSpan  (496  ),
                SecondSpan (513  ), MilliSecondSpan (492  ), MonthsBetween (497  )


                Listing:  ./datutex/ex64.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e MonthSpan         f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;



                                                                                 498

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  months      b e t w e e n ' ) ;
                  Write    ( DateToStr      ( AThen    ) , '  and    ' ,DateToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', MonthSpan      ( ANow   , AThen    ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Today    ;
                    D2 :=  Today    -364;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -365;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -366;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -390;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -368;
                    T e s t(D1  , D2  ) ;
                    D2 :=  Today    -1000;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.96         NthDayOfWeek

    Synopsis:    Calculate which occurrence of weekday in the month a given day represents

Declaration:     function  NthDayOfWeek(const  AValue:  TDateTime)  :  Word

    Visibility:   default

Description:     NthDayOfWeek returns the occurence of the weekday of  AValue in the month.  This is the
                N-th time that this weekday occurs in the month (e.g.  the third saturday of the month).

    See also:    EncodeDateMonthWeek (466  ), #rtl.sysutils.DayOfWeek (1504   ), DecodeDayOfWeekInMonth
                (465  ), EncodeDayOfWeekInMonth (467  ), TryEncodeDayOfWeekInMonth (522  )


                Listing:  ./datutex/ex104.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e NthDayOfWeek           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Begin
                    Write    ( 'Today      i s  t h e  ' ,NthDayOfWeek         ( Today    ) , '- t h  ' ) ;
                    W r i t e l n(formatdateTime          ( ' dddd   ' ,Today    ) , '  o f  t h e  month    . ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 499

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.97         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 (540  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.98         RecodeDate

    Synopsis:    Replace date part of a TDateTime value with another date.

Declaration:     function  RecodeDate(const  AValue:  TDateTime;const  AYear:  Word;
                                                const  AMonth:  Word;const  ADay:  Word)  :  TDateTime

    Visibility:   default

Description:     RecodeDate replaces the date part of the timestamp AValue with the date specified in AYear,
                AMonth, ADay.  All other parts (the time part) of the date/time stamp are left untouched.

       Errors:   If one of the AYear, AMonth, ADay values is not within a valid range then an EConvertError
                exception is raised.

    See also:    RecodeYear (506  ), RecodeMonth (504  ), RecodeDay (502  ), RecodeHour (502  ), RecodeMinute
                (504  ), RecodeSecond (505  ), RecodeDate (500  ), RecodeTime (506  ), RecodeDateTime (501  )


                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 ';



                                                                                 500

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,R e c o d e D a t e(Now  , 2 0 0 1 , 1 , 1 ) ) ;
                    W r i t e l n(' T h i s moment       on   t h e  f i r s t o f   t h e  m i l l e n i u m:   ', S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.99         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  (452  ),  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 (506  ), RecodeMonth (504  ), RecodeDay (502  ), RecodeHour (502  ), RecodeMinute
                (504  ), RecodeSecond (505  ), RecodeMilliSecond (503  ), RecodeDate (500  ), RecodeTime (506  ),
                TryRecodeDateTime (524  )


                Listing:  ./datutex/ex96.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e RecodeDateTime             f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;
                    D   :  TDateTime         ;


                Begin
                    D := Now   ;
                    D := RecodeDateTime           (D , 2 0 0 0 , 2 ,R e c o d e L e a v e F i e l d A s,I0s, 0 , 0 , 0 ) ;
                    S := FormatDateTime           (Fmt   ,D ) ;
                    W r i t e l n(' T h i s moment       i n  f e b r u a r i2 0 0 0  :   ' ,S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 501

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.100          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 (506  ), RecodeMonth (504  ), RecodeHour (502  ), RecodeMinute (504  ), RecodeSec-
                ond  (505  ),  RecodeMilliSecond  (503  ),  RecodeDate  (500  ),  RecodeTime  (506  ),  RecodeDate-
                Time (501  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.101          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 (506  ), RecodeMonth (504  ), RecodeDay (502  ), RecodeMinute (504  ), RecodeSec-
                ond  (505  ),  RecodeMilliSecond  (503  ),  RecodeDate  (500  ),  RecodeTime  (506  ),  RecodeDate-
                Time (501  )


                Listing:  ./datutex/ex90.pp



                                                                                 502

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e RecodeHour          f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,RecodeHour        (Now   , 0 ) ) ;
                    W r i t e l n(' Today    ,  i n  t h e  f i r s t  h o u r :   ' ,S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.102          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 (506  ), RecodeMonth (504  ), RecodeDay (502  ), RecodeHour (502  ), RecodeMinute
                (504  ), RecodeSecond (505  ), RecodeDate (500  ), RecodeTime (506  ), RecodeDateTime (501  )


                Listing:  ./datutex/ex93.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 3;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R e c o d e M i l l i S e c o n df u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,R e c o d e M i l l i S e c o n(dNow , 0 ) ) ;
                    W r i t e l n(' T h i s moment     ,   m i l l i s e c o n d ss t r i p p e d:   ',S  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 503

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.103          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 (506  ), RecodeMonth (504  ), RecodeDay (502  ), RecodeHour (502  ), RecodeSec-
                ond  (505  ),  RecodeMilliSecond  (503  ),  RecodeDate  (500  ),  RecodeTime  (506  ),  RecodeDate-
                Time (501  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.104          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 (506  ), RecodeDay (502  ), RecodeHour (502  ), RecodeMinute (504  ), RecodeSec-
                ond  (505  ),  RecodeMilliSecond  (503  ),  RecodeDate  (500  ),  RecodeTime  (506  ),  RecodeDate-
                Time (501  )


                Listing:  ./datutex/ex88.pp



                                                                                 504

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e RecodeMonth          f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,RecodeMonth         (Now   , 5 ) ) ;
                    W r i t e l n(' T h i s moment       i n  May    :   ', S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.105          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 (506  ), RecodeMonth (504  ), RecodeDay (502  ), RecodeHour (502  ), RecodeMinute
                (504  ),  RecodeMilliSecond  (503  ),  RecodeDate  (500  ),  RecodeTime  (506  ),  RecodeDateTime
                (501  )


                Listing:  ./datutex/ex92.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R e c o d e S e c o n df u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,R e c o d e S e c o n(dNow   , 0 ) ) ;
                    W r i t e l n(' T h i s moment     ,  s e c o n d s s t r i p p e d :   ' ,S ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 505

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.106          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 (506  ), RecodeMonth (504  ), RecodeDay (502  ), RecodeHour (502  ), RecodeMinute
                (504  ), RecodeSecond (505  ), RecodeMilliSecond (503  ), RecodeDate (500  ), RecodeDateTime
                (501  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.107          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 (504  ), RecodeDay (502  ), RecodeHour (502  ), RecodeMinute (504  ), RecodeSec-
                ond  (505  ),  RecodeMilliSecond  (503  ),  RecodeDate  (500  ),  RecodeTime  (506  ),  RecodeDate-
                Time (501  )



                                                                                 506

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                Listing:  ./datutex/ex87.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 7;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e R e c o d e Y e a r f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    S   :  A n s i S t r i n g;


                Begin
                    S := FormatDateTime           (Fmt   ,R e c o d e Y e a r(Now  , 1 9 9 9 ) ) ;
                    W r i t e l n(' T h i s moment       i n  1 9 9 9  :  ' ,S  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.108          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 (452  ) returns zero.

    See also:    CompareDateTime (453  ), CompareDate (452  ), CompareTime (454  ), SameDateTime (508  ),
                SameTime (509  )


                Listing:  ./datutex/ex102.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e SameDate        f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                 P r o c e d u r eT e s t(D1  , D2   :  TDateTime        ) ;


                 b e g i n
                    Write    (FormatDateTime           (Fmt   ,D1  ) , '  i s  t h e  same     d a t e  a s  ' ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,D2  ) ,'   :  ' ,SameDate      ( D1  ,D2  ) ) ;
                end   ;


                Var
                    D ,N   :  TDateTime       ;


                Begin
                    D := Today    ;



                                                                                 507

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                    N := Now   ;
                    T e s t(D  ,D ) ;
                    T e s t(N  ,N ) ;
                    T e s t(N +1 , N  ) ;
                    T e s t(N -1 , N  ) ;
                    T e s t(N + OneSecond       ,N  ) ;
                    T e s t(N - OneSecond       ,N  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.109          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 (453  ) returns zero.

    See also:    CompareDateTime (453  ), CompareDate (452  ), CompareTime (454  ), SameDate (507  ), Same-
                Time (509  )


                Listing:  ./datutex/ex101.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e SameDateTime           f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                 P r o c e d u r eT e s t(D1  , D2   :  TDateTime        ) ;


                 b e g i n
                    Write    (FormatDateTime           (Fmt   ,D1  ) , '  i s  t h e  same     d a t e t i m e a s  ' ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,D2  ) ,'   :  ' ,SameDateTime         ( D1  ,D2  ) ) ;
                end   ;


                Var
                    D ,N   :  TDateTime       ;


                Begin
                    D := Today    ;
                    N := Now   ;
                    T e s t(D  ,D ) ;
                    T e s t(N  ,N ) ;
                    T e s t(N +1 , N  ) ;
                    T e s t(N -1 , N  ) ;
                    T e s t(N + OneSecond       ,N  ) ;
                    T e s t(N - OneSecond       ,N  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 508

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.110          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 (454  ) returns zero.

    See also:    CompareDateTime (453  ), CompareDate (452  ), CompareTime (454  ), SameDateTime (508  ),
                SameDate (507  )


                Listing:  ./datutex/ex103.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e SameTime        f u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    'dddd     dd  mmmm      y y y y hh  : nn : s s .z z z ';


                 P r o c e d u r eT e s t(D1  , D2   :  TDateTime        ) ;


                 b e g i n
                    Write    (FormatDateTime           (Fmt   ,D1  ) , '  i s  t h e  same     t i m e  a s  ' ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,D2  ) ,'   :  ' ,SameTime      ( D1  ,D2  ) ) ;
                end   ;


                Var
                    D ,N   :  TDateTime       ;


                Begin
                    D := Today    ;
                    N := Now   ;
                    T e s t(D  ,D ) ;
                    T e s t(N  ,N ) ;
                    T e s t(N +1 , N  ) ;
                    T e s t(N -1 , N  ) ;
                    T e s t(N + OneSecond       ,N  ) ;
                    T e s t(N - OneSecond       ,N  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.111          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



                                                                                 509

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



Description:     ScanDateTime scans string S for the date/time pattern Pattern, starting at position StartPos
                (default 1).  Optionally, the format settings fmt can be specified.

                In effect, this function does the opposite of what FormatDateTime (1544   ) 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 (1606   ) exception is raised.

    See also:    FormatDateTime (1544   )



                9.4.112          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 (538  )

    See also:    YearOf (538  ), WeekOf (525  ), MonthOf (497  ), DayOf (457  ), HourOf (472  ), MinuteOf (493  ),
                MilliSecondOf (488  )



                9.4.113          SecondOfTheDay

    Synopsis:    Calculate the number of seconds elapsed since the start of the day

Declaration:     function  SecondOfTheDay(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default

Description:     SecondOfTheDay  returns  the  number  of  seconds  that  have  passed  since  the  start  of  the
                Day  (00:00:00)  till  the  moment  indicated  by  AValue.   This  is  a  zero-based  number,  i.e.
                00:00:00.999 return 0.

                For an example, see the HourOfTheDay (473  ) function.

    See also:    SecondOfTheYear (512  ), SecondOfTheMonth (511  ), SecondOfTheWeek (511  ), SecondOfThe-
                Hour (510  ), SecondOfTheMinute (511  ), HourOfTheDay (473  ), MinuteOfTheDay (493  ), Mil-
                liSecondOfTheDay (489  )



                9.4.114          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 (493  ) function.

    See also:    SecondOfTheYear (512  ), SecondOfTheMonth (511  ), SecondOfTheWeek (511  ), SecondOfThe-
                Day (510  ), SecondOfTheMinute (511  ), MinuteOfTheHour (493  ), MilliSecondOfTheHour (489  )



                                                                                 510

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.115          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 (512  ), SecondOfTheMonth (511  ), SecondOfTheWeek (511  ), SecondOfThe-
                Day (510  ), SecondOfTheHour (510  ), MilliSecondOfTheMinute (489  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.116          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 (526  ) function.

    See also:    WeekOfTheMonth (526  ),  DayOfTheMonth (458  ),  HourOfTheMonth (473  ),  MinuteOfThe-
                Month (494  ), MilliSecondOfTheMonth (490  )



                9.4.117          SecondOfTheWeek

    Synopsis:    Calculate the number of seconds elapsed since the start of the week

Declaration:     function  SecondOfTheWeek(const  AValue:  TDateTime)  :  LongWord

    Visibility:   default



                                                                                 511

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



Description:     SecondOfTheWeek  returns  the  number  of  seconds  that  have  passed  since  the  start  of  the
                week  (00:00:00)  till  the  moment  indicated  by  AValue.   This  is  a  zero-based  number,  i.e.
                00:00:00.999 on the first day of the week will return 0.

                For an example, see the DayOfTheWeek (458  ) function.

    See also:    SecondOfTheYear (512  ), SecondOfTheMonth (511  ), SecondOfTheDay (510  ), SecondOfThe-
                Hour (510  ), SecondOfTheMinute (511  ), DayOfTheWeek (458  ), HourOfTheWeek (474  ), Min-
                uteOfTheWeek (494  ), MilliSecondOfTheWeek (490  )



                9.4.118          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 (526  ) function.

    See also:    WeekOfTheYear  (526  ),  DayOfTheYear  (458  ),  HourOfTheYear  (474  ),  MinuteOfTheYear
                (494  ), SecondOfTheYear (512  ), MilliSecondOfTheYear (491  )



                9.4.119          SecondsBetween

    Synopsis:    Calculate the number of whole seconds between two DateTime values.

Declaration:     function  SecondsBetween(const  ANow:  TDateTime;const  AThen:  TDateTime)
                                                        :  Int64

    Visibility:   default

Description:     SecondsBetween returns the number of whole seconds between ANow and AThen.  This means
                the fractional part of a second (milliseconds etc.)  is dropped.

    See also:    YearsBetween (538  ), MonthsBetween (497  ), WeeksBetween (527  ), DaysBetween (459  ), Hours-
                Between (474  ), MinutesBetween (495  ), MilliSecondsBetween (491  )


                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



                                                                                 512

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(999*     O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(1001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(2001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(5001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 5 . 4 *OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.120          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 (539  ), MonthSpan (498  ), WeekSpan (529  ), DaySpan (462  ), HourSpan (475  ), Min-
                uteSpan (496  ), MilliSecondSpan (492  ), SecondsBetween (512  )


                Listing:  ./datutex/ex69.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 9;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S e c o n d S p a n f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                 P r o c e d u r eT e s t(ANow    ,AThen      :  TDateTime       ) ;


                 b e g i n
                  Write    ( 'Number       o f  s e c o n d s b e t w e e n ' ) ;
                  Write    ( TimeToStr      ( AThen    ) , '  and    ' ,TimeToStr       (ANow    ) ) ;
                  W r i t e l n( '  :   ', S e c o n d S p a(nANow   ,AThen     ) ) ;
                end   ;


                Var
                    D1  ,D2    :  TDateTime       ;


                Begin
                    D1 :=  Now  ;
                    D2 :=  D1 -(999*     O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(1001*      O n e M i l l i S e c o n)d;



                                                                                 513

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(2001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 -(5001*      O n e M i l l i S e c o n)d;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 5 . 4 *OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                    D2 :=  D1 - ( 2 . 5 *OneSecond       ) ;
                    T e s t(D1  , D2  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.121          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 (516  ), StartOfTheWeek (517  ), StartOfAWeek (515  ), StartOfAMonth (515  ),
                StartOfTheMonth (517  ), EndOfTheWeek (471  ), EndOfAWeek (469  ), EndOfTheYear (472  ),
                EndOfAYear  (470  ),  EndOfTheMonth  (471  ),  EndOfAMonth  (469  ),  EndOfTheDay  (470  ),
                EndOfADay (468  )


                Listing:  ./datutex/ex38.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t a r t O f A D a yf u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" S t a r t  o f  t h e  day    :  " dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    Y ,M , D   :  Word   ;


                Begin
                    Y := Y e a r O f(Today    ) ;
                   M  := MonthOf     ( Today    ) ;
                    D := DayOf    ( Today    ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f A D a(yY ,M ,D  ) ) ) ;
                    DecodeDateDay          (Today    , Y ,D ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f A D a(yY ,D ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                                                                                 514

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.122          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 (517  ), EndOfTheMonth (471  ), EndOfAMonth (469  ), EndOfTheYear (472  ),
                EndOfAYear (470  ), StartOfAWeek (515  ), StartOfTheWeek (517  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.123          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 (517  ), EndOfTheWeek (471  ), EndOfAWeek (469  ), StartOfAMonth (515  ),
                EndOfTheYear (472  ), EndOfAYear (470  ), EndOfTheMonth (471  ), EndOfAMonth (469  )


                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;



                                                                                 515

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                Const
                    Fmt   =    '" F i r s t day    o f   t h i s week     :  " dd   mmmm     y y y y  hh  :nn  : s s' ;
                    Fmt2    =    '" S e c o n d day    o f  t h i s  week     :  " dd  mmmm      y y y y hh  : nn : s s ';


                Var
                    Y ,W   :  Word    ;


                Begin
                    Y := Y e a r O f(Today    ) ;
                   W  := WeekOf     (Today    ) ;
                    W r i t e l n(FormatDateTime          ( Fmt   ,StartOfAWeek         (Y  ,W ) ) ) ;
                    W r i t e l n(FormatDateTime          ( Fmt2   , StartOfAWeek         (Y ,W  , 2 ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.124          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 (518  ),  EndOfTheYear (472  ),  EndOfAYear (470  ),  EndOfTheMonth (471  ),
                EndOfAMonth (469  ), StartOfAWeek (515  ), StartOfTheWeek (517  )


                Listing:  ./datutex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t a r t O f A Y e a rf u n c t i o n }


                Uses     S y s U t i l s,D a t e U t i l s;


                Const
                    Fmt   =    '" F i r s t day    o f   t h i s y e a r  :  " dd   mmmm     y y y y ';


                Begin
                    W r i t e l n(FormatDateTime          ( Fmt   ,S t a r t O f A Y e a(rY e a r O f(Today    ) ) ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.125          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.



                                                                                 516

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    See also:    StartOfADay  (514  ),  StartOfTheWeek  (517  ),  StartOfAWeek  (515  ),  StartOfAMonth  (515  ),
                StartOfTheMonth (517  ), EndOfTheWeek (471  ), EndOfAWeek (469  ), EndOfTheYear (472  ),
                EndOfAYear (470  ), EndOfTheMonth (471  ), EndOfAMonth (469  ), EndOftheDay (470  ), End-
                OfADay (468  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.126          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  (515  )
                function.

    See also:    StartOfAMonth  (515  ),  EndOfTheYear  (472  ),  EndOfAYear  (470  ),  EndOfTheMonth  (471  ),
                EndOfAMonth (469  ), StartOfAWeek (515  ), StartOfTheWeek (517  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.127          StartOfTheWeek

    Synopsis:    Return the first day of the week, given a date.

Declaration:     function  StartOfTheWeek(const  AValue:  TDateTime)  :  TDateTime



                                                                                 517

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    Visibility:  default

Description:     StartOfTheWeek extracts the year and week parts of AValue and returns a TDateTime value
                with the date of the first day of that week as the StartOfAWeek (515  ) function.

    See also:    StartOfAWeek  (515  ),  EndOfTheWeek  (471  ),  EndOfAWeek  (469  ),  StartOfAMonth  (515  ),
                EndOfTheYear (472  ), EndOfAYear (470  ), EndOfTheMonth (471  ), EndOfAMonth (469  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.128          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 (516  ) function.

    See also:    StartOfAYear (516  ), EndOfTheYear (472  ), EndOfAYear (470  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.129          TimeOf

    Synopsis:    Extract the time part from a DateTime indication.

Declaration:     function  TimeOf(const  AValue:  TDateTime)  :  TDateTime



                                                                                 518

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    Visibility:  default

Description:     TimeOf extracts the time part from AValue and returns the result.

                Since the TDateTime is actually a double with the time part encoded in the fractional part,
                this operation corresponds to a call to Frac.

    See also:    DateOf (455  ), YearOf (538  ), MonthOf (497  ), DayOf (457  ), HourOf (472  ), MinuteOf (493  ),
                SecondOf (510  ), MilliSecondOf (488  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.130          Today

    Synopsis:    Return the current date

Declaration:     function  Today  :  TDateTime

    Visibility:   default

Description:     Today is an alias for the Date (1500   ) function in the sysutils (1450   ) unit.

                For an example, see Yesterday (540  )

    See also:    Date (1500   ), Yesterday (540  ), Tomorrow (519  )



                9.4.131          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 (519  ) +1.

    See also:    Today (519  ), Yesterday (540  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 519

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.132          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  (466  ),  EncodeDateTime  (466  ),  EncodeDateMonthWeek  (466  ),  Encode-
                DateWeek (467  ), TryEncodeDateTime (521  ), TryEncodeDateMonthWeek (520  ), TryEncode-
                DateWeek (522  )


                Listing:  ./datutex/ex84.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e TryEncodeDateDay              f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,DoY     :  Word   ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateDay          (Now   ,Y , DoY  ) ;
                    I f  TryEncodeDateDay            ( Y ,DoY   ,TS  )  then
                        W r i t e l n('Today      i s  :   ', DateToStr       (TS  ) )
                    e l s e
                        W r i t e l n('Wrong      y e a r/day    o f   y e a r  i n d i c a t i o'n) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.133          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  (463  ),  EncodeDateTime  (466  ),  EncodeDateWeek  (467  ),  Encode-
                DateDay (466  ), EncodeDateMonthWeek (466  ), TryEncodeDateTime (521  ), TryEncodeDate-
                Week (522  ), TryEncodeDateDay (520  ), NthDayOfWeek (499  )



                                                                                 520

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                Listing:  ./datutex/ex86.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e TryEncodeDateMonthWeek                   f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,M ,Wom   , Dow    :  Word    ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateMonthWeek              (Now   ,Y  ,M ,WoM   ,DoW   ) ;
                    I f  TryEncodeDateMonthWeek                 (Y ,M  ,WoM   ,Dow   ,TS  )  then
                        W r i t e l n('Today      i s  :   ', DateToStr       (TS  ) )
                    e l s e
                        W r i t e l n('I n v a l i d y e a r/ month   / week   / dow    i n d i c a t i o n') ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.134          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

    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  (466  ),  EncodeDateMonthWeek  (466  ),  EncodeDateWeek  (467  ),  Encode-
                DateDay (466  ), TryEncodeDateDay (520  ), TryEncodeDateWeek (522  ), TryEncodeDateMon-
                thWeek (520  )


                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



                                                                                 521

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                        W r i t e l n('Now    i s   :  ' ,DateTimeToStr          (TS  ) )
                    e l s e
                        W r i t e l n('Wrong      d a t e/t i m e  i n d i c a t i o n') ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.135          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  (466  ),  EncodeDateWeek  (467  ),  EncodeDateTime  (466  ),  Encode-
                DateDay (466  ), TryEncodeDateTime (521  ), TryEncodeDateMonthWeek (520  ), TryEncode-
                DateDay (520  )


                Listing:  ./datutex/ex82.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e TryEncodeDateWeek               f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,W , Dow    :  Word    ;
                    TS   :   TDateTime       ;


                Begin
                    DecodeDateWeek          ( Now   ,Y ,W  ,Dow   ) ;
                    I f  TryEncodeDateWeek             (Y  ,W ,TS  ,Dow   )  then
                        W r i t e l n('Today      i s  :   ', DateToStr       (TS  ) )
                    e l s e
                        W r i t e l n('I n v a l i d d a t e/ week     i n d i c a t i o'n) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.136          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



                                                                                 522

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    Visibility:  default

Description:     EncodeDayOfWeekInMonth  encodes  AYear,  AMonth,  ADayOfweek  and  ANthDayOfweek  to  a
                valid date stamp and returns the result in AValue.

                ANthDayOfweekis  the  N-th  time  that  this  weekday  occurs  in  the  month,  e.g.   the  third
                saturday of the month.

                The function returns True if the encoding was succesful, False if any of the values is not in
                range.

    See also:    NthDayOfWeek (499  ), EncodeDateMonthWeek (466  ), #rtl.sysutils.DayOfWeek (1504   ), De-
                codeDayOfWeekInMonth (465  ), EncodeDayOfWeekInMonth (467  )


                Listing:  ./datutex/ex106.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DecodeDayOfWeekInMonth                   f u n c t i o n}


                Uses     S y s U t i l s,D a t e U t i l s;


                Var
                    Y ,M ,NDoW    ,DoW     :  Word   ;
                    D   :  TDateTime       ;
                Begin
                    DecodeDayOfWeekInMonth                ( Date   ,Y  ,M ,NDoW    ,DoW   ) ;
                    I f  TryEncodeDayOfWeekInMonth                   (Y ,M  ,NDoW    ,DoW   ,D )  then
                        b e g i n
                       Write    ( DateToStr       (D ) , '  i s  t h e   ',NDow    , '- t h   ') ;
                        W r i t e l n(formatdateTime          ( 'dddd    ',D  ) ,'   o f  t h e  month    . ') ;
                       end
                    e l s e
                        W r i t e l n('I n v a l i d y e a r/ month   / NthDayOfweek           c o m b i n a t i o'n) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.137          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 (??  )



                9.4.138          TryJulianDateToDateTime

    Synopsis:    Convert a Julian date representation to a TDateTime value.

Declaration:     function  TryJulianDateToDateTime(const  AValue:  Double;
                                                                     out  ADateTime:  TDateTime)  :  Boolean



                                                                                 523

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    Visibility:  default

Description:     Try to convert a Julian date to a regular TDateTime date/time representation.

    See also:    DateTimeToJulianDate  (456  ),  JulianDateToDateTime  (488  ),  DateTimeToModifiedJulian-
                Date (457  ), TryModifiedJulianDateToDateTime (524  )



                9.4.139          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  (456  ),  JulianDateToDateTime  (488  ),  TryJulianDateToDateTime
                (523  ), DateTimeToModifiedJulianDate (457  ), ModifiedJulianDateToDateTime (496  )



                9.4.140          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  (452  ),  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 (506  ), RecodeMonth (504  ), RecodeDay (502  ), RecodeHour (502  ), RecodeMinute
                (504  ), RecodeSecond (505  ), RecodeMilliSecond (503  ), RecodeDate (500  ), RecodeTime (506  ),
                RecodeDateTime (501  )


                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



                                                                                 524

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                9.4.141          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 (456  ), MacToDateTime (488  ), MacTimeStampToUnix (488  )



                9.4.142          UnixToDateTime

    Synopsis:    Convert Unix epoch time to a TDateTime value

Declaration:     function  UnixToDateTime(const  AValue:  Int64)  :  TDateTime

    Visibility:   default

Description:     UnixToDateTime converts epoch time (time elapsed since 1/1/1970) to a TDateTime value.

    See also:    DateTimeToUnix (457  )



                9.4.143          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 (538  )

    See also:    YearOf (538  ), DayOf (457  ), MonthOf (497  ), HourOf (472  ), MinuteOf (493  ), SecondOf (510  ),
                MilliSecondOf (488  )



                                                                                 525

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                9.4.144          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  (526  ),  DayOfTheMonth  (458  ),  HourOfTheMonth  (473  ),  MinuteOfThe-
                Month (494  ), SecondOfTheMonth (511  ), MilliSecondOfTheMonth (490  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.145          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 (525  ).

 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.



                                                                                 526

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



    See also:    WeekOf (525  ), MonthOfTheYear (497  ), DayOfTheYear (458  ), HourOfTheYear (474  ), Min-
                uteOfTheYear (494  ), SecondOfTheYear (512  ), MilliSecondOfTheYear (491  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.146          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 (538  ), MonthsBetween (497  ), DaysBetween (459  ), HoursBetween (474  ), Min-
                utesBetween (495  ), SecondsBetween (512  ), MilliSecondsBetween (491  )


                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   ;



                                                                                 527

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.147          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 (528  ), DaysInYear (461  ), DaysInAYear (460  ), DaysInMonth (461  ), DaysInA-
                Month (460  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.148          WeeksInYear

    Synopsis:    return the number of weeks in the year, given a date

Declaration:     function  WeeksInYear(const  AValue:  TDateTime)  :  Word



                                                                                 528

                ______________________________________________________CHAPTER_9.___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  (528  ),  DaysInYear  (461  ),  DaysInAYear  (460  ),  DaysInMonth  (461  ),  DaysI-
                nAMonth (460  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.149          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  (539  ),  MonthSpan  (498  ),  DaySpan  (462  ),  HourSpan  (475  ),  MinuteSpan  (496  ),
                SecondSpan (513  ), MilliSecondSpan (492  ), WeeksBetween (527  )


                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



                                                                                 529

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.150          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 (459  ) 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 (537  ), WithinPastMonths (534  ), WithinPastWeeks (536  ), WithinPastHours
                (531  ), WithinPastMinutes (533  ), WithinPastSeconds (535  ), WithinPastMilliSeconds (532  )


                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  ;



                                                                                 530

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.151          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 (474  ) 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  (537  ),  WithinPastMonths  (534  ),  WithinPastWeeks  (536  ),  WithinPast-
                Days  (530  ),  WithinPastMinutes  (533  ),  WithinPastSeconds  (535  ),  WithinPastMilliSeconds
                (532  )


                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       ) ;



                                                                                 531

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.152          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 (491  ) 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  (537  ),  WithinPastMonths  (534  ),  WithinPastWeeks  (536  ),  WithinPast-
                Days (530  ), WithinPastHours (531  ), WithinPastMinutes (533  ), WithinPastSeconds (535  )


                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  ;



                                                                                 532

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.153          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  (495  )  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  (537  ),  WithinPastMonths  (534  ),  WithinPastWeeks  (536  ),  WithinPast-
                Days (530  ), WithinPastHours (531  ), WithinPastSeconds (535  ), WithinPastMilliSeconds (532  )


                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       ) ;



                                                                                 533

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.154          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  (497  )  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 (537  ), WithinPastWeeks (536  ), WithinPastDays (530  ), WithinPastHours
                (531  ), WithinPastMinutes (533  ), WithinPastSeconds (535  ), WithinPastMilliSeconds (532  )


                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;



                                                                                 534

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.155          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  (512  )  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  (537  ),  WithinPastMonths  (534  ),  WithinPastWeeks  (536  ),  WithinPast-
                Days (530  ), WithinPastHours (531  ), WithinPastMinutes (533  ), WithinPastMilliSeconds (532  )


                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 ) ;



                                                                                 535

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.156          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  (527  )  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 (537  ), WithinPastMonths (534  ), WithinPastDays (530  ), WithinPastHours
                (531  ), WithinPastMinutes (533  ), WithinPastSeconds (535  ), WithinPastMilliSeconds (532  )


                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 ) ;



                                                                                 536

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.157          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 (538  ) 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 (534  ), WithinPastWeeks (536  ), WithinPastDays (530  ), WithinPastHours
                (531  ), WithinPastMinutes (533  ), WithinPastSeconds (535  ), WithinPastMilliSeconds (532  )


                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 ) ;



                                                                                 537

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'DATEUTILS'__________________*
 *___________________



                    T e s t(D1  , D2  , 2 ) ;
                    T e s t(D1  , D2  , 3 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                9.4.158          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  (497  ),  DayOf  (457  ),  WeekOf  (525  ),  HourOf  (472  ),  MinuteOf  (493  ),  SecondOf
                (510  ), MilliSecondOf (488  )


                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___.____________________________________________________________________________________________________________*
 *___________



                9.4.159          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 (497  ), WeeksBetween (527  ), DaysBetween (459  ), HoursBetween (474  ), Min-
                utesBetween (495  ), SecondsBetween (512  ), MilliSecondsBetween (491  ), YearSpan (539  )



                                                                                 538

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.160          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  (498  ),  WeekSpan  (529  ),  DaySpan  (462  ),  HourSpan  (475  ),  MinuteSpan  (496  ),
                SecondSpan (513  ), MilliSecondSpan (492  ), YearsBetween (538  )


                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;



                                                                                 539

                ______________________________________________________CHAPTER_9.___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___.____________________________________________________________________________________________________________*
 *___________



                9.4.161          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 (519  ) -1.

    See also:    Today (519  ), Tomorrow (519  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 540




Chapter   10



Reference   for   unit   'Dos'



10.1          Used  units



                                      Table 10.1:  Used units by unit 'Dos'


                                                  __Name____________Page_____
                                                    baseunix          102
                                                    System          1230



10.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 (1450   ) unit instead.



10.3          System  information


Functions for retrieving and setting general system information such as date and time.



                                                             541

________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



                                                       Table 10.2:

                  __Name__________________________Description________________________________________________
                    DosVersion (102  )            Get OS version
                    GetCBreak (556  )             Get setting of control-break handling flag
                    GetDate (556  )               Get system date
                    GetIntVec (559  )             Get interrupt vector status
                    GetTime (561  )               Get system time
                    GetVerify (561  )             Get verify flag
                    Intr (562  )                  Execute an interrupt
                    Keep (562  )                  Keep process in memory and exit
                    MSDos (562  )                 Execute MS-dos function call
                    PackTime (562  )              Pack time for file time
                    SetCBreak (563  )             Set control-break handling flag
                    SetDate (564  )               Set system date
                    SetIntVec (565  )             Set interrupt vectors
                    SetTime (565  )               Set system time
                    SetVerify (565  )             Set verify flag
                    SwapVectors (566  )           Swap interrupt vectors
                    UnPackTime (566  )            Unpack file time



10.4          Process  handling


Functions to handle process information and starting new processes.



                                                       Table 10.3:

                  __Name__________________________Description_______________________________________________
                    DosExitCode (102  )           Exit code of last executed program
                    EnvCount (552  )              Return number of environment variables
                    EnvStr (552  )                Return environment string pair
                    Exec (552  )                  Execute program
                    GetEnv (557  )                Return specified environment string



10.5          Directory  and  disk  handling


Routines to handle disk information.



                                                       Table 10.4:

                        _Name____________________Description____________________________________________
                          AddDisk (548  )         Add disk to list of disks (UNIX only)
                          DiskFree (549  )        Return size of free disk space
                          DiskSize (549  )        Return total disk size



                                                                 542

________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



10.6          File  handling


Routines to handle files on disk.



                                                       Table 10.5:

         __Name_____________________________Description______________________________________________________________
           FExpand (553  )                  Expand filename to full path
           FindClose (553  )                Close finfirst/findnext session
           FindFirst (554  )                Start find of file
           FindNext (554  )                 Find next file
           FSearch (555  )                  Search for file in a path
           FSplit (555  )                   Split filename in parts
           GetFAttr (557  )                 Return file attributes
           GetFTime (558  )                 Return file time
           GetLongName (559  )              Convert short filename to long filename (DOS only)
           GetShortName (560  )             Convert long filename to short filename (DOS only)
           SetFAttr (564  )                 Set file attributes
           SetFTime (564  )                 Set file time



10.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 10.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



10.8          File  attributes


The File Attribute constants are used in FindFirst (554  ), FindNext (554  ) to determine what
type of special file to search for in addition to normal files.  These flags are also used in the
SetFAttr (564  ) and GetFAttr (557  ) routines to set and retrieve attributes of files.  For their
definitions consult fileattributes (543  ).



                                                                 543

________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



                                        Table 10.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



10.9          Constants,  types  and  variables



10.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


filerecnamelength  =  255


Maximum length of FileName part in FileRec (546  )


fmclosed  =  $D7B0


File is closed


fminout  =  $D7B3


File is read and write



                                                                 544

________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



fminput  =  $D7B1


File is read only


fmoutput  =  $D7B2


File is write only


foverflow  =  $0800


CPU overflow flag.  Not used.


fparity  =  $0004


CPU parity flag.  Not used.


fsign  =  $0080


CPU sign flag.  Not used.


fzero  =  $0040


CPU zero flag.  Not used.


hidden  =  $02


Hidden file attribute


readonly  =  $01


Read-Only file attribute


sysfile  =  $04


System file attribute


TextRecBufSize  =  256


Size of default buffer in TextRec (548  )


TextRecNameLength  =  256


Maximum length of filename in TextRec (548  )


volumeid  =  $08


Volumd ID file attribute



                                                                 545

________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



10.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



The DateTime type is used in PackTime (562  ) and UnPackTime (566  ) for setting/reading
file times with GetFTime (558  ) and SetFTime (564  ).


DirStr  =  string


Full directory string type.


ExtStr  =  string


Filename extension string type.


FileRec  =  packed  record
    Handle  :  THandle;
    Mode  :  LongInt;
    RecSize  :  SizeInt;
    _private  :  Array[1..3*SizeOf(SizeInt)+5*SizeOf(pointer)]  of  Byte;
    UserData  :  Array[1..32]  of  Byte;
    name  :  Array[0..filerecnamelength]  of  Char;
end



FileRec is used for internal representation of typed and untyped files.


NameStr  =  string


Fill filename string type.


PathStr  =  string


Full File path string type.


Registers  =  packed  record
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.



                                                                 546

________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________________________*
 *___



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  (554  )  call  and  can  be  used  in  subsequent  FindNext
(554  ) 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)


TextBuf  =  Array[0..TextRecBufSize-1]  of  Char


Type for default buffer in TextRec (548  )


TextRec  =  packed  record
   Handle  :  THandle;
   Mode  :  LongInt;
   bufsize  :  SizeInt;
   _private  :  SizeInt;
   bufpos  :  SizeInt;
   bufend  :  SizeInt;
   bufptr  :  ^TextBuf;
   openfunc  :  pointer;
   inoutfunc  :  pointer;
   flushfunc  :  pointer;
   closefunc  :  pointer;
   UserData  :  Array[1..32]  of  Byte;
   name  :  Array[0..textrecnamelength-1]  of  Char;
   LineEnd  :  TLineEndStr;
   buffer  :  TextBuf;
end



                                                                 547

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                TextRec describes the internal working of a Text file.

                Remark  that  this  is  not  binary  compatible  with  the  Turbo  Pascal  definition  of  TextRec,
                since the sizes of the different fields are different.


                TLineEndStr  =  string


                TLineEndStr is used in the TextRec (548  ) record to indicate the end-of-line sequence for a
                text file.



                10.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 10.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.



                10.10            Procedures  and  functions



                10.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 (549  ) and DiskSize (549  ) calls.  The DiskFree (549  ) and DiskSize (549  ) 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.



                                                                                 548

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                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 (549  ), DiskSize (549  )



                10.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 (548  ) 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 (549  ), AddDisk (548  )


                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___.____________________________________________________________________________________________________________*
 *___________



                10.10.3          DiskSize

    Synopsis:    Get total size of disk.

Declaration:     function  DiskSize(drive:  Byte)  :  Int64

    Visibility:   default



                                                                                 549

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



Description:     DiskSize returns the total size (in bytes) of a disk.  The parameter Drive indicates which
                disk should be checked.  This parameter is 1 for floppy a:, 2 for floppy b:, etc.  A value of 0
                returns the size of the current drive.

 Remark:         For  unix  only:  The  diskfree  and  disksize  functions  need  a  file  on  the  specified  drive,
                since this is required for the statfs system call.  These filenames are set in the initialization
                of the dos unit, and have been preset to :


                      o'.'  for the current drive,

                      o'/fd0/.'  for the first floppy-drive (linux only).

                      o'/fd1/.'  for the second floppy-drive (linux only).

                      o'/' for the first hard disk.


                There is room for 1-26 drives.  You can add a drive with the AddDisk (548  ) procedure.  These
                settings can be coded in dos.pp, in the initialization part.

                For an example, see DiskFree (549  ).

       Errors:   -1 when a failure occurs, or an invalid drive number is given.

    See also:    DiskFree (549  ), AddDisk (548  )



                10.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 (552  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 550

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                10.10.5          DosVersion

    Synopsis:    Current OS version

Declaration:     function  DosVersion  :  Word

    Visibility:   default

Description:     DosVersion  returns  the  operating  system  or  kernel  version.   The  low  byte  contains  the
                major version number, while the high byte contains the minor version number.

 Remark:         On systems where versions consists of more then two numbers, only the first two numbers
                will  be  returned.   For  example  Linux  version  2.1.76  will  give  you  DosVersion  2.1.   Some
                operating systems, such as FreeBSD, do not have system calls to return the kernel version,
                in that case a value of 0 will be returned.

       Errors:   None.


                Listing:  ./dosex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;
                 u s e s Dos   ;


                {   Program       t o  d e m o n s t r a t et h e  D o s V e r s i o nf u n c t i o n.  }


                 v a r
                    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___.____________________________________________________________________________________________________________*
 *___________



                10.10.6          DTToUnixDate

    Synopsis:    Convert a DateTime to unix timestamp

Declaration:     function  DTToUnixDate(DT:  DateTime)  :  LongInt

    Visibility:   default



                                                                                 551

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



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 (566  ), PackTime (562  ), UnpackTime (566  ), GetTime (561  ), SetTime (565  )



                10.10.7          EnvCount

    Synopsis:    Return the number of environment variables

Declaration:     function  EnvCount  :  LongInt

    Visibility:   default

Description:     EnvCount returns the number of environment variables.

       Errors:   None.

    See also:    EnvStr (552  ), GetEnv (557  )



                10.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 (552  ), GetEnv (557  )


                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___.____________________________________________________________________________________________________________*
 *___________



                10.10.9          Exec

    Synopsis:    Execute another program, and wait for it to finish.

Declaration:     procedure  Exec(const  path:  PathStr;const  comline:  ComStr)

    Visibility:   default



                                                                                 552

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



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 (102  )

       Errors:   Errors are reported in DosError.

    See also:    DosExitCode (102  )



                10.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 (555  )


                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___.____________________________________________________________________________________________________________*
 *___________



                10.10.11           FindClose

    Synopsis:    Dispose resources allocated by a FindFirst (554  )/FindNext (554  ) 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 (554  ) or FindNext
                (554  ) 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



                                                                                 553

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                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 (554  ), FindNext (554  )



                10.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 (553  ) 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 (554  ), FindClose (553  )


                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___.____________________________________________________________________________________________________________*
 *___________



                10.10.13           FindNext

    Synopsis:    Find next matching file after FindFirst (554  )

Declaration:     procedure  FindNext(var  f:  SearchRec)



                                                                                 554

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



    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 (554  ).

       Errors:   DosError is used to report errors.

    See also:    FindFirst (554  ), FindClose (553  )



                10.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 (553  )


                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___.____________________________________________________________________________________________________________*
 *___________



                10.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



                                                                                 555

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



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 (555  )


                Listing:  ./dosex/ex12.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 1 2;


                 u s e s Dos   ;


                {   Program       t o  d e m o n s t r a t et h e  F S p l i t f u n c t i o n.  }


                 v a r  d i r: d i r s t r;
                       name    :n a m e s t r;
                        e x t: e x t s t r;


                 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___.____________________________________________________________________________________________________________*
 *___________



                10.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 (563  )



                10.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.



                                                                                 556

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



       Errors:   None.

    See also:    GetTime (561  ), SetDate (564  )


                Listing:  ./dosex/ex2.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example2       ;
                 u s e s Dos   ;


                {   Program       t o  d e m o n s t r a t et h e  G e t D a t e f u n c t i o n. }


                 c o n s t
                    D a y S t r:a r r a y[ 0 . . 6 ] o f   s t r i n g[ 3 ] = ('Sun  ' ,'Mon   ' , 'Tue   ' ,'Wed   ' , 'Thu   ', '*
 * F r i' , 'S a t ') ;
                    MonthStr      : a r r a y[ 1 . . 1 2 ]o f   s t r i n g[ 3 ] = ('Jan  ' , 'Feb   ', 'Mar   ' ,' Apr  ' , 'May  *
 * ' ,' Jun  ' ,
                                                                                   ' J u l' , 'Aug   ', 'Sep   ' ,' Oct  ' , 'Nov  *
 * ' ,' Dec  ' ) ;
                 v a r
                    Year   , Month    ,Day   ,WDay     :  word    ;
                 b e g i n
                    G e t D a t e(Year   ,Month     ,Day   ,WDay   ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                10.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 (552  ), EnvStr (552  )


                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___.____________________________________________________________________________________________________________*
 *___________



                10.10.19           GetFAttr

    Synopsis:    Get file attributes

Declaration:     procedure  GetFAttr(var  f;var  attr:  Word)

    Visibility:   default



                                                                                 557

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



Description:     GetFAttr returns the file attributes of the file-variable f.  F can be a untyped or typed file,
                or of type Text.  f must have been assigned, but not opened.  The attributes can be examined
                with the following constants :


                      oReadOnly

                      oHidden

                      oSysFile

                      oVolumeId

                      oDirectory

                      oArchive


                Under linux, supported attributes are:


                      oDirectory

                      oReadOnly if the current process doesn't have access to the file.

                      oHidden for files whose name starts with a dot ('.').


       Errors:   Errors are reported in DosError

    See also:    SetFAttr (564  )


                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___.____________________________________________________________________________________________________________*
 *___________



                10.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



                                                                                 558

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



    See also:    SetFTime (564  ), PackTime (562  ), UnPackTime (566  )


                Listing:  ./dosex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;
                 u s e s Dos   ;


                {   Program       t o  d e m o n s t r a t et h e  GetFTime        f u n c t i o n. }


                 F u n c t i o nL0  (w : word   ) : s t r i n g;
                 v a r
                    s   :  s t r i n g;
                 b e g i n
                    S t r( w , s) ;
                    i f  w <10    then
                      L0 :=  '0  '+ s
                    e l s e
                      L0 :=  s ;
                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___.____________________________________________________________________________________________________________*
 *___________



                10.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 (565  )



                10.10.22           GetLongName

    Synopsis:    Get the long filename of a DOS 8.3 filename.



                                                                                 559

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



Declaration:     function  GetLongName(var  p:  string)  :  Boolean

    Visibility:  default

Description:     This function is only implemented in the GO32V2 and Win32 versions of Free Pascal.

                GetLongName changes the filename p to a long filename if the API call to do this is successful.
                The resulting string is the long file name corresponding to the short filename p.

                The function returns True if the API call was successful, False otherwise.

                This  function  should  only  be  necessary  when  using  the  DOS  extender  under  Windows  95
                and higher.

       Errors:   If the API call was not succesfull, False is returned.

    See also:    GetShortName (560  )



                10.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 (561  )



                10.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 (559  )



                                                                                 560

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                10.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 (556  ), SetTime (565  )


                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___.____________________________________________________________________________________________________________*
 *___________



                10.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 (565  )



                                                                                 561

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                10.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 (562  )



                10.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.



                10.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 (562  )



                10.10.30           PackTime

    Synopsis:    Pack DateTime value to a packed-time format.

Declaration:     procedure  PackTime(var  t:  DateTime;var  p:  LongInt)

    Visibility:   default



                                                                                 562

                ________________________________________________________________CHAPTER_10.___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 (564  ), FindFirst (554  ), FindNext (554  ), UnPackTime (566  )


                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___.____________________________________________________________________________________________________________*
 *___________



                10.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 (556  )



                                                                                 563

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                10.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 (556  ), SetTime (565  )



                10.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 (557  )



                10.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 (558  ), PackTime (562  ), UnPackTime (566  )



                                                                                 564

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                10.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 (559  )



                10.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 (561  ), SetDate (564  )



                10.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 (565  )



                                                                                 565

                ________________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'DOS'_____________*
 *___________________



                10.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 (552  ), SetIntVec (565  )



                10.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 (551  ), PackTime (562  ), UnpackTime (566  ), GetTime (561  ), SetTime (565  )



                10.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 (562  ).

       Errors:   None.

    See also:    GetFTime (558  ), FindFirst (554  ), FindNext (554  ), PackTime (562  )



                10.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 (562  ), UnpackTime (566  ), GetTime (561  ), SetTime (565  )



                                                                                 566




                Chapter   11



                Reference   for   unit   'dxeload'



                11.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.



                11.2          Procedures  and  functions



                11.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 (571  ) unit in the RTL.

       Errors:   If an error occurs during the load or relocations, Nil is returned.



                                                                             567




Chapter   12



Reference   for   unit   'dynlibs'



12.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.



12.2          Constants,  types  and  variables



12.2.1         Constants

NilHandle  =  (0)


Correctly typed Nil handle - returned on error by LoadLibrary (569  )


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.



12.2.2         Types

HModule  =  TLibHandle


Alias for TLibHandle (568  ) 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.



                                                             568

                _________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'DYNLIBS'________________*
 *___________________



                12.3          Procedures  and  functions



                12.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 (570  ), and is provided for
                compatibility with Delphi.

    See also:    UnloadLibrary (570  )



                12.3.2         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  (569  ),  and  is
                provided for compatibility with Delphi.

    See also:    GetProcedureAddress (569  )



                12.3.3         GetProcedureAddress

    Synopsis:    Get the address of a procedure or symbol in a dynamic library.

Declaration:     function  GetProcedureAddress(Lib:  TLibHandle;const  ProcName:  AnsiString)
                                                                :  Pointer

    Visibility:   default

Description:     GetProcedureAddress returns a pointer to the location in memory of the symbol ProcName
                in the dynamically loaded library specified by it's handle lib.  If the symbol cannot be found
                or the handle is invalid, Nil is returned.

                On Windows,  only an exported procedure or function can be searched this way.  On Unix
                platforms the location of any exported symbol can be retrieved this way.

       Errors:   If the symbol cannot be found, Nil is returned.

    See also:    LoadLibrary (569  ), UnLoadLibrary (570  )



                12.3.4         LoadLibrary

    Synopsis:    Load a dynamic library and return a handle to it.

Declaration:     function  LoadLibrary(const  Name:  AnsiString)  :  TLibHandle

    Visibility:   default



                                                                                 569

                _________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'DYNLIBS'________________*
 *___________________



Description:     LoadLibrary loads a dynamic library in file Name and returns a handle to it.  If the library
                cannot be loaded, NilHandle (568  ) 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 (568  ) is returned.

    See also:    UnloadLibrary (570  ), GetProcedureAddress (569  )



                12.3.5         SafeLoadLibrary

    Synopsis:    Saves the control word and loads a library

Declaration:     function  SafeLoadLibrary(const  Name:  AnsiString)  :  TLibHandle

    Visibility:   default

Description:     SafeLoadLibary  saves  the  FPU  control  word,  and  calls  LoadLibrary  (569  )  with  library
                name Name.  After that function has returned, the FPU control word is saved again.  (only
                on Intel i386 CPUS).

    See also:    LoadLibrary (569  )



                12.3.6         UnloadLibrary

    Synopsis:    Unload a previously loaded library

Declaration:     function  UnloadLibrary(Lib:  TLibHandle)  :  Boolean

    Visibility:   default

Description:     UnloadLibrary unloads a previously loaded library (specified by the handle lib).  The call
                returns True if succesful, False otherwisa.

       Errors:   On error, False is returned.

    See also:    LoadLibrary (569  ), GetProcedureAddress (569  )



                                                                                 570




                Chapter   13



                Reference   for   unit   'emu387'



                13.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.



                13.2          Procedures  and  functions



                13.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.



                                                                             571

         ___________________________________________________________CHAPTER_13.___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.



                                                                          572




Chapter   14



Reference   for   unit   'exeinfo'



14.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  (739  )  and  lnfodwrf  (759  )  unit  to  examine  the  binary  for
debug info.



14.2          Constants,  types  and  variables



14.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.



                                                             573

                ________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'EXEINFO'_________________*
 *___________________



                14.3          Procedures  and  functions



                14.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 (574  ),
                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 (574  )



                14.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 (574  ) (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 (574  )



                14.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.



                14.3.4         OpenExeFile

    Synopsis:    Open an executable file

Declaration:     function  OpenExeFile(var  e:  TExeFile;const  fn:  string)  :  Boolean

    Visibility:   default



                                                                                 574

                ________________________________________________________CHAPTER_14.___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 (574  ), CloseExeFile (574  ), ReadDebugLink (575  )



                14.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 (574  ), CloseExeFile (574  )



                                                                                 575




Chapter   15



Reference   for   unit   'getopts'



15.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.



15.2          Constants,  types  and  variables



15.2.1         Constants

EndOfOptions  =  #255


Returned by getopt (578  ),getlongopts (578  ) 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.



                                                             576

_______________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'GETOPTS'__________________________________*
 *___



15.2.2         Types

Orderings  =  (require_order,permute,return_in_order)



                            Table 15.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 (577  ) 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 (578  ).  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.



15.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.



                                                                 577

                _______________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'GETOPTS'__________________*
 *___________________



                15.3          Procedures  and  functions



                15.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 (578  ) 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 (578  ).

    See also:    Getopt (578  )



                15.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 (578  )



                                                                                 578

_______________________________________________________CHAPTER_15.___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 ;



                                                                 579

_______________________________________________________CHAPTER_15.___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___._______________________________________________________________________________________________________________________



                                                                 580




Chapter   16



Reference   for   unit   'go32'



16.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



16.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 (603  )

     o  %DS:%ESI = 48 bit pointer to to real mode SS:SP

     o  %ES:%EDI = 48 bit pointer of real mode register data structure.

     o  %SS:%ESP = locked protected mode stack

     o  All other registers undefined



                                                             581

            _______________________________________________________________CHAPTER_16.___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 (603  ), free_rm_callback (598  ), lock_code (611  ), lock_data (611  )



            16.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 (620  ) and
            it's linear address via transfer_buffer (621  ).  Another way is to allocate a completely new dos
            memory area via the global_dos_alloc (608  ) function for your use and supply its real mode
            address.


See also:    tb_size  (620  ),  transfer_buffer  (621  ),  global_dos_alloc  (608  ),  global_dos_free  (609  ),  realintr
            (614  )


            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,



                                                                             582

_______________________________________________________________CHAPTER_16.___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') ;



                                                                 583

            _______________________________________________________________CHAPTER_16.___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___.________________________________________________________________________________________________________________*
 *_______



            16.4          Software  interrupts


            Ordinarily, a handler installed with set_pm_interrupt (618  ) only services software interrupts
            that  are  executed  in  protected  mode;  real  mode  software  interrupts  can  be  redirected  by
            set_rm_interrupt (619  ).


See also:    set_rm_interrupt  (619  ),  get_rm_interrupt  (606  ),  set_pm_interrupt  (618  ),  get_pm_interrupt
            (602  ), lock_data (611  ), lock_code (611  ), enable (597  ), disable (596  ), outportb (612  )



            16.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  }



                                                                             584

_______________________________________________________________CHAPTER_16.___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;



                                                                 585

_______________________________________________________________CHAPTER_16.___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___._______________________________________________________________________________________________________________________



16.6          Disabling  interrupts


The GO32 unit provides the two procedures disable() and enable() to disable and enable all
interrupts.



16.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.



16.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.



                                                                 586

            _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________



            16.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.



            16.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.



            16.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 (599  ), get_ds (599  ), get_ss (608  )



            16.12            I/O  port  access


            The I/O port access is done via the various inportb (610  ), outportb (612  ) 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 (612  ), inportb (610  )



            16.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  (589  ),  dosmemput  (590  ),  dosmemmove  (589  ),  dosmemfillchar  (589  ),  dosmem-
            fillword (589  ), seg_move (616  ), seg_fillchar (615  ), seg_fillword (616  )



                                                                             587

            _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_________________*
 *_______________



            16.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  (599  ),  get_ds  (599  ),  get_ss  (608  ),  allocate_ldt_descriptors  (592  ),  free_ldt_descriptor
            (598  ), segment_to_descriptor (615  ), get_next_selector_increment_value (601  ), get_segment_base_address
            (607  ), set_segment_base_address (619  ), set_segment_limit (620  ), create_code_segment_alias_descriptor
            (595  )



            16.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.



            16.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.



            16.17            Constants,  types  and  variables



            16.17.1          Constants

            auxcarryflag  =  $010


            Check for auxiliary carry flag in trealregs (591  )


            carryflag  =  $001


            Check for carry flag in trealregs (591  )


            directionflag  =  $400


            Check for direction flag in trealregs (591  )



                                                                             588

_______________________________________________________________CHAPTER_16.___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 (608  ).


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.



                                                                 589

_______________________________________________________________CHAPTER_16.___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 (608  ).


interruptflag  =  $200


Check for interrupt flag in trealregs (591  )


overflowflag  =  $800


Check for overflow flag in trealregs (591  )


parityflag  =  $004


Check for parity flag in trealregs (591  )


rm_dpmi  =  4


get_run_mode (606  ) return value:  DPMI (e.g.  dos box or 386Max)


rm_raw  =  1


get_run_mode (606  ) return value:  raw (without HIMEM)


rm_unknown  =  0


get_run_mode (606  ) return value:  Unknown runmode


rm_vcpi  =  3


get_run_mode (606  ) return value:  VCPI (with HIMEM and EMM386)



                                                                 590

_______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



rm_xms  =  2


get_run_mode (606  ) return value:  XMS (with HIMEM, without EMM386)


signflag  =  $080


Check for sign flag in trealregs (591  )


trapflag  =  $100


Check for trap flag in trealregs (591  )


zeroflag  =  $040


Check for zero flag in trealregs (591  )



16.17.2          Types

registers  =  trealregs


Alias for trealregs (591  )


tmeminfo  =  record
    available_memory  :  LongInt;
    available_pages  :  LongInt;
    available_lockable_pages  :  LongInt;
    linear_space  :  LongInt;
    unlocked_pages  :  LongInt;
    available_physical_pages  :  LongInt;
    total_physical_pages  :  LongInt;
    free_linear_space  :  LongInt;
    max_pages_in_paging_file  :  LongInt;
    reserved0  :  LongInt;
    reserved1  :  LongInt;
    reserved2  :  LongInt;
end



tmeminfo Holds information about the memory allocation, etc.

NOTE:  The  value  of  a  field  is  -1  (0ffffffffh)  if  the  value  is  unknown,  it's  only  guaranteed,
that available_memory contains a valid value.  The size of the pages can be determined by
the get_page_size() function.


trealregs  =  record
end



The trealregs type contains the data structure to pass register values to a interrupt handler
or real mode callback.



                                                                 591

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                tseginfo  =  record
                   offset  :  pointer;
                   segment  :  Word;
                end



                This  record  is  used  to  store  a  full  48-bit  pointer.   This  may  be  either  a  protected  mode
                selector:offset address or in real mode a segment:offset address, depending on application.

                See also:  Selectors and descriptors, dos memory access, Interrupt redirection



                16.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.



                16.18            Procedures  and  functions



                16.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
                (601  ) function.

       Errors:   Check the int31error (592  ) variable.

    See also:    free_ldt_descriptor (598  ), get_next_selector_increment_value (601  ), segment_to_descriptor (615  ),
                create_code_segment_alias_descriptor (595  ), set_segment_limit (620  ), set_segment_base_address
                (619  )


                Listing:  ./go32ex/seldes.pp



                                                                                 592

_______________________________________________________________CHAPTER_16.___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 ,



                                                                 593

                _______________________________________________________________CHAPTER_16.___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___.____________________________________________________________________________________________________________*
 *___________



                16.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.



                                                                                 594

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



       Errors:   Check the int31error (592  ) variable.

    See also:    free_memory_block (598  )



                16.18.3          copyfromdos

    Synopsis:    Copy data from DOS to to heap

Declaration:     procedure  copyfromdos(var  addr;len:  LongInt)

    Visibility:   default

Description:     Copies data from the pre-allocated dos memory transfer buffer to the heap.

                Parameters:


                addr    data to copy to.

                len  number of bytes to copy to heap.


                Notes:  Can only be used in conjunction with the dos memory transfer buffer.

       Errors:   Check the int31error (592  ) variable.

    See also:    tb_size (620  ), transfer_buffer (621  ), copytodos (595  )



                16.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 (592  ) variable.

    See also:    tb_size (620  ), transfer_buffer (621  ), copyfromdos (595  )



                16.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.



                                                                                 595

                _______________________________________________________________CHAPTER_16.___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 (592  ) variable.

    See also:    allocate_ldt_descriptors (592  ), set_segment_limit (620  ), set_segment_base_address (619  )



                16.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 (597  )



                16.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 (597  ), dpmi_dosmemget (597  ), dpmi_dosmemmove (597  ), dpmi_dosmemfillword
                (596  )



                16.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 (597  ), dpmi_dosmemget (597  ), dpmi_dosmemfillchar (596  ), dpmi_dosmemmove
                (597  )



                                                                                 596

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                16.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 (597  ), dpmi_dosmemmove (597  ), dpmi_dosmemfillchar (596  ), dpmi_dosmemfillword
                (596  )



                16.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 (597  ), dpmi_dosmemget (597  ), dpmi_dosmemfillchar (596  ), dpmi_dosmemfillword
                (596  )



                16.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 (597  ), dpmi_dosmemmove (597  ), dpmi_dosmemfillchar (596  ), dpmi_dosmemfillword
                (596  )



                16.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 (596  )



                                                                                 597

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                16.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 (592  ) 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 (592  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    allocate_ldt_descriptors (592  ), get_next_selector_increment_value (601  )



                16.18.14           free__memory__block

    Synopsis:    Free allocated memory block

Declaration:     function  free_memory_block(blockhandle:  LongInt)  :  Boolean

    Visibility:   default

Description:     Frees a previously allocated memory block.

                Parameters:


                blockhandle        the handle to the memory area to free.


                Return value:  True if successful, false otherwise.  Notes:  Frees memory that was previously
                allocated  with  allocate_memory_block  (594  )  .   This  function  doesn't  free  any  descriptors
                mapped to this block, it's the application's responsibility.

       Errors:   Check int31error (592  ) variable.

    See also:    allocate_memory_block (594  )



                16.18.15           free__rm__callback

    Synopsis:    Release real mode callback.

Declaration:     function  free_rm_callback(var  intaddr:  tseginfo)  :  Boolean

    Visibility:   default

Description:     Releases a real mode callback address that was previously allocated with the get_rm_callback
                (603  ) function.

                Parameters:


                intaddr     real mode address buffer returned by get_rm_callback (603  ) .



                                                                                 598

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                Return values:  True if successful, False if not

                For an example, see get_rm_callback (603  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    set_rm_interrupt (619  ), get_rm_callback (603  )



                16.18.16           get__cs

    Synopsis:    Get CS selector

Declaration:     function  get_cs  :  Word

    Visibility:   default

Description:     Returns the cs selector.

                Return value:  The content of the cs segment register.

                For an example, see set_pm_interrupt (618  ).

       Errors:   None.

    See also:    get_ds (599  ), get_ss (608  )



                16.18.17           get__descriptor__access__right

    Synopsis:    Get descriptor's access rights

Declaration:     function  get_descriptor_access_right(d:  Word)  :  LongInt

    Visibility:   default

Description:     Gets the access rights of a descriptor.

                Parameters:


                d selector to descriptor.


                Return value:  Access rights bit field.

       Errors:   Check the int31error (592  ) variable.

    See also:    set_descriptor_access_right (617  )



                16.18.18           get__ds

    Synopsis:    Get DS Selector

Declaration:     function  get_ds  :  Word

    Visibility:   default

Description:     Returns the ds selector.

                Return values:  The content of the ds segment register.

       Errors:   None.

    See also:    get_cs (599  ), get_ss (608  )



                                                                                 599

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                16.18.19           get__exception__handler

    Synopsis:    Return current exception handler

Declaration:     function  get_exception_handler(e:  Byte;var  intaddr:  tseginfo)  :  Boolean

    Visibility:   default

Description:     get_exception_handler returns the exception handler for exception E in intaddr.  It re-
                turns True if the call was successful, False if not.

    See also:    set_exception_handler (617  ), get_pm_exception_handler (602  )



                16.18.20           get__linear__addr

    Synopsis:    Convert physical to linear address

Declaration:     function  get_linear_addr(phys_addr:  LongInt;size:  LongInt)  :  LongInt

    Visibility:   default

Description:     Converts a physical address into a linear address.

                Parameters:


                phys__addr      physical address of device.

                size  Size of region to map in bytes.


                Return value:  Linear address that can be used to access the physical memory.  Notes:  It's
                the applications resposibility to allocate and set up a descriptor for access to the memory.
                This function shouldn't be used to map real mode addresses.

       Errors:   Check the int31error (592  ) variable.

    See also:    allocate_ldt_descriptors (592  ), set_segment_limit (620  ), set_segment_base_address (619  )



                16.18.21           get__meminfo

    Synopsis:    Return information on the available memory

Declaration:     function  get_meminfo(var  meminfo:  tmeminfo)  :  Boolean

    Visibility:   default

Description:     Returns information about the amount of available physical memory, linear address space,
                and disk space for page swapping.

                Parameters:


                meminfo       buffer to fill memory information into.


                Return  values:  Due  to  an  implementation  bug  this  function  always  returns  False,  but  it
                always succeeds.

 Remark:          Notes:   Only  the  first  field  of  the  returned  structure  is  guaranteed  to  contain  a  valid
                value.   Any  fields  that  are  not  supported  by  the  DPMI  host  will  be  set  by  the  host  to
                -1  (0FFFFFFFFH)  to  indicate  that  the  information  is  not  available.  The  size  of  the  pages
                used by the DPMI host can be obtained with the get_page_size (602  ) function.

       Errors:   Check the int31error (592  ) variable.



                                                                                 600

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



    See also:    get_page_size (602  )


                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 :   ' ,
                                                                                      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@
                                                           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  @
                                                                                       '  k b y t e s') ;
                                            end   ;
                              end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                16.18.22           get__next__selector__increment__value

    Synopsis:    Return selector increment value

Declaration:     function  get_next_selector_increment_value  :  Word

    Visibility:   default



                                                                                 601

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



Description:     Returns  the  selector  increment  value  when  allocating  multiple  subsequent  descriptors  via
                allocate_ldt_descriptors (592  ).

                Return value:  Selector increment value.

 Remark:        Notes:  Because allocate_ldt_descriptors (592  ) 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 (592  ) variable.

    See also:    allocate_ldt_descriptors (592  ), free_ldt_descriptor (598  )



                16.18.23           get__page__size

    Synopsis:    Return the page size

Declaration:     function  get_page_size  :  LongInt

    Visibility:   default

Description:     Returns the size of a single memory page.

                Return value:  Size of a single page in bytes.

 Remark:         The returned size is typically 4096 bytes.

                For an example, see get_meminfo (600  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    get_meminfo (600  )



                16.18.24           get__pm__exception__handler

    Synopsis:    Get protected mode exception handler

Declaration:     function  get_pm_exception_handler(e:  Byte;var  intaddr:  tseginfo)
                                                                        :  Boolean

    Visibility:   default

Description:     get_pm_exception_handler returns the protected mode exception handler for exception E
                in intaddr.  It returns True if the call was successful, False if not.

    See also:    get_exception_handler (600  ), set_pm_exception_handler (617  )



                16.18.25           get__pm__interrupt

    Synopsis:    Return protected mode interrupt handler

Declaration:     function  get_pm_interrupt(vector:  Byte;var  intaddr:  tseginfo)  :  Boolean

    Visibility:   default

Description:     Returns the address of a current protected mode interrupt handler.

                Parameters:


                vector    interrupt handler number you want the address to.

                intaddr     buffer to store address.



                                                                                 602

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                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 (618  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    set_pm_interrupt (618  ), set_rm_interrupt (619  ), get_rm_interrupt (606  )



                16.18.26           get__rm__callback

    Synopsis:    Return real mode callback

Declaration:     function  get_rm_callback(pm_func:  pointer;const  reg:  trealregs;
                                                        var  rmcb:  tseginfo)  :  Boolean

    Visibility:   default

Description:     Returns  a  unique  real  mode  segment:offset  address,  known  as  a  "real  mode  callback,"
                that will transfer control from real mode to a protected mode procedure.

                Parameters:


                pm__func     pointer to the protected mode callback function.

                reg  supplied registers structure.

                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 (592  ) variable.

    See also:    free_rm_callback (598  )


                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   ;



                                                                                 603

_______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



              mouse _x     ,  m o u s e _y  :  Word    ;
              mouse _b       :  Word   ;


               u s e r p r o c _i n s t a l l e d: L o n g b o o l;
               u s e r p r o c _l e n g t h:  L o n g i n t;
               u s e r p r o c _p r o c:   p o i n t e r;


 p r o c e d u r ec a l l b a c k _h a n d l e;r a s s e m b l e r;
asm
      pushw    %  d s
      p u s h l%  e a x
     movw    %  e s ,  % a x
     movw    %  ax  ,  % d s


      cmpl    $1  ,  USERPROC_INSTALLED
      j n e  . L N o C a l l b a c k
      p u s h a l
     movw     DOSmemSELECTOR           ,  % a x
     movw    %  ax  ,  % f s
      c a l l * USERPROC_PROC
      p o p a l
 .L N o C a l l b a c k:


      p o p l%  e a x
      popw   %  d s


      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;



                                                                 604

_______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________________________*
 *___



                             u s e r p r o c _i n s t a l l e:d=   t r u e;
                             u s e r p r o c _l e n g t h: =  u s e r p r o c l e;n
                             l o c k _c o d e(u s e r p r o c _p r o c, u s e r p r o c _l e n g t)h;
              end     e l s e b e g i n
                             u s e r p r o c _p r o c: =  n i l;
                             u s e r p r o c _l e n g t h: =  0 ;
                             u s e r p r o c _i n s t a l l e:d=   f a l s e;
              end   ;
               l o c k _d a t a(mouse _x    ,   s i z e o f(m o u s e _x) ) ;
               l o c k _d a t a(mouse _y    ,   s i z e o f(m o u s e _y) ) ;
               l o c k _d a t a(mouse _b    ,   s i z e o f(mouse _b    ) ) ;
               l o c k _d a t a(m o u s e _a c t i o n, s i z e o f( m o u s e _a c t i o n) ) ;


               l o c k _d a t a(u s e r p r o c _i n s t a l l e,d s i z e o f(u s e r p r o c _i n s t a l l e)d) ;
               l o c k _d a t a(u s e r p r o c _p r o c, s i z e o f(u s e r p r o c _p r o c) ) ;


               l o c k _d a t a(m o u s e _r e g s,  s i z e o f(m o u s e _r e g s) ) ;
               l o c k _d a t a(m o u s e _s e g i n f o, s i z e o f(m o u s e _s e g i n f o) ) ;
               l o c k _c o d e(@ c a l l b a c k _h a n d l e,r
                             l o n g i n t(@mouse _dummy       )-  l o n g i n t(@ c a l l b a c k _h a n d l e)r) ;
               g e t _r m _c a l l b a c k(@ c a l l b a c k _h a n d l e,r m o u s e _r e g s,  m o u s e _s e g i n f)o;
               r. e a x  : =  $ 0 c ;  r .e c x  : =   $ 7 f;
               r. e d x  : =  l o n g i n t(m o u s e _s e g i n f o.o f f s e t) ;
               r. e s  : =   m o u s e _s e g i n f.os e g m e n t;
               r e a l i n t(rm o u s e i n t,  r ) ;
               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   ;



                                                                 605

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                 b e g i n
                               i n s t a l l _m o u s(e@ t e x t u s e r p r o,c 4 0 0 ) ;
                               W r i t e l n('P r e s s  any    k e y  t o  e x i t. . .' ) ;
                               w h i l e ( not    k e y p r e s s e)d do    b e g i n
                                            g o t o x y( 1 ,  wherey     ) ;
                                             w r i t e('MouseX       :   ' ,  m o u s e _x: 2 ,  '  MouseY       :  ' ,  m o u s e *
 *_y: 2 ,
                                                           '  B u t t o n s :   ' , mouse _b     : 2 ) ;
                              end   ;
                              r e m o v e _m o u s e;
                end___.____________________________________________________________________________________________________________*
 *___________



                16.18.27           get__rm__interrupt

    Synopsis:    Get real mode interrupt vector

Declaration:     function  get_rm_interrupt(vector:  Byte;var  intaddr:  tseginfo)  :  Boolean

    Visibility:   default

Description:     Returns the contents of the current machine's real mode interrupt vector for the specified
                interrupt.

                Parameters:


                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 (592  ) variable.

    See also:    set_rm_interrupt (619  ), set_pm_interrupt (618  ), get_pm_interrupt (602  )



                16.18.28           get__run__mode

    Synopsis:    Return current run mode

Declaration:     function  get_run_mode  :  Word

    Visibility:   default

Description:     Returns the current mode your application runs with.

                Return values:  One of the constants used by this function.

       Errors:   None.

    See also:    get_run_mode (606  )


                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



                                                                                 606

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                                            rm _unknown         :
                                                          W r i t e l n( 'Unknown       e n v i r o n m e n tf o u n d' ) ;
                                            rm _raw             :
                                                          W r i t e l n( 'You    a r e  c u r r e n t l y r u n n i n g i n  raw   *
 *mode      ',
                                                                         '( w i t h o u tHIMEM    )  ') ;
                                            rm _xms             :
                                                          W r i t e l n( 'You    a r e  c u r r e n t l y u s i n gHIMEM     .SYS  *
 *  o n l y ') ;
                                             r m _v c p i       :
                                                          W r i t e l n( 'VCPI     s e r v e r d e t e c t e d. You   ' 'r e  u s i*
 * n g HIMEM      and     ',
                                                                         'EMM386     ') ;
                                            rm _dpmi            :
                                                          W r i t e l n( 'DPMI     d e t e c t e d. You   ' 'r e  u s i n g a   DPM*
 *I     h o s t  l i k e  ',
                                                                         'a  windows       DOS    box    o r  CWSDPMI      ' ) ;
                              end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                16.18.29           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 (592  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    allocate_ldt_descriptors (592  ), set_segment_base_address (619  ), allocate_ldt_descriptors (592  ),
                set_segment_limit (620  ), get_segment_limit (607  )



                16.18.30           get__segment__limit

    Synopsis:    Return segment limite from descriptor

Declaration:     function  get_segment_limit(d:  Word)  :  LongInt

    Visibility:   default

Description:     Returns a descriptors segment limit.

                Parameters:


                d selector.


                Return value:  Limit of the descriptor in bytes.

       Errors:   Returns zero if descriptor is invalid.

    See also:    allocate_ldt_descriptors (592  ), set_segment_limit (620  ), set_segment_base_address (619  ), get_segment_base_ad*
 *dress
                (607  )



                                                                                 607

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                16.18.31           get__ss

    Synopsis:    Return SS selector

Declaration:     function  get_ss  :  Word

    Visibility:   default

Description:     Returns the ss selector.

                Return values:  The content of the ss segment register.

       Errors:   None.

    See also:    get_ds (599  ), get_cs (599  )



                16.18.32           global__dos__alloc

    Synopsis:    Allocate DOS real mode memory

Declaration:     function  global_dos_alloc(bytes:  LongInt)  :  LongInt

    Visibility:   default

Description:     Allocates a block of dos real mode memory.

                Parameters:


                bytes    size of requested real mode memory.


                Return  values:  The  low  word  of  the  returned  value  contains  the  selector  to  the  allocated
                dos  memory  block,  the  high  word  the  corresponding  real  mode  segment  value.  The  offset
                value is always zero.  This function allocates memory from dos memory pool, i.e.  memory
                below the 1 MB boundary that is controlled by dos.  Such memory blocks are typically used
                to exchange data with real mode programs, TSRs, or device drivers.  The function returns
                both the real mode segment base address of the block and one descriptor that can be used
                by  protected  mode  applications  to  access  the  block.   This  function  should  only  used  for
                temporary buffers to get real mode information (e.g.  interrupts that need a data structure
                in  ES:(E)DI),  because  every  single  block  needs  an  unique  selector.  The  returned  selector
                should only be freed by a global_dos_free (609  ) call.

       Errors:   Check the int31error (592  ) variable.

    See also:    global_dos_free (609  )


                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   ;



                                                                                 608

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                 p r o c e d u r ed o s f r e e(s e l e c t o r :  word   ) ;
                 b e g i n
                               g l o b a l _d o s _f r e e(s e l e c t o r) ;
                end   ;


                 t y p e
                              V B E I n f o B u f=   packed      r e c o r d
                                             S i g n a t u r e:  a r r a y[ 0 . . 3 ] o f   c h a r;
                                             V e r s i o n :  Word   ;
                                             r e s e r v e d:   a r r a y[ 0 . . 5 0 5 ]o f  b y t e;
                              end   ;


                 v a r
                               s e l e c t o r,
                              s e g m e n t  :  Word   ;


                               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___.____________________________________________________________________________________________________________*
 *___________



                16.18.33           global__dos__free

    Synopsis:    Free DOS memory block

Declaration:     function  global_dos_free(selector:  Word)  :  Boolean

    Visibility:   default

Description:     Frees a previously allocated dos memory block.

                Parameters:



                                                                                 609

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                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
                (608  ).

                For an example, see global_dos_alloc (608  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    global_dos_alloc (608  )



                16.18.34           inportb

    Synopsis:    Read byte from I/O port

Declaration:     function  inportb(port:  Word)  :  Byte

    Visibility:   default

Description:     Reads 1 byte from the selected I/O port.

                Parameters:


                port   the I/O port number which is read.


                Return values:  Current I/O port value.

       Errors:   None.

    See also:    outportb (612  ), inportw (611  ), inportl (610  )



                16.18.35           inportl

    Synopsis:    Read longint from I/O port

Declaration:     function  inportl(port:  Word)  :  LongInt

    Visibility:   default

Description:     Reads 1 longint from the selected I/O port.

                Parameters:


                port   the I/O port number which is read.


                Return values:  Current I/O port value.

       Errors:   None.

    See also:    outportb (612  ), inportb (610  ), inportw (611  )



                                                                                 610

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                16.18.36           inportw

    Synopsis:    Read word from I/O port

Declaration:     function  inportw(port:  Word)  :  Word

    Visibility:   default

Description:     Reads 1 word from the selected I/O port.

                Parameters:


                port   the I/O port number which is read.


                Return values:  Current I/O port value.

       Errors:   None.

    See also:    outportw (613  ), inportb (610  ), inportl (610  )



                16.18.37           lock__code

    Synopsis:    Lock code memory range

Declaration:     function  lock_code(functionaddr:  pointer;size:  LongInt)  :  Boolean

    Visibility:   default

Description:     Locks a memory range which is in the code segment selector.

                Parameters:


                functionaddr        address of the function to be locked.

                size  size in bytes to be locked.


                Return values:  True if successful, False otherwise.

                For an example, see get_rm_callback (603  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    lock_linear_region (612  ), lock_data (611  ), unlock_linear_region (622  ), unlock_data (621  ), un-
                lock_code (621  )



                16.18.38           lock__data

    Synopsis:    Lock data memory range

Declaration:     function  lock_data(var  data;size:  LongInt)  :  Boolean

    Visibility:   default

Description:     Locks a memory range which resides in the data segment selector.

                Parameters:


                data   address of data to be locked.

                size  length of data to be locked.


                Return values:  True if successful, False otherwise.

                For an example, see get_rm_callback (603  ).



                                                                                 611

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



       Errors:   Check the int31error (592  ) variable.

    See also:    lock_linear_region (612  ), lock_code (611  ), unlock_linear_region (622  ), unlock_data (621  ), un-
                lock_code (621  )



                16.18.39           lock__linear__region

    Synopsis:    Lock linear memory region

Declaration:     function  lock_linear_region(linearaddr:  LongInt;size:  LongInt)  :  Boolean

    Visibility:   default

Description:     Locks a memory region to prevent swapping of it.

                Parameters:


                linearaddr      the linear address of the memory are to be locked.

                size  size in bytes to be locked.


                Return value:  True if successful, False otherwise.

       Errors:   Check the int31error (592  ) variable.

    See also:    lock_data (611  ), lock_code (611  ), unlock_linear_region (622  ), unlock_data (621  ), unlock_code
                (621  )



                16.18.40           map__device__in__memory__block

    Synopsis:    Map a device into program's memory space

Declaration:     function  map_device_in_memory_block(handle:  LongInt;offset:  LongInt;
                                                                          pagecount:  LongInt;device:  LongInt)
                                                                            :  Boolean

    Visibility:   default

Description:     map_device_in_memory_block allows to map a device in memory.  This function is a direct
                call of the extender.  For more information about it's arguments, see the extender documen-
                tation.



                16.18.41           outportb

    Synopsis:    Write byte to I/O port

Declaration:     procedure  outportb(port:  Word;data:  Byte)

    Visibility:   default

Description:     Sends 1 byte of data to the specified I/O port.

                Parameters:


                port   the I/O port number to send data to.

                data   value sent to I/O port.


                Return values:  None.



                                                                                 612

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



       Errors:   None.

    See also:    inportb (610  ), outportl (613  ), outportw (613  )


                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___.____________________________________________________________________________________________________________*
 *___________



                16.18.42           outportl

    Synopsis:    Write longint to I/O port

Declaration:     procedure  outportl(port:  Word;data:  LongInt)

    Visibility:   default

Description:     Sends 1 longint of data to the specified I/O port.

                Parameters:


                port   the I/O port number to send data to.

                data   value sent to I/O port.


                Return values:  None.

                For an example, see outportb (612  ).

       Errors:   None.

    See also:    inportl (610  ), outportw (613  ), outportb (612  )



                16.18.43           outportw

    Synopsis:    Write word to I/O port

Declaration:     procedure  outportw(port:  Word;data:  Word)

    Visibility:   default

Description:     Sends 1 word of data to the specified I/O port.

                Parameters:


                port   the I/O port number to send data to.

                data   value sent to I/O port.


                Return values:  None.

                For an example, see outportb (612  ).

       Errors:   None.

    See also:    inportw (611  ), outportl (613  ), outportb (612  )



                                                                                 613

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                16.18.44           realintr

    Synopsis:    Simulate interrupt

Declaration:     function  realintr(intnr:  Word;var  regs:  trealregs)  :  Boolean

    Visibility:   default

Description:     Simulates an interrupt in real mode.

                Parameters:


                intnr   interrupt number to issue in real mode.

                regs   registers data structure.


                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 (592  ) 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___.____________________________________________________________________________________________________________*
 *___________



                16.18.45           request__linear__region

    Synopsis:    Request linear address region.

Declaration:     function  request_linear_region(linearaddr:  LongInt;size:  LongInt;
                                                                  var  blockhandle:  LongInt)  :  Boolean

    Visibility:   default

Description:     request_linear_region requests a linear range of addresses of size Size, starting at linearaddr.
                If successful, True is returned, and a handle to the address region is returned in blockhandle.

       Errors:   On error, False is returned.



                                                                                 614

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                16.18.46           segment__to__descriptor

    Synopsis:    Map segment address to descriptor

Declaration:     function  segment_to_descriptor(seg:  Word)  :  Word

    Visibility:   default

Description:     Maps a real mode segment (paragraph) address onto an descriptor that can be used by a
                protected mode program to access the same memory.

                Parameters:


                seg  the real mode segment you want the descriptor to.


                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 (592  ) and change the
                base address as necessary.

                For an example, see seg_fillchar (615  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    allocate_ldt_descriptors (592  ), free_ldt_descriptor (598  ), set_segment_base_address (619  )



                16.18.47           seg__fillchar

    Synopsis:    Fill segment with byte value

Declaration:     procedure  seg_fillchar(seg:  Word;ofs:  LongInt;count:  LongInt;c:  Char)

    Visibility:   default

Description:     Sets a memory area to a specific value.

                Parameters:


                seg  selector to memory area.

                ofs  offset to memory.

                count    number of bytes to set.

                c byte data which is set.


                Return values:  None.

                Notes:  No range check is done in any way.

       Errors:   None.

    See also:    seg_move (616  ), seg_fillword (616  ), dosmemfillchar (589  ), dosmemfillword (589  ), dosmemget
                (589  ), dosmemput (590  ), dosmemmove (589  )


                Listing:  ./go32ex/vgasel.pp



                                                                                 615

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                 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___.____________________________________________________________________________________________________________*
 *___________



                16.18.48           seg__fillword

    Synopsis:    Fill segment with word value

Declaration:     procedure  seg_fillword(seg:  Word;ofs:  LongInt;count:  LongInt;w:  Word)

    Visibility:   default

Description:     Sets a memory area to a specific value.

                Parameters:


                seg  selector to memory area.

                ofs  offset to memory.

                count    number of words to set.

                w  word data which is set.


                Return values:  None.

                Notes:  No range check is done in any way.

                For an example, see allocate_ldt_descriptors (592  ).

       Errors:   None.

    See also:    seg_move (616  ), seg_fillchar (615  ), dosmemfillchar (589  ), dosmemfillword (589  ), dosmemget
                (589  ), dosmemput (590  ), dosmemmove (589  )



                16.18.49           seg__move

    Synopsis:    Move data between 2 locations

Declaration:     procedure  seg_move(sseg:  Word;source:  LongInt;dseg:  Word;dest:  LongInt;
                                              count:  LongInt)

    Visibility:   default

Description:     Copies data between two memory locations.

                Parameters:


                sseg   source selector.



                                                                                 616

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                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 (592  ).

       Errors:   None.

    See also:    seg_fillchar (615  ), seg_fillword (616  ), dosmemfillchar (589  ), dosmemfillword (589  ), dosmemget
                (589  ), dosmemput (590  ), dosmemmove (589  )



                16.18.50           set__descriptor__access__right

    Synopsis:    Set access rights to memory descriptor

Declaration:     function  set_descriptor_access_right(d:  Word;w:  Word)  :  LongInt

    Visibility:   default

Description:     set_descriptor_access_right sets the access rights for descriptor d to w



                16.18.51           set__exception__handler

    Synopsis:    Set exception handler

Declaration:     function  set_exception_handler(e:  Byte;const  intaddr:  tseginfo)
                                                                   :  Boolean

    Visibility:   default

Description:     set_exception_handler sets the exception handler for exception E to intaddr.  It returns
                True if the call was successful, False if not.

    See also:    get_exception_handler (600  ), set_pm_exception_handler (617  )



                16.18.52           set__pm__exception__handler

    Synopsis:    Set protected mode exception handler

Declaration:     function  set_pm_exception_handler(e:  Byte;const  intaddr:  tseginfo)
                                                                        :  Boolean

    Visibility:   default

Description:     set_pm_exception_handler sets the protected mode exception handler for exception E to
                intaddr.  It returns True if the call was successful, False if not.

    See also:    set_exception_handler (617  ), get_pm_exception_handler (602  )



                                                                                 617

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                16.18.53           set__pm__interrupt

    Synopsis:    Set protected mode interrupt handler

Declaration:     function  set_pm_interrupt(vector:  Byte;const  intaddr:  tseginfo)
                                                           :  Boolean

    Visibility:   default

Description:     Sets the address of the protected mode handler for an interrupt.

                Parameters:


                vector    number of protected mode interrupt to set.

                intaddr     selector:offset address to the interrupt vector.


                Return values:  True if successful, False otherwise.

 Remark:         The address supplied must be a valid selector:offset protected mode address.

       Errors:   Check the int31error (592  ) variable.

    See also:    get_pm_interrupt (602  ), set_rm_interrupt (619  ), get_rm_interrupt (606  )


                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) ;



                                                                                 618

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                         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___.____________________________________________________________________________________________________________*
 *___________



                16.18.54           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 (603  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    get_rm_interrupt (606  ), set_pm_interrupt (618  ), get_pm_interrupt (602  ), get_rm_callback (603  )



                16.18.55           set__segment__base__address

    Synopsis:    Set descriptor's base address

Declaration:     function  set_segment_base_address(d:  Word;s:  LongInt)  :  Boolean

    Visibility:   default

Description:     Sets the 32-bit linear base address of a descriptor.

                Parameters:


                d selector.

                s new base address of the descriptor.


       Errors:   Check the int31error (592  ) variable.

    See also:    allocate_ldt_descriptors (592  ), get_segment_base_address (607  ), allocate_ldt_descriptors (592  ),
                set_segment_limit (620  ), get_segment_base_address (607  ), get_segment_limit (607  )



                                                                                 619

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                16.18.56           set__segment__limit

    Synopsis:    Set descriptor limit

Declaration:     function  set_segment_limit(d:  Word;s:  LongInt)  :  Boolean

    Visibility:   default

Description:     Sets the limit of a descriptor.

                Parameters:


                d selector.

                s new limit of the descriptor.


                Return values:  Returns True if successful, else False.

 Remark:         The new limit specified must be the byte length of the segment - 1.  Segment limits bigger
                than or equal to 1MB must be page aligned, they must have the lower 12 bits set.

                For an example, see allocate_ldt_descriptors (592  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    allocate_ldt_descriptors (592  ), set_segment_base_address (619  ), get_segment_limit (607  ), set_segment_limit
                (620  )



                16.18.57           tb__offset

    Synopsis:    Return DOS transfer buffer offset

Declaration:     function  tb_offset  :  LongInt

    Visibility:   default

Description:     tb_offset returns the DOS transfer buffer segment.

    See also:    transfer_buffer (621  ), tb_segment (620  ), tb_size (620  )



                16.18.58           tb__segment

    Synopsis:    Return DOS transfer buffer segment

Declaration:     function  tb_segment  :  LongInt

    Visibility:   default

Description:     tb_segment returns the DOS transfer buffer segment.

    See also:    transfer_buffer (621  ), tb_offset (620  ), tb_size (620  )



                16.18.59           tb__size

    Synopsis:    Return DOS transfer memory buffer size

Declaration:     function  tb_size  :  LongInt

    Visibility:   default



                                                                                 620

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



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 (621  ), copyfromdos (595  ), copytodos (595  )



                16.18.60           transfer__buffer

    Synopsis:    Return offset of DOS transfer buffer

Declaration:     function  transfer_buffer  :  LongInt

    Visibility:   default

Description:     transfer_buffer returns the offset of the transfer buffer.

       Errors:   None.

    See also:    tb_size (620  )



                16.18.61           unlock__code

    Synopsis:    Unlock code segment

Declaration:     function  unlock_code(functionaddr:  pointer;size:  LongInt)  :  Boolean

    Visibility:   default

Description:     Unlocks a memory range which resides in the code segment selector.

                Parameters:


                functionaddr        address of function to be unlocked.

                size  size bytes to be unlocked.


                Return value:  True if successful, False otherwise.

                For an example, see get_rm_callback (603  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    unlock_linear_region (622  ), unlock_data (621  ), lock_linear_region (612  ), lock_data (611  ), lock_code
                (611  )



                16.18.62           unlock__data

    Synopsis:    Unlock data segment

Declaration:     function  unlock_data(var  data;size:  LongInt)  :  Boolean

    Visibility:   default

Description:     Unlocks a memory range which resides in the data segment selector.

                Parameters:


                data   address of memory to be unlocked.



                                                                                 621

                _______________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'GO32'_____________*
 *___________________



                size size bytes to be unlocked.


                Return values:  True if successful, False otherwise.

                For an example, see get_rm_callback (603  ).

       Errors:   Check the int31error (592  ) variable.

    See also:    unlock_linear_region  (622  ),  unlock_code  (621  ),  lock_linear_region  (612  ),  lock_data  (611  ),
                lock_code (611  )



                16.18.63           unlock__linear__region

    Synopsis:    Unlock linear memory region

Declaration:     function  unlock_linear_region(linearaddr:  LongInt;size:  LongInt)
                                                                  :  Boolean

    Visibility:   default

Description:     Unlocks a previously locked linear region range to allow it to be swapped out again if needed.

                Parameters:


                linearaddr      linear address of the memory to be unlocked.

                size  size bytes to be unlocked.


                Return values:  True if successful, False otherwise.

       Errors:   Check the int31error (592  ) variable.

    See also:    unlock_data  (621  ),  unlock_code  (621  ),  lock_linear_region  (612  ),  lock_data  (611  ),  lock_code
                (611  )



                                                                                 622




Chapter   17



Reference   for   unit   'gpm'



17.1          Used  units



                                      Table 17.1:  Used units by unit 'gpm'


                                                  __Name____________Page_____
                                                    baseUnix          102
                                                    System           1230



17.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.



17.3          Constants,  types  and  variables



17.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



                                                             623

_______________________________________________________________CHAPTER_17.___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 (102  ).


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



                                                                 624

_______________________________________________________________CHAPTER_17.___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.



17.3.2         Types

Pgpmconnect  =  Pgpm_connect


Pointer to TGpmConnect (626  ) record.


Pgpmevent  =  Pgpm_event



                                                                 625

_______________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'GPM'______________________________*
 *___



Pointer to TGpmEvent (626  ) record


Pgpmroi  =  Pgpm_roi


Pointer to TGpmRoi (626  ) record.


Pgpm_connect  =  ^TGpm_connect


Pointer to TGpm_Connect (627  ) record.


Pgpm_event  =  ^Tgpm_event


Pointer to TGpm_Event (627  ) record


Pgpm_roi  =  ^Tgpm_roi


Pointer to Tgpm_roi (627  ) record.


Tgpmconnect  =  Tgpm_connect


Alias for TGpm_Connect (627  ) record.


TGpmEtype  =  LongInt


Type for event type.


Tgpmevent  =  Tgpm_event


Alias for TGPM_EVent (627  ) record


TGpmHandler  =  function(var  event:  Tgpmevent;clientdata:  pointer)
                                       :  LongInt  of  object


Mouse event handler callback.


TGpmMargin  =  LongInt


Type to hold area margin.


Tgpmroi  =  Tgpm_roi


Alias for TGpm_roi (627  )Record


Tgpm_connect  =  packed  record
   eventMask  :  Word;
   defaultMask  :  Word;
   minMod  :  Word;
   maxMod  :  Word;
   pid  :  LongInt;
   vc  :  LongInt;
end



                                                                 626

_______________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'GPM'______________________________*
 *___



GPM server connection information.


Tgpm_event  =  packed  record
   buttons  :  Byte;
   modifiers  :  Byte;
   vc  :  Word;
   dx  :  Word;
   dy  :  Word;
   x  :  Word;
   y  :  Word;
   EventType  :  TGpmEtype;
   clicks  :  LongInt;
   margin  :  TGpmMargin;
   wdx  :  Word;
   wdy  :  Word;
end



Tgpm_event describes the events that are reported by GPM.


Tgpm_roi  =  packed  record
   xmin  :  Integer;
   xmax  :  Integer;
   ymin  :  Integer;
   ymax  :  Integer;
   minmod  :  Word;
   maxmod  :  Word;
   eventmask  :  Word;
   owned  :  Word;
   handler  :  TGpmHandler;
   clientdata  :  pointer;
   prev  :  Pgpm_roi;
   next  :  Pgpm_roi;
end



Record used to define regions of interest.



17.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



                                                                 627

                _______________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



                Internal gpm library variable.  Do not use.


                gpm_roi_handler  :  TGpmHandler


                Internal gpm library variable.  Do not use.



                17.4          Procedures  and  functions



                17.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 (633  ), Gpm_AnySingle (628  ), Gpm_StrictDouble (633  ), Gpm_StrictTriple
                (633  ), Gpm_AnyTriple (628  )



                17.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 (633  ), Gpm_AnyDouble (628  ), Gpm_StrictDouble (633  ), Gpm_StrictTriple
                (633  ), Gpm_AnyTriple (628  )



                17.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 (633  ), Gpm_AnyDouble (628  ), Gpm_StrictDouble (633  ), Gpm_StrictTriple
                (633  ), Gpm_AnySingle (628  )



                                                                                 628

                _______________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



                17.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 (629  ).

       Errors:   None.

    See also:    Gpm_Open (631  )



                17.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 (629  )



                17.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 (629  )



                17.4.7         gpm__getevent

    Synopsis:    Get event from event queue.

Declaration:     function  gpm_getevent(var  event:  Tgpm_event)  :  LongInt

    Visibility:   default



                                                                                 629

                _______________________________________________________________CHAPTER_17.___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 (631  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 630

                _______________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



                17.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 (629  )



                17.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 (632  ), Gpm_PopRoi (632  ), Gpm_PushRoi (632  )



                17.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 (626  ).

                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 (629  ).

       Errors:   On Error, the return value is -1.

    See also:    Gpm_Open (631  )



                                                                                 631

                _______________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



                17.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 (632  ), Gpm_LowerRoi (631  ), Gpm_PushRoi (632  )



                17.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 (632  ), Gpm_PopRoi (632  ), Gpm_LowerRoi (631  )



                17.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 (632  ), Gpm_PopRoi (632  ), Gpm_LowerRoi (631  )



                17.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.



                                                                                 632

                _______________________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'GPM'______________*
 *___________________



       Errors:   None.

    See also:    Gpm_GetEvent (629  )



                17.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  (633  ),  Gpm_AnyTriple  (628  ),  Gpm_AnyDouble  (628  ),  Gpm_StrictTriple
                (633  ), Gpm_AnySingle (628  )



                17.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 (628  ), Gpm_StrictDouble (633  ), Gpm_AnyDouble (628  ), Gpm_StrictTriple
                (633  ), Gpm_AnySingle (628  )



                17.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 (628  ), Gpm_StrictDouble (633  ), Gpm_AnyDouble (628  ), Gpm_StrictSingle
                (633  ), Gpm_AnySingle (628  )



                                                                                 633




Chapter   18



Reference   for   unit   'Graph'



18.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.



18.2          Categorized  functions:   Text  and  font  handling


Functions to set texts on the screen.



                                                       Table 18.1:

                  __Name________________________________Description_________________________________________
                    GetTextSettings (675  )            Get current text settings
                    InstallUserFont (678  )            Install a new font
                    OutText (679  )                    Write text at current cursor position
                    OutTextXY (666  )                  Write text at coordinates X,Y
                    RegisterBGIFont (680  )            Register a new font
                    SetTextJustify (683  )             Set text justification
                    SetTextStyle (684  )               Set text style
                    SetUserCharSize (685  )            Set text size
                    TextHeight (686  )                 Calculate height of text
                    TextWidth (686  )                  Calculate width of text



18.3          Categorized  functions:   Filled  drawings


Functions for drawing filled regions.



                                                             634

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



                                                       Table 18.2:

                         __Name_____________________________Description______________________________
                           Bar3D (668  )                    Draw a filled 3D-style bar
                           Bar (667  )                      Draw a filled rectangle
                           FloodFill (670  )                Fill starting from coordinate
                           FillEllipse (669  )              Draw a filled ellipse
                           FillPoly (670  )                 Draw a filled polygone
                           GetFillPattern (672  )           Get current fill pattern
                           GetFillSettings (672  )          Get current fill settings
                           SetFillPattern (682  )           Set current fill pattern
                           SetFillStyle (682  )             Set current fill settings



18.4          Categorized  functions:   Drawing  primitives


Functions for simple drawing.



                                                       Table 18.3:

        __Name______________________________Description_______________________________________________________________
          Arc (667  )                       Draw an arc
          Circle (665  )                    Draw a complete circle
          DrawPoly (669  )                  Draw a polygone with N points
          Ellipse (669  )                   Draw an ellipse
          GetArcCoords (670  )              Get arc coordinates
          GetLineSettings (672  )           Get current line drawing settings
          Line (666  )                      Draw line between 2 points
          LineRel (678  )                   Draw line relative to current position
          LineTo (678  )                    Draw line from current position to absolute position
          MoveRel (678  )                   Move cursor relative to current position
          MoveTo (679  )                    Move cursor to absolute position
          PieSlice (679  )                  Draw a pie slice
          PutPixel (666  )                  Draw 1 pixel
          Rectangle (680  )                 Draw a non-filled rectangle
          Sector (681  )                    Draw a sector
          SetLineStyle (683  )              Set current line drawing style



18.5          Categorized  functions:   Color  management


All functions related to color management.



                                                                 635

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



                                                       Table 18.4:

                  __Name_________________________________Description________________________________________
                    GetBkColor (665  )                   Get current background color
                    GetColor (671  )                     Get current foreground color
                    GetDefaultPalette (671  )            Get default palette entries
                    GetMaxColor (673  )                  Get maximum valid color
                    GetPaletteSize (674  )               Get size of palette for current mode
                    GetPixel (665  )                     Get color of selected pixel
                    GetPalette (674  )                   Get palette entry
                    SetAllPalette (666  )                Set all colors in palette
                    SetBkColor (667  )                   Set background color
                    SetColor (681  )                     Set foreground color
                    SetPalette (683  )                   Set palette entry
                    SetRGBPalette (667  )                Set palette entry with RGB values



18.6          Categorized  functions:   Screen  management


General drawing screen management functions.



                                                       Table 18.5:

                   _Name_______________________________Description___________________________________________
                     ClearViewPort (665  )              Clear the current viewport
                     GetImage (665  )                   Copy image from screen to memory
                     GetMaxX (673  )                    Get maximum X coordinate
                     GetMaxY (673  )                    Get maximum Y coordinate
                     GetX (675  )                       Get current X position
                     GetY (675  )                       Get current Y position
                     ImageSize (665  )                  Get size of selected image
                     GetViewSettings (675  )            Get current viewport settings
                     PutImage (666  )                   Copy image from memory to screen
                     SetActivePage (666  )              Set active video page
                     SetAspectRatio (681  )             Set aspect ratio for drawing routines
                     SetViewPort (685  )                Set current viewport
                     SetVisualPage (667  )              Set visual page
                     SetWriteMode (685  )               Set write mode for screen operations



18.7          Categorized  functions:   Initialization


Initialization of the graphics screen.



                                                                 636

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



                                                       Table 18.6:

            __Name__________________________________Description___________________________________________________
              ClearDevice (668  )                   Empty the graphics screen
              CloseGraph (668  )                    Finish drawing session, return to text mode
              DetectGraph (668  )                   Detect graphical modes
              GetAspectRatio (670  )                Get aspect ratio of screen
              GetModeRange (674  )                  Get range of valid modes for current driver
              GraphDefaults (1 )                    Set defaults
              GetDriverName (671  )                 Return name of graphical driver
              GetGraphMode (672  )                  Return current or last used graphics mode
              GetMaxMode (673  )                    Get maximum mode for current driver
              GetModeName (674  )                   Get name of current mode
              GraphErrorMsg (1 )                    String representation of graphical error
              GraphResult (1 )                      Result of last drawing operation
              InitGraph (677  )                     Initialize graphics drivers
              InstallUserDriver (677  )             Install a new driver
              RegisterBGIDriver (680  )             Register a new driver
              RestoreCRTMode (680  )                Go back to text mode
              SetGraphMode (682  )                  Set graphical mode



18.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.



                                                                 637

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



18.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.



18.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)  "



                                                                 638

___________________________________________________________CHAPTER_18.___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 )



                                                                 639

___________________________________________________________CHAPTER_18.___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



                                                                 640

___________________________________________________________CHAPTER_18.___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



                                                                 641

___________________________________________________________CHAPTER_18.___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___._______________________________________________________________________________________________________________________



18.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).



                                                                 642

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



18.12            Constants,  types  and  variables



18.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@


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



                                                                 643

___________________________________________________________CHAPTER_18.___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



                                                                 644

___________________________________________________________CHAPTER_18.___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.



                                                                 645

___________________________________________________________CHAPTER_18.___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



                                                                 646

___________________________________________________________CHAPTER_18.___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



                                                                 647

___________________________________________________________CHAPTER_18.___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,@


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



                                                                 648

___________________________________________________________CHAPTER_18.___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



                                                                 649

___________________________________________________________CHAPTER_18.___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



                                                                 650

___________________________________________________________CHAPTER_18.___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



                                                                 651

___________________________________________________________CHAPTER_18.___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.



                                                                 652

___________________________________________________________CHAPTER_18.___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  =  30015


Mode:  Highest possible value of the new modes.


HorizDir  =  0


Text write direction:  Horizontal



                                                                 653

___________________________________________________________CHAPTER_18.___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  =  30001


Mode:  Lowest possible value of the new modes.


LowRes  =  6


Mode:  Low resolution.



                                                                 654

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



LtBkSlashFill  =  6


Fill style:  Light diagonal (backslash) lines


LtSlashFill  =  3


Fill style:  Light diagonal (slash) lines


m1024x768  =  30012


Mode:  Resolution 1024x768


m1280x1024  =  30013


Mode:  Resolution 1280x1024


m1600x1200  =  30014


Mode:  Resolution 1600x1200


m2048x1536  =  30015


Mode:  Resolution 2048x1536


m320x200  =  30001


Mode:  Resolution 320x200


m320x256  =  30002


Mode:  Resolution 320x256


m320x400  =  30003


Mode:  Resolution 320x400


m512x384  =  30004


Mode:  Resolution 512x384


m640x200  =  30005


Mode:  Resolution 640x200


m640x256  =  30006


Mode:  Resolution 640x256


m640x350  =  30007


Mode:  Resolution 640x350



                                                                 655

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



m640x400  =  30008


Mode:  Resolution 640x400


m640x480  =  30009


Mode:  Resolution 640x480


m800x600  =  30010


Mode:  Resolution 800x600


m832x624  =  30011


Mode:  Resolution 832x624


magenta  =  5


Color code:  Magenta


MaxColors  =  255


Max amount of colors in a palette


maxsmallint  =  (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



                                                                 656

___________________________________________________________CHAPTER_18.___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:  51@


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



                                                                 657

___________________________________________________________CHAPTER_18.___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.



                                                                 658

___________________________________________________________CHAPTER_18.___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



18.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)



                                                                 659

___________________________________________________________CHAPTER_18.___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  (665  )  method  handler  in
TModeInfo (664  ).  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 (665  ) 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 (665  )


getscanlineproc  =  procedure(X1:  SmallInt;X2:  SmallInt;Y:  SmallInt;
                                              var  data)



                                                                 660

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



This routine is used for FloodFill (670  ) 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 (665  ) 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 (666  )


PaletteType  =  record
   Size  :  LongInt;
   Colors  :  Array[0..MaxColors]  of  RGBRec;
end



                                                                 661

___________________________________________________________CHAPTER_18.___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 (663  ) array.


PModeInfo  =  ^TModeInfo


Pointer to TModeInfo (664  ) 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 (666  ) 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 (666  ) procedure prototype.



                                                                 662

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



SetAllPaletteProc  =  procedure(const  Palette:  PaletteType)


This routine prototype is a hook for SetAllPalette (666  )


SetBkColorProc  =  procedure(ColorNum:  Word)


SetBkColorProc  is  the  procedure  prototype  for  the  SetBkColor  (667  )  method  handler  in
TModeInfo (664  ).  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 (667  )


setvisualpageproc  =  procedure(page:  Word)


Standard SetVisualPage (667  ) 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;



                                                                 663

___________________________________________________________CHAPTER_18.___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.


TNewModeInfo  =  record
   modeInfo  :  Array[lowNewDriver..highNewDriver]  of  PModeInfo;
   loHiModeNr  :  Array[lowNewDriver..highNewDriver]  of  ;
end



Mode information for new modes.a


TResolutionRec  =  record
   x  :  LongInt;
   y  :  LongInt;
end



Record describing resolution


ViewPortType  =  record
   x1  :  SmallInt;
   y1  :  SmallInt;
   x2  :  SmallInt;
   y2  :  SmallInt;
   Clip  :  Boolean;
end



Record describing a viewport


vlineproc  =  procedure(x:  SmallInt;y:  SmallInt;y2:  SmallInt)


Standard procedure prototype to draw a single vertical line



                                                                 664

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



18.12.3          Variables

Circle  :  CircleProc


Circle draws a complete circle with center at (X,Y), radius radius.


ClearViewPort  :  clrviewproc


Clears  the  current  viewport.   The  current  background  color  is  used  as  filling  color.   The
pointer is set at (0,0).


DirectPutPixel  :  defpixelproc


Hook to directly draw a pixel on the screen.


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).



                                                                 665

___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________________________*
 *___



InternalEllipse  :  ellipseproc


Hook to draw an ellipse


Line  :  lineproc


Line draws a line starting from (X1,Y1 to (X2,Y2), in the current line style and color.  The
current position is put to (X2,Y2)


OutTextXY  :  OutTextXYProc


OutText puts TextString on the screen, at position (X,Y), using the current font and text
settings.  The current position is moved to the end of the text.


PatternLine  :  patternlineproc


Hook to draw a patterned line


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



                                                                 666

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                SetBkColor  :  SetBkColorProc


                Sets the background color to Color.


                SetRGBPalette  :  setrgbpaletteproc


                SetRGBPalette sets the ColorNr-th entry in the palette to the color with RGB-values Red,
                Green  Blue.


                SetVisualPage  :  setvisualpageproc


                SetVisualPage sets the video page to page number Page.


                VLine  :  vlineproc


                Hook to draw a solid vertical line



                18.13            Procedures  and  functions



                18.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 (665  ), Ellipse (669  ), GetArcCoords (670  ), PieSlice (679  ), Sector (681  )



                18.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 (668  ), Rectangle (680  )



                                                                                 667

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.13.3          Bar3D

    Synopsis:    Draw filled 3-dimensional rectangle

Declaration:     procedure  Bar3D(x1:  SmallInt;y1:  SmallInt;x2:  SmallInt;y2:  SmallInt;
                                         depth:  Word;top:  Boolean)

    Visibility:   default

Description:     Bar3d draws a 3-dimensional Bar with corners at (X1,Y1) and (X2,Y2) and fills it with the
                current color and fill-style.  Depth specifies the number of pixels used to show the depth of
                the bar.

                If  Top is true; then a 3-dimensional top is drawn.

       Errors:   None.

    See also:    Bar (667  ), Rectangle (680  )



                18.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 (665  ), SetBkColor (667  )



                18.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 (677  )



                18.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.



                                                                                 668

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



       Errors:   None.

    See also:    InitGraph (677  )



                18.13.7          DrawPoly

    Synopsis:    Draw a polygone

Declaration:     procedure  DrawPoly(NumPoints:  Word;var  polypoints)

    Visibility:   default

Description:     DrawPoly  draws  a  polygone  with  NumberOfPoints  corner  points,  using  the  current  color
                and line-style.  PolyPoints is an array of type PointType (662  ).

       Errors:   None.

    See also:    Bar (667  ), Bar3D (668  ), Rectangle (680  )



                18.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 (667  ), Circle (665  ), FillEllipse (669  )



                18.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 (667  ), Circle (665  ), GetArcCoords (670  ), PieSlice (679  ), Sector (681  )



                                                                                 669

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (667  ), Bar3D (668  ), Rectangle (680  )



                18.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 (681  ), SetBkColor (667  )



                18.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 (667  ), Ellipse (669  )



                18.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 (677  ), SetAspectRatio (681  )



                                                                                 670

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (671  ), SetBkColor (667  )



                18.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 (671  ), GetBkColor (665  )



                18.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.



                18.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 (674  ), InitGraph (677  )



                                                                                 671

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (682  )



                18.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 (682  )



                18.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 (677  )



                18.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 (683  )



                                                                                 672

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (681  ), GetPaletteSize (674  )



                18.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 (677  )



                18.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 (673  )



                18.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 (673  )



                                                                                 673

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (671  ), InitGraph (677  )



                18.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 (677  )



                18.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 (674  ), SetPalette (683  )



                18.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 (674  ), SetPalette (683  )



                                                                                 674

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (684  ), SetTextJustify (683  )



                18.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 (685  )



                18.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 (675  )



                18.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 (675  )



                                                                                 675

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (685  ), SetFillStyle (682  ), SetColor (681  ), SetBkColor (667  ), SetLineStyle (683  )



                18.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 )



                18.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 (678  )

                      oSetLineStyle (683  )

                      oSetWriteMode (685  )

                      oSetFillStyle (682  )

                      oSetTextJustify (683  )

                      oSetGraphMode (682  )

                      oSetTextStyle (684  )


       Errors:   None.

    See also:    GraphErrorMsg (1 )



                                                                                 676

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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:


                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 (638  ), DetectGraph (668  ), CloseGraph (668  ), GraphResult (1 )



                18.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 (677  ), InstallUserFont (678  )



                                                                                 677

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (677  ), InstallUserDriver (677  )



                18.13.40           LineRel

    Synopsis:    Draw a line starting from current position in given direction

Declaration:     procedure  LineRel(Dx:  SmallInt;Dy:  SmallInt)

    Visibility:   default

Description:     LineRel  draws  a  line  starting  from  the  current  pointer  position  to  the  point(DX,DY),
                \textbf{relative}  to  the  current  position,  in  the  current  line  style  and  color.  The  Current
                Position is set to the endpoint of the line.

       Errors:   None.

    See also:    Line (666  ), LineTo (678  )



                18.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, \textbf{relative}
                to the current position,  in the current line style and color.  The Current position is set to
                the end of the line.

       Errors:   None.

    See also:    LineRel (678  ), Line (666  )



                18.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 (679  )



                                                                                 678

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (678  )



                18.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 (666  )



                18.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 (667  ), Circle (665  ), Sector (681  )



                18.13.46           queryadapterinfo

    Synopsis:    Function called to retrieve the current video adapter settings.

Declaration:     function  queryadapterinfo  :  PModeInfo

    Visibility:   default



                                                                                 679

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (667  ), Bar3D (668  )



                18.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 (677  ), RegisterBGIFont (680  )



                18.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 (678  ), RegisterBGIDriver (680  )



                18.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 (677  )



                                                                                 680

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (667  ), Circle (665  ), PieSlice (679  )



                18.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 (677  ), GetAspectRatio (670  )



                18.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 (671  ), SetBkColor (667  ), SetWriteMode (685  )



                18.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.



                                                                                 681

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (672  ), SetFillStyle (682  ), SetWriteMode (685  )



                18.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 (682  ), SetWriteMode (685  )



                18.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 (677  )



                                                                                 682

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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:


                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 (672  ), SetWriteMode (685  )



                18.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 (666  ), SetRGBPalette (667  )



                18.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.



                                                                                 683

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                RightText       Text is set to the right of the pointer.


                Vertical controls the vertical placement of the text, relative to the (graphical) cursor posi-
                tion.  Its value can be one of the following pre-defined constants :


                BottomText         Text is placed under the pointer.

                CenterText       Text is placed centered vertically on the pointer.

                TopText      Text is placed above the pointer.


       Errors:   None.

    See also:    OutText (679  ), OutTextXY (666  )



                18.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 (675  )



                                                                                 684

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (684  )



                18.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 (675  )



                18.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 (681  ), SetBkColor (667  ), SetLineStyle (683  ), SetFillStyle (682  )



                                                                                 685

                ___________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'GRAPH'________________*
 *___________________



                18.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 (686  )



                18.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.

       Errors:   None.

    See also:    TextHeight (686  )



                                                                                 686




Chapter   19



Reference   for   unit   'heaptrc'



19.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.



19.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 (689  ) variable is set to True

disabled       If this string occurs, then the UseHeapTrace (690  ) 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  (689  )  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 (692  ))


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.



                                                             687

_______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________________________*
 *___



19.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 ) ;



                                                                 688

_______________________________________________________CHAPTER_19.___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___._______________________________________________________________________________________________________________________



19.4          Constants,  types  and  variables



19.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 (690  ) 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 (690  ) or printfaultyblock (689  ) 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 (689  ) bytes of
the memory block will be printed.


printleakedblock  :  Boolean  =  False



                                                                 689

                _______________________________________________________CHAPTER_19.___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 (689  ) 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.



                19.4.2         Types

                tdisplayextrainfoProc  =  procedure(var  ptext:  text;p:  pointer)


                The TDisplayExtraInfoType is a procedural type used in the SetHeapExtraInfo (691  ) call
                to display a memory location which was previously filled with TFillExtraInfoProc (690  )


                tFillExtraInfoProc  =  procedure(p:  pointer)


                The TFillExtraInfoProc is a procedural type used in the SetHeapExtraInfo (691  ) call to
                fill a memory location with extra data for displaying.



                19.5          Procedures  and  functions



                19.5.1         DumpHeap

    Synopsis:    Dump memory usage report to stderr.

Declaration:     procedure  DumpHeap

    Visibility:   default



                                                                                 690

                _______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________*
 *___________________



Description:     DumpHeap dumps to standard output a summary of memory usage.  It is called automatically
                by the heaptrc unit when your program exits (by installing an exit procedure), but it can be
                called at any time.

       Errors:   None.

    See also:    MarkHeap (1 )



                19.5.2         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 (690  ) is executed.

    See also:    DumpHeap (690  ), SetHeapTraceOutput (692  )


                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;


                 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  ) ;



                                                                                 691

                _______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'HEAPTRC'__________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                19.5.3         SetHeapTraceOutput

    Synopsis:    Specify filename for heap trace output.

Declaration:     procedure  SetHeapTraceOutput(const  name:  string)

    Visibility:   default

Description:     SetHeapTraceOutput  sets  the  filename  into  which  heap  trace  info  will  be  written.   By
                default information is written to standard output,  this function allows you to redirect the
                information to a file with full filename name.

       Errors:   If the file cannot be written to, errors will occur when writing the trace.

    See also:    SetHeapExtraInfo (691  )



                                                                                 692




Chapter   20



Reference   for   unit   'ipc'



20.1          Used  units



                                       Table 20.1:  Used units by unit 'ipc'


                                                 __Name______________Page____
                                                   BaseUnix           102
                                                   System            1230
                                                   UnixType          1715



20.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.



20.3          Constants,  types  and  variables



20.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



                                                             693

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



IPC_NOWAIT  =  4  shl  9


return error on wait


IPC_RMID  =  0


Remove resource


IPC_SET  =  1


set ipc_perm options


IPC_STAT  =  2


get ipc_perm options


MSGMAX  =  4056


Internal Message control code.  Do not use


MSGMNB  =  16384


Internal Message control code.  Do not use


MSGMNI  =  128


Internal Message control code.  Do not use


MSG_EXCEPT  =  2  shl  12


Internal Message control code.  Do not use


MSG_NOERROR  =  1  shl  12


Internal Message control code.  Do not use


SEM_GETALL  =  13


Semaphore operation:  Get all semaphore values


SEM_GETNCNT  =  14


Semaphore operation:  Get number of processes waiting for resource.


SEM_GETPID  =  11


Semaphore operation:  Get process ID of last operation.


SEM_GETVAL  =  12


Semaphore operation:  Get current value of semaphore



                                                                 694

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



SEM_GETZCNT  =  15


Semaphore operation:  Get number of processes waiting for semaphores to reach zero


SEM_SEMMNI  =  128


Semaphore operation:  ?


SEM_SEMMNS  =  SEM_SEMMNI  *  SEM_SEMMSL


Semaphore operation:  ?


SEM_SEMMSL  =  32


Semaphore operation:  ?


SEM_SEMOPM  =  32


Semaphore operation:  ?


SEM_SEMVMX  =  32767


Semaphore operation:  ?


SEM_SETALL  =  17


Semaphore operation:  Set all semaphore values


SEM_SETVAL  =  16


Semaphore operation:  Set semaphore value


SEM_UNDO  =  $1000


Constant for use in semop (709  )


SHM_LOCK  =  11


This constant is used in the shmctl (711  ) call.


SHM_R  =  4  shl  6


This constant is used in the shmctl (711  ) call.


SHM_RDONLY  =  1  shl  12


This constant is used in the shmctl (711  ) call.


SHM_REMAP  =  4  shl  12


This constant is used in the shmctl (711  ) call.



                                                                 695

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



SHM_RND  =  2  shl  12


This constant is used in the shmctl (711  ) call.


SHM_UNLOCK  =  12


This constant is used in the shmctl (711  ) call.


SHM_W  =  2  shl  6


This constant is used in the shmctl (711  ) call.



20.3.2         Types

key_t  =  TKey


Alias for TKey (697  ) type


msglen_t  =  culong


Message length type


msgqnum_t  =  culong


Message queue number type


PIPC_Perm  =  ^TIPC_Perm


Pointer to TIPC_Perm (697  ) record.


PMSG  =  ^TMSG


Pointer to TMSG (697  ) record


PMSGbuf  =  ^TMSGbuf


Pointer to TMsgBuf (698  ) rcord


PMSGinfo  =  ^TMSGinfo


Pointer to TMSGinfo (698  ) record


PMSQid_ds  =  ^TMSQid_ds


Pointer to TMSQid_ds (698  )


PSEMbuf  =  ^TSEMbuf


Pointer to TSembuf (698  ) record.



                                                                 696

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



PSEMid_ds  =  ^TSEMid_ds


Pointer to TSEMid_ds (699  ) record.


PSEMinfo  =  ^TSEMinfo


Pointer to TSEMinfo (699  ) record.


PSEMun  =  ^TSEMun


Pointer to TSEMun (699  ) record


PShmid_DS  =  ^TShmid_ds


Pointer to TSHMid_ds (699  ) 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 (700  ) key generating function.


TMSG  =  record
   msg_next  :  PMSG;
   msg_type  :  LongInt;
   msg_spot  :  PChar;
   msg_stime  :  LongInt;
   msg_ts  :  Integer;
end



Record used in the handling of message queues.  Do not use directly.


TMSGbuf  =  record
   mtype  :  clong;
   mtext  :  Array[0..0]  of  Char;
end



                                                                 697

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



The TMSGbuf record is a record containing the data of a record.  you should never use this
record directly, instead you should make your own record that follows the structure of the
TMSGbuf record, but that has a size that is big enough to accomodate your messages.  The
mtype field should always be present, and should always be filled.


TMSGinfo  =  record
   msgpool  :  cint;
   msgmap  :  cint;
   msgmax  :  cint;
   msgmnb  :  cint;
   msgmni  :  cint;
   msgssz  :  cint;
   msgtql  :  cint;
   msgseg  :  cushort;
end



Internal message system record.  Do not use directly.


TMSQid_ds  =  record
   msg_perm  :  TIPC_Perm;
   msg_first  :  PMSG;
   msg_last  :  PMSG;
   msg_stime  :  time_t;
   msg_rtime  :  time_t;
   msg_ctime  :  time_t;
   msg_cbytes  :  Word;
   msg_qnum  :  Word;
   msg_qbytes  :  Word;
   msg_lspid  :  ipc_pid_t;
   msg_lrpid  :  ipc_pid_t;
end



This  record  should  never  be  used  directly,  it  is  an  internal  kernel  record.   It's  fields  may
change at any time.


TSEMbuf  =  record
   sem_num  :  cushort;
   sem_op  :  cshort;
   sem_flg  :  cshort;
end



The TSEMbuf record is used in the semop (709  ) call, and is used to specify which operations
you want to do.


TSEMid_ds  =  record
   sem_perm  :  TIPC_Perm;
   sem_otime  :  time_t;
   sem_ctime  :  time_t;
   sem_base  :  pointer;
   sem_pending  :  pointer;



                                                                 698

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



   sem_pending_last  :  pointer;
   undo  :  pointer;
   sem_nsems  :  cushort;
end



Structure returned by the semctl (704  ) call, contains all data of a semahore


TSEMinfo  =  record
   semmap  :  cint;
   semmni  :  cint;
   semmns  :  cint;
   semmnu  :  cint;
   semmsl  :  cint;
   semopm  :  cint;
   semume  :  cint;
   semusz  :  cint;
   semvmx  :  cint;
   semaem  :  cint;
end



Internal semaphore system record.  Do not use.


TSEMun  =  record
end



Record used in semctl (704  ) call.


TShmid_ds  =  record
   shm_perm  :  TIPC_Perm;
   shm_segsz  :  size_t;
   shm_atime  :  time_t;
   shm_dtime  :  time_t;
   shm_ctime  :  time_t;
   shm_cpid  :  pid_t;
   shm_lpid  :  pid_t;
   shm_nattch  :  culong;
   __unused4  :  culong;
   __unused5  :  culong;
end



Record used in the shmctl (711  ) call to set or retrieve settings for shared memory.


TSHMinfo  =  record
   shmmax  :  cint;
   shmmin  :  cint;
   shmmni  :  cint;
   shmseg  :  cint;
   shmall  :  cint;
end



Record used by the shared memory system, Do not use directly.



                                                                 699

                _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                20.4          Procedures  and  functions



                20.4.1         ftok

    Synopsis:    Create token from filename

Declaration:     function  ftok(Path:  PChar;ID:  cint)  :  TKey

    Visibility:   default

Description:     ftok returns a key that can be used in a semget (709  )shmget (713  ) or msgget (702  ) 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 (700  ), semctl (704  ) or shmctl (711  ).

       Errors:   ftok returns -1 if the file in Path doesn't exist.

    See also:    semget (709  ), shmget (713  ), msgget (702  )



                20.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 (702  ), msgsnd (704  ), msgrcv (703  )


                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 ] ;



                                                                                 700

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



    end  ;


 P r o c e d u r eD o E r r o r ( Const     Msg    :   s t r i n g) ;


 b e g i n
    W r i t e l n (msg   , '  r e t u r n e d an   e r r o r  :  ' , f p g e t e r r n)o;
    h a l t( 1 ) ;
end   ;


 P r o c e d u r eS e n d M e s s a g e( I d  :  L o n g i n t;
                                        Var     Buf    :  TMyMsgBuf       ;
                                        MType      :   L o n g i n t;
                                         Const     MText      :  S t r i n g) ;


 b e g i n
    W r i t e l n ( 'S e n d i n g m e s s a g e. ') ;
    Buf  . mtype    := mtype    ;
    Buf  . Mtext    := m t e x t;
    I f    msgsnd    ( I d ,PMsgBuf      (@Buf   ) , 2 5 6 , 0 ) = - 1then
        D o E r r o r('msgsnd     ' ) ;
end   ;


 P r o c e d u r eReadMessage          ( ID   :  L o n g i n t;
                                        Var     Buf    :  TMyMsgBuf       ;
                                        MType      :   l o n g i n t) ;


 b e g i n
    W r i t e l n ( 'R e a d i n g m e s s a g e. ') ;
    Buf  . MType    := MType    ;
    I f  m s g r c v(ID  ,PMSGBuf      (@Buf    ) , 2 5 6 ,mtype   ,0)<>-1       then
        W r i t e l n(  'Type     :  ' , b u f.mtype    , '   T e x t :   ' ,b u f .m t e x t)
    e l s e
        D o E r r o r(  'm s g r c v') ;
end   ;


 P r o c e d u r eRemoveQueue          (  ID    :  L o n g i n t) ;


 b e g i n
    I f  m s g c t l ( i d ,IPC _RMID      ,N i l)<>-1      then
        W r i t e l n(  'Removed       Queue     w i t h  i d   ', I d) ;
end   ;


 P r o c e d u r eChangeQueueMode             (ID  , mode     :  l o n g i n t) ;


Var    QueueDS        :  TMSQid _ds      ;


 b e g i n
    I f    m s g c t l ( I d ,IPC _STAT     , @QueueDS      )=-1    then
        D o E r r o r(  'm s g c t l :   s t a t' ) ;
    W r i t e l n ( 'Old     p e r m i s s i o n s:  ' ,QueueDS      .msg _perm     . mode   ) ;
    QueueDS     . msg _perm     .mode   :=  Mode   ;
    i f  m s g c t l ( ID  ,IPC _SET     ,@QueueDS      )=0    then
        W r i t e l n(  'New    p e r m i s s i o n s:   ', QueueDS     . msg _perm     .mode   )
    e l s e
      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;



                                                                 701

            _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'________________*
 *_______________



             b e g i n
                W r i t e l n ( 'Usage      :  m s g t o o l s ( end  )       <  t y p e> <  t e x t>  ( max    2 5 5  c h a r a c *
 *t e r)s' ) ;
                W r i t e l n ( '                            r ( e c e i v e)  < t y p e> ') ;
                W r i t e l n ( '                            d ( e l e t e) ') ;
                W r i t e l n ( '                            m ( ode  )  < d e c i m a l mode   > ' ) ;
                h a l t( 1 ) ;
            end   ;


             F u n c t i o nS t r T o I n t (S   :   S t r i n g) :  l o n g i n t;


            Var    M   :   l o n g i n t;
                   C   :   I n t e g e r;


             b e g i n
                v a l  (S  ,M ,C  ) ;
                I f  C <>0    Then     D o E r r o r(  'S t r T o I n t :   '+ S ) ;
                S t r T o I n t:=M ;
            end   ;


            Var
                Key    :  TKey    ;
                ID     :   l o n g i n t;
                Buf    :  TMyMsgBuf       ;


             c o n s t i p c k e y =   ' . '#0;


             b e g i n
                I f  Paramcount        <1   then     Usage    ;
                k e y  : =F t o k( @ i p c k e y[ 1 ] ,o r d( 'M ' ) ) ;
                ID :=  m s g g e t(key   ,IPC_CREAT         o r  4 3 8 ) ;
                I f  ID  <0   then     D o E r r o r(  'MsgGet     ' ) ;
                Case     upCase    ( Paramstr      ( 1 ) [ 1 ] ) o f
                  'S  '  :  I f  ParamCount        <>3    then
                                Usage
                            e l s e
                                S e n d M e s s a g e(i d ,Buf   , S t r T o I n t(Paramstr     ( 2 ) ) ,p a r a m s t r( 3 ) ) ;
                  'R  '  :  I f  ParamCount        <>2    then
                                Usage
                            e l s e
                                ReadMessage         ( i d , b u f, s t r t o i n t(Paramstr     ( 2 ) ) ) ;
                  'D  '  :  I f  ParamCount        <>1    then
                                Usage
                            e l s e
                                RemoveQueue         ( ID  ) ;
                  'M  '  :  I f  ParamCount        <>2    then
                                Usage
                            e l s e
                                ChangeQueueMode            ( i d , s t r t o i n t(p a r a m s t(r2 ) ) ) ;
                  e l s e
                     Usage
                  end  ;
            end___.________________________________________________________________________________________________________________*
 *_______



            20.4.3         msgget

Synopsis:    Return message queue ID, possibly creating the queue



                                                                             702

                _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



Declaration:     function  msgget(key:  TKey;msgflg:  cint)  :  cint

    Visibility:  default

Description:     msgget returns the ID of the message queue described by key.  Depending on the flags in
                msgflg, a new queue is created.

                msgflg can have one or more of the following values (combined by ORs):


                IPC__CREAT          The queue is created if it doesn't already exist.

                IPC__EXCL        If used in combination with IPC_CREAT, causes the call to fail if the queue already
                      exists.  It cannot be used by itself.


                Optionally, the flags can be ORed with a permission mode, which is the same mode that can
                be used in the file system.

                For an example, see msgctl (700  ).

       Errors:   On error, -1 is returned, and IPCError is set.

    See also:    ftok (700  ), msgsnd (704  ), msgrcv (703  ), msgctl (700  )



                20.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  immediatly,  with  the
                       ENOMSG error.

                MSG__NOERROR                If the message size is wrong (too large), no error is generated, instead
                       the message is truncated.  Normally, in such cases, the call returns an error (E2BIG)


                The function returns True if the message was received correctly, False otherwise.

                For an example, see msgctl (700  ).

       Errors:   In case of error, False is returned, and IPCerror is set.

    See also:    msgget (702  ), msgsnd (704  ), msgctl (700  )



                                                                                 703

                _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                20.4.5         msgsnd

    Synopsis:    Send a message to the messague queue

Declaration:     function  msgsnd(msqid:  cint;msgp:  PMSGbuf;msgsz:  size_t;msgflg:  cint)
                                           :  cint

    Visibility:   default

Description:     msgsend sends a message to a message queue with ID msqid.  msgp is a pointer to a message
                buffer, that should be based on the TMsgBuf type.  msgsiz is the size of the message (NOT
                of the message buffer record !)

                The msgflg can have a combination of the following values (ORed together):


                0 No special meaning.  The message will be written to the queue.  If the queue is full, then
                       the process is blocked.

                IPC__NOWAIT            If the queue is full, then no message is written, and the call returns imme-
                       diatly.


                The function returns True if the message was sent successfully, False otherwise.

                For an example, see msgctl (700  ).

       Errors:   In case of error, the call returns False, and IPCerror is set.

    See also:    msgget (702  ), msgrcv (703  ), msgctl (700  )



                20.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.



                                                                                 704

            _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'________________*
 *_______________



            IPC__SET      In  this  case,  the  arg  record  should  have  it's  buf  field  set  to  the  address  of  a
                  TSEMid_ds record.  The semctl call sets the permissions of the queue as specified in the
                  ipc_perm record.

            IPC__RMID         If this is specified, the semaphore set is removed from from the system.

            GETALL        In this case, the arr field of arg should point to a memory area where the values
                  of the semaphores will be stored.  The size of this memory area is \var{SizeOf(Word)*
                  Number of semaphores in the set}.  This call will then fill the memory array with all
                  the values of the semaphores.

            GETNCNT           This will fill the val field of the arg union with the number of processes waiting
                  for resources.

            GETPID        semctl returns the process ID of the process that performed the last semop (709  )
                  call.

            GETVAL        semctl returns the value of the semaphore with number semnum.

            GETZCNT          semctl returns the number of processes waiting for semaphores that reach value
                  zero.

            SETALL       In  this  case,  the  arr  field  of  arg  should  point  to  a  memory  area  where  the
                  values  of  the  semaphores  will  be  retrieved  from.   The  size  of  this  memory  area  is
                  \var{SizeOf(Word)*  Number  of  semaphores  in  the  set}.   This  call  will  then  set  the
                  values of the semaphores from the memory array.

            SETVAL        This will set the value of semaphore semnum to the value in the val field of the
                  arg parameter.


            The function returns -1 on error.

   Errors:   The function returns -1 on error, and IPCerror is set accordingly.

See also:    semget (709  ), semop (709  )


            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   ;



                                                                             705

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



 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
       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   ;



                                                                 706

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



      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) ;


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



                                                                 707

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



        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 ) ;
    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



                                                                 708

                _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                                 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
                                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___.____________________________________________________________________________________________________________*
 *___________



                20.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 (700  ), semop (709  ), semctl (704  )



                20.4.8         semop

    Synopsis:    Perform semaphore operation.

Declaration:     function  semop(semid:  cint;sops:  PSEMbuf;nsops:  cuint)  :  cint



                                                                                 709

                _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



    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 (698  ) structure


                TSEMbuf  =  record
                      sem_num  :  word;
                      sem_op    :  integer;
                      sem_flg  :  integer;


                should be filled as follows:


                sem__num      The number of the semaphore in the set on which the operation must be performed.

                sem__op    The operation to be performed.  The operation depends on the sign of  sem_op:  A
                      positive number is simply added to the current value of the semaphore.  If 0 (zero) is
                      specified, then the process is suspended until the specified semaphore reaches zero.  If a
                      negative number is specified, it is substracted from the current value of the semaphore.
                      If the value would become negative then the process is suspended until the value becomes
                      big enough, unless IPC_NOWAIT is specified in the sem_flg.

                sem__flg   Optional  flags:  if  IPC_NOWAIT  is  specified,  then  the  calling  process  will  never  be
                      suspended.


                The function returns True if the operations were successful, False otherwise.

       Errors:   In case of error, False is returned, and IPCerror is set.

    See also:    semget (709  ), semctl (704  )



                20.4.9         semtimedop

    Synopsis:    Perform semaphore operation using timeout.

Declaration:     function  semtimedop(semid:  cint;sops:  PSEMbuf;nsops:  cuint;
                                                timeOut:  ptimespec)  :  cint

    Visibility:   default

Description:     semop performs a set of operations on a message queue, just as semop (709  ).  sops points to
                an array of type TSEMbuf.  The array should contain nsops elements.  The timeOut argument
                points to a time specification:  if the operations cannot be performed withing the specified,
                time, the function will return with an error.

                For more information on the actual operations, see semop (709  ).

    See also:    semop (709  )



                20.4.10          shmat

    Synopsis:    Attach a shared memory block.

Declaration:     function  shmat(shmid:  cint;shmaddr:  pointer;shmflg:  cint)  :  pointer

    Visibility:   default



                                                                                 710

                _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



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 (711  ).

       Errors:   If an error occurs, -1 is returned, and IPCerror is set.

    See also:    shmget (713  ), shmdt (713  ), shmctl (711  )



                20.4.11          shmctl

    Synopsis:    Perform control operations on a shared memory block.

Declaration:     function  shmctl(shmid:  cint;cmd:  cint;buf:  PShmid_DS)  :  cint

    Visibility:   default

Description:     shmctl  performs  various  operations  on  the  shared  memory  block  identified  by  identifier
                shmid.

                The buf parameter points to a TSHMid_ds record.  The cmd parameter is used to pass which
                operation is to be performed.  It can have one of the following values :


                IPC__STAT        shmctl fills the TSHMid_ds record that buf points to with the available informa-
                       tion about the shared memory block.

                IPC__SET       applies the values in the ipc_perm record that buf points to, to the shared memory
                       block.

                IPC__RMID         the shared memory block is destroyed (after all processes to which the block is
                       attached, have detached from it).


                If successful, the function returns True, False otherwise.

       Errors:   If an error occurs, the function returns False, and IPCerror is set.

    See also:    shmget (713  ), shmat (710  ), shmdt (713  )


                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 ;



                                                                                 711

_________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________________________*
 *___



 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') ;
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   ;



                                                                 712

                _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



                 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
                        w r i t e l n( p a r a m s t r( 1 ) ) ;
                        u s a g e;
                       end   ;
                    end  ;
                end___.____________________________________________________________________________________________________________*
 *___________



                20.4.12          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 (710  ).

                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 (713  ), shmat (710  ), shmctl (711  )



                20.4.13          shmget

    Synopsis:    Return the ID of a shared memory block, possibly creating it



                                                                                 713

                _________________________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'IPC'____________*
 *___________________



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.



                                                                                 714




Chapter   21



Reference   for   unit   'keyboard'



21.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 (729  ) function, which will return a driver-dependent key
event.  This key event can be translated to a interpretable event by the TranslateKeyEvent
(738  ) 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 (737  ) function.  The
current keyboard driver can be retrieved using the GetKeyboardDriver (729  ) function.  The
last section of this chapter demonstrates how to make a keyboard driver.



21.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.



                                                             715

____________________________________________________CHAPTER_21.___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.



21.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;



                                                                 716

____________________________________________________CHAPTER_21.___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 (729  ).  Must wait for and return the next key event.
       It should NOT store keys.

PollKeyEvent           Called by PollKeyEvent (734  ).  It must return the next key event if there is
       one.  Should not store keys.

GetShiftState          Called by PollShiftStateEvent (735  ).  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;



                                                                 717

____________________________________________________CHAPTER_21.___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;



                                                                 718

____________________________________________________CHAPTER_21.___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___._______________________________________________________________________________________________________________________



21.4          Keyboard  scan  codes


Special physical keys are encoded with the DOS scan codes for these keys in the second byte
of the TKeyEvent (726  ) 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.



                                                                 719

____________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



                                             Table 21.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



                                                                 720

____________________________________________________CHAPTER_21.___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 21.2:  Special keys scan codes


                       _Key______________Code_______SHIFT-Key___________CTRL-Key___________Alt-Key_______
                         NoKey            00
                         F1               3B        54                  5E                 68
                         F2               3C        55                  5F                 69
                         F3               3D        56                  60                 6A
                         F4               3E        57                  61                 6B
                         F5               3F        58                  62                 6C
                         F6               40        59                  63                 6D
                         F7               41        5A                  64                 6E
                         F8               42        5A                  65                 6F
                         F9               43        5B                  66                 70
                         F10              44        5C                  67                 71
                         F11              85        87                  89                 8B
                         F12              86        88                  8A                 8C
                         Home             47                            77                 97
                         Up               48                            8D                 98
                         PgUp             49                            84                 99
                         Left             4B                            73                 9B
                         Center           4C                            8F
                         Right            4D                            74                 9D
                         end              4F                            75                 9F
                         Down             50                            91                 A0
                         PgDn             51                            76                 A1
                         Ins              52        05                  04                 A2
                         Del              53        07                  06                 A3
                         Tab              8         0F                  94                 A5
                         GreyPlus                                       90                 4E



21.5          Constants,  types  and  variables



21.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



                                                                 721

____________________________________________________CHAPTER_21.___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



                                                                 722

____________________________________________________CHAPTER_21.___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



                                                                 723

____________________________________________________CHAPTER_21.___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



                                                                 724

____________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



function key pressed.


kbLeftShift  =  1


Left shift key modifier


kbPhys  =  $03


Physical key code event


kbReleased  =  $04


Key release event


kbRightShift  =  2


Right shift key modifier


kbShift  =  kbLeftShift  or  kbRightShift


Shift key modifier


kbUniCode  =  $01


Unicode code key event


SAnd  :  string  =  'AND'


This constant is used as the 'And' word in key descriptions.  This constant is used by the key
event description routines.  It can be changed to localize the key descriptions when needed.


ShiftPrefix  :  Byte  =  0


Keycode for alternate prefix key for Shift key.  Unix Only


SKeyPad  :  Array[0..($FF2F-kbdHome)]  of    =  ('Home',  'Up',  'PgUp',  'Left',  'Middle',  'Right',  'End',  'Down',  'PgDn',  '*
 *Insert',  'Del@


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    =  ('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.



                                                                 725

____________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________________________*
 *___



SShift  :  Array[1..3]  of    =  ('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.



21.5.2         Types

PTreeElement  =  ^TTreeElement


Pointer to TTreeElement (727  ) 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 (737  ) function.

The various fields correspond to the different functions of the keyboard unit interface.  For
more information about this record see kbddriver (716  )


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
(727  ) type.


TKeyRecord  =  packed  record
    KeyCode  :  Word;
    ShiftState  :  Byte;
    Flags  :  Byte;
end



                                                                 726

                ____________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                The structure of a TKeyRecord structure is explained in the following table:



                                                     Table 21.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@
                  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 (727  ) on unix platforms.  There should be no need to
                handle records of this type.



                21.6          Procedures  and  functions



                21.6.1         AddSequence

Declaration:     procedure  AddSequence(const  St:  string;AChar:  Byte;AScan:  Byte)

    Visibility:   default



                21.6.2         AddSpecialSequence

    Synopsis:    Add a handler for a special key sequence



                                                                                 727

                ____________________________________________________CHAPTER_21.___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 (727  )



                21.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
                (733  ).   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 (733  )



                21.6.4         FindSequence

Declaration:     function  FindSequence(const  St:  string;var  AChar:  Byte;var  Ascan:  Byte)
                                                     :  Boolean

    Visibility:   default



                21.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 (738  ), KeyEventToString (734  )



                                                                                 728

                ____________________________________________________CHAPTER_21.___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___.____________________________________________________________________________________________________________*
 *___________



                21.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 (716  ).

       Errors:   None.

    See also:    SetKeyboardDriver (737  )



                21.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 (734  ).

                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  (738  )  or  TranslateKeyEventUniCode  (738  ).   See
                the types section for a description of how the key is described.



                                                                                 729

                ____________________________________________________CHAPTER_21.___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 (736  ), PollKeyEvent (734  ), TranslateKeyEvent (738  ), TranslateKeyEventU-
                niCode (738  )


                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___.____________________________________________________________________________________________________________*
 *___________



                21.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 (729  )

       Errors:   None.

    See also:    GetKeyEventUniCode (732  ), GetKeyEventShiftState (732  ), GetKeyEventFlags (731  ), GetKeyEvent-
                Code (731  ), GetKeyEvent (729  )



                                                                                 730

                ____________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                21.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 (732  ), GetKeyEventShiftState (732  ), GetKeyEventFlags (731  ), GetKeyEventChar
                (730  ), GetKeyEvent (729  )


                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___.____________________________________________________________________________________________________________*
 *___________



                21.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 (729  )

       Errors:   None.

    See also:    GetKeyEventUniCode (732  ), GetKeyEventShiftState (732  ), GetKeyEventCode (731  ), GetKeyEventChar
                (730  ), GetKeyEvent (729  )



                                                                                 731

                ____________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                21.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 (732  ), GetKeyEventFlags (731  ), GetKeyEventCode (731  ), GetKeyEventChar
                (730  ), GetKeyEvent (729  )


                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___.____________________________________________________________________________________________________________*
 *___________



                21.6.12          GetKeyEventUniCode

    Synopsis:    Return the unicode key event.

Declaration:     function  GetKeyEventUniCode(KeyEvent:  TKeyEvent)  :  Word

    Visibility:   default



                                                                                 732

                ____________________________________________________CHAPTER_21.___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 (732  ), GetKeyEventFlags (731  ), GetKeyEventCode (731  ), GetKeyEventChar
                (730  ), GetKeyEvent (729  )



                21.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 (728  ) function should also be called before exiting the program or
                changing the keyboard driver with SetKeyboardDriver (737  ).

                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 (728  ), SetKeyboardDriver (737  )



                21.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 (729  )


                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       ;



                                                                                 733

                ____________________________________________________CHAPTER_21.___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___.____________________________________________________________________________________________________________*
 *___________



                21.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 (728  ), ShiftStateToString (738  )



                21.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 (734  ) and
                checks for a valid result.

       Errors:   None.

    See also:    PollKeyEvent (734  ), GetKeyEvent (729  )



                21.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 (729  ) function.



                                                                                 734

                ____________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



       Errors:   None.

    See also:    PutKeyEvent (736  ), GetKeyEvent (729  )


                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___.____________________________________________________________________________________________________________*
 *___________



                21.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 (734  ), GetKeyEvent (729  )


                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       ;



                                                                                 735

                ____________________________________________________CHAPTER_21.___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___.____________________________________________________________________________________________________________*
 *___________



                21.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 (734  ), GetKeyEvent (729  )


                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



                                                                                 736

                ____________________________________________________CHAPTER_21.___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___.____________________________________________________________________________________________________________*
 *___________



                21.6.20          RawReadKey

Declaration:     function  RawReadKey  :  Char

    Visibility:   default



                21.6.21          RawReadString

Declaration:     function  RawReadString  :  string

    Visibility:   default



                21.6.22          RestoreStartMode

Declaration:     procedure  RestoreStartMode

    Visibility:   default



                21.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 (728  ).

                The function returns True if the driver was set, False if not.

                For more information on setting the keyboard driver, see kbddriver (716  ).

       Errors:   None.

    See also:    GetKeyboardDriver (729  ), DoneKeyboard (728  )



                                                                                 737

                ____________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'KEYBOARD'____________________*
 *___________________



                21.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 (735  ).

       Errors:   None.

    See also:    FunctionKeyName (728  ), KeyEventToString (734  )



                21.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 (729  )

       Errors:   None.

    See also:    TranslateKeyEventUniCode (738  )



                21.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 (738  )



                                                                                 738




                Chapter   22



                Reference   for   unit   'lineinfo'



                22.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 (759  ) unit must be used.



                22.2          Procedures  and  functions



                22.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 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.



                                                                             739




Chapter   23



Reference   for   unit   'Linux'



23.1          Used  units



                                     Table 23.1:  Used units by unit 'Linux'


                                                  _Name_____________Page______
                                                    BaseUnix           102
                                                    System           1230
                                                    unixtype         1715



23.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 (1677   ), baseunix (102  ) and unixutil (1729   ) units.

The X86-specific parts have been moved to the X86 (1763   ) unit.

People wanting to use the old version (FPC 1.0.X and before) of the linux can use the oldlinux
(1010   ) unit instead.



23.3          Constants,  types  and  variables



23.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



                                                             740

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



Perform chown operation


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



                                                                 741

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



Allow binding to ports less than 1024


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



                                                                 742

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



Allow raw I/O port operations


CAP_SYS_RESOURCE  =  24


Allow use of special resources or raising of resource limits


CAP_SYS_TIME  =  25


Allow system or real-time clock modification


CAP_SYS_TTY_CONFIG  =  26


Allow vhangup calls


CLONE_CHILD_CLEARTID  =  $00200000


Clone option:  Erase child thread ID in child memory space when child exits.


CLONE_CHILD_SETTID  =  $01000000


Clone option:  Store child thread ID in child memory.


CLONE_DETACHED  =  $00400000


Clone option:  Start clone detached.


CLONE_FILES  =  $00000400


Clone (102  ) option:  open files shared between processes


CLONE_FS  =  $00000200


Clone (102  ) 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 (102  ) option:  PID shared between processes


CLONE_PTRACE  =  $00002000



                                                                 743

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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 (102  ) option:  signal handlers shared between processes


CLONE_STOPPED  =  $02000000


Clone option:  Start child in stopped state.


CLONE_SYSVSEM  =  $00040000


Clone option:  Caller and child share the same semaphore undo values


CLONE_THREAD  =  $00010000


Clone options:  Set child in thread group of calling process.


CLONE_UNTRACED  =  $00800000


Clone option:  Do not allow a ptrace call on this clone.


CLONE_VFORK  =  $00004000


Clone options:  suspend parent till child execs


CLONE_VM  =  $00000100


Clone (102  ) option:  VM shared between processes


CSIGNAL  =  $000000ff


Clone (102  ) 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



                                                                 744

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


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



                                                                 745

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


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



                                                                 746

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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.


GIO_FONTX  =  $4B6B


IOCTL: Get font in consolefontdesc record.


GIO_SCRNMAP  =  $4B40


IOCTL: get screen mapping from kernel


GIO_UNIMAP  =  $4B66


IOCTL: get unicode-to-font mapping from kernel


GIO_UNISCRNMAP  =  $4B69


IOCTL: get full Unicode screen mapping


KB_101  =  2


IOCTL: Keyboard types:  101 keys


KB_84  =  1


IOCTL: Keyboard types:  84 keys


KB_OTHER  =  3


IOCTL: Keyboard types:  other type


KDADDIO  =  $4B34


IOCTL: add i/o port as valid


KDDELIO  =  $4B35


IOCTL: delete i/o port as valid


KDDISABIO  =  $4B37



                                                                 747

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


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



                                                                 748

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


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



                                                                 749

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


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



                                                                 750

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



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


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.



23.3.2         Types

EPoll_Data  =  record
end



Data structure used in EPOLL IOCTL call.


EPoll_Event  =  record
    Events  :  cuint32;
    Data  :  TEPoll_Data;
end



Structure used in epoll_ctl (754  ) call.


PEPoll_Data  =  ^EPoll_Data



                                                                 751

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



Pointer to EPoll_Data (751  ) record


PEpoll_Event  =  ^EPoll_Event


Pointer to EPoll_Event (751  ) type


PSysInfo  =  ^TSysInfo


Pointer to TSysInfo (752  ) record.


Puser_cap_data  =  ^user_cap_data


Pointer to user_cap_data (753  ) record


Puser_cap_header  =  ^user_cap_header


Pointer to user_cap_header (753  ) record


TCloneFunc  =  function(args:  pointer)  :  LongInt  of  object


Clone function prototype.


TEPoll_Data  =  EPoll_Data


Alias for EPoll_Data (751  ) type


TEPoll_Event  =  EPoll_Event


Alias for EPoll_Event (751  ) type


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 (757  ) call.



                                                                 752

                _____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                user_cap_data  =  packed  record
                   effective  :  Cardinal;
                   permitted  :  Cardinal;
                   inheritable  :  Cardinal;
                end



                user_cap_data describes the set of capabilities for the indicated thread.


                user_cap_header  =  packed  record
                   version  :  Cardinal;
                   pid  :  Cardinal;
                end



                user_cap_header describes the root user capabilities for the current thread, as set by getcap
                (102  ) and setcap (102  )



                23.4          Procedures  and  functions



                23.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 (753  )



                23.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 (753  )



                                                                                 753

                _____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                23.4.3         epoll__create

    Synopsis:    Create new epoll file descriptor

Declaration:     function  epoll_create(size:  cint)  :  cint

    Visibility:   default

Description:     epoll_create creates a new epoll file descriptor.  The size argument indicates to the kernel
                approximately how many structures should be allocated, but is by no means an upper limit.

                On  success,  a  file  descriptor  is  returned  that  can  be  used  in  subsequent  epoll_ctl  (754  )  or
                epoll_wait (755  ) calls, and should be closed using the fpClose (146  ) call.

       Errors:   On error, -1 is returned, and errno (156  ) is set.

    See also:    epoll_ctl (754  ), epoll_wait (755  ), fpClose (146  )



                23.4.4         epoll__ctl

    Synopsis:    Modify an epoll file descriptor

Declaration:     function  epoll_ctl(epfd:  cint;op:  cint;fd:  cint;event:  PEpoll_Event)
                                                :  cint

    Visibility:   default

Description:     epoll_ctl performs the op operation on epoll file descriptor epfd.  The operation will be
                monitored on file descriptor fd, and is optionally controlled by event.

                op can be one of the following values:


                EPOLL__CTL__ADD               Add filedescriptor to list of events

                EPOLL__CTL__MOD                Modify event for filedescriptor

                EPOLL__CTL__DEL              Delete event for filedescriptor


                The events field in event_data is a bitmask of one or more of the following values:


                EPOLLIN         The file is ready for read operations

                EPOLLOUT            The file is ready for write operations.

                EPOLLPRI           Urgent data is available for read operations.

                EPOLLERR            An error condition is signaled on the file descriptor.

                EPOLLHUP            A Hang up happened on the file descriptor.

                EPOLLET          Set the Edge Triggered behaviour for the file descriptor.

                EPOLLONESHOT                  Set One-Shot behaviour for the file descriptor.  The event will be trig-
                       gered only once.


       Errors:   On error -1 is returned, and errno is set accordingly.

    See also:    epoll_create (754  ), epoll_wait (755  ), fpClose (146  )



                                                                                 754

                _____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                23.4.5         epoll__wait

    Synopsis:    Wait for an event on an epoll file descriptor.

Declaration:     function  epoll_wait(epfd:  cint;events:  PEpoll_Event;maxevents:  cint;
                                                timeout:  cint)  :  cint

    Visibility:   default

Description:     epoll_wait  waits  for  timeout  milliseconds  for  an  event  to  occur  on  epoll  file  descriptor
                epfd.  If  timeout is -1, it waits indefinitely, if  timeour is zero, it does not wait, but returns
                immediatly, even if no events were detected.

                On return, data for at most maxevents will be returned in the memory pointed to by events.
                The function returns the number of file descriptors for which events were reported.  This can
                be zero if the timeout was reached.

       Errors:   On error -1 is returned, and errno is set accordingly.

    See also:    epoll_create (754  ), epoll_ctl (754  ), fpClose (146  )



                23.4.6         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 (1705   )



                23.4.7         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.



                                                                                 755

                _____________________________________________________________CHAPTER_23.___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 fpgeterrno (156  ) to get the error code.



                23.4.8         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);



                23.4.9         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.



                23.4.10          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



                                                                                 756

                _____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________*
 *___________________



                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.


                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 (755  )



                23.4.11          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 (192  )


                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;



                                                                                 757

_____________________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'LINUX'______________________________*
 *___



       D ,M  ,S e c s ,H   :  l o n g i n t;
{ $ e n d i f}


 b e g i n
    { $ i f d e f L i n u x}
    I f  Not    S y s I n f o(I n f o)   then
       H a l t ( 1 ) ;
    With     I n f o do
        b e g i n
       D :=  Uptime      d i v  ( 3 6 0 0 * 2 4 ) ;
       UpTime     := UpTime      mod    ( 3 6 0 0 * 2 4 ) ;
       h :=  u p t i m e d i v  3 6 0 0 ;
        u p t i m e:=u p t i m e mod    3 6 0 0 ;
       m :=  u p t i m e d i v  6 0 ;
        s e c s:= u p t i m e mod    6 0 ;
        W r i t e l n('Uptime       :  ' ,d , ' d a y s,  ' ,h , '   h o u r s,  ' ,m , '  min   ,  ' ,s e c s ,'   s. ' ) ;
        W r i t e l n('L o a d s    :  ' ,L o a d s[ 1 ] ,' / ' ,L o a d s[ 2 ] ,'/  ', L o a d s[ 3 ] ) ;
        W r i t e l n('T o t a l Ram       :  ' ,Mb  ( t o t a l r a m) ,'Mb . ' ) ;
        W r i t e l n('F r e e  Ram        :  ' ,Mb  ( f r e e r a m) ,'Mb  . ') ;
        W r i t e l n('S h a r e d Ram     :  ' ,Mb  ( s h a r e d r a)m, 'Mb  . ' ) ;
        W r i t e l n('B u f f e r Ram     :  ' ,Mb  ( b u f f e r r a)m, 'Mb  . ' ) ;
        W r i t e l n('T o t a l Swap      :  ' ,Mb  ( t o t a l s w a)p, 'Mb  . ' ) ;
        W r i t e l n('F r e e  Swap       :  ' ,Mb  ( f r e e s w a p) ,'Mb . ' ) ;
       end   ;
    { $ e n d i f}
end___._______________________________________________________________________________________________________________________



                                                                 758




                Chapter   24



                Reference   for   unit   'lnfodwrf '



                24.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 (739  ) unit must be used.



                24.2          Procedures  and  functions



                24.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.



                                                                             759




Chapter   25



Reference   for   unit   'math'



25.1          Used  units



                                     Table 25.1:  Used units by unit 'math'


                                                   __Name__________Page_____
                                                     System        1230
                                                     sysutils      1450



25.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.



25.3          Geometrical  functions



                                                       Table 25.2:

                                    __Name_______________Description_______________________
                                      hypot (778  )       Hypotenuse of triangle
                                      norm (790  )        Euclidian norm



                                                             760

_____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



25.4          Statistical  functions



                                                       Table 25.3:

              __Name_____________________________________Description____________________________________________
                mean (786  )                            Mean of values
                meanandstddev (786  )                   Mean and standard deviation of values
                momentskewkurtosis (789  )              Moments, skew and kurtosis
                popnstddev (791  )                      Population standarddeviation
                popnvariance (792  )                    Population variance
                randg (795  )                           Gaussian distributed randum value
                stddev (799  )                          Standard deviation
                sum (800  )                             Sum of values
                sumofsquares (801  )                    Sum of squared values
                sumsandsquares (802  )                  Sum of values and squared values
                totalvariance (804  )                   Total variance of values
                variance (804  )                        variance of values



25.5          Number  converting



                                                       Table 25.4:

                               _Name_______________Description___________________________________
                                 ceil (771  )       Round to infinity
                                 floor (775  )      Round to minus infinity
                                 frexp (776  )      Return mantissa and exponent



25.6          Exponential  and  logarithmic  functions



                                                       Table 25.5:

                             __Name____________________Description_______________________________
                               intpower (779  )        Raise float to integer power
                               ldexp (781  )           Calculate $2^p x$
                               lnxp1 (781  )           calculate log(x+1)
                               log10 (782  )           calculate 10-base log
                               log2 (782  )            calculate 2-base log
                               logn (783  )            calculate N-base log
                               power (793  )           raise float to arbitrary power



                                                                 761

_____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



25.7          Hyperbolic  functions



                                                       Table 25.6:

                          __Name_________________Description________________________________________
                            arcosh (767  )       caculate reverse hyperbolic cosine
                            arsinh (770  )       caculate reverse hyperbolic sine
                            artanh (770  )       caculate reverse hyperbolic tangent
                            cosh (772  )         calculate hyperbolic cosine
                            sinh (799  )         calculate hyperbolic sine
                            tanh (803  )         calculate hyperbolic tangent



25.8          Trigoniometric  functions



                                                       Table 25.7:

                                 __Name__________________Description__________________________
                                   arccos (766  )        calculate reverse cosine
                                   arcsin (768  )        calculate reverse sine
                                   arctan2 (769  )       calculate reverse tangent
                                   cotan (773  )         calculate cotangent
                                   sincos (798  )        calculate sine and cosine
                                   tan (803  )           calculate tangent



25.9          Angle  unit  conversion


Routines to convert angles between different angle units.



                                                       Table 25.8:

                              __Name______________________Description___________________________
                                cycletorad (773  )        convert cycles to radians
                                degtograd (774  )         convert degrees to grads
                                degtorad (774  )          convert degrees to radians
                                gradtodeg (777  )         convert grads to degrees
                                gradtorad (778  )         convert grads to radians
                                radtocycle (793  )        convert radians to cycles
                                radtodeg (794  )          convert radians to degrees
                                radtograd (794  )         convert radians to grads



25.10            Min/max  determination


Functions to determine the minimum or maximum of numbers:



                                                                 762

_____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



                                                       Table 25.9:

                    __Name_________________________Description_____________________________________________
                      max (783  )                   Maximum of 2 values
                      maxIntValue (784  )           Maximum of an array of integer values
                      maxvalue (785  )              Maximum of an array of values
                      min (787  )                   Minimum of 2 values
                      minIntValue (788  )           Minimum of an array of integer values
                      minvalue (789  )              Minimum of an array of values



25.11            Constants,  types  and  variables



25.11.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


MaxExtended  =  1.1e  +  4932


Maximum value of extended type


MaxFloat  =  MaxExtended


Maximum value of float type


MinExtended  =  3.4e  -  4932


Minimum value (closest to zero) of extended type


MinFloat  =  MinExtended


Minimum value (closest to zero) of float type


NaN  =  0.0  /  0.0


Value is Not a Number



                                                                 763

_____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



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



25.11.2          Types

  =  -1..1


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.


  =  -1..1


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.


  =  -37..37



                                                                 764

_____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________________________*
 *___



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.


float  =  extended


All  calculations  are  done  with  the  Float  type.   This  allows  to  recompile  the  unit  with  a
different float type to obtain a desired precision.  The pointer type PFloat (765  ) is used in
functions that accept an array of values of arbitrary length.


PFloat  =  ^float


Pointer to Float (765  ) type.


PInteger  =  ObjPas.PInteger


Pointer to integer type


TFPUException  =  (exInvalidOp,exDenormalized,exZeroDivide,exOverflow,
                            exUnderflow,exPrecision)



                      Table 25.10:  Enumeration values for type TFPUException


                                 __Value____________________Explanation_______________________
                                   exDenormalized
                                   exInvalidOp               Invalid operation error
                                   exOverflow                Float overflow error
                                   exPrecision               Precision error
                                   exUnderflow               Float underflow error
                                   exZeroDivide              Division by zero error.



Type describing Floating Point processor exceptions.


TFPUExceptionMask  =  Set  of  TFPUException


Type to set the Floating Point Unit exception mask.


TFPUPrecisionMode  =  (pmSingle,pmReserved,pmDouble,pmExtended)



                                                                 765

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                                   Table 25.11:  Enumeration values for type TFPUPrecisionMode


                                                  __Value________________Explanation_________________________
                                                    pmDouble             Double-type precision
                                                    pmExtended           Extended-type precision
                                                    pmReserved           ?
                                                    pmSingle             Single-type precision



                Type describing the default precision for the Floating Point processor.


                TFPURoundingMode  =  (rmNearest,rmDown,rmUp,rmTruncate)



                                   Table 25.12:  Enumeration values for type TFPURoundingMode


                                     __Value______________Explanation_____________________________________________________
                                       rmDown              Round to biggest integer smaller than value.
                                       rmNearest           Round to nearest integer value
                                       rmTruncate          Cut off fractional part.
                                       rmUp                Round to smallest integer larger than value.



                Type describing the rounding mode for the Floating Point processor.


                tpaymenttime  =  (ptendofperiod,ptstartofperiod)



                                        Table 25.13:  Enumeration values for type tpaymenttime


                                                      __Value____________________Explanation____________
                                                        ptendofperiod            End of period.
                                                        ptstartofperiod          Start of period.



                Type used in financial (interest) calculations.



                25.12            Procedures  and  functions



                25.12.1          arccos

    Synopsis:    Return inverse cosine

Declaration:     function  arccos(x:  float)  :  float

    Visibility:   default

Description:     Arccos returns the inverse cosine of its argument x.  The argument x should lie between -1
                and 1 (borders included).

       Errors:   If the argument x is not in the allowed range, an EInvalidArgument exception is raised.



                                                                                 766

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    See also:    arcsin (768  ), arcosh (767  ), arsinh (770  ), artanh (770  )


                Listing:  ./mathex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   Program       t o  d e m o n s t r a t et h e  a r c c o s f u n c t i o n.  }


                Uses     math   ;


                    P r o c e d u r eWriteRadDeg         (X   :   f l o a t) ;


                    b e g i n
                        W r i t e l n(X: 8 : 5 ,'  r a d  =   ' ,r a d t o d e g(x ) : 8 : 5 ,'  d e g r e e s.')
                    end  ;


                 b e g i n
                    WriteRadDeg          ( a r c c o s( 1 ) ) ;
                    WriteRadDeg          ( a r c c o s(s q r t( 3 ) / 2 ) ) ;
                    WriteRadDeg          ( a r c c o s(s q r t( 2 ) / 2 ) ) ;
                    WriteRadDeg          ( a r c c o s( 1 / 2 ) ) ;
                    WriteRadDeg          ( a r c c o s( 0 ) ) ;
                    WriteRadDeg          ( a r c c o s( - 1 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.2          arccosh

    Synopsis:    Return inverse hyperbolic cosine

Declaration:     function  arccosh(x:  float)  :  float

    Visibility:   default

Description:     arccosh returns the inverse hyperbolic cosine of it's argument x.

                This function is an alias for arcosh (767  ), provided for Delphi compatibility.

    See also:    arcosh (767  )



                25.12.3          arcosh

    Synopsis:    Return inverse hyperbolic cosine

Declaration:     function  arcosh(x:  float)  :  float

    Visibility:   default

Description:     Arcosh returns the inverse hyperbolic cosine of its argument x.  The argument x should be
                larger than 1.  The arccosh variant of this function is supplied for Delphi compatibility.

       Errors:   If the argument x is not in the allowed range, an EInvalidArgument exception is raised.

    See also:    cosh (772  ), sinh (799  ), arcsin (768  ), arsinh (770  ), artanh (770  ), tanh (803  )


                Listing:  ./mathex/ex3.pp



                                                                                 767

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                {   Program       t o  d e m o n s t r a t et h e  a r c o s h f u n c t i o n.  }


                Uses     math   ;


                 b e g i n
                    W r i t e l n(a r c o s h( 1 ) ) ;
                    W r i t e l n(a r c o s h( 2 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.4          arcsin

    Synopsis:    Return inverse sine

Declaration:     function  arcsin(x:  float)  :  float

    Visibility:   default

Description:     Arcsin returns the inverse sine of its argument x.  The argument x should lie between -1
                and 1.

       Errors:   If the argument x is not in the allowed range, an EInvalidArgument exception is raised.

    See also:    arccos (766  ), arcosh (767  ), arsinh (770  ), artanh (770  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.5          arcsinh

    Synopsis:    Return inverse hyperbolic sine

Declaration:     function  arcsinh(x:  float)  :  float

    Visibility:   default



                                                                                 768

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



Description:     arcsinh returns the inverse hyperbolic sine of it's argument x.

                This function is an alias for arsinh (770  ), provided for Delphi compatibility.

    See also:    arsinh (770  )



                25.12.6          arctan2

    Synopsis:    Return arctangent of (y/x)

Declaration:     function  arctan2(y:  float;x:  float)  :  float

    Visibility:   default

Description:     arctan2  calculates  arctan(y/x),  and  returns  an  angle  in  the  correct  quadrant.  The  re-
                turned angle will be in the range $-\pi$ to $\pi$ radians.  The values of  x and y must be
                between  -2\{^}64  and  2\{^}64,  moreover  x  should  be  different  from  zero.  On  Intel  systems
                this function is implemented with the native intel fpatan instruction.

       Errors:   If  x is zero, an overflow error will occur.

    See also:    arccos (766  ), arcosh (767  ), arsinh (770  ), artanh (770  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.7          arctanh

    Synopsis:    Return inverse hyperbolic tangent

Declaration:     function  arctanh(x:  float)  :  float

    Visibility:   default

Description:     arcsinh returns the inverse hyperbolic tangent of it's argument x.

                This function is an alias for artanh (770  ), provided for Delphi compatibility.

    See also:    artanh (770  )



                                                                                 769

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                25.12.8          arsinh

    Synopsis:    Return inverse hyperbolic sine

Declaration:     function  arsinh(x:  float)  :  float

    Visibility:   default

Description:     arsinh returns the inverse hyperbolic sine of its argument x.  The arscsinh variant of this
                function is supplied for Delphi compatibility.

       Errors:   None.

    See also:    arcosh (767  ), arccos (766  ), arcsin (768  ), artanh (770  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.9          artanh

    Synopsis:    Return inverse hyperbolic tangent

Declaration:     function  artanh(x:  float)  :  float

    Visibility:   default

Description:     artanh returns the inverse hyperbolic tangent of its argument x, where x should lie in the
                interval [-1,1], borders included.  The arctanh variant of this function is supplied for Delphi
                compatibility.

       Errors:   In case x is not in the interval [-1,1], an EInvalidArgument exception is raised.

    See also:    arcosh (767  ), arccos (766  ), arcsin (768  ), artanh (770  )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 770

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                25.12.10           ceil

    Synopsis:    Return the lowest integer number greater than or equal to argument

Declaration:     function  ceil(x:  float)  :  Integer

    Visibility:   default

Description:     Ceil returns the lowest integer number greater than or equal to x.  The absolute value of x
                should be less than maxint.

       Errors:   If the asolute value of  x is larger than maxint, an overflow error will occur.

    See also:    floor (775  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.11           ClearExceptions

    Synopsis:    Clear Floating Point Unit exceptions

Declaration:     procedure  ClearExceptions(RaisePending:  Boolean)

    Visibility:   default

Description:     Clear Floating Point Unit exceptions



                25.12.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:  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



                                                                                 771

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                0if  A=B

                -1 if  A>B


    See also:    TValueRelationship (1230   )



                25.12.13           cosecant

    Synopsis:    Calculate cosecant

Declaration:     function  cosecant(x:  float)  :  float

    Visibility:   default

Description:     cosecant calculates the cosecant (1/sin(x)) of its argument x.

       Errors:   If 0 or 180 degrees is specified, an exception will be raised.

    See also:    secant (797  )



                25.12.14           cosh

    Synopsis:    Return hyperbolic cosine

Declaration:     function  cosh(x:  float)  :  float

    Visibility:   default

Description:     Cosh returns the hyperbolic cosine of it's argument {x}.

       Errors:   None.

    See also:    arcosh (767  ), sinh (799  ), arsinh (770  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.15           cot

    Synopsis:    Alias for Cotan

Declaration:     function  cot(x:  float)  :  float

    Visibility:   default

Description:     cot is an alias for the cotan (773  ) function.

    See also:    cotan (773  )



                                                                                 772

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                25.12.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 (803  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.17           csc

    Synopsis:    Alias for cosecant

Declaration:     function  csc(x:  float)  :  float

    Visibility:   default

Description:     csc is an alias for the cosecant (772  ) function.

    See also:    cosecant (772  )



                25.12.18           cycletorad

    Synopsis:    Convert cycle angle to radians angle

Declaration:     function  cycletorad(cycle:  float)  :  float

    Visibility:   default

Description:     Cycletorad transforms it's argument cycle (an angle expressed in cycles) to radians.  (1
                cycle is $2 \pi$ radians).

       Errors:   None.

    See also:    degtograd (774  ), degtorad (774  ), radtodeg (794  ), radtograd (794  ), radtocycle (793  )


                Listing:  ./mathex/ex10.pp



                                                                                 773

                _____________________________________________________________CHAPTER_25.___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___.____________________________________________________________________________________________________________*
 *___________



                25.12.19           degtograd

    Synopsis:    Convert degree angle to grads angle

Declaration:     function  degtograd(deg:  float)  :  float

    Visibility:   default

Description:     Degtograd transforms it's argument deg (an angle in degrees) to grads.  (90 degrees is 100
                grad.)

       Errors:   None.

    See also:    cycletorad (773  ), degtorad (774  ), radtodeg (794  ), radtograd (794  ), radtocycle (793  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.20           degtorad

    Synopsis:    Convert degree angle to radians angle.

Declaration:     function  degtorad(deg:  float)  :  float

    Visibility:   default

Description:     Degtorad  converts  it's  argument  deg  (an  angle  in  degrees)  to  radians.  (pi  radians  is  180
                degrees)

       Errors:   None.

    See also:    cycletorad (773  ), degtograd (774  ), radtodeg (794  ), radtograd (794  ), radtocycle (793  )


                Listing:  ./mathex/ex12.pp



                                                                                 774

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.21           DivMod

    Synopsis:    Return DIV and MOD of arguments

Declaration:     procedure  DivMod(Dividend:  Integer;Divisor:  Word;var  Result:  Word;
                                           var  Remainder:  Word)
                procedure  DivMod(Dividend:  Integer;Divisor:  Word;var  Result:  SmallInt;
                                           var  Remainder:  SmallInt)
                procedure  DivMod(Dividend:  DWord;Divisor:  DWord;var  Result:  DWord;
                                           var  Remainder:  DWord)
                procedure  DivMod(Dividend:  Integer;Divisor:  Integer;var  Result:  Integer;
                                           var  Remainder:  Integer)

    Visibility:   default

Description:     DivMod returns Dividend DIV Divisor in Result, and Dividend MOD Divisor in Remainder



                25.12.22           EnsureRange

    Synopsis:    Change value to it falls in specified range.

Declaration:     function  EnsureRange(const  AValue:  Integer;const  AMin:  Integer;
                                                 const  AMax:  Integer)  :  Integer;    Overload
                function  EnsureRange(const  AValue:  Int64;const  AMin:  Int64;
                                                 const  AMax:  Int64)  :  Int64;    Overload

    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 (779  )



                25.12.23           floor

    Synopsis:    Return the largest integer smaller than or equal to argument

Declaration:     function  floor(x:  float)  :  Integer

    Visibility:   default



                                                                                 775

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



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 (771  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.24           Frexp

    Synopsis:    Return mantissa and exponent.

Declaration:     procedure  Frexp(X:  float;var  Mantissa:  float;var  Exponent:  Integer)

    Visibility:   default

Description:     Frexp returns the mantissa and exponent of it's argument x in mantissa and exponent.

       Errors:   None


                Listing:  ./mathex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;


                {   Program       t o  d e m o n s t r a t et h e  f r e x p  f u n c t i o n. }


                Uses     math   ;


                 P r o c e d u r ed o f r e x p(Const     X   :  e x t e n d e d) ;


                 v a r man     :  e x t e n d e d;
                       exp   :  l o n g i n t;


                 b e g i n
                    man  : = 0 ;
                    exp  : = 0 ;
                    f r e x p(x , man  , exp  ) ;
                    w r i t e(x , '  h a s   ') ;
                    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 ) ;



                                                                                 776

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                      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___.____________________________________________________________________________________________________________*
 *___________



                25.12.25           GetExceptionMask

    Synopsis:    Get the Floating Point Unit exception mask.

Declaration:     function  GetExceptionMask  :  TFPUExceptionMask

    Visibility:   default

Description:     Get the Floating Point Unit exception mask.



                25.12.26           GetPrecisionMode

    Synopsis:    Return the Floating Point Unit precision mode.

Declaration:     function  GetPrecisionMode  :  TFPUPrecisionMode

    Visibility:   default

Description:     Return the Floating Point Unit precision mode.



                25.12.27           GetRoundMode

    Synopsis:    Return the Floating Point Unit rounding mode.

Declaration:     function  GetRoundMode  :  TFPURoundingMode

    Visibility:   default

Description:     Return the Floating Point Unit rounding mode.



                25.12.28           gradtodeg

    Synopsis:    Convert grads angle to degrees angle

Declaration:     function  gradtodeg(grad:  float)  :  float

    Visibility:   default

Description:     Gradtodeg  converts  its  argument  grad  (an  angle  in  grads)  to  degrees.   (100  grad  is  90
                degrees)

       Errors:   None.

    See also:    cycletorad (773  ), degtograd (774  ), radtodeg (794  ), radtograd (794  ), radtocycle (793  ), grad-
                torad (778  )


                Listing:  ./mathex/ex15.pp



                                                                                 777

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.29           gradtorad

    Synopsis:    Convert grads angle to radians angle

Declaration:     function  gradtorad(grad:  float)  :  float

    Visibility:   default

Description:     Gradtorad  converts  its  argument  grad  (an  angle  in  grads)  to  radians.   (200  grad  is  pi
                degrees).

       Errors:   None.

    See also:    cycletorad (773  ), degtograd (774  ), radtodeg (794  ), radtograd (794  ), radtocycle (793  ), grad-
                todeg (777  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.30           hypot

    Synopsis:    Return hypotenuse of triangle

Declaration:     function  hypot(x:  float;y:  float)  :  float

    Visibility:   default

Description:     Hypot returns the hypotenuse of the triangle where the sides adjacent to the square angle
                have lengths x and y.  The function uses Pythagoras' rule for this.

       Errors:   None.


                Listing:  ./mathex/ex17.pp



                                                                                 778

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.31           ifthen

    Synopsis:    Return one of two values, depending on a boolean condition

Declaration:     function  ifthen(val:  Boolean;const  iftrue:  Integer;
                                         const  iffalse:  Integer)  :  Integer;    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.



                25.12.32           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

    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 (775  )



                25.12.33           intpower

    Synopsis:    Return integer power.

Declaration:     function  intpower(base:  float;const  exponent:  Integer)  :  float

    Visibility:   default

Description:     Intpower returns base to the power exponent, where exponent is an integer value.

       Errors:   If  base is zero and the exponent is negative, then an overflow error will occur.

    See also:    power (793  )



                                                                                 779

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                Listing:  ./mathex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  d e m o n s t r a t et h e  i n t p o w e r f u n c t i o n. }


                Uses     math   ;


                 P r o c e d u r eD o I n t p o w e r(X    :  e x t e n d e d; Pow    :   I n t e g e r) ;


                 b e g i n
                    w r i t e l n(X : 8 : 4 ,'^ ' ,Pow   : 2 ,'  =   ' ,i n t p o w e r(X ,pow   ) : 8 : 4 ) ;
                end   ;


                 b e g i n
                    d o i n t p o w e r( 0 . 0 , 0 ) ;
                    d o i n t p o w e r( 1 . 0 , 0 ) ;
                    d o i n t p o w e r( 2 . 0 , 5 ) ;
                    d o i n t p o w e r( 4 . 0 , 3 ) ;
                    d o i n t p o w e r( 2 . 0 , - 1 ) ;
                    d o i n t p o w e r( 2 . 0 , - 2 ) ;
                    d o i n t p o w e r( - 2 . 0 , 4 ) ;
                    d o i n t p o w e r( - 4 . 0 , 3 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.34           IsInfinite

    Synopsis:    Check whether value is infinite

Declaration:     function  IsInfinite(const  d:  Double)  :  Boolean

    Visibility:   default

Description:     IsInfinite returns True if the double d contains the infinite value.

    See also:    IsZero (780  ), IsInfinite (780  )



                25.12.35           IsNan

    Synopsis:    Check whether value is Not a Number

Declaration:     function  IsNan(const  d:  Single)  :  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 (780  ), IsInfinite (780  )



                25.12.36           IsZero

    Synopsis:    Check whether value is zero



                                                                                 780

                _____________________________________________________________CHAPTER_25.___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:  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 (780  ), IsInfinite (780  ), SameValue (796  )



                25.12.37           ldexp

    Synopsis:    Return (2 to the power p) times x

Declaration:     function  ldexp(x:  float;const  p:  Integer)  :  float

    Visibility:   default

Description:     Ldexp returns (2 to the power p) times x.

       Errors:   None.

    See also:    lnxp1 (781  ), log10 (782  ), log2 (782  ), logn (783  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.38           lnxp1

    Synopsis:    Return natural logarithm of 1+X

Declaration:     function  lnxp1(x:  float)  :  float

    Visibility:   default

Description:     Lnxp1 returns the natural logarithm of  1+X. The result is more precise for small values of
                x.  x should be larger than -1.

       Errors:   If $x\leq -1$ then an EInvalidArgument exception will be raised.

    See also:    ldexp (781  ), log10 (782  ), log2 (782  ), logn (783  )



                                                                                 781

                _____________________________________________________________CHAPTER_25.___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___.____________________________________________________________________________________________________________*
 *___________



                25.12.39           log10

    Synopsis:    Return 10-Based logarithm.

Declaration:     function  log10(x:  float)  :  float

    Visibility:   default

Description:     Log10 returns the 10-base logarithm of  X.

       Errors:   If  x is less than or equal to 0 an 'invalid fpu operation' error will occur.

    See also:    ldexp (781  ), lnxp1 (781  ), log2 (782  ), logn (783  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.40           log2

    Synopsis:    Return 2-based logarithm

Declaration:     function  log2(x:  float)  :  float

    Visibility:   default

Description:     Log2 returns the 2-base logarithm of  X.

       Errors:   If  x is less than or equal to 0 an 'invalid fpu operation' error will occur.



                                                                                 782

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    See also:    ldexp (781  ), lnxp1 (781  ), log10 (782  ), logn (783  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.41           logn

    Synopsis:    Return N-based logarithm.

Declaration:     function  logn(n:  float;x:  float)  :  float

    Visibility:   default

Description:     Logn returns the n-base logarithm of  X.

       Errors:   If  x is less than or equal to 0 an 'invalid fpu operation' error will occur.

    See also:    ldexp (781  ), lnxp1 (781  ), log10 (782  ), log2 (782  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.42           Max

    Synopsis:    Return largest of 2 values



                                                                                 783

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



Declaration:     function  Max(a:  Integer;b:  Integer)  :  Integer;    Overload
                function  Max(a:  Int64;b:  Int64)  :  Int64;    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 (787  ), maxIntValue (784  ), maxvalue (785  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.43           MaxIntValue

    Synopsis:    Return largest element in integer array

Declaration:     function  MaxIntValue(const  Data:  Array  of  Integer)  :  Integer

    Visibility:   default

Description:     MaxIntValue returns the largest integer out of the Data array.

                This function is provided for Delphi compatibility, use the maxvalue (785  ) function instead.

       Errors:   None.

    See also:    maxvalue (785  ), minvalue (789  ), minIntValue (788  )


                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;


                Var



                                                                                 784

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                25.12.44           maxvalue

    Synopsis:    Return largest value in array

Declaration:     function  maxvalue(const  data:  Array  of  Extended)  :  Extended
                function  maxvalue(const  data:  PExtended;const  N:  Integer)  :  Extended
                function  maxvalue(const  data:  Array  of  Integer)  :  Integer
                function  maxvalue(const  data:  PInteger;const  N:  Integer)  :  Integer

    Visibility:   default

Description:     Maxvalue returns the largest value in the data array with integer or float values.  The return
                value has the same type as the elements of the array.

                The third and fourth forms accept a pointer to an array of  N integer or float values.

       Errors:   None.

    See also:    maxIntValue (784  ), minvalue (789  ), minIntValue (788  )


                Listing:  ./mathex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 2 6;


                {   Program       t o  d e m o n s t r a t et h e  MaxValue        f u n c t i o n. }


                {   Make     s o r e  i n t e g e r i s 3 2   b i t}
                { $mode      o b j f p c}


                 u s e s math   ;


                 v a r  i : 1 . . 1 0 0 ;
                        f _a r r a y: a r r a y[ 1 . . 1 0 0 ]o f  F l o a t;
                        i _a r r a y: a r r a y[ 1 . . 1 0 0 ]o f  I n t e g e r;
                        P f _a r r a y:P f l o a t;
                        P I _a r r a y:P i n t e g e r;


                 b e g i n
                    randomize       ;


                    P f _a r r a y:=  @ f _a r r a y[ 1 ] ;
                    P i _a r r a y:=  @ i _a r r a y[ 1 ] ;


                    f o r  i := low  ( f _a r r a y )  t o  h i g h( f _a r r a y)  do
                        f _a r r a y[ i] : = (random    - random     ) * 1 0 0 ;
                    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 ) ;



                                                                                 785

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                25.12.45           mean

    Synopsis:    Return mean value of array

Declaration:     function  mean(const  data:  Array  of  Extended)  :  float
                function  mean(const  data:  PExtended;const  N:  LongInt)  :  float

    Visibility:   default

Description:     Mean returns the average value of  data.  The second form accepts a pointer to an array of
                N values.

       Errors:   None.

    See also:    meanandstddev (786  ), momentskewkurtosis (789  ), sum (800  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.46           meanandstddev

    Synopsis:    Return mean and standard deviation of array

Declaration:     procedure  meanandstddev(const  data:  Array  of  Extended;var  mean:  float;
                                                      var  stddev:  float)
                procedure  meanandstddev(const  data:  PExtended;const  N:  LongInt;
                                                      var  mean:  float;var  stddev:  float)



                                                                                 786

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    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 (786  ), sum (800  ), sumofsquares (801  ), momentskewkurtosis (789  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.47           Min

    Synopsis:    Return smallest of two values.

Declaration:     function  Min(a:  Integer;b:  Integer)  :  Integer;    Overload
                function  Min(a:  Int64;b:  Int64)  :  Int64;    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 (783  )


                Listing:  ./mathex/ex29.pp



                                                                                 787

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 9;


                {   Program       t o  d e m o n s t r a t et h e  min    f u n c t i o n. }


                Uses     math   ;


                Var
                    A ,B   :   C a r d i n a l;


                 b e g i n
                    A : = 1 ;b : = 2 ;
                    w r i t e l n(min  ( a ,b ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.48           MinIntValue

    Synopsis:    Return smallest value in integer array

Declaration:     function  MinIntValue(const  Data:  Array  of  Integer)  :  Integer

    Visibility:   default

Description:     MinIntvalue returns the smallest value in the Data array.

                This function is provided for Delphi compatibility, use minvalue instead.

       Errors:   None

    See also:    minvalue (789  ), maxIntValue (784  ), maxvalue (785  )


                Listing:  ./mathex/ex30.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 0;


                {   Program       t o  d e m o n s t r a t et h e  M i n I n t V a l u ef u n c t i o n. }


                {   Make     s o r e  i n t e g e r i s 3 2   b i t}
                { $mode      o b j f p c}


                Uses     math   ;


                Type
                    TExArray       =   A r r a y[ 1 . . 1 0 0 ] o f  I n t e g e r;


                Var
                    I   :  I n t e g e r;
                    E x A r r a y :  TExArray       ;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) do
                        E x A r r a y[i] : =Random     ( I)-  Random    ( 1 0 0 ) ;
                    W r i t e l n(M i n I n t V a l u(eE x A r r a y) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                 788

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                25.12.49           minvalue

    Synopsis:    Return smallest value in array

Declaration:     function  minvalue(const  data:  Array  of  Extended)  :  Extended
                function  minvalue(const  data:  PExtended;const  N:  Integer)  :  Extended
                function  minvalue(const  data:  Array  of  Integer)  :  Integer
                function  MinValue(const  Data:  PInteger;const  N:  Integer)  :  Integer

    Visibility:   default

Description:     Minvalue  returns  the  smallest  value  in  the  data  array  with  integer  or  float  values.  The
                return value has the same type as the elements of the array.

                The third and fourth forms accept a pointer to an array of  N integer or float values.

       Errors:   None.

    See also:    maxIntValue (784  ), maxvalue (785  ), minIntValue (788  )


                Listing:  ./mathex/ex31.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 1;


                {   Program       t o  d e m o n s t r a t et h e  M i n V a l u e f u n c t i o n. }


                {   Make     s u r e  i n t e g e r i s 3 2   b i t}
                { $mode      o b j f p c}


                 u s e s math   ;


                 v a r  i : 1 . . 1 0 0 ;
                        f _a r r a y: a r r a y[ 1 . . 1 0 0 ]o f  F l o a t;
                        i _a r r a y: a r r a y[ 1 . . 1 0 0 ]o f  I n t e g e r;
                        P f _a r r a y:P f l o a t;
                        P I _a r r a y:P i n t e g e r;


                 b e g i n
                    randomize       ;


                    P f _a r r a y:=  @ f _a r r a y[ 1 ] ;
                    P i _a r r a y:=  @ i _a r r a y[ 1 ] ;


                    f o r  i := low  ( f _a r r a y )  t o  h i g h( f _a r r a y)  do
                        f _a r r a y[ i] : = (random    - random     ) * 1 0 0 ;
                    f o r  i := low  ( i _a r r a y )  t o  h i g h( i _a r r a y)  do
                        i _a r r a y[ i] : =random     ( I)-  random    ( 1 0 0 ) ;


                    W r i t e l n(' Min    F l o a t            :  ' , M i n V a l u e(f _a r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Min    F l o a t     (b )  :   ' , M i n V a l u e(P f _a r r a y, 1 0 0 ) : 8 : 4 ) ;
                    W r i t e l n(' Min    I n t e g e r        :  ' , M i n V a l u e(i _a r r a y) : 8 ) ;
                    W r i t e l n(' Min    I n t e g e r( b )  :   ' , M i n V a l u e(P i _a r r a y, 1 0 0 ) : 8 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.50           momentskewkurtosis

    Synopsis:    Return 4 first moments of distribution



                                                                                 789

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



Declaration:     procedure  momentskewkurtosis(const  data:  Array  of  Extended;
                                                              out  m1:  float;out  m2:  float;out  m3:  float;
                                                              out  m4:  float;out  skew:  float;
                                                              out  kurtosis:  float)
                procedure  momentskewkurtosis(const  data:  PExtended;const  N:  Integer;
                                                              out  m1:  float;out  m2:  float;out  m3:  float;
                                                              out  m4:  float;out  skew:  float;
                                                              out  kurtosis:  float)

    Visibility:  default

Description:     momentskewkurtosis  calculates  the  4  first  moments  of  the  distribution  of  valuesin  data
                and returns them in m1,m2,m3 and m4, as well as the skew and kurtosis.

       Errors:   None.

    See also:    mean (786  ), meanandstddev (786  )


                Listing:  ./mathex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 2;


                {   Program       t o  d e m o n s t r a t et h e  m o m e n t s k e w k u r t o s ifsu n c t i o n. }


                 u s e s math   ;


                 v a r  d i s t a r r a:ya r r a y[ 1 . . 1 0 0 0 ]o f   f l o a t;
                        I: l o n g i n t;
                       m1  ,m2  , m3  ,m4  ,skew    ,k u r t o s i s:f l o a t;


                 b e g i n
                    randomize       ;
                    f o r  I := low  ( d i s t a r r a y) t o   h i g h( d i s t a r r a)y do
                        d i s t a r r a[yi ] : =random     ;
                    m o m e n t s k e w k u r t o s(iDsi s t A r r a y,m1 ,m2  , m3  ,m4  ,skew    ,k u r t o s i s) ;


                    W r i t e l n ( '1 s t  moment       :  ' ,m1  : 8 : 6 ) ;
                    W r i t e l n ( '2 nd   moment       :  ' ,m2  : 8 : 6 ) ;
                    W r i t e l n ( '3 r d  moment       :  ' ,m3  : 8 : 6 ) ;
                    W r i t e l n ( '4 t h  moment       :  ' ,m4  : 8 : 6 ) ;
                    W r i t e l n ( 'Skew                :  ' , skew   : 8 : 6 ) ;
                    W r i t e l n ( ' k u r t o s i s    :  ' , k u r t o s i s: 8 : 6 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.51           norm

    Synopsis:    Return Euclidian norm

Declaration:     function  norm(const  data:  Array  of  Extended)  :  float
                function  norm(const  data:  PExtended;const  N:  Integer)  :  float

    Visibility:   default

Description:     Norm calculates the Euclidian norm of the array of data.  This equals sqrt(sumofsquares(data)).

                The second form accepts a pointer to an array of  N values.

       Errors:   None.



                                                                                 790

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    See also:    sumofsquares (801  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.52           operator  **(float,  float):  float

Declaration:     operator  operator  **(float,  float):  float(bas:  float;expo:  float)
                                                                                     :  float

    Visibility:   default



                25.12.53           operator  **(Int64,  Int64):  Int64

Declaration:     operator  operator  **(Int64,  Int64):  Int64(bas:  Int64;expo:  Int64)
                                                                                     :  Int64

    Visibility:   default



                25.12.54           popnstddev

    Synopsis:    Return population variance

Declaration:     function  popnstddev(const  data:  Array  of  Extended)  :  float
                function  popnstddev(const  data:  PExtended;const  N:  Integer)  :  float

    Visibility:   default

Description:     Popnstddev  returns  the  square  root  of  the  population  variance  of  the  values  in  the  Data
                array.  It returns zero if there is only one value.

                The second form of this function accepts a pointer to an array of  N values.

       Errors:   None.

    See also:    popnvariance (792  ), mean (786  ), meanandstddev (786  ), stddev (799  ), momentskewkurtosis
                (789  )


                Listing:  ./mathex/ex35.pp



                                                                                 791

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 5;


                {   Program       t o  d e m o n s t r a t et h e  PopnStdDev         f u n c t i o n.  }


                Uses     Math   ;


                Type
                    TExArray       =   A r r a y[ 1 . . 1 0 0 ] o f  F l o a t;


                Var
                    I   :  I n t e g e r;
                    E x A r r a y :  TExArray       ;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) do
                        E x A r r a y[i] : = (Random    - Random     ) * 1 0 0 ;
                    W r i t e l n('Max                            :  ' ,MaxValue      ( E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Min                           :  ' ,M i n V a l u e(E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Pop  .   s t d d e v.         :  ' ,PopnStdDev        (E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Pop  .   s t d d e v.  (b )  :   ' ,PopnStdDev        (@ E x A r r a y[ 1 ] , 1 0 0 ) : 8 : 4 )*
 * ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.55           popnvariance

    Synopsis:    Return population variance

Declaration:     function  popnvariance(const  data:  PExtended;const  N:  Integer)  :  float
                function  popnvariance(const  data:  Array  of  Extended)  :  float

    Visibility:   default

Description:     Popnvariance  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  (791  ),  mean  (786  ),  meanandstddev  (786  ),  stddev  (799  ),  momentskewkurtosis
                (789  )


                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 ;



                                                                                 792

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                    W r i t e l n('Max                      :   ' ,MaxValue      ( E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Min                     :   ' ,M i n V a l u e(E x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Pop  .   v a r.         :   ' ,P o p n V a r i a n c(eE x A r r a y) : 8 : 4 ) ;
                    W r i t e l n(' Pop  .   v a r.  ( b )  :   ' ,P o p n V a r i a n c(e@ E x A r r a y[ 1 ] , 1 0 0 ) : 8 : 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.56           power

    Synopsis:    Return real power.

Declaration:     function  power(base:  float;exponent:  float)  :  float

    Visibility:   default

Description:     power raises base to the power power.  This is equivalent to exp(power*ln(base)).  There-
                fore base should be non-negative.

       Errors:   None.

    See also:    intpower (779  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.57           radtocycle

    Synopsis:    Convert radians angle to cycle angle

Declaration:     function  radtocycle(rad:  float)  :  float

    Visibility:   default

Description:     Radtocycle converts its argument rad (an angle expressed in radians) to an angle in cycles.

                (1 cycle equals 2 pi radians)

       Errors:   None.

    See also:    degtograd (774  ), degtorad (774  ), radtodeg (794  ), radtograd (794  ), cycletorad (773  )


                Listing:  ./mathex/ex37.pp



                                                                                 793

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 7;


                {   Program       t o  d e m o n s t r a t et h e  r a d t o c y c l ef u n c t i o n.  }


                Uses     math   ;


                 b e g i n
                    w r i t e l n(r a d t o c y c l(e2 * p i) : 8 : 6 ) ;
                    w r i t e l n(r a d t o c y c l(ep i ) : 8 : 6 ) ;
                    w r i t e l n(r a d t o c y c l(ep i / 2 ) : 8 : 6 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.58           radtodeg

    Synopsis:    Convert radians angle to degrees angle

Declaration:     function  radtodeg(rad:  float)  :  float

    Visibility:   default

Description:     Radtodeg converts its argument rad (an angle expressed in radians) to an angle in degrees.
                (180 degrees equals pi radians)

       Errors:   None.

    See also:    degtograd (774  ), degtorad (774  ), radtocycle (793  ), radtograd (794  ), cycletorad (773  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.59           radtograd

    Synopsis:    Convert radians angle to grads angle

Declaration:     function  radtograd(rad:  float)  :  float

    Visibility:   default

Description:     Radtodeg converts its argument rad (an angle expressed in radians) to an angle in grads.

                (200 grads equals pi radians)

       Errors:   None.

    See also:    degtograd (774  ), degtorad (774  ), radtocycle (793  ), radtodeg (794  ), cycletorad (773  )



                                                                                 794

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                Listing:  ./mathex/ex39.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 9;


                {   Program       t o  d e m o n s t r a t et h e  r a d t o g r a d f u n c t i o n. }


                Uses     math   ;


                 b e g i n
                    w r i t e l n(r a d t o g r a d( 2 *p i) : 8 : 6 ) ;
                    w r i t e l n(r a d t o g r a d(p i) : 8 : 6 ) ;
                    w r i t e l n(r a d t o g r a d(p i/ 2 ) : 8 : 6 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.60           randg

    Synopsis:    Return gaussian distributed random number.

Declaration:     function  randg(mean:  float;stddev:  float)  :  float

    Visibility:   default

Description:     randg returns a random number which - when produced in large quantities - has a Gaussian
                distribution with mean mean and standarddeviation stddev.

       Errors:   None.

    See also:    mean (786  ), stddev (799  ), meanandstddev (786  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.61           RandomFrom

    Synopsis:    Return a random element of an array of numbers



                                                                                 795

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



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 (1385   ), RandomRange (796  )



                25.12.62           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 (1385   ), RandomFrom (795  )



                25.12.63           RoundTo

    Synopsis:    Round to the specified number of digits

Declaration:     function  RoundTo(const  AVAlue:  Extended;const  Digits:  TRoundToRange)
                                            :  Extended

    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 (1230   ), SimpleRoundTo (798  )



                25.12.64           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:  Single;const  B:  Single)  :  Boolean;    Overload
                function  SameValue(const  A:  Extended;const  B:  Extended;
                                              Epsilon:  Extended)  :  Boolean;    Overload
                function  SameValue(const  A:  Single;const  B:  Single;Epsilon:  Single)
                                                :  Boolean;    Overload

    Visibility:   default



                                                                                 796

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



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 (763  ), IsZero (780  )



                25.12.65           sec

    Synopsis:    Alias for secant

Declaration:     function  sec(x:  float)  :  float

    Visibility:   default

Description:     sec is an alias for the secant (797  ) function.

    See also:    secant (797  )



                25.12.66           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 (772  )



                25.12.67           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.



                25.12.68           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.



                                                                                 797

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                25.12.69           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.



                25.12.70           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:  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.



                25.12.71           SimpleRoundTo

    Synopsis:    Round to the specified number of digits (rounding up if needed)

Declaration:     function  SimpleRoundTo(const  AValue:  Extended;
                                                     const  Digits:  TRoundToRange)  :  Extended

    Visibility:   default

Description:     SimplRoundTo rounds the specified float AVAlue to the specified number of digits, but rounds
                up, and returns the result.  This result is accurate to "10 to the power Digits".  It uses the
                standard Round function for this.

    See also:    TRoundToRange (1230   ), RoundTo (796  )



                25.12.72           sincos

    Synopsis:    Return sine and cosine of argument

Declaration:     procedure  sincos(theta:  float;out  sinus:  float;out  cosinus:  float)

    Visibility:   default

Description:     Sincos calculates the sine and cosine of the angle theta, and returns the result in sinus
                and cosinus.

                On Intel hardware, This calculation will be faster than making 2 calls to calculate the sine
                and cosine separately.

       Errors:   None.

    See also:    arcsin (768  ), arccos (766  )



                                                                                 798

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                Listing:__./mathex/ex41.pp_________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 4 1;


                {   Program       t o  d e m o n s t r a t et h e  s i n c o s f u n c t i o n.  }


                Uses     math   ;


                 P r o c e d u r ed o s i n c o s(A n g l e :   F l o a t) ;


                Var
                    S i n e, C o s i n e :   F l o a t;


                 b e g i n
                    s i n c o s(a n g l e, s i n e, c o s i n e) ;
                    Write    ( 'A n g l e  :   ', A n g l e: 8 : 6 ) ;
                    Write    ( '  S i n e  : ' ,s i n e: 8 : 6 ) ;
                    Write    ( '  C o s i n e : ' , c o s i n e: 8 : 6 ) ;
                end   ;


                 b e g i n
                    d o s i n c o s(p i) ;
                    d o s i n c o s(p i/ 2 ) ;
                    d o s i n c o s(p i/ 3 ) ;
                    d o s i n c o s(p i/ 4 ) ;
                    d o s i n c o s(p i/ 6 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.12.73           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 (772  ), arsinh (770  ), tanh (803  ), artanh (770  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.74           stddev

    Synopsis:    Return standard deviation of data



                                                                                 799

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



Declaration:     function  stddev(const  data:  Array  of  Extended)  :  float
                function  stddev(const  data:  PExtended;const  N:  Integer)  :  float

    Visibility:  default

Description:     Stddev returns the standard deviation of the values in Data.  It returns zero if there is only
                one value.

                The second form of the function accepts a pointer to an array of  N values.

       Errors:   None.

    See also:    mean (786  ), meanandstddev (786  ), variance (804  ), totalvariance (804  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.75           sum

    Synopsis:    Return sum of values

Declaration:     function  sum(const  data:  Array  of  Extended)  :  float
                function  sum(const  data:  PExtended;const  N:  LongInt)  :  float

    Visibility:   default

Description:     Sum returns the sum of the values in the data array.

                The second form of the function accepts a pointer to an array of  N values.

       Errors:   None.

    See also:    sumofsquares (801  ), sumsandsquares (802  ), totalvariance (804  ), variance (804  )


                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



                                                                                 800

                _____________________________________________________________CHAPTER_25.___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;


                 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___.____________________________________________________________________________________________________________*
 *___________



                25.12.76           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.



                25.12.77           sumofsquares

    Synopsis:    Return sum of squares of values

Declaration:     function  sumofsquares(const  data:  Array  of  Extended)  :  float
                function  sumofsquares(const  data:  PExtended;const  N:  Integer)  :  float

    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 (800  ), sumsandsquares (802  ), totalvariance (804  ), variance (804  )


                Listing:  ./mathex/ex45.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 5;


                {   Program       t o  d e m o n s t r a t et h e  SumOfSquares           f u n c t i o n. }


                Uses     math   ;


                Var
                    I   :  1 . . 1 0 0 ;
                    E x A r r a y :  A r r a y[ 1 . . 1 0 0 ] o f  F l o a t;


                 b e g i n
                    Randomize       ;



                                                                                 801

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                25.12.78           sumsandsquares

    Synopsis:    Return sum and sum of squares of values.

Declaration:     procedure  sumsandsquares(const  data:  Array  of  Extended;var  sum:  float;
                                                        var  sumofsquares:  float)
                procedure  sumsandsquares(const  data:  PExtended;const  N:  Integer;
                                                        var  sum:  float;var  sumofsquares:  float)

    Visibility:   default

Description:     sumsandsquares calculates the sum of the values and the sum of the squares of the values
                in the data array and returns the results in sum and sumofsquares.

                The second form of the function accepts a pointer to an array of  N values.

       Errors:   None.

    See also:    sum (800  ), sumofsquares (801  ), totalvariance (804  ), variance (804  )


                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
                    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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 802

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



                25.12.79           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 (803  ), arcsin (768  ), sincos (798  ), arccos (766  )


                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___.____________________________________________________________________________________________________________*
 *___________



                25.12.80           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 (768  ), sincos (798  ), arccos (766  )


                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   ;



                                                                                 803

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'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___.____________________________________________________________________________________________________________*
 *___________



                25.12.81           totalvariance

    Synopsis:    Return total varians of values

Declaration:     function  totalvariance(const  data:  Array  of  Extended)  :  float
                function  totalvariance(const  data:  PExtended;const  N:  Integer)  :  float

    Visibility:   default

Description:     TotalVariance returns the total variance of the values in the data array.  It returns zero if
                there is only one value.

                The second form of the function accepts a pointer to an array of  N values.

       Errors:   None.

    See also:    variance (804  ), stddev (799  ), mean (786  )


                Listing:  ./mathex/ex49.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 9;


                {   Program       t o  d e m o n s t r a t et h e  T o t a l V a r i a n c ef u n c t i o n. }


                Uses     math   ;


                Type
                    TExArray       =   A r r a y[ 1 . . 1 0 0 ] o f  F l o a t;


                Var
                    I   :  I n t e g e r;
                    E x A r r a y :  TExArray       ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                25.12.82           variance

    Synopsis:    Return variance of values

Declaration:     function  variance(const  data:  Array  of  Extended)  :  float
                function  variance(const  data:  PExtended;const  N:  Integer)  :  float



                                                                                 804

                _____________________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'MATH'_______________*
 *___________________



    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 (804  ), stddev (799  ), mean (786  )


                Listing:  ./mathex/ex50.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 0;


                {   Program       t o  d e m o n s t r a t et h e  V a r i a n c e f u n c t i o n. }


                Uses     math   ;


                Var
                    I   :  1 . . 1 0 0 ;
                    E x A r r a y :  A r r a y[ 1 . . 1 0 0 ] o f  F l o a t;
                    V   :  f l o a t;


                 b e g i n
                    Randomize       ;
                    f o r  I := low  ( E x A r r a y)  t o  h i g h( E x A r r a y) do
                        E x A r r a y[i] : = (Random    - Random     ) * 1 0 0 ;
                    V := V a r i a n c e(E x A r r a y) ;
                    W r i t e l n(' V a r i a n c e        :  ' ,V : 8 : 4 ) ;
                    V := V a r i a n c e(@ E x A r r a y[ 1 ] , 1 0 0 ) ;
                    W r i t e l n(' V a r i a n c e( b )  :   ' ,V : 8 : 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                25.13            EInvalidArgument



                25.13.1          Description

                Exception raised when invalid arguments are passed to a function.



                                                                                 805




Chapter   26



Reference   for   unit   'matrix'



26.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.



                                                             806

__________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________________________*
 *___



26.2          Constants,  types  and  variables



26.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.



                                                                 807

__________________________________________________________CHAPTER_26.___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



                                                                 808

                __________________________________________________________CHAPTER_26.___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.



                26.3          Procedures  and  functions



                26.3.1         operator  *(Tmatrix2__double,  Double):  Tmatrix2__double

    Synopsis:    Multiply a two-dimensional double precision matrix by a scalar

Declaration:     operator  operator  *(Tmatrix2_double,  Double):  Tmatrix2_double
                                                                                                                     (const  m:  Tm*
 *atrix2_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix2_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                26.3.2         operator *(Tmatrix2__double, Tmatrix2__double):  Tmatrix2__double

    Synopsis:    Give product of two two-dimensional double precision matrices

Declaration:     operator  operator  *(Tmatrix2_double,  Tmatrix2_double):  Tmatrix2_double
                                                                                                                                   *
 * (const  m1:  Tmatrix2_double;
                                                                                                                                   *
 * const  m2:  Tmatrix2_double)
                                                                                                                                   *
 *  :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.



                                                                                 809

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.3         operator *(Tmatrix2__double, Tvector2__double):  Tvector2__double

    Synopsis:    Give product of a two-dimendional double precision matrix and vector

Declaration:     operator  operator  *(Tmatrix2_double,  Tvector2_double):  Tvector2_double
                                                                                                                                   *
 * (const  m:  Tmatrix2_double;
                                                                                                                                   *
 * const  v:  Tvector2_double)
                                                                                                                                   *
 *  :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  multipy  a  two-dimensional  double  precision  matrices  with  a
                two dimensional double precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.



                26.3.4         operator  *(Tmatrix2__extended,  extended):  Tmatrix2__extended

    Synopsis:    Multiply a two-dimensional extended precision matrix by a scalar

Declaration:     operator  operator  *(Tmatrix2_extended,  extended):  Tmatrix2_extended
                                                                                                                               (con*
 *st  m:  Tmatrix2_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                26.3.5         operator *(Tmatrix2__extended, Tmatrix2__extended):  Tmatrix2__extended

    Synopsis:    Give product of two two-dimensional extended precision matrices

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m1:  Tmatri@
                                                                                                                                   *
 *           const  m2:  Tmatrix@
                                                                                                                                   *
 *            :  Tmatrix2_extend@

    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.



                26.3.6         operator *(Tmatrix2__extended, Tvector2__extended):  Tvector2__extended

    Synopsis:    Give product of a two-dimendional extended precision matrix and vector

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m:  Tmatrix@
                                                                                                                                   *
 *           const  v:  Tvector2@
                                                                                                                                   *
 *            :  Tvector2_extend@

    Visibility:   default



                                                                                 810

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



Description:     This operator allows you to multipy a two-dimensional extended precision matrices with a
                two dimensional extended precision vector.  A new vector is returned which is the product
                of the matrix and the vector.  The product is calculated using the well known matrix-vector
                multiplication algorithm.



                26.3.7         operator  *(Tmatrix2__single,  single):  Tmatrix2__single

    Synopsis:    Multiply a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  *(Tmatrix2_single,  single):  Tmatrix2_single
                                                                                                                     (const  m:  Tm*
 *atrix2_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix2_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                26.3.8         operator  *(Tmatrix2__single,  Tmatrix2__single):  Tmatrix2__single

    Synopsis:    Give product of two two-dimensional single precision matrices

Declaration:     operator  operator  *(Tmatrix2_single,  Tmatrix2_single):  Tmatrix2_single
                                                                                                                                   *
 * (const  m1:  Tmatrix2_single;
                                                                                                                                   *
 * const  m2:  Tmatrix2_single)
                                                                                                                                   *
 *  :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.



                26.3.9         operator  *(Tmatrix2__single,  Tvector2__single):  Tvector2__single

    Synopsis:    Give product of a two-dimendional single precision matrix and vector

Declaration:     operator  operator  *(Tmatrix2_single,  Tvector2_single):  Tvector2_single
                                                                                                                                   *
 * (const  m:  Tmatrix2_single;
                                                                                                                                   *
 * const  v:  Tvector2_single)
                                                                                                                                   *
 *  :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  multipy  a  two-dimensional  single  precision  matrices  with  a
                two dimensional single precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.



                26.3.10          operator  *(Tmatrix3__double,  Double):  Tmatrix3__double

    Synopsis:    Multiply a three-dimensional double precision matrix by a scalar



                                                                                 811

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



Declaration:     operator  operator  *(Tmatrix3_double,  Double):  Tmatrix3_double
                                                                                                                    (const  m:  Tma*
 *trix3_double;
                                                                                                                    const  x:  Doub*
 *le)
                                                                                                                      :  Tmatrix3_d*
 *ouble

    Visibility:  default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                26.3.11          operator *(Tmatrix3__double, Tmatrix3__double):  Tmatrix3__double

    Synopsis:    Give product of two three-dimensional double precision matrices

Declaration:     operator  operator  *(Tmatrix3_double,  Tmatrix3_double):  Tmatrix3_double
                                                                                                                                   *
 * (const  m1:  Tmatrix3_double;
                                                                                                                                   *
 * const  m2:  Tmatrix3_double)
                                                                                                                                   *
 *  :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.



                26.3.12          operator *(Tmatrix3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Give product of a three-dimendional double precision matrix and vector

Declaration:     operator  operator  *(Tmatrix3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 * (const  m:  Tmatrix3_double;
                                                                                                                                   *
 * const  v:  Tvector3_double)
                                                                                                                                   *
 *  :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to multipy a three-dimensional double precision matrices with a
                three dimensional double precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.



                26.3.13          operator  *(Tmatrix3__extended,  extended):  Tmatrix3__extended

    Synopsis:    Multiply a three-dimensional extended precision matrix by a scalar

Declaration:     operator  operator  *(Tmatrix3_extended,  extended):  Tmatrix3_extended
                                                                                                                               (con*
 *st  m:  Tmatrix3_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                                                                                 812

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.14          operator *(Tmatrix3__extended, Tmatrix3__extended):  Tmatrix3__extended

    Synopsis:    Give product of two three-dimensional extended precision matrices

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m1:  Tmatri@
                                                                                                                                   *
 *           const  m2:  Tmatrix@
                                                                                                                                   *
 *            :  Tmatrix3_extend@

    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.



                26.3.15          operator *(Tmatrix3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Give product of a three-dimendional extended precision matrix and vector

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m:  Tmatrix@
                                                                                                                                   *
 *           const  v:  Tvector3@
                                                                                                                                   *
 *            :  Tvector3_extend@

    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.



                26.3.16          operator  *(Tmatrix3__single,  single):  Tmatrix3__single

    Synopsis:    Multiply a three-dimensional single precision matrix by a scalar

Declaration:     operator  operator  *(Tmatrix3_single,  single):  Tmatrix3_single
                                                                                                                     (const  m:  Tm*
 *atrix3_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix3_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                26.3.17          operator  *(Tmatrix3__single,  Tmatrix3__single):  Tmatrix3__single

    Synopsis:    Give product of two three-dimensional single precision matrices

Declaration:     operator  operator  *(Tmatrix3_single,  Tmatrix3_single):  Tmatrix3_single
                                                                                                                                   *
 * (const  m1:  Tmatrix3_single;
                                                                                                                                   *
 * const  m2:  Tmatrix3_single)
                                                                                                                                   *
 *  :  Tmatrix3_single

    Visibility:   default



                                                                                 813

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.



                26.3.18          operator  *(Tmatrix3__single,  Tvector3__single):  Tvector3__single

    Synopsis:    Give product of a three-dimendional single precision matrix and vector

Declaration:     operator  operator  *(Tmatrix3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 * (const  m:  Tmatrix3_single;
                                                                                                                                   *
 * const  v:  Tvector3_single)
                                                                                                                                   *
 *  :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  multipy  a  three-dimensional  single  precision  matrices  with  a
                three dimensional single precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.



                26.3.19          operator  *(Tmatrix4__double,  Double):  Tmatrix4__double

    Synopsis:    Multiply a four-dimensional double precision matrix by a scalar

Declaration:     operator  operator  *(Tmatrix4_double,  Double):  Tmatrix4_double
                                                                                                                     (const  m:  Tm*
 *atrix4_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix4_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                26.3.20          operator *(Tmatrix4__double, Tmatrix4__double):  Tmatrix4__double

    Synopsis:    Give product of two four-dimensional double precision matrices

Declaration:     operator  operator  *(Tmatrix4_double,  Tmatrix4_double):  Tmatrix4_double
                                                                                                                                   *
 * (const  m1:  Tmatrix4_double;
                                                                                                                                   *
 * const  m2:  Tmatrix4_double)
                                                                                                                                   *
 *  :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.



                26.3.21          operator *(Tmatrix4__double, Tvector4__double):  Tvector4__double

    Synopsis:    Give product of a four-dimendional double precision matrix and vector



                                                                                 814

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



Declaration:     operator  operator  *(Tmatrix4_double,  Tvector4_double):  Tvector4_double
                                                                                                                                   *
 *(const  m:  Tmatrix4_double;
                                                                                                                                   *
 *const  v:  Tvector4_double)
                                                                                                                                   *
 *  :  Tvector4_double

    Visibility:  default

Description:     This  operator  allows  you  to  multipy  a  four-dimensional  double  precision  matrices  with  a
                four dimensional double precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.



                26.3.22          operator  *(Tmatrix4__extended,  extended):  Tmatrix4__extended

    Synopsis:    Multiply a four-dimensional extended precision matrix by a scalar

Declaration:     operator  operator  *(Tmatrix4_extended,  extended):  Tmatrix4_extended
                                                                                                                               (con*
 *st  m:  Tmatrix4_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                26.3.23          operator *(Tmatrix4__extended, Tmatrix4__extended):  Tmatrix4__extended

    Synopsis:    Give product of two four-dimensional extended precision matrices

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m1:  Tmatri@
                                                                                                                                   *
 *           const  m2:  Tmatrix@
                                                                                                                                   *
 *            :  Tmatrix4_extend@

    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.



                26.3.24          operator *(Tmatrix4__extended, Tvector4__extended):  Tvector4__extended

    Synopsis:    Give product of a four-dimendional extended precision matrix and vector

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m:  Tmatrix@
                                                                                                                                   *
 *           const  v:  Tvector4@
                                                                                                                                   *
 *            :  Tvector4_extend@

    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.



                                                                                 815

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.25          operator  *(Tmatrix4__single,  single):  Tmatrix4__single

    Synopsis:    Multiply a four-dimensional single precision matrix by a scalar

Declaration:     operator  operator  *(Tmatrix4_single,  single):  Tmatrix4_single
                                                                                                                     (const  m:  Tm*
 *atrix4_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix4_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to multiply a matrix with a scalar.  All elements in the matrix are
                multiplied by the scalar, the result is returned as a new matrix.



                26.3.26          operator  *(Tmatrix4__single,  Tmatrix4__single):  Tmatrix4__single

    Synopsis:    Give product of two four-dimensional single precision matrices

Declaration:     operator  operator  *(Tmatrix4_single,  Tmatrix4_single):  Tmatrix4_single
                                                                                                                                   *
 * (const  m1:  Tmatrix4_single;
                                                                                                                                   *
 * const  m2:  Tmatrix4_single)
                                                                                                                                   *
 *  :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to multipy two two-dimensional single precision matrices.  A new
                matrix is returned which is the product of both matrices.  The product is calculated using
                the well known matrix multiplication algorithm.



                26.3.27          operator  *(Tmatrix4__single,  Tvector4__single):  Tvector4__single

    Synopsis:    Give product of a four-dimendional single precision matrix and vector

Declaration:     operator  operator  *(Tmatrix4_single,  Tvector4_single):  Tvector4_single
                                                                                                                                   *
 * (const  m:  Tmatrix4_single;
                                                                                                                                   *
 * const  v:  Tvector4_single)
                                                                                                                                   *
 *  :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  multipy  a  four-dimensional  single  precision  matrices  with  a
                four dimensional single precision vector.  A new vector is returned which is the product of
                the  matrix  and  the  vector.  The  product  is  calculated  using  the  well  known  matrix-vector
                multiplication algorithm.



                26.3.28          operator  *(Tvector2__double,  Double):  Tvector2__double

    Synopsis:    Multiply a two-dimensional double precision vector by a scalar

Declaration:     operator  operator  *(Tvector2_double,  Double):  Tvector2_double
                                                                                                                     (const  x:  Tv*
 *ector2_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector2_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                                                                                 816

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.29          operator *(Tvector2__double, Tvector2__double):  Tvector2__double

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  operator  *(Tvector2_double,  Tvector2_double):  Tvector2_double
                                                                                                                                   *
 * (const  x:  Tvector2_double;
                                                                                                                                   *
 * const  y:  Tvector2_double)
                                                                                                                                   *
 *  :  Tvector2_double

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.



                26.3.30          operator  *(Tvector2__extended,  extended):  Tvector2__extended

    Synopsis:    Multiply a two-dimensional extended precision vector by a scalar

Declaration:     operator  operator  *(Tvector2_extended,  extended):  Tvector2_extended
                                                                                                                               (con*
 *st  x:  Tvector2_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                26.3.31          operator *(Tvector2__extended, Tvector2__extended):  Tvector2__extended

    Synopsis:    Multiply two vectors element wise

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  x:  Tvector@
                                                                                                                                   *
 *           const  y:  Tvector2@
                                                                                                                                   *
 *            :  Tvector2_extend@

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.



                26.3.32          operator  *(Tvector2__single,  single):  Tvector2__single

    Synopsis:    Multiply a two-dimensional single precision vector by a scalar

Declaration:     operator  operator  *(Tvector2_single,  single):  Tvector2_single
                                                                                                                     (const  x:  Tv*
 *ector2_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector2_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                                                                                 817

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.33          operator  *(Tvector2__single,  Tvector2__single):  Tvector2__single

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  operator  *(Tvector2_single,  Tvector2_single):  Tvector2_single
                                                                                                                                   *
 * (const  x:  Tvector2_single;
                                                                                                                                   *
 * const  y:  Tvector2_single)
                                                                                                                                   *
 *  :  Tvector2_single

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.



                26.3.34          operator  *(Tvector3__double,  Double):  Tvector3__double

    Synopsis:    Multiply a three-dimensional double precision vector by a scalar

Declaration:     operator  operator  *(Tvector3_double,  Double):  Tvector3_double
                                                                                                                     (const  x:  Tv*
 *ector3_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector3_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                26.3.35          operator *(Tvector3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  operator  *(Tvector3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 * (const  x:  Tvector3_double;
                                                                                                                                   *
 * const  y:  Tvector3_double)
                                                                                                                                   *
 *  :  Tvector3_double

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.



                26.3.36          operator  *(Tvector3__extended,  extended):  Tvector3__extended

    Synopsis:    Multiply a three-dimensional extended precision vector by a scalar

Declaration:     operator  operator  *(Tvector3_extended,  extended):  Tvector3_extended
                                                                                                                               (con*
 *st  x:  Tvector3_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                                                                                 818

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.37          operator *(Tvector3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Multiply two vectors element wise

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  x:  Tvector@
                                                                                                                                   *
 *           const  y:  Tvector3@
                                                                                                                                   *
 *            :  Tvector3_extend@

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.



                26.3.38          operator  *(Tvector3__single,  single):  Tvector3__single

    Synopsis:    Multiply a three-dimensional single precision vector by a scalar

Declaration:     operator  operator  *(Tvector3_single,  single):  Tvector3_single
                                                                                                                     (const  x:  Tv*
 *ector3_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector3_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                26.3.39          operator  *(Tvector3__single,  Tvector3__single):  Tvector3__single

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  operator  *(Tvector3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 * (const  x:  Tvector3_single;
                                                                                                                                   *
 * const  y:  Tvector3_single)
                                                                                                                                   *
 *  :  Tvector3_single

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.



                26.3.40          operator  *(Tvector4__double,  Double):  Tvector4__double

    Synopsis:    Multiply a four-dimensional double precision vector by a scalar

Declaration:     operator  operator  *(Tvector4_double,  Double):  Tvector4_double
                                                                                                                     (const  x:  Tv*
 *ector4_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector4_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                                                                                 819

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.41          operator *(Tvector4__double, Tvector4__double):  Tvector4__double

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  operator  *(Tvector4_double,  Tvector4_double):  Tvector4_double
                                                                                                                                   *
 * (const  x:  Tvector4_double;
                                                                                                                                   *
 * const  y:  Tvector4_double)
                                                                                                                                   *
 *  :  Tvector4_double

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.



                26.3.42          operator  *(Tvector4__extended,  extended):  Tvector4__extended

    Synopsis:    Multiply a four-dimensional extended precision vector by a scalar

Declaration:     operator  operator  *(Tvector4_extended,  extended):  Tvector4_extended
                                                                                                                               (con*
 *st  x:  Tvector4_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                26.3.43          operator *(Tvector4__extended, Tvector4__extended):  Tvector4__extended

    Synopsis:    Multiply two vectors element wise

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  x:  Tvector@
                                                                                                                                   *
 *           const  y:  Tvector4@
                                                                                                                                   *
 *            :  Tvector4_extend@

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.



                26.3.44          operator  *(Tvector4__single,  single):  Tvector4__single

    Synopsis:    Multiply a four-dimensional single precision vector by a scalar

Declaration:     operator  operator  *(Tvector4_single,  single):  Tvector4_single
                                                                                                                     (const  x:  Tv*
 *ector4_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector4_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  multiply  a  vector  by  a  scalar  value.   Each  vector  element  is
                multiplied by the scalar value; the result is returned as a new vector.



                                                                                 820

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.45          operator  *(Tvector4__single,  Tvector4__single):  Tvector4__single

    Synopsis:    Multiply two vectors element wise

Declaration:     operator  operator  *(Tvector4_single,  Tvector4_single):  Tvector4_single
                                                                                                                                   *
 * (const  x:  Tvector4_single;
                                                                                                                                   *
 * const  y:  Tvector4_single)
                                                                                                                                   *
 *  :  Tvector4_single

    Visibility:   default

Description:     This operator returns a vector that contains the element by element multiplication of the
                two multiplied vectors.



                26.3.46          operator  **(Tvector2__double,  Tvector2__double):  Double

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  operator  **(Tvector2_double,  Tvector2_double):  Double
                                                                                                                      (const  x:  T*
 *vector2_double;
                                                                                                                      const  y:  Tv*
 *ector2_double)
                                                                                                                        :  Double

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                26.3.47          operator  **(Tvector2__extended,  Tvector2__extended):  extended

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  operator  **(Tvector2_extended,  Tvector2_extended):  extended
                                                                                                                                (co*
 *nst  x:  Tvector2_extended;
                                                                                                                                con*
 *st  y:  Tvector2_extended)
                                                                                                                                  :*
 *  extended

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                26.3.48          operator  **(Tvector2__single,  Tvector2__single):  single

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  operator  **(Tvector2_single,  Tvector2_single):  single
                                                                                                                      (const  x:  T*
 *vector2_single;
                                                                                                                      const  y:  Tv*
 *ector2_single)
                                                                                                                        :  single

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                                                                                 821

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.49          operator  **(Tvector3__double,  Tvector3__double):  Double

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  operator  **(Tvector3_double,  Tvector3_double):  Double
                                                                                                                      (const  x:  T*
 *vector3_double;
                                                                                                                      const  y:  Tv*
 *ector3_double)
                                                                                                                        :  Double

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                26.3.50          operator  **(Tvector3__extended,  Tvector3__extended):  extended

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  operator  **(Tvector3_extended,  Tvector3_extended):  extended
                                                                                                                                (co*
 *nst  x:  Tvector3_extended;
                                                                                                                                con*
 *st  y:  Tvector3_extended)
                                                                                                                                  :*
 *  extended

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                26.3.51          operator  **(Tvector3__single,  Tvector3__single):  single

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  operator  **(Tvector3_single,  Tvector3_single):  single
                                                                                                                      (const  x:  T*
 *vector3_single;
                                                                                                                      const  y:  Tv*
 *ector3_single)
                                                                                                                        :  single

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                26.3.52          operator  **(Tvector4__double,  Tvector4__double):  Double

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  operator  **(Tvector4_double,  Tvector4_double):  Double
                                                                                                                      (const  x:  T*
 *vector4_double;
                                                                                                                      const  y:  Tv*
 *ector4_double)
                                                                                                                        :  Double

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                                                                                 822

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.53          operator  **(Tvector4__extended,  Tvector4__extended):  extended

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  operator  **(Tvector4_extended,  Tvector4_extended):  extended
                                                                                                                                (co*
 *nst  x:  Tvector4_extended;
                                                                                                                                con*
 *st  y:  Tvector4_extended)
                                                                                                                                  :*
 *  extended

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                26.3.54          operator  **(Tvector4__single,  Tvector4__single):  single

    Synopsis:    Calculate the internal product of two vectors.

Declaration:     operator  operator  **(Tvector4_single,  Tvector4_single):  single
                                                                                                                      (const  x:  T*
 *vector4_single;
                                                                                                                      const  y:  Tv*
 *ector4_single)
                                                                                                                        :  single

    Visibility:   default

Description:     This operator returns the internal product of the two vectors, that is, the elements of the
                two vectors are element-wise multiplied, and then added together.



                26.3.55          operator  +(Tmatrix2__double,  Double):  Tmatrix2__double

    Synopsis:    Add scalar to two-dimensional double precision matrix

Declaration:     operator  operator  +(Tmatrix2_double,  Double):  Tmatrix2_double
                                                                                                                     (const  m:  Tm*
 *atrix2_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix2_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.



                26.3.56          operator +(Tmatrix2__double, Tmatrix2__double):  Tmatrix2__double

    Synopsis:    Add two two-dimensional double precision matrices together.

Declaration:     operator  operator  +(Tmatrix2_double,  Tmatrix2_double):  Tmatrix2_double
                                                                                                                                   *
 * (const  m1:  Tmatrix2_double;
                                                                                                                                   *
 * const  m2:  Tmatrix2_double)
                                                                                                                                   *
 *  :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to add two two-dimensional double precision matrices together.  A
                new matrix is returned with all elements of the two matrices added together.



                                                                                 823

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.57          operator  +(Tmatrix2__extended,  extended):  Tmatrix2__extended

    Synopsis:    Add scalar to two-dimensional extended precision matrix

Declaration:     operator  operator  +(Tmatrix2_extended,  extended):  Tmatrix2_extended
                                                                                                                               (con*
 *st  m:  Tmatrix2_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.



                26.3.58          operator +(Tmatrix2__extended, Tmatrix2__extended):  Tmatrix2__extended

    Synopsis:    Add two two-dimensional extended precision matrices together.

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m1:  Tmatri@
                                                                                                                                   *
 *           const  m2:  Tmatrix@
                                                                                                                                   *
 *            :  Tmatrix2_extend@

    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.



                26.3.59          operator  +(Tmatrix2__single,  single):  Tmatrix2__single

    Synopsis:    Add scalar to two-dimensional single precision matrix

Declaration:     operator  operator  +(Tmatrix2_single,  single):  Tmatrix2_single
                                                                                                                     (const  m:  Tm*
 *atrix2_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix2_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.



                26.3.60          operator  +(Tmatrix2__single,  Tmatrix2__single):  Tmatrix2__single

    Synopsis:    Add two two-dimensional single precision matrices together.

Declaration:     operator  operator  +(Tmatrix2_single,  Tmatrix2_single):  Tmatrix2_single
                                                                                                                                   *
 * (const  m1:  Tmatrix2_single;
                                                                                                                                   *
 * const  m2:  Tmatrix2_single)
                                                                                                                                   *
 *  :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to add two two-dimensional single precision matrices together.  A
                new matrix is returned with all elements of the two matrices added together.



                                                                                 824

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.61          operator  +(Tmatrix3__double,  Double):  Tmatrix3__double

    Synopsis:    Add scalar to three-dimensional double precision matrix

Declaration:     operator  operator  +(Tmatrix3_double,  Double):  Tmatrix3_double
                                                                                                                     (const  m:  Tm*
 *atrix3_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix3_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.



                26.3.62          operator +(Tmatrix3__double, Tmatrix3__double):  Tmatrix3__double

    Synopsis:    Add two three-dimensional double precision matrices together.

Declaration:     operator  operator  +(Tmatrix3_double,  Tmatrix3_double):  Tmatrix3_double
                                                                                                                                   *
 * (const  m1:  Tmatrix3_double;
                                                                                                                                   *
 * const  m2:  Tmatrix3_double)
                                                                                                                                   *
 *  :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to add two three-dimensional double precision matrices together.
                A new matrix is returned with all elements of the two matrices added together.



                26.3.63          operator  +(Tmatrix3__extended,  extended):  Tmatrix3__extended

    Synopsis:    Add scalar to three-dimensional extended precision matrix

Declaration:     operator  operator  +(Tmatrix3_extended,  extended):  Tmatrix3_extended
                                                                                                                               (con*
 *st  m:  Tmatrix3_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.



                26.3.64          operator +(Tmatrix3__extended, Tmatrix3__extended):  Tmatrix3__extended

    Synopsis:    Add two three-dimensional extended precision matrices together.

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m1:  Tmatri@
                                                                                                                                   *
 *           const  m2:  Tmatrix@
                                                                                                                                   *
 *            :  Tmatrix3_extend@

    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.



                                                                                 825

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.65          operator  +(Tmatrix3__single,  single):  Tmatrix3__single

    Synopsis:    Add scalar to three-dimensional single precision matrix

Declaration:     operator  operator  +(Tmatrix3_single,  single):  Tmatrix3_single
                                                                                                                     (const  m:  Tm*
 *atrix3_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix3_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.



                26.3.66          operator  +(Tmatrix3__single,  Tmatrix3__single):  Tmatrix3__single

    Synopsis:    Add two three-dimensional single precision matrices together.

Declaration:     operator  operator  +(Tmatrix3_single,  Tmatrix3_single):  Tmatrix3_single
                                                                                                                                   *
 * (const  m1:  Tmatrix3_single;
                                                                                                                                   *
 * const  m2:  Tmatrix3_single)
                                                                                                                                   *
 *  :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to add two three-dimensional single precision matrices together.
                A new matrix is returned with all elements of the two matrices added together.



                26.3.67          operator  +(Tmatrix4__double,  Double):  Tmatrix4__double

    Synopsis:    Add scalar to four-dimensional double precision matrix

Declaration:     operator  operator  +(Tmatrix4_double,  Double):  Tmatrix4_double
                                                                                                                     (const  m:  Tm*
 *atrix4_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix4_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.



                26.3.68          operator +(Tmatrix4__double, Tmatrix4__double):  Tmatrix4__double

    Synopsis:    Add two four-dimensional double precision matrices together.

Declaration:     operator  operator  +(Tmatrix4_double,  Tmatrix4_double):  Tmatrix4_double
                                                                                                                                   *
 * (const  m1:  Tmatrix4_double;
                                                                                                                                   *
 * const  m2:  Tmatrix4_double)
                                                                                                                                   *
 *  :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to add two four-dimensional double precision matrices together.
                A new matrix is returned with all elements of the two matrices added together.



                                                                                 826

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.69          operator  +(Tmatrix4__extended,  extended):  Tmatrix4__extended

    Synopsis:    Add scalar to four-dimensional extended precision matrix

Declaration:     operator  operator  +(Tmatrix4_extended,  extended):  Tmatrix4_extended
                                                                                                                               (con*
 *st  m:  Tmatrix4_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.



                26.3.70          operator +(Tmatrix4__extended, Tmatrix4__extended):  Tmatrix4__extended

    Synopsis:    Add two four-dimensional extended precision matrices together.

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m1:  Tmatri@
                                                                                                                                   *
 *           const  m2:  Tmatrix@
                                                                                                                                   *
 *            :  Tmatrix4_extend@

    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.



                26.3.71          operator  +(Tmatrix4__single,  single):  Tmatrix4__single

    Synopsis:    Add scalar to four-dimensional single precision matrix

Declaration:     operator  operator  +(Tmatrix4_single,  single):  Tmatrix4_single
                                                                                                                     (const  m:  Tm*
 *atrix4_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix4_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  matrix.   The  scalar  is  added  to  all
                elements of the matrix, the result is returned as a new vector.



                26.3.72          operator  +(Tmatrix4__single,  Tmatrix4__single):  Tmatrix4__single

    Synopsis:    Add two four-dimensional single precision matrices together.

Declaration:     operator  operator  +(Tmatrix4_single,  Tmatrix4_single):  Tmatrix4_single
                                                                                                                                   *
 * (const  m1:  Tmatrix4_single;
                                                                                                                                   *
 * const  m2:  Tmatrix4_single)
                                                                                                                                   *
 *  :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to add two four-dimensional single precision matrices together.  A
                new matrix is returned with all elements of the two matrices added together.



                                                                                 827

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.73          operator  +(Tvector2__double,  Double):  Tvector2__double

    Synopsis:    Add scalar to two-dimensional double precision vector

Declaration:     operator  operator  +(Tvector2_double,  Double):  Tvector2_double
                                                                                                                     (const  x:  Tv*
 *ector2_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector2_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.



                26.3.74          operator +(Tvector2__double, Tvector2__double):  Tvector2__double

    Synopsis:    Add two-dimensional double precision vectors together

Declaration:     operator  operator  +(Tvector2_double,  Tvector2_double):  Tvector2_double
                                                                                                                                   *
 * (const  x:  Tvector2_double;
                                                                                                                                   *
 * const  y:  Tvector2_double)
                                                                                                                                   *
 *  :  Tvector2_double

    Visibility:   default

Description:     This operator allows you to add two two-dimensional vectors with double precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.



                26.3.75          operator  +(Tvector2__extended,  extended):  Tvector2__extended

    Synopsis:    Add scalar to two-dimensional extended precision vector

Declaration:     operator  operator  +(Tvector2_extended,  extended):  Tvector2_extended
                                                                                                                               (con*
 *st  x:  Tvector2_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.



                26.3.76          operator +(Tvector2__extended, Tvector2__extended):  Tvector2__extended

    Synopsis:    Add two-dimensional extended precision vectors together

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  x:  Tvector@
                                                                                                                                   *
 *           const  y:  Tvector2@
                                                                                                                                   *
 *            :  Tvector2_extend@

    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.



                                                                                 828

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.77          operator  +(Tvector2__single,  single):  Tvector2__single

    Synopsis:    Add scalar to two-dimensional single precision vector

Declaration:     operator  operator  +(Tvector2_single,  single):  Tvector2_single
                                                                                                                     (const  x:  Tv*
 *ector2_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector2_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.



                26.3.78          operator  +(Tvector2__single,  Tvector2__single):  Tvector2__single

    Synopsis:    Add two-dimensional single precision vectors together

Declaration:     operator  operator  +(Tvector2_single,  Tvector2_single):  Tvector2_single
                                                                                                                                   *
 * (const  x:  Tvector2_single;
                                                                                                                                   *
 * const  y:  Tvector2_single)
                                                                                                                                   *
 *  :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to add two two-dimensional vectors with single precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.



                26.3.79          operator  +(Tvector3__double,  Double):  Tvector3__double

    Synopsis:    Add scalar to three-dimensional double precision vector

Declaration:     operator  operator  +(Tvector3_double,  Double):  Tvector3_double
                                                                                                                     (const  x:  Tv*
 *ector3_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector3_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.



                26.3.80          operator +(Tvector3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Add three-dimensional double precision vectors together

Declaration:     operator  operator  +(Tvector3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 * (const  x:  Tvector3_double;
                                                                                                                                   *
 * const  y:  Tvector3_double)
                                                                                                                                   *
 *  :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  add  two  three-dimensional  vectors  with  double  precision  to-
                gether.  The result is a new vector which consists of the sums of the individual elements of
                the two vectors.



                                                                                 829

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.81          operator  +(Tvector3__extended,  extended):  Tvector3__extended

    Synopsis:    Add scalar to three-dimensional extended precision vector

Declaration:     operator  operator  +(Tvector3_extended,  extended):  Tvector3_extended
                                                                                                                               (con*
 *st  x:  Tvector3_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.



                26.3.82          operator +(Tvector3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Add three-dimensional extended precision vectors together

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  x:  Tvector@
                                                                                                                                   *
 *           const  y:  Tvector3@
                                                                                                                                   *
 *            :  Tvector3_extend@

    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.



                26.3.83          operator  +(Tvector3__single,  single):  Tvector3__single

    Synopsis:    Add scalar to three-dimensional single precision vector

Declaration:     operator  operator  +(Tvector3_single,  single):  Tvector3_single
                                                                                                                     (const  x:  Tv*
 *ector3_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector3_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.



                26.3.84          operator  +(Tvector3__single,  Tvector3__single):  Tvector3__single

    Synopsis:    Add three-dimensional extended precision vectors together

Declaration:     operator  operator  +(Tvector3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 * (const  x:  Tvector3_single;
                                                                                                                                   *
 * const  y:  Tvector3_single)
                                                                                                                                   *
 *  :  Tvector3_single

    Visibility:   default

Description:     This operator allows you to add two three-dimensional vectors with single precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.



                                                                                 830

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.85          operator  +(Tvector4__double,  Double):  Tvector4__double

    Synopsis:    Add scalar to four-dimensional double precision vector

Declaration:     operator  operator  +(Tvector4_double,  Double):  Tvector4_double
                                                                                                                     (const  x:  Tv*
 *ector4_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector4_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.



                26.3.86          operator +(Tvector4__double, Tvector4__double):  Tvector4__double

    Synopsis:    Add four-dimensional double precision vectors together

Declaration:     operator  operator  +(Tvector4_double,  Tvector4_double):  Tvector4_double
                                                                                                                                   *
 * (const  x:  Tvector4_double;
                                                                                                                                   *
 * const  y:  Tvector4_double)
                                                                                                                                   *
 *  :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to add two four-dimensional vectors with single precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.



                26.3.87          operator  +(Tvector4__extended,  extended):  Tvector4__extended

    Synopsis:    Add scalar to four-dimensional extended precision vector

Declaration:     operator  operator  +(Tvector4_extended,  extended):  Tvector4_extended
                                                                                                                               (con*
 *st  x:  Tvector4_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.



                26.3.88          operator +(Tvector4__extended, Tvector4__extended):  Tvector4__extended

    Synopsis:    Add four-dimensional extended precision vectors together

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  x:  Tvector@
                                                                                                                                   *
 *           const  y:  Tvector4@
                                                                                                                                   *
 *            :  Tvector4_extend@

    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.



                                                                                 831

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.89          operator  +(Tvector4__single,  single):  Tvector4__single

    Synopsis:    Add scalar to four-dimensional single precision vector

Declaration:     operator  operator  +(Tvector4_single,  single):  Tvector4_single
                                                                                                                     (const  x:  Tv*
 *ector4_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector4_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  add  a  scalar  value  to  a  vector.   The  scalar  is  added  to  all
                elements of the vector, the result is returned as a new vector.



                26.3.90          operator  +(Tvector4__single,  Tvector4__single):  Tvector4__single

    Synopsis:    Add four-dimensional single precision vectors together

Declaration:     operator  operator  +(Tvector4_single,  Tvector4_single):  Tvector4_single
                                                                                                                                   *
 * (const  x:  Tvector4_single;
                                                                                                                                   *
 * const  y:  Tvector4_single)
                                                                                                                                   *
 *  :  Tvector4_single

    Visibility:   default

Description:     This operator allows you to add two four-dimensional vectors with single precision together.
                The result is a new vector which consists of the sums of the individual elements of the two
                vectors.



                26.3.91          operator  -(Tmatrix2__double):  Tmatrix2__double

    Synopsis:    Negate two-dimensional double precision matrix.

Declaration:     operator  operator  -(Tmatrix2_double):  Tmatrix2_double
                                                                                                        (const  m1:  Tmatrix2_doubl*
 *e)
                                                                                                         :  Tmatrix2_double

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                26.3.92          operator  -(Tmatrix2__double,  Double):  Tmatrix2__double

    Synopsis:    Subtract scalar to two-dimensional double precision matrix

Declaration:     operator  operator  -(Tmatrix2_double,  Double):  Tmatrix2_double
                                                                                                                     (const  m:  Tm*
 *atrix2_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix2_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                                                                                 832

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.93          operator -(Tmatrix2__double, Tmatrix2__double):  Tmatrix2__double

    Synopsis:    Subtract a two-dimensional double precision matrix from another.

Declaration:     operator  operator  -(Tmatrix2_double,  Tmatrix2_double):  Tmatrix2_double
                                                                                                                                   *
 * (const  m1:  Tmatrix2_double;
                                                                                                                                   *
 * const  m2:  Tmatrix2_double)
                                                                                                                                   *
 *  :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to subtract a two-dimensional double precision matrix from an-
                other.  A new matrix is returned with all elements of the two matrices subtracted from each
                other.



                26.3.94          operator  -(Tmatrix2__extended):  Tmatrix2__extended

    Synopsis:    Negate two-dimensional extended precision matrix.

Declaration:     operator  operator  -(Tmatrix2_extended):  Tmatrix2_extended
                                                                                                              (const  m1:  Tmatrix2*
 *_extended)
                                                                                                                :  Tmatrix2_extended

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                26.3.95          operator  -(Tmatrix2__extended,  extended):  Tmatrix2__extended

    Synopsis:    Add scalar to two-dimensional extended precision matrix

Declaration:     operator  operator  -(Tmatrix2_extended,  extended):  Tmatrix2_extended
                                                                                                                               (con*
 *st  m:  Tmatrix2_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                26.3.96          operator -(Tmatrix2__extended, Tmatrix2__extended):  Tmatrix2__extended

    Synopsis:    Subtract a two-dimensional extended precision matrix from another.

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m1:  Tmatri@
                                                                                                                                   *
 *           const  m2:  Tmatrix@
                                                                                                                                   *
 *            :  Tmatrix2_extend@

    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.



                                                                                 833

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.97          operator  -(Tmatrix2__single):  Tmatrix2__single

    Synopsis:    Negate two-dimensional single precision matrix.

Declaration:     operator  operator  -(Tmatrix2_single):  Tmatrix2_single
                                                                                                        (const  m1:  Tmatrix2_singl*
 *e)
                                                                                                         :  Tmatrix2_single

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                26.3.98          operator  -(Tmatrix2__single,  single):  Tmatrix2__single

    Synopsis:    Subtract scalar to two-dimensional single precision matrix

Declaration:     operator  operator  -(Tmatrix2_single,  single):  Tmatrix2_single
                                                                                                                     (const  m:  Tm*
 *atrix2_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix2_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                26.3.99          operator  -(Tmatrix2__single,  Tmatrix2__single):  Tmatrix2__single

    Synopsis:    Subtract a two-dimensional single precision matrix from another.

Declaration:     operator  operator  -(Tmatrix2_single,  Tmatrix2_single):  Tmatrix2_single
                                                                                                                                   *
 * (const  m1:  Tmatrix2_single;
                                                                                                                                   *
 * const  m2:  Tmatrix2_single)
                                                                                                                                   *
 *  :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to subtract a two-dimensional single precision matrix from another.
                A new matrix is returned with all elements of the two matrices subtracted from each other.



                26.3.100           operator  -(Tmatrix3__double):  Tmatrix3__double

    Synopsis:    Negate three-dimensional double precision matrix.

Declaration:     operator  operator  -(Tmatrix3_double):  Tmatrix3_double
                                                                                                        (const  m1:  Tmatrix3_doubl*
 *e)
                                                                                                         :  Tmatrix3_double

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                                                                                 834

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.101           operator  -(Tmatrix3__double,  Double):  Tmatrix3__double

    Synopsis:    Add scalar to three-dimensional double precision matrix

Declaration:     operator  operator  -(Tmatrix3_double,  Double):  Tmatrix3_double
                                                                                                                     (const  m:  Tm*
 *atrix3_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix3_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                26.3.102           operator -(Tmatrix3__double, Tmatrix3__double):  Tmatrix3__double

    Synopsis:    Subtract a three-dimensional double precision matrix from another.

Declaration:     operator  operator  -(Tmatrix3_double,  Tmatrix3_double):  Tmatrix3_double
                                                                                                                                   *
 * (const  m1:  Tmatrix3_double;
                                                                                                                                   *
 * const  m2:  Tmatrix3_double)
                                                                                                                                   *
 *  :  Tmatrix3_double

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  a  three-dimensional  double  precision  matrix  from
                another.  A new matrix is returned with all elements of the two matrices subtracted from
                each other.



                26.3.103           operator  -(Tmatrix3__extended):  Tmatrix3__extended

    Synopsis:    Negate three-dimensional extended precision matrix.

Declaration:     operator  operator  -(Tmatrix3_extended):  Tmatrix3_extended
                                                                                                              (const  m1:  Tmatrix3*
 *_extended)
                                                                                                                :  Tmatrix3_extended

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                26.3.104           operator -(Tmatrix3__extended, extended):  Tmatrix3__extended

    Synopsis:    Add scalar to three-dimensional extended precision matrix

Declaration:     operator  operator  -(Tmatrix3_extended,  extended):  Tmatrix3_extended
                                                                                                                               (con*
 *st  m:  Tmatrix3_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to substract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                                                                                 835

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.105           operator -(Tmatrix3__extended, Tmatrix3__extended):  Tmatrix3__extended

    Synopsis:    Subtract a three-dimensional extended precision matrix from another.

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m1:  Tmatri@
                                                                                                                                   *
 *           const  m2:  Tmatrix@
                                                                                                                                   *
 *            :  Tmatrix3_extend@

    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.



                26.3.106           operator  -(Tmatrix3__single):  Tmatrix3__single

    Synopsis:    Negate three-dimensional single precision matrix.

Declaration:     operator  operator  -(Tmatrix3_single):  Tmatrix3_single
                                                                                                        (const  m1:  Tmatrix3_singl*
 *e)
                                                                                                         :  Tmatrix3_single

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                26.3.107           operator  -(Tmatrix3__single,  single):  Tmatrix3__single

    Synopsis:    Add scalar to three-dimensional single precision matrix

Declaration:     operator  operator  -(Tmatrix3_single,  single):  Tmatrix3_single
                                                                                                                     (const  m:  Tm*
 *atrix3_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix3_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                26.3.108           operator  -(Tmatrix3__single,  Tmatrix3__single):  Tmatrix3__single

    Synopsis:    Subtract a three-dimensional single precision matrix from another.

Declaration:     operator  operator  -(Tmatrix3_single,  Tmatrix3_single):  Tmatrix3_single
                                                                                                                                   *
 * (const  m1:  Tmatrix3_single;
                                                                                                                                   *
 * const  m2:  Tmatrix3_single)
                                                                                                                                   *
 *  :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to subtract a three-dimensional single precision matrix from an-
                other.  A new matrix is returned with all elements of the two matrices subtracted from each
                other.



                                                                                 836

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.109           operator  -(Tmatrix4__double):  Tmatrix4__double

    Synopsis:    Negate four-dimensional double precision matrix.

Declaration:     operator  operator  -(Tmatrix4_double):  Tmatrix4_double
                                                                                                        (const  m1:  Tmatrix4_doubl*
 *e)
                                                                                                         :  Tmatrix4_double

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                26.3.110           operator  -(Tmatrix4__double,  Double):  Tmatrix4__double

    Synopsis:    Add scalar to four-dimensional double precision matrix

Declaration:     operator  operator  -(Tmatrix4_double,  Double):  Tmatrix4_double
                                                                                                                     (const  m:  Tm*
 *atrix4_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix4_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                26.3.111           operator -(Tmatrix4__double, Tmatrix4__double):  Tmatrix4__double

    Synopsis:    Subtract a four-dimensional double precision matrix from another.

Declaration:     operator  operator  -(Tmatrix4_double,  Tmatrix4_double):  Tmatrix4_double
                                                                                                                                   *
 * (const  m1:  Tmatrix4_double;
                                                                                                                                   *
 * const  m2:  Tmatrix4_double)
                                                                                                                                   *
 *  :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to subtract a four-dimensional double precision matrix from an-
                other.  A new matrix is returned with all elements of the two matrices subtracted from each
                other.



                26.3.112           operator  -(Tmatrix4__extended):  Tmatrix4__extended

    Synopsis:    Negate four-dimensional extended precision matrix.

Declaration:     operator  operator  -(Tmatrix4_extended):  Tmatrix4_extended
                                                                                                              (const  m1:  Tmatrix4*
 *_extended)
                                                                                                                :  Tmatrix4_extended

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                                                                                 837

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.113           operator -(Tmatrix4__extended, extended):  Tmatrix4__extended

    Synopsis:    Add scalar to four-dimensional extended precision matrix

Declaration:     operator  operator  -(Tmatrix4_extended,  extended):  Tmatrix4_extended
                                                                                                                               (con*
 *st  m:  Tmatrix4_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                26.3.114           operator -(Tmatrix4__extended, Tmatrix4__extended):  Tmatrix4__extended

    Synopsis:    Subtract a four-dimensional extended precision matrix from another.

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  m1:  Tmatri@
                                                                                                                                   *
 *           const  m2:  Tmatrix@
                                                                                                                                   *
 *            :  Tmatrix4_extend@

    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.



                26.3.115           operator  -(Tmatrix4__single):  Tmatrix4__single

    Synopsis:    Negate four-dimensional single precision matrix.

Declaration:     operator  operator  -(Tmatrix4_single):  Tmatrix4_single
                                                                                                        (const  m1:  Tmatrix4_singl*
 *e)
                                                                                                         :  Tmatrix4_single

    Visibility:   default

Description:     This operation returns a matrix with all elements negated.



                26.3.116           operator  -(Tmatrix4__single,  single):  Tmatrix4__single

    Synopsis:    Add scalar to four-dimensional single precision matrix

Declaration:     operator  operator  -(Tmatrix4_single,  single):  Tmatrix4_single
                                                                                                                     (const  m:  Tm*
 *atrix4_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix4_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a matrix.  The scalar is subtracted
                from all elements of the matrix, the result is returned as a new matrix.



                                                                                 838

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.117           operator  -(Tmatrix4__single,  Tmatrix4__single):  Tmatrix4__single

    Synopsis:    Subtract a four-dimensional single precision matrix from another.

Declaration:     operator  operator  -(Tmatrix4_single,  Tmatrix4_single):  Tmatrix4_single
                                                                                                                                   *
 * (const  m1:  Tmatrix4_single;
                                                                                                                                   *
 * const  m2:  Tmatrix4_single)
                                                                                                                                   *
 *  :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to subtract a four-dimensional single precision matrix from another.
                A new matrix is returned with all elements of the two matrices subtracted from each other.



                26.3.118           operator  -(Tvector2__double):  Tvector2__double

    Synopsis:    Negate two-dimensional vector.

Declaration:     operator  operator  -(Tvector2_double):  Tvector2_double
                                                                                                        (const  x:  Tvector2_double)
                                                                                                         :  Tvector2_double

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                26.3.119           operator  -(Tvector2__double,  Double):  Tvector2__double

    Synopsis:    Subtract scalar from two-dimensional double precision vector

Declaration:     operator  operator  -(Tvector2_double,  Double):  Tvector2_double
                                                                                                                     (const  x:  Tv*
 *ector2_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector2_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                26.3.120           operator -(Tvector2__double, Tvector2__double):  Tvector2__double

    Synopsis:    Subtract two-dimensional double precision vectors from each other

Declaration:     operator  operator  -(Tvector2_double,  Tvector2_double):  Tvector2_double
                                                                                                                                   *
 * (const  x:  Tvector2_double;
                                                                                                                                   *
 * const  y:  Tvector2_double)
                                                                                                                                   *
 *  :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  two-dimensional  vectors  with  double  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.



                                                                                 839

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.121           operator  -(Tvector2__extended):  Tvector2__extended

    Synopsis:    Negate two-dimensional vector.

Declaration:     operator  operator  -(Tvector2_extended):  Tvector2_extended
                                                                                                              (const  x:  Tvector2_*
 *extended)
                                                                                                                :  Tvector2_extended

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                26.3.122           operator  -(Tvector2__extended,  extended):  Tvector2__extended

    Synopsis:    Subtract scalar from two-dimensional extended precision vector

Declaration:     operator  operator  -(Tvector2_extended,  extended):  Tvector2_extended
                                                                                                                               (con*
 *st  x:  Tvector2_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector2_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                26.3.123           operator -(Tvector2__extended, Tvector2__extended):  Tvector2__extended

    Synopsis:    Subtract two-dimensional extended precision vectors from each other

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  x:  Tvector@
                                                                                                                                   *
 *           const  y:  Tvector2@
                                                                                                                                   *
 *            :  Tvector2_extend@

    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.



                26.3.124           operator  -(Tvector2__single):  Tvector2__single

    Synopsis:    Negate two-dimensional vector.

Declaration:     operator  operator  -(Tvector2_single):  Tvector2_single
                                                                                                        (const  x:  Tvector2_single)
                                                                                                         :  Tvector2_single

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                                                                                 840

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.125           operator  -(Tvector2__single,  single):  Tvector2__single

    Synopsis:    Subtract scalar from two-dimensional single precision vector

Declaration:     operator  operator  -(Tvector2_single,  single):  Tvector2_single
                                                                                                                     (const  x:  Tv*
 *ector2_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector2_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                26.3.126           operator  -(Tvector2__single,  Tvector2__single):  Tvector2__single

    Synopsis:    Subtract two-dimensional single precision vectors from each other

Declaration:     operator  operator  -(Tvector2_single,  Tvector2_single):  Tvector2_single
                                                                                                                                   *
 * (const  x:  Tvector2_single;
                                                                                                                                   *
 * const  y:  Tvector2_single)
                                                                                                                                   *
 *  :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to subtract two two-dimensional vectors with single precision from
                each  other.   The  result  is  a  new  vector  which  consists  of  the  difference  of  the  individual
                elements of the two vectors.



                26.3.127           operator  -(Tvector3__double):  Tvector3__double

    Synopsis:    Negate three-dimensional vector.

Declaration:     operator  operator  -(Tvector3_double):  Tvector3_double
                                                                                                        (const  x:  Tvector3_double)
                                                                                                         :  Tvector3_double

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                26.3.128           operator  -(Tvector3__double,  Double):  Tvector3__double

    Synopsis:    Subtract scalar from three-dimensional double precision vector

Declaration:     operator  operator  -(Tvector3_double,  Double):  Tvector3_double
                                                                                                                     (const  x:  Tv*
 *ector3_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector3_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                                                                                 841

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.129           operator -(Tvector3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Subtract three-dimensional double precision vectors from each other

Declaration:     operator  operator  -(Tvector3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 * (const  x:  Tvector3_double;
                                                                                                                                   *
 * const  y:  Tvector3_double)
                                                                                                                                   *
 *  :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  two-dimensional  vectors  with  double  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.



                26.3.130           operator  -(Tvector3__extended):  Tvector3__extended

    Synopsis:    Negate three-dimensional vector.

Declaration:     operator  operator  -(Tvector3_extended):  Tvector3_extended
                                                                                                              (const  x:  Tvector3_*
 *extended)
                                                                                                                :  Tvector3_extended

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                26.3.131           operator  -(Tvector3__extended,  extended):  Tvector3__extended

    Synopsis:    Subtract scalar from three-dimensional extended precision vector

Declaration:     operator  operator  -(Tvector3_extended,  extended):  Tvector3_extended
                                                                                                                               (con*
 *st  x:  Tvector3_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector3_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                26.3.132           operator -(Tvector3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Subtract three-dimensional extended precision vectors from each other

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  x:  Tvector@
                                                                                                                                   *
 *           const  y:  Tvector3@
                                                                                                                                   *
 *            :  Tvector3_extend@

    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.



                                                                                 842

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.133           operator  -(Tvector3__single):  Tvector3__single

    Synopsis:    Negate three-dimensional vector.

Declaration:     operator  operator  -(Tvector3_single):  Tvector3_single
                                                                                                        (const  x:  Tvector3_single)
                                                                                                         :  Tvector3_single

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                26.3.134           operator  -(Tvector3__single,  single):  Tvector3__single

    Synopsis:    Subtract scalar from three-dimensional single precision vector

Declaration:     operator  operator  -(Tvector3_single,  single):  Tvector3_single
                                                                                                                     (const  x:  Tv*
 *ector3_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector3_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                26.3.135           operator  -(Tvector3__single,  Tvector3__single):  Tvector3__single

    Synopsis:    Subtract three-dimensional single precision vectors from each other

Declaration:     operator  operator  -(Tvector3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 * (const  x:  Tvector3_single;
                                                                                                                                   *
 * const  y:  Tvector3_single)
                                                                                                                                   *
 *  :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  three-dimensional  vectors  with  single  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.



                26.3.136           operator  -(Tvector4__double):  Tvector4__double

    Synopsis:    Negate four-dimensional vector.

Declaration:     operator  operator  -(Tvector4_double):  Tvector4_double
                                                                                                        (const  x:  Tvector4_double)
                                                                                                         :  Tvector4_double

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                                                                                 843

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.137           operator  -(Tvector4__double,  Double):  Tvector4__double

    Synopsis:    Subtract scalar from four-dimensional double precision vector

Declaration:     operator  operator  -(Tvector4_double,  Double):  Tvector4_double
                                                                                                                     (const  x:  Tv*
 *ector4_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector4_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                26.3.138           operator -(Tvector4__double, Tvector4__double):  Tvector4__double

    Synopsis:    Subtract four-dimensional double precision vectors from each other

Declaration:     operator  operator  -(Tvector4_double,  Tvector4_double):  Tvector4_double
                                                                                                                                   *
 * (const  x:  Tvector4_double;
                                                                                                                                   *
 * const  y:  Tvector4_double)
                                                                                                                                   *
 *  :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  four-dimensional  vectors  with  double  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.



                26.3.139           operator  -(Tvector4__extended):  Tvector4__extended

    Synopsis:    Negate four-dimensional vector.

Declaration:     operator  operator  -(Tvector4_extended):  Tvector4_extended
                                                                                                              (const  x:  Tvector4_*
 *extended)
                                                                                                                :  Tvector4_extended

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                26.3.140           operator  -(Tvector4__extended,  extended):  Tvector4__extended

    Synopsis:    Subtract scalar from four-dimensional extended precision vector

Declaration:     operator  operator  -(Tvector4_extended,  extended):  Tvector4_extended
                                                                                                                               (con*
 *st  x:  Tvector4_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector4_extended

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                                                                                 844

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.141           operator -(Tvector4__extended, Tvector4__extended):  Tvector4__extended

    Synopsis:    Subtract four-dimensional extended precision vectors from each other

Declaration:
                                                                                                                                   *
 *           operator  operator @
                                                                                                                                   *
 *           (const  x:  Tvector@
                                                                                                                                   *
 *           const  y:  Tvector4@
                                                                                                                                   *
 *            :  Tvector4_extend@

    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.



                26.3.142           operator  -(Tvector4__single):  Tvector4__single

    Synopsis:    Negate four-dimensional vector.

Declaration:     operator  operator  -(Tvector4_single):  Tvector4_single
                                                                                                        (const  x:  Tvector4_single)
                                                                                                         :  Tvector4_single

    Visibility:   default

Description:     This operation returns a vector in the opposite direction of the vector that is passed.  In
                order to do so, all values in the vector are negated.



                26.3.143           operator  -(Tvector4__single,  single):  Tvector4__single

    Synopsis:    Subtract scalar from four-dimensional single precision vector

Declaration:     operator  operator  -(Tvector4_single,  single):  Tvector4_single
                                                                                                                     (const  x:  Tv*
 *ector4_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector4_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to subtract a scalar value from a vector.  The scalar is subtracted
                from all elements of the vector, the result is returned as a new vector.



                26.3.144           operator  -(Tvector4__single,  Tvector4__single):  Tvector4__single

    Synopsis:    Subtract four-dimensional single precision vectors from each other

Declaration:     operator  operator  -(Tvector4_single,  Tvector4_single):  Tvector4_single
                                                                                                                                   *
 * (const  x:  Tvector4_single;
                                                                                                                                   *
 * const  y:  Tvector4_single)
                                                                                                                                   *
 *  :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  subtract  two  four-dimensional  vectors  with  single  precision
                from each other.  The result is a new vector which consists of the difference of the individual
                elements of the two vectors.



                                                                                 845

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.145           operator  /(Tmatrix2__double,  Double):  Tmatrix2__double

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  /(Tmatrix2_double,  Double):  Tmatrix2_double
                                                                                                                     (const  m:  Tm*
 *atrix2_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix2_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                26.3.146           operator /(Tmatrix2__extended, extended):  Tmatrix2__extended

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  /(Tmatrix2_extended,  extended):  Tmatrix2_extended
                                                                                                                               (con*
 *st  m:  Tmatrix2_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                26.3.147           operator  /(Tmatrix2__single,  single):  Tmatrix2__single

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  /(Tmatrix2_single,  single):  Tmatrix2_single
                                                                                                                     (const  m:  Tm*
 *atrix2_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix2_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                26.3.148           operator  /(Tmatrix3__double,  Double):  Tmatrix3__double

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  /(Tmatrix3_double,  Double):  Tmatrix3_double
                                                                                                                     (const  m:  Tm*
 *atrix3_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix3_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                                                                                 846

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.149           operator /(Tmatrix3__extended, extended):  Tmatrix3__extended

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  /(Tmatrix3_extended,  extended):  Tmatrix3_extended
                                                                                                                               (con*
 *st  m:  Tmatrix3_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                26.3.150           operator  /(Tmatrix3__single,  single):  Tmatrix3__single

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  /(Tmatrix3_single,  single):  Tmatrix3_single
                                                                                                                     (const  m:  Tm*
 *atrix3_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix3_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                26.3.151           operator  /(Tmatrix4__double,  Double):  Tmatrix4__double

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  /(Tmatrix4_double,  Double):  Tmatrix4_double
                                                                                                                     (const  m:  Tm*
 *atrix4_double;
                                                                                                                     const  x:  Dou*
 *ble)
                                                                                                                      :  Tmatrix4_d*
 *ouble

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                26.3.152           operator /(Tmatrix4__extended, extended):  Tmatrix4__extended

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  /(Tmatrix4_extended,  extended):  Tmatrix4_extended
                                                                                                                               (con*
 *st  m:  Tmatrix4_extended;
                                                                                                                               cons*
 *t  x:  extended)
                                                                                                                                :  *
 *Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                                                                                 847

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.153           operator  /(Tmatrix4__single,  single):  Tmatrix4__single

    Synopsis:    Divide a two-dimensional single precision matrix by a scalar

Declaration:     operator  operator  /(Tmatrix4_single,  single):  Tmatrix4_single
                                                                                                                     (const  m:  Tm*
 *atrix4_single;
                                                                                                                     const  x:  sin*
 *gle)
                                                                                                                      :  Tmatrix4_s*
 *ingle

    Visibility:   default

Description:     This  operator  allows  you  to  divide  a  matrix  by  a  scalar.  All  elements  in  the  matrix  are
                divided by the scalar, the result is returned as a new matrix.



                26.3.154           operator  /(Tvector2__double,  Double):  Tvector2__double

    Synopsis:    Divide a two-dimensional double precision vector by a scalar

Declaration:     operator  operator  /(Tvector2_double,  Double):  Tvector2_double
                                                                                                                     (const  x:  Tv*
 *ector2_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector2_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                26.3.155           operator  /(Tvector2__extended,  extended):  Tvector2__extended

    Synopsis:    Divide a two-dimensional extended precision vector by a scalar

Declaration:     operator  operator  /(Tvector2_extended,  extended):  Tvector2_extended
                                                                                                                               (con*
 *st  x:  Tvector2_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector2_extended

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                26.3.156           operator  /(Tvector2__single,  single):  Tvector2__single

    Synopsis:    Divide a two-dimensional single precision vector by a scalar

Declaration:     operator  operator  /(Tvector2_single,  single):  Tvector2_single
                                                                                                                     (const  x:  Tv*
 *ector2_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector2_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                                                                                 848

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.157           operator  /(Tvector3__double,  Double):  Tvector3__double

    Synopsis:    Divide a three-dimensional double precision vector by a scalar

Declaration:     operator  operator  /(Tvector3_double,  Double):  Tvector3_double
                                                                                                                     (const  x:  Tv*
 *ector3_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector3_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                26.3.158           operator  /(Tvector3__extended,  extended):  Tvector3__extended

    Synopsis:    Divide a three-dimensional extended precision vector by a scalar

Declaration:     operator  operator  /(Tvector3_extended,  extended):  Tvector3_extended
                                                                                                                               (con*
 *st  x:  Tvector3_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector3_extended

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                26.3.159           operator  /(Tvector3__single,  single):  Tvector3__single

    Synopsis:    Divide a three-dimensional single precision vector by a scalar

Declaration:     operator  operator  /(Tvector3_single,  single):  Tvector3_single
                                                                                                                     (const  x:  Tv*
 *ector3_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector3_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                26.3.160           operator  /(Tvector4__double,  Double):  Tvector4__double

    Synopsis:    Divide a four-dimensional double precision vector by a scalar

Declaration:     operator  operator  /(Tvector4_double,  Double):  Tvector4_double
                                                                                                                     (const  x:  Tv*
 *ector4_double;
                                                                                                                     y:  Double)
                                                                                                                      :  Tvector4_d*
 *ouble

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                                                                                 849

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.161           operator  /(Tvector4__extended,  extended):  Tvector4__extended

    Synopsis:    Divide a four-dimensional extended precision vector by a scalar

Declaration:     operator  operator  /(Tvector4_extended,  extended):  Tvector4_extended
                                                                                                                               (con*
 *st  x:  Tvector4_extended;
                                                                                                                               y:  *
 *extended)
                                                                                                                                :  *
 *Tvector4_extended

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                26.3.162           operator  /(Tvector4__single,  single):  Tvector4__single

    Synopsis:    Divide a four-dimensional single precision vector by a scalar

Declaration:     operator  operator  /(Tvector4_single,  single):  Tvector4_single
                                                                                                                     (const  x:  Tv*
 *ector4_single;
                                                                                                                     y:  single)
                                                                                                                      :  Tvector4_s*
 *ingle

    Visibility:   default

Description:     This operator allows you to divide a vector by a scalar value.  Each vector element is divided
                by the scalar value; the result is returned as a new vector.



                26.3.163           operator  :=(Tmatrix2__double):  Tmatrix2__extended

    Synopsis:    Allow assignment of two-dimensional double precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_double):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix2_d*
 *ouble)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with extended precision is expected.



                26.3.164           operator  :=(Tmatrix2__double):  Tmatrix2__single

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_double):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with single precision is expected.  Some accurace is lost
                because of the conversion.



                                                                                 850

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.165           operator  :=(Tmatrix2__double):  Tmatrix3__double

    Synopsis:    Allow assignment of two-dimensional double precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_double):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with double precision is expected.  The extra fields are
                set to 0.



                26.3.166           operator  :=(Tmatrix2__double):  Tmatrix3__extended

    Synopsis:    Allow assignment of two-dimensional double precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_double):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix2_d*
 *ouble)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with extended precision is expected.  The extra fields
                are set to 0.



                26.3.167           operator  :=(Tmatrix2__double):  Tmatrix3__single

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_double):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a three-dimensional matrix with single precision is expected.  The extra fields are set to
                0 and some accuracy is lost because of the conversion.



                26.3.168           operator  :=(Tmatrix2__double):  Tmatrix4__double

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_double):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with double precision is expected.  The extra fields are
                set to 0.



                                                                                 851

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.169           operator  :=(Tmatrix2__double):  Tmatrix4__extended

    Synopsis:    Allow assignment of two-dimensional double precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_double):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix2_d*
 *ouble)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever  a  four-dimensional  matrix  with  extended  precision  is  expected.  The  extra  fields
                are set to 0.



                26.3.170           operator  :=(Tmatrix2__double):  Tmatrix4__single

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  matrix  to  four-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_double):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix2_doubl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with single precision is expected.  The extra fields are
                set to 0 and some precision is lost because of the conversion.



                26.3.171           operator  :=(Tmatrix2__extended):  Tmatrix2__double

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to two-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_extended):  Tmatrix2_double
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional two with extended precision values wher-
                ever  a  two-dimensional  matrix  with  double  precision  is  expected.   Some  accuracy  is  lost
                because of the conversion.



                26.3.172           operator  :=(Tmatrix2__extended):  Tmatrix2__single

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to two-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_extended):  Tmatrix2_single
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with single precision is expected.  Some accuracy is lost
                because of the conversion.



                                                                                 852

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.173           operator  :=(Tmatrix2__extended):  Tmatrix3__double

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_extended):  Tmatrix3_double
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with double precision is expected.  The extra fields are
                set to 0 and some accuracy is lost because of the conversion.



                26.3.174           operator  :=(Tmatrix2__extended):  Tmatrix3__extended

    Synopsis:    Allow  assignment  of  two-dimensional  extended  precision  matrix  to  three-dimensional  ex-
                tended precision matrix

Declaration:     operator  operator  :=(Tmatrix2_extended):  Tmatrix3_extended
                                                                                                                (const  v:  Tmatrix*
 *2_extended)
                                                                                                                  :  Tmatrix3_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with extended precision is expected.  The extra fields
                are set to 0.



                26.3.175           operator  :=(Tmatrix2__extended):  Tmatrix3__single

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to three-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_extended):  Tmatrix3_single
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with single precision is expected.  The extra fields are
                set to 0 and some accuracy is lost because of the conversion.



                26.3.176           operator  :=(Tmatrix2__extended):  Tmatrix4__double

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to four-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_extended):  Tmatrix4_double
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with double precision is expected.  The extra fields are
                set to 0 and some accuracy is lost because of the conversion.



                                                                                 853

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.177           operator  :=(Tmatrix2__extended):  Tmatrix4__extended

    Synopsis:    Allow  assignment  of  two-dimensional  extended  precision  matrix  to  four-dimensional  ex-
                tended precision matrix

Declaration:     operator  operator  :=(Tmatrix2_extended):  Tmatrix4_extended
                                                                                                                (const  v:  Tmatrix*
 *2_extended)
                                                                                                                  :  Tmatrix4_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with single precision is expected.  The extra fields are set to
                0.



                26.3.178           operator  :=(Tmatrix2__extended):  Tmatrix4__single

    Synopsis:    Allow assignment of two-dimensional extended precision matrix to four-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_extended):  Tmatrix4_single
                                                                                                             (const  v:  Tmatrix2_e*
 *xtended)
                                                                                                              :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with single precision is expected.  The extra fields are
                set to 0 and some precision is lost because of the conversion.



                26.3.179           operator  :=(Tmatrix2__single):  Tmatrix2__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_single):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with double precision is expected.



                26.3.180           operator  :=(Tmatrix2__single):  Tmatrix2__extended

    Synopsis:    Allow assignment of two-dimensional single precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_single):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix2_s*
 *ingle)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with extended precision is expected.



                                                                                 854

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.181           operator  :=(Tmatrix2__single):  Tmatrix3__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  three-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_single):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a three-dimensional matrix with double precision is expected.  The extra fields are set
                to 0.



                26.3.182           operator  :=(Tmatrix2__single):  Tmatrix3__extended

    Synopsis:    Allow assignment of two-dimensional single precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_single):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix2_s*
 *ingle)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever  a  three-dimensional  matrix  with  extended  precision  is  expected.  The  extra  fields  are
                set to 0.



                26.3.183           operator  :=(Tmatrix2__single):  Tmatrix3__single

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_single):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a three-dimensional matrix with single precision is expected.  The extra fields are set to
                0.



                26.3.184           operator  :=(Tmatrix2__single):  Tmatrix4__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_single):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with double precision is expected.  The extra fields are set to
                0.



                                                                                 855

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.185           operator  :=(Tmatrix2__single):  Tmatrix4__extended

    Synopsis:    Allow assignment of two-dimensional single precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix2_single):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix2_s*
 *ingle)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with extended precision is expected.  The extra fields are set
                to 0.



                26.3.186           operator  :=(Tmatrix2__single):  Tmatrix4__single

    Synopsis:    Allow assignment of two-dimensional single precision matrix to four-dimensional single pre-
                cision matrix

Declaration:     operator  operator  :=(Tmatrix2_single):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix2_singl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with single precision is expected.  The extra fields are set to
                0.



                26.3.187           operator  :=(Tmatrix3__double):  Tmatrix2__double

    Synopsis:    Allow assignment of three-dimensional double precision matrix to two-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_double):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away.



                26.3.188           operator  :=(Tmatrix3__double):  Tmatrix2__extended

    Synopsis:    Allow assignment of three-dimensional double precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_double):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix3_d*
 *ouble)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.



                                                                                 856

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.189           operator  :=(Tmatrix3__double):  Tmatrix2__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_double):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some accuracy is lost because of the conversion.



                26.3.190           operator  :=(Tmatrix3__double):  Tmatrix3__extended

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  matrix  to  three-dimensional  ex-
                tended precision matrix

Declaration:     operator  operator  :=(Tmatrix3_double):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix3_d*
 *ouble)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with extended precision is expected.



                26.3.191           operator  :=(Tmatrix3__double):  Tmatrix3__single

    Synopsis:    Allow assignment of three-dimensional double precision matrix to three-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_double):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.



                26.3.192           operator  :=(Tmatrix3__double):  Tmatrix4__double

    Synopsis:    Allow assignment of three-dimensional double precision matrix to four-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_double):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with double precision is expected.



                                                                                 857

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.193           operator  :=(Tmatrix3__double):  Tmatrix4__extended

    Synopsis:    Allow assignment of three-dimensional double precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_double):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix3_d*
 *ouble)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with extended precision is expected.



                26.3.194           operator  :=(Tmatrix3__double):  Tmatrix4__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  matrix  to  four-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_double):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix3_doubl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.



                26.3.195           operator  :=(Tmatrix3__extended):  Tmatrix2__double

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to two-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_extended):  Tmatrix2_double
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away and some accuracy is lost becuase of the conversion.



                26.3.196           operator  :=(Tmatrix3__extended):  Tmatrix2__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  matrix  to  two-dimensional  ex-
                tended precision matrix

Declaration:     operator  operator  :=(Tmatrix3_extended):  Tmatrix2_extended
                                                                                                                (const  v:  Tmatrix*
 *3_extended)
                                                                                                                  :  Tmatrix2_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.



                                                                                 858

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.197           operator  :=(Tmatrix3__extended):  Tmatrix2__single

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to two-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_extended):  Tmatrix2_single
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost because of the conversion.



                26.3.198           operator  :=(Tmatrix3__extended):  Tmatrix3__double

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to three-dimensional dou-
                ble precision matrix

Declaration:     operator  operator  :=(Tmatrix3_extended):  Tmatrix3_double
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever  a  three-dimensional  matrix  with  double  precision  is  expected.  Some  precision  is
                lost because of the conversion.



                26.3.199           operator  :=(Tmatrix3__extended):  Tmatrix3__single

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to three-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_extended):  Tmatrix3_single
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.



                26.3.200           operator  :=(Tmatrix3__extended):  Tmatrix4__double

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to four-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_extended):  Tmatrix4_double
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with double precision is expected.  Some precision is lost
                because of the conversion.



                                                                                 859

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.201           operator  :=(Tmatrix3__extended):  Tmatrix4__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  matrix  to  four-dimensional  ex-
                tended precision matrix

Declaration:     operator  operator  :=(Tmatrix3_extended):  Tmatrix4_extended
                                                                                                                (const  v:  Tmatrix*
 *3_extended)
                                                                                                                  :  Tmatrix4_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with extended precision is expected.



                26.3.202           operator  :=(Tmatrix3__extended):  Tmatrix4__single

    Synopsis:    Allow assignment of three-dimensional extended precision matrix to four-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_extended):  Tmatrix4_single
                                                                                                             (const  v:  Tmatrix3_e*
 *xtended)
                                                                                                              :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.



                26.3.203           operator  :=(Tmatrix3__single):  Tmatrix2__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_single):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away.



                26.3.204           operator  :=(Tmatrix3__single):  Tmatrix2__extended

    Synopsis:    Allow assignment of three-dimensional single precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_single):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix3_s*
 *ingle)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a two-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.



                                                                                 860

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.205           operator  :=(Tmatrix3__single):  Tmatrix2__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_single):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away.



                26.3.206           operator  :=(Tmatrix3__single):  Tmatrix3__double

    Synopsis:    Allow assignment of three-dimensional single precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_single):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a three-dimensional matrix with double precision is expected.



                26.3.207           operator  :=(Tmatrix3__single):  Tmatrix3__extended

    Synopsis:    Allow assignment of three-dimensional single precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_single):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix3_s*
 *ingle)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a three-dimensional matrix with extended precision is expected.



                26.3.208           operator  :=(Tmatrix3__single):  Tmatrix4__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_single):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a four-dimensional matrix with double precision is expected.



                                                                                 861

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.209           operator  :=(Tmatrix3__single):  Tmatrix4__extended

    Synopsis:    Allow assignment of three-dimensional single precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_single):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix3_s*
 *ingle)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a four-dimensional matrix with extended precision is expected.



                26.3.210           operator  :=(Tmatrix3__single):  Tmatrix4__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  matrix  to  four-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix3_single):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix3_singl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  matrix  with  single  precision  values
                wherever a four-dimensional matrix with single precision is expected.



                26.3.211           operator  :=(Tmatrix4__double):  Tmatrix2__double

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_double):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away.



                26.3.212           operator  :=(Tmatrix4__double):  Tmatrix2__extended

    Synopsis:    Allow assignment of four-dimensional double precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_double):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix4_d*
 *ouble)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.



                                                                                 862

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.213           operator  :=(Tmatrix4__double):  Tmatrix2__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  matrix  to  two-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_double):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost in the conversion.



                26.3.214           operator  :=(Tmatrix4__double):  Tmatrix3__double

    Synopsis:    Allow assignment of four-dimensional double precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_double):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with double precision is expected.  The surplus fields
                are thrown away.



                26.3.215           operator  :=(Tmatrix4__double):  Tmatrix3__extended

    Synopsis:    Allow assignment of four-dimensional double precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_double):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix4_d*
 *ouble)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with extended precision is expected.  The surplus fields
                are thrown away.



                26.3.216           operator  :=(Tmatrix4__double):  Tmatrix3__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_double):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a three-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost because of the conversion.



                                                                                 863

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.217           operator  :=(Tmatrix4__double):  Tmatrix4__extended

    Synopsis:    Allow assignment of four-dimensional double precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_double):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix4_d*
 *ouble)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with extended precision is expected.



                26.3.218           operator  :=(Tmatrix4__double):  Tmatrix4__single

    Synopsis:    Allow assignment of four-dimensional single precision matrix to four-dimensional single pre-
                cision matrix

Declaration:     operator  operator  :=(Tmatrix4_double):  Tmatrix4_single
                                                                                                         (const  v:  Tmatrix4_doubl*
 *e)
                                                                                                           :  Tmatrix4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  matrix  with  double  precision  values
                wherever a four-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.



                26.3.219           operator  :=(Tmatrix4__extended):  Tmatrix2__double

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to two-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_extended):  Tmatrix2_double
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with double precision is expected.  The surplus fields are
                thrown away and some precision is lost in the conversion.



                26.3.220           operator  :=(Tmatrix4__extended):  Tmatrix2__extended

    Synopsis:    Allow  assignment  of  four-dimensional  extended  precision  matrix  to  two-dimensional  ex-
                tended precision matrix

Declaration:     operator  operator  :=(Tmatrix4_extended):  Tmatrix2_extended
                                                                                                                (const  v:  Tmatrix*
 *4_extended)
                                                                                                                  :  Tmatrix2_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with single precision is expected.  The surplus fields are thrown
                away.



                                                                                 864

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.221           operator  :=(Tmatrix4__extended):  Tmatrix2__single

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to two-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_extended):  Tmatrix2_single
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a two-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost in the conversion.



                26.3.222           operator  :=(Tmatrix4__extended):  Tmatrix3__double

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to three-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_extended):  Tmatrix3_double
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with double precision is expected.  The surplus fields
                are thrown away.



                26.3.223           operator  :=(Tmatrix4__extended):  Tmatrix3__extended

    Synopsis:    Allow  assignment  of  four-dimensional  extended  precision  matrix  to  three-dimensional  ex-
                tended precision matrix

Declaration:     operator  operator  :=(Tmatrix4_extended):  Tmatrix3_extended
                                                                                                                (const  v:  Tmatrix*
 *4_extended)
                                                                                                                  :  Tmatrix3_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with double precision is expected.  The surplus fields
                are thrown away.



                26.3.224           operator  :=(Tmatrix4__extended):  Tmatrix3__single

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to three-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_extended):  Tmatrix3_single
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a three-dimensional matrix with single precision is expected.  The surplus fields are
                thrown away and some precision is lost because of the conversion.



                                                                                 865

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.225           operator  :=(Tmatrix4__extended):  Tmatrix4__double

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to four-dimensional double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_extended):  Tmatrix4_double
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with double precision is expected.



                26.3.226           operator  :=(Tmatrix4__extended):  Tmatrix4__single

    Synopsis:    Allow assignment of four-dimensional extended precision matrix to four-dimensional single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_extended):  Tmatrix4_single
                                                                                                             (const  v:  Tmatrix4_e*
 *xtended)
                                                                                                              :  Tmatrix4_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with extended precision values
                wherever a four-dimensional matrix with single precision is expected.  Some precision is lost
                because of the conversion.



                26.3.227           operator  :=(Tmatrix4__single):  Tmatrix2__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  two-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_single):  Tmatrix2_double
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix2_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever  a  two-dimensional  matrix  with  double  precision  is  expected.   The  surplus  fields  are
                thrown away.



                26.3.228           operator  :=(Tmatrix4__single):  Tmatrix2__extended

    Synopsis:    Allow assignment of four-dimensional single precision matrix to two-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_single):  Tmatrix2_extended
                                                                                                             (const  v:  Tmatrix4_s*
 *ingle)
                                                                                                              :  Tmatrix2_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with extended precision is expected.  The surplus fields are
                thrown away.



                                                                                 866

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.229           operator  :=(Tmatrix4__single):  Tmatrix2__single

    Synopsis:    Allow assignment of four-dimensional single precision matrix to two-dimensional single pre-
                cision matrix

Declaration:     operator  operator  :=(Tmatrix4_single):  Tmatrix2_single
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix2_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a two-dimensional matrix with single precision is expected.  The surplus fields are thrown
                away.



                26.3.230           operator  :=(Tmatrix4__single):  Tmatrix3__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  three-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_single):  Tmatrix3_double
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix3_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever  a  three-dimensional  matrix  with  double  precision  is  expected.  The  surplus  fields  are
                thrown away.



                26.3.231           operator  :=(Tmatrix4__single):  Tmatrix3__extended

    Synopsis:    Allow assignment of four-dimensional single precision matrix to three-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_single):  Tmatrix3_extended
                                                                                                             (const  v:  Tmatrix4_s*
 *ingle)
                                                                                                              :  Tmatrix3_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a three-dimensional matrix with extended precision is expected.  The surplus fields are
                thrown away.



                26.3.232           operator  :=(Tmatrix4__single):  Tmatrix3__single

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  three-dimensional  single
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_single):  Tmatrix3_single
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix3_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever  a  three-dimensional  matrix  with  single  precision  is  expected.   The  surplus  fields  are
                thrown away.



                                                                                 867

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.233           operator  :=(Tmatrix4__single):  Tmatrix4__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  matrix  to  four-dimensional  double
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_single):  Tmatrix4_double
                                                                                                         (const  v:  Tmatrix4_singl*
 *e)
                                                                                                           :  Tmatrix4_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with double precision is expected.



                26.3.234           operator  :=(Tmatrix4__single):  Tmatrix4__extended

    Synopsis:    Allow assignment of four-dimensional single precision matrix to four-dimensional extended
                precision matrix

Declaration:     operator  operator  :=(Tmatrix4_single):  Tmatrix4_extended
                                                                                                             (const  v:  Tmatrix4_s*
 *ingle)
                                                                                                              :  Tmatrix4_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional matrix with single precision values wher-
                ever a four-dimensional matrix with extended precision is expected.



                26.3.235           operator  :=(Tvector2__double):  Tvector2__extended

    Synopsis:    Allow assignment of double precision vector to extended precision vector

Declaration:     operator  operator  :=(Tvector2_double):  Tvector2_extended
                                                                                                             (const  v:  Tvector2_d*
 *ouble)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to use a vector with double precision values wherever an extended
                precision vector is expected.



                26.3.236           operator  :=(Tvector2__double):  Tvector2__single

    Synopsis:    Allow assignment of double precision vector to single precision vector

Declaration:     operator  operator  :=(Tvector2_double):  Tvector2_single
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  vector  with  double  precision  values  wherever  a  single
                precision vector is expected, at the cost of loosing some precision.



                                                                                 868

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.237           operator  :=(Tvector2__double):  Tvector3__double

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  vector  to  three-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector2_double):  Tvector3_double
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever a three-dimensional vector with double precision is expected.  The third dimension is
                set to 0.0.



                26.3.238           operator  :=(Tvector2__double):  Tvector3__extended

    Synopsis:    Allow assignment of two-dimensional double precision vector to three-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector2_double):  Tvector3_extended
                                                                                                             (const  v:  Tvector2_d*
 *ouble)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever a three-dimensional vector with extended precision is expected.  The third dimension is
                set to 0.0.



                26.3.239           operator  :=(Tvector2__double):  Tvector3__single

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     operator  operator  :=(Tvector2_double):  Tvector3_single
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever  a  three-dimensional  vector  with  single  precision  is  expected.   Some  accuracy  is  lost
                because of the conversion and the third dimension is set to 0.0.



                26.3.240           operator  :=(Tvector2__double):  Tvector4__double

    Synopsis:    Allow  assignment  of  two-dimensional  double  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector2_double):  Tvector4_double
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever  a  four-dimensional  vector  with  double  precision  is  expected.   The  third  and  fourth
                dimensions are set to 0.0.



                                                                                 869

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.241           operator  :=(Tvector2__double):  Tvector4__extended

    Synopsis:    Allow assignment of two-dimensional double precision vector to four-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector2_double):  Tvector4_extended
                                                                                                             (const  v:  Tvector2_d*
 *ouble)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever  a  four-dimensional  vector  with  extended  precision  is  expected.  The  third  and  fourth
                dimensions are set to 0.0.



                26.3.242           operator  :=(Tvector2__double):  Tvector4__single

    Synopsis:    Allow assignment of two-dimensional double precision vector to four-dimensional single pre-
                cision vector

Declaration:     operator  operator  :=(Tvector2_double):  Tvector4_single
                                                                                                         (const  v:  Tvector2_doubl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with double precision values wher-
                ever a four-dimensional vector with single precision is expected.  Some accurace is lost because
                of the conversion and the third and fourth dimensions are set to 0.0.



                26.3.243           operator  :=(Tvector2__extended):  Tvector2__double

    Synopsis:    Allow assignment of extended precision vector to double precision vector

Declaration:     operator  operator  :=(Tvector2_extended):  Tvector2_double
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector2_double

    Visibility:   default

Description:     This operator allows you to use a vector with extended precision values wherever a double
                precision vector is expected, at the cost of loosing some precision.



                26.3.244           operator  :=(Tvector2__extended):  Tvector2__single

    Synopsis:    Allow assignment of extended precision vector to single precision vector

Declaration:     operator  operator  :=(Tvector2_extended):  Tvector2_single
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to use a vector with extended precision values wherever a single
                precision vector is expected, at the cost of loosing some precision.



                                                                                 870

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.245           operator  :=(Tvector2__extended):  Tvector3__double

    Synopsis:    Allow assignment of two-dimensional extended precision vector to three-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector2_extended):  Tvector3_double
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with double precision is expected.  Some accuracy is lost
                because of the conversion and the third dimension is set to 0.0.



                26.3.246           operator  :=(Tvector2__extended):  Tvector3__extended

    Synopsis:    Allow assignment of two-dimensional extened precision vector to three-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector2_extended):  Tvector3_extended
                                                                                                                (const  v:  Tvector*
 *2_extended)
                                                                                                                  :  Tvector3_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with extended precision is expected.  The third dimen-
                sion is set to 0.0.



                26.3.247           operator  :=(Tvector2__extended):  Tvector3__single

    Synopsis:    Allow assignment of two-dimensional extended precision vector to three-dimensional single
                precision vector

Declaration:     operator  operator  :=(Tvector2_extended):  Tvector3_single
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with single precision is expected.  Some accuracy is lost
                because of the conversion and the third dimension is set to 0.0.



                26.3.248           operator  :=(Tvector2__extended):  Tvector4__double

    Synopsis:    Allow assignment of two-dimensional extended precision vector to four-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector2_extended):  Tvector4_double
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with double precision is expected.  Some accuracy is lost
                because of the conversion and the third and fourth dimensions are set to 0.0.



                                                                                 871

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.249           operator  :=(Tvector2__extended):  Tvector4__extended

    Synopsis:    Allow assignment of two-dimensiona extended precision vector to four-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector2_extended):  Tvector4_extended
                                                                                                                (const  v:  Tvector*
 *2_extended)
                                                                                                                  :  Tvector4_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with extended precision is expected.  The third and fourth
                dimensions are set to 0.0.



                26.3.250           operator  :=(Tvector2__extended):  Tvector4__single

    Synopsis:    Allow assignment of two-dimensional extended precision vector to four-dimensional single
                precision vector

Declaration:     operator  operator  :=(Tvector2_extended):  Tvector4_single
                                                                                                             (const  v:  Tvector2_e*
 *xtended)
                                                                                                              :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  two-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with single precision is expected.  Some accuracy is lost
                because of the conversion and the third and fourth dimensions are set to 0.0.



                26.3.251           operator  :=(Tvector2__single):  Tvector2__double

    Synopsis:    Allow assignment of single precision vector to double precision vector

Declaration:     operator  operator  :=(Tvector2_single):  Tvector2_double
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  vector  with  single  precision  values  wherever  a  double
                precision vector is expected.



                26.3.252           operator  :=(Tvector2__single):  Tvector2__extended

    Synopsis:    Allow assignment of single precision vector to extended precision vector

Declaration:     operator  operator  :=(Tvector2_single):  Tvector2_extended
                                                                                                             (const  v:  Tvector2_s*
 *ingle)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to use a vector with single precision values wherever an extended
                precision vector is expected.



                                                                                 872

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.253           operator  :=(Tvector2__single):  Tvector3__double

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  vector  to  three-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector2_single):  Tvector3_double
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever a three-dimensional vector with double precision is expected.  The third dimension is
                set to 0.0.



                26.3.254           operator  :=(Tvector2__single):  Tvector3__extended

    Synopsis:    Allow assignment of two-dimensional single precision vector to three-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector2_single):  Tvector3_extended
                                                                                                             (const  v:  Tvector2_s*
 *ingle)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever a three-dimensional vector with extended precision is expected.  The third dimension is
                set to 0.0.



                26.3.255           operator  :=(Tvector2__single):  Tvector3__single

    Synopsis:    Allow  assignment  of  two-dimensional  single  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     operator  operator  :=(Tvector2_single):  Tvector3_single
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever a three-dimensional vector with single precision is expected.  The third dimension is set
                to 0.0.



                26.3.256           operator  :=(Tvector2__single):  Tvector4__double

    Synopsis:    Allow assignment of two-dimensional single precision vector to four-dimensional double pre-
                cision vector

Declaration:     operator  operator  :=(Tvector2_single):  Tvector4_double
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever  a  four-dimensional  vector  with  double  precision  is  expected.   The  third  and  fourth
                dimensions are set to 0.0.



                                                                                 873

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.257           operator  :=(Tvector2__single):  Tvector4__extended

    Synopsis:    Allow assignment of two-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector2_single):  Tvector4_extended
                                                                                                             (const  v:  Tvector2_s*
 *ingle)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever  a  four-dimensional  vector  with  extended  precision  is  expected.  The  third  and  fourth
                dimensions are set to 0.0.



                26.3.258           operator  :=(Tvector2__single):  Tvector4__single

    Synopsis:    Allow assignment of two-dimensional single precision vector to four-dimensional single pre-
                cision vector

Declaration:     operator  operator  :=(Tvector2_single):  Tvector4_single
                                                                                                         (const  v:  Tvector2_singl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This operator allows you to use a two-dimensional vector with single precision values wher-
                ever  a  four-dimensional  vector  with  single  precision  is  expected.  The  third  and  fourth  di-
                mensions are set to 0.0.



                26.3.259           operator  :=(Tvector3__double):  Tvector2__double

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  two-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector3_double):  Tvector2_double
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with double precision is expected.  The third dimension
                is thrown away.



                26.3.260           operator  :=(Tvector3__double):  Tvector2__extended

    Synopsis:    Allow assignment of three-dimensional double precision vector to two-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector3_double):  Tvector2_extended
                                                                                                             (const  v:  Tvector3_d*
 *ouble)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with extended precision is expected.  The third dimension
                is thrown away.



                                                                                 874

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.261           operator  :=(Tvector3__double):  Tvector2__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  two-dimensional  single
                precision vector

Declaration:     operator  operator  :=(Tvector3_double):  Tvector2_single
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with single precision is expected.  The third dimension is
                thrown away and some precision is lost because of the conversion.



                26.3.262           operator  :=(Tvector3__double):  Tvector3__extended

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  three-dimensional  ex-
                tended precision vector

Declaration:     operator  operator  :=(Tvector3_double):  Tvector3_extended
                                                                                                             (const  v:  Tvector3_d*
 *ouble)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a three-dimensional vector with extended precision is expected.



                26.3.263           operator  :=(Tvector3__double):  Tvector3__single

    Synopsis:    Allow assignment of three-dimensional double precision vector to three-dimensional single
                precision vector

Declaration:     operator  operator  :=(Tvector3_double):  Tvector3_single
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a three-dimensional vector with single precision is expected.  Some precision is lost
                because of the conversion.



                26.3.264           operator  :=(Tvector3__double):  Tvector4__double

    Synopsis:    Allow assignment of three-dimensional double precision vector to four-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector3_double):  Tvector4_double
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a four-dimensional vector with double precision is expected.  The fourth dimension
                is set to 0.



                                                                                 875

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.265           operator  :=(Tvector3__double):  Tvector4__extended

    Synopsis:    Allow assignment of three-dimensional double precision vector to four-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector3_double):  Tvector4_extended
                                                                                                             (const  v:  Tvector3_d*
 *ouble)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  double  precision  values
                wherever a four-dimensional vector with extended precision is expected.  The fourth dimen-
                sion is set to 0.



                26.3.266           operator  :=(Tvector3__double):  Tvector4__single

    Synopsis:    Allow  assignment  of  three-dimensional  double  precision  vector  to  four-dimensional  single
                precision vector

Declaration:     operator  operator  :=(Tvector3_double):  Tvector4_single
                                                                                                         (const  v:  Tvector3_doubl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a four-dimensional vector with double precision is expected.  The fourth dimension
                is set to 0 and some precision is lost because of the conversion.



                26.3.267           operator  :=(Tvector3__extended):  Tvector2__double

    Synopsis:    Allow assignment of three-dimensional extended precision vector to two-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector3_extended):  Tvector2_double
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector2_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a two-dimensional vector with double precision is expected.  The third dimension
                is thrown away and some precision is lost because of the conversion.



                26.3.268           operator  :=(Tvector3__extended):  Tvector2__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  vector  to  two-dimensional  ex-
                tended precision vector

Declaration:     operator  operator  :=(Tvector3_extended):  Tvector2_extended
                                                                                                                (const  v:  Tvector*
 *3_extended)
                                                                                                                  :  Tvector2_exten*
 *ded

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a two-dimensional vector with extended precision is expected.  The third dimension
                is thrown away.



                                                                                 876

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.269           operator  :=(Tvector3__extended):  Tvector2__single

    Synopsis:    Allow assignment of three-dimensional extended precision vector to two-dimensional single
                precision vector

Declaration:     operator  operator  :=(Tvector3_extended):  Tvector2_single
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a two-dimensional vector with single precision is expected.  The third dimension is
                thrown away and some precision is lost because of the conversion.



                26.3.270           operator  :=(Tvector3__extended):  Tvector3__double

    Synopsis:    Allow assignment of three-dimensional extended precision vector to three-dimensional dou-
                ble precision vector

Declaration:     operator  operator  :=(Tvector3_extended):  Tvector3_double
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever  a  three-dimensional  vector  with  double  precision  is  expected.  Some  precision  is
                lost because of the conversion.



                26.3.271           operator  :=(Tvector3__extended):  Tvector3__single

    Synopsis:    Allow assignment of three-dimensional single precision vector to three-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector3_extended):  Tvector3_single
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever  a  three-dimensional  vector  with  double  precision  is  expected.  Some  precision  is
                lost because of the conversion.



                26.3.272           operator  :=(Tvector3__extended):  Tvector4__double

    Synopsis:    Allow assignment of three-dimensional extended precision vector to four-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector3_extended):  Tvector4_double
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a four-dimensional vector with double precision is expected.  The fourth dimension
                is set to 0 and some accuracy is lost because of the conversion.



                                                                                 877

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.273           operator  :=(Tvector3__extended):  Tvector4__extended

    Synopsis:    Allow  assignment  of  three-dimensional  extended  precision  vector  to  four-dimensional  ex-
                tended precision vector

Declaration:     operator  operator  :=(Tvector3_extended):  Tvector4_extended
                                                                                                                (const  v:  Tvector*
 *3_extended)
                                                                                                                  :  Tvector4_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  extended  precision  val-
                ues  wherever  a  four-dimensional  vector  with  extended  precision  is  expected.   The  fourth
                dimension is set to 0.



                26.3.274           operator  :=(Tvector3__extended):  Tvector4__single

    Synopsis:    Allow assignment of three-dimensional extended precision vector to four-dimensional single
                precision vector

Declaration:     operator  operator  :=(Tvector3_extended):  Tvector4_single
                                                                                                             (const  v:  Tvector3_e*
 *xtended)
                                                                                                              :  Tvector4_single

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with extended precision values
                wherever a four-dimensional vector with single precision is expected.  The fourth dimension
                is set to 0 and some accuracy is lost because of the conversion.



                26.3.275           operator  :=(Tvector3__single):  Tvector2__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  two-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector3_single):  Tvector2_double
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a two-dimensional vector with double precision is expected.  The third dimension
                is thrown away.



                26.3.276           operator  :=(Tvector3__single):  Tvector2__extended

    Synopsis:    Allow assignment of three-dimensional single precision vector to two-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector3_single):  Tvector2_extended
                                                                                                             (const  v:  Tvector3_s*
 *ingle)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a two-dimensional vector with extended precision is expected.  The third dimension
                is thrown away.



                                                                                 878

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.277           operator  :=(Tvector3__single):  Tvector2__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  two-dimensional  single
                precision vector

Declaration:     operator  operator  :=(Tvector3_single):  Tvector2_single
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a two-dimensional vector with single precision is expected.  The third dimension is
                thrown away.



                26.3.278           operator  :=(Tvector3__single):  Tvector3__double

    Synopsis:    Allow assignment of three-dimensional single precision vector to three-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector3_single):  Tvector3_double
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a three-dimensional vector with double precision is expected.



                26.3.279           operator  :=(Tvector3__single):  Tvector3__extended

    Synopsis:    Allow assignment of three-dimensional single precision vector to three-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector3_single):  Tvector3_extended
                                                                                                             (const  v:  Tvector3_s*
 *ingle)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a three-dimensional vector with extended precision is expected.



                26.3.280           operator  :=(Tvector3__single):  Tvector4__double

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector3_single):  Tvector4_double
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a four-dimensional vector with double precision is expected.  The fourth dimension
                is set to 0.



                                                                                 879

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.281           operator  :=(Tvector3__single):  Tvector4__extended

    Synopsis:    Allow assignment of three-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector3_single):  Tvector4_extended
                                                                                                             (const  v:  Tvector3_s*
 *ingle)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to use a three-dimensional vector with single precision values wher-
                ever a four-dimensional vector with extended precision is expected.  The fourth dimension is
                set to 0.



                26.3.282           operator  :=(Tvector3__single):  Tvector4__single

    Synopsis:    Allow  assignment  of  three-dimensional  single  precision  vector  to  four-dimensional  single
                precision vector

Declaration:     operator  operator  :=(Tvector3_single):  Tvector4_single
                                                                                                         (const  v:  Tvector3_singl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  three-dimensional  vector  with  single  precision  values
                wherever a four-dimensional vector with single precision is expected.  The fourth dimension
                is set to 0.



                26.3.283           operator  :=(Tvector4__double):  Tvector2__double

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  vector  to  two-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector4_double):  Tvector2_double
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with double precision is expected.  The third and fourth
                dimensions are thrown away.



                26.3.284           operator  :=(Tvector4__double):  Tvector2__extended

    Synopsis:    Allow assignment of four-dimensional double precision vector to two-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector4_double):  Tvector2_extended
                                                                                                             (const  v:  Tvector4_d*
 *ouble)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever  a  two-dimensional  vector  with  extended  precision  is  expected.   The  third  and
                fourth dimensions are thrown away.



                                                                                 880

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.285           operator  :=(Tvector4__double):  Tvector2__single

    Synopsis:    Allow assignment of four-dimensional double precision vector to two-dimensional single pre-
                cision vector

Declaration:     operator  operator  :=(Tvector4_double):  Tvector2_single
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a two-dimensional vector with single precision is expected.  The third and fourth
                dimensions are thrown away and some accuracy is lost because of the conversion.



                26.3.286           operator  :=(Tvector4__double):  Tvector3__double

    Synopsis:    Allow assignment of four-dimensional double precision vector to three-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector4_double):  Tvector3_double
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a three-dimensional vector with double precision is expected.  The fourth dimension
                is thrown away.



                26.3.287           operator  :=(Tvector4__double):  Tvector3__extended

    Synopsis:    Allow assignment of four-dimensional double precision vector to three-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector4_double):  Tvector3_extended
                                                                                                             (const  v:  Tvector4_d*
 *ouble)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with double precision values wher-
                ever a three-dimensional vector with extended precision is expected.  The fourth dimension
                is thrown away.



                26.3.288           operator  :=(Tvector4__double):  Tvector3__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     operator  operator  :=(Tvector4_double):  Tvector3_single
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a three-dimensional vector with single precision is expected.  The fourth dimension
                is thrown away and some accuracy is lost because of the conversion.



                                                                                 881

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.289           operator  :=(Tvector4__double):  Tvector4__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector4_double):  Tvector4_extended
                                                                                                             (const  v:  Tvector4_d*
 *ouble)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a four-dimensional vector with extended precision is expected.



                26.3.290           operator  :=(Tvector4__double):  Tvector4__single

    Synopsis:    Allow  assignment  of  four-dimensional  double  precision  vector  to  four-dimensional  single
                precision vector

Declaration:     operator  operator  :=(Tvector4_double):  Tvector4_single
                                                                                                         (const  v:  Tvector4_doubl*
 *e)
                                                                                                           :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  double  precision  values
                wherever a four-dimensional vector with single precision is expected.  Some accuracy is lost
                because of the conversion.



                26.3.291           operator  :=(Tvector4__extended):  Tvector2__double

    Synopsis:    Allow assignment of four-dimensional extended precision vector to two-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector4_extended):  Tvector2_double
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector2_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a two-dimensional vector with double precision is expected.  The third and fourth
                dimensions are thrown away and some accuracy is lost because of the conversion.



                26.3.292           operator  :=(Tvector4__extended):  Tvector2__extended

    Synopsis:    Allow assignment of four-dimensional extended precision vector to two-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector4_extended):  Tvector2_extended
                                                                                                                (const  v:  Tvector*
 *4_extended)
                                                                                                                  :  Tvector2_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a two-dimensional vector with extended precision is expected.  The third and fourth
                dimensions are thrown away.



                                                                                 882

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.293           operator  :=(Tvector4__extended):  Tvector2__single

    Synopsis:    Allow assignment of four-dimensional extended precision vector to two-dimensional single
                precision vector

Declaration:     operator  operator  :=(Tvector4_extended):  Tvector2_single
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector2_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a two-dimensional vector with single precision is expected.  The third and fourth
                dimensions are thrown away and some accuracy is los because of the conversion.



                26.3.294           operator  :=(Tvector4__extended):  Tvector3__double

    Synopsis:    Allow assignment of four-dimensional extended precision vector to three-dimensional double
                precision vector

Declaration:     operator  operator  :=(Tvector4_extended):  Tvector3_double
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector3_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with double precision is expected.  The fourth dimension
                is thrown away and some accuracy is lost because of the conversion.



                26.3.295           operator  :=(Tvector4__extended):  Tvector3__extended

    Synopsis:    Allow  assignment  of  four-dimensional  extended  precision  vector  to  three-dimensional  ex-
                tended precision vector

Declaration:     operator  operator  :=(Tvector4_extended):  Tvector3_extended
                                                                                                                (const  v:  Tvector*
 *4_extended)
                                                                                                                  :  Tvector3_exten*
 *ded

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with extended precision is expected.  The fourth dimen-
                sions are thrown away.



                26.3.296           operator  :=(Tvector4__extended):  Tvector3__single

    Synopsis:    Allow assignment of four-dimensional extended precision vector to three-dimensional single
                precision vector

Declaration:     operator  operator  :=(Tvector4_extended):  Tvector3_single
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector3_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a three-dimensional vector with single precision is expected.  The fourth dimension
                is thrown away and some accuracy is los because of the conversion.



                                                                                 883

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.297           operator  :=(Tvector4__extended):  Tvector4__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector4_extended):  Tvector4_double
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector4_double

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with double precision is expected.  Some accuracy is lost
                because of the conversion.



                26.3.298           operator  :=(Tvector4__extended):  Tvector4__single

    Synopsis:    Allow assignment of four-dimensional extended precision vector to four-dimensional single
                precision vector

Declaration:     operator  operator  :=(Tvector4_extended):  Tvector4_single
                                                                                                             (const  v:  Tvector4_e*
 *xtended)
                                                                                                              :  Tvector4_single

    Visibility:   default

Description:     This  operator  allows  you  to  use  a  four-dimensional  vector  with  extended  precision  values
                wherever a four-dimensional vector with single precision is expected.  Some accuracy is lost
                because of the conversion.



                26.3.299           operator  :=(Tvector4__single):  Tvector2__double

    Synopsis:    Allow assignment of four-dimensional single precision vector to two-dimensional double pre-
                cision vector

Declaration:     operator  operator  :=(Tvector4_single):  Tvector2_double
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector2_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever  a  two-dimensional  vector  with  double  precision  is  expected.   The  third  and  fourth
                dimensions are thrown away.



                26.3.300           operator  :=(Tvector4__single):  Tvector2__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to two-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector4_single):  Tvector2_extended
                                                                                                             (const  v:  Tvector4_s*
 *ingle)
                                                                                                              :  Tvector2_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever  a  two-dimensional  vector  with  extended  precision  is  expected.  The  third  and  fourth
                dimensions are thrown away.



                                                                                 884

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.301           operator  :=(Tvector4__single):  Tvector2__single

    Synopsis:    Allow assignment of four-dimensional single precision vector to two-dimensional single pre-
                cision vector

Declaration:     operator  operator  :=(Tvector4_single):  Tvector2_single
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector2_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a two-dimensional vector with single precision is expected.  The third and fourth dimen-
                sions are thrown away.



                26.3.302           operator  :=(Tvector4__single):  Tvector3__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  three-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector4_single):  Tvector3_double
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector3_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a three-dimensional vector with double precision is expected.  The fourth dimension is
                thrown away.



                26.3.303           operator  :=(Tvector4__single):  Tvector3__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to three-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector4_single):  Tvector3_extended
                                                                                                             (const  v:  Tvector4_s*
 *ingle)
                                                                                                              :  Tvector3_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a three-dimensional vector with extended precision is expected.  The fourth dimension
                is thrown away.



                26.3.304           operator  :=(Tvector4__single):  Tvector3__single

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  three-dimensional  single
                precision vector

Declaration:     operator  operator  :=(Tvector4_single):  Tvector3_single
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector3_single

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a three-dimensional vector with single precision is expected.  The fourth dimension is
                thrown away.



                                                                                 885

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.3.305           operator  :=(Tvector4__single):  Tvector4__double

    Synopsis:    Allow  assignment  of  four-dimensional  single  precision  vector  to  four-dimensional  double
                precision vector

Declaration:     operator  operator  :=(Tvector4_single):  Tvector4_double
                                                                                                         (const  v:  Tvector4_singl*
 *e)
                                                                                                           :  Tvector4_double

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a four-dimensional vector with double precision is expected.



                26.3.306           operator  :=(Tvector4__single):  Tvector4__extended

    Synopsis:    Allow assignment of four-dimensional single precision vector to four-dimensional extended
                precision vector

Declaration:     operator  operator  :=(Tvector4_single):  Tvector4_extended
                                                                                                             (const  v:  Tvector4_s*
 *ingle)
                                                                                                              :  Tvector4_extended

    Visibility:   default

Description:     This operator allows you to use a four-dimensional vector with single precision values wher-
                ever a four-dimensional vector with extended precision is expected.



                26.3.307           operator ><(Tvector3__double, Tvector3__double):  Tvector3__double

    Synopsis:    Calculate the external product of two three-dimensional vectors

Declaration:     operator  operator  ><(Tvector3_double,  Tvector3_double):  Tvector3_double
                                                                                                                                   *
 *  (const  x:  Tvector3_double;
                                                                                                                                   *
 *  const  y:  Tvector3_double)
                                                                                                                                   *
 *    :  Tvector3_double

    Visibility:   default

Description:     This operator returns the external product of two three dimensional vector.  It is a vector
                orthonormal to the two multiplied vectors.  The length of that vector is equal to the surface
                area of a parallelogram with the two vectors as sides.

                The external product is often used to get a vector orthonormal to two other vectors, but of a
                predefined length.  In order to do so, the result vector from the external product, is divided
                by its length, and then multiplied by the desired size.



                26.3.308           operator ><(Tvector3__extended, Tvector3__extended):  Tvector3__extended

    Synopsis:    Calculate the external product of two three-dimensional vectors

Declaration:
                                                                                                                                   *
 *            operator  operator@
                                                                                                                                   *
 *            (const  x:  Tvecto@
                                                                                                                                   *
 *            const  y:  Tvector@
                                                                                                                                   *
 *              :  Tvector3_exte@

    Visibility:   default



                                                                                 886

                __________________________________________________________CHAPTER_26.___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.



                26.3.309           operator ><(Tvector3__single, Tvector3__single):  Tvector3__single

    Synopsis:    Calculate the external product of two three-dimensional vectors

Declaration:     operator  operator  ><(Tvector3_single,  Tvector3_single):  Tvector3_single
                                                                                                                                   *
 *  (const  x:  Tvector3_single;
                                                                                                                                   *
 *  const  y:  Tvector3_single)
                                                                                                                                   *
 *    :  Tvector3_single

    Visibility:   default

Description:     This operator returns the external product of two three dimensional vector.  It is a vector
                orthonormal to the two multiplied vectors.  The length of that vector is equal to the surface
                area of a parallelogram with the two vectors as sides.

                The external product is often used to get a vector orthonormal to two other vectors, but of a
                predefined length.  In order to do so, the result vector from the external product, is divided
                by its length, and then multiplied by the desired size.



                26.4          Tmatrix2 __double



                26.4.1         Description

                The Tmatrix2_double object provides a matrix of 2*2 double precision scalars.



                26.4.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  889       determinant           Calculates the determinant of the matrix.
                  888       get\_column           Returns the c-th column of the matrix as vector.
                  888       get\_row              Returns the r-th row of the matrix as vector.
                  888       init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  888       init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  887       init\_zero            Initializes the matrix and sets its elements to zero
                  889       inverse               Calculates the inverse of the matrix.
                  888       set\_column           Sets c-th column of the matrix with a vector.
                  888       set\_row              Sets r-th row of the matrix with a vector.
                __889_______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                26.4.3         Tmatrix2__double.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                                                                                 887

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.4.5         Tmatrix2__double.init

    Synopsis:    Initializes the matrix, setting its elements to the values passed to the constructor.

Declaration:     constructor  init(aa:  Double;ab:  Double;ba:  Double;bb:  Double)

    Visibility:   default

Description:     Initializes the matrix, setting its elements to the values passed to the constructor.  The order
                of the values is left to right, then top to bottom.



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 888

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.5          Tmatrix2 __extended



                26.5.1         Description

                The Tmatrix2_extended object provides a matrix of 2*2 extended precision scalars.



                26.5.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  891       determinant           Calculates the determinant of the matrix.
                  890       get\_column           Returns the c-th column of the matrix as vector.
                  890       get\_row              Returns the r-th row of the matrix as vector.
                  890       init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  890       init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  890       init\_zero            Initializes the matrix and sets its elements to zero
                  891       inverse               Calculates the inverse of the matrix.
                  890       set\_column           Sets c-th column of the matrix with a vector.
                  891       set\_row              Sets r-th row of the matrix with a vector.
                __891_______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                                                                                 889

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.5.3         Tmatrix2__extended.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 890

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.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.



                26.6          Tmatrix2 __single



                26.6.1         Description

                The Tmatrix2_single object provides a matrix of 2*2 single precision scalars.



                                                                                 891

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.6.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  893       determinant           Calculates the determinant of the matrix.
                  892       get\_column           Returns the c-th column of the matrix as vector.
                  893       get\_row              Returns the r-th row of the matrix as vector.
                  892       init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  892       init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  892       init\_zero            Initializes the matrix and sets its elements to zero
                  893       inverse               Calculates the inverse of the matrix.
                  893       set\_column           Sets c-th column of the matrix with a vector.
                  893       set\_row              Sets r-th row of the matrix with a vector.
                __893_______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                26.6.3         Tmatrix2__single.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.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.



                26.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.



                26.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.



                                                                                 892

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 893

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.7          Tmatrix3 __double



                26.7.1         Description

                The Tmatrix3_double object provides a matrix of 3*3 double precision scalars.



                26.7.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  895       determinant           Calculates the determinant of the matrix.
                  895       get\_column           Returns the c-th column of the matrix as vector.
                  895       get\_row              Returns the r-th row of the matrix as vector.
                  894       init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  894       init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  894       init\_zero            Initializes the matrix and sets its elements to zero
                  895       inverse               Calculates the inverse of the matrix.
                  895       set\_column           Sets c-th column of the matrix with a vector.
                  895       set\_row              Sets r-th row of the matrix with a vector.
                __896_______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                26.7.3         Tmatrix3__double.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.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.



                26.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.



                                                                                 894

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 895

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.8          Tmatrix3 __extended



                26.8.1         Description

                The Tmatrix3_extended object provides a matrix of 3*3 extended precision scalars.



                26.8.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  898       determinant           Calculates the determinant of the matrix.
                  897       get\_column           Returns the c-th column of the matrix as vector.
                  897       get\_row              Returns the r-th row of the matrix as vector.
                  897       init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  896       init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  896       init\_zero            Initializes the matrix and sets its elements to zero
                  898       inverse               Calculates the inverse of the matrix.
                  897       set\_column           Sets r-th column of the matrix with a vector.
                  897       set\_row              Sets r-th row of the matrix with a vector.
                __898_______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                26.8.3         Tmatrix3__extended.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.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.



                                                                                 896

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 897

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.9          Tmatrix3 __single



                26.9.1         Description

                The Tmatrix3_single object provides a matrix of 3*3 single precision scalars.



                26.9.2         Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  900       determinant           Calculates the determinant of the matrix.
                  899       get\_column           Returns the c-th column of the matrix as vector.
                  899       get\_row              Returns the r-th row of the matrix as vector.
                  899       init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  899       init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  899       init\_zero            Initializes the matrix and sets its elements to zero
                  900       inverse               Calculates the inverse of the matrix.
                  899       set\_column           Sets c-th column of the matrix with a vector.
                  900       set\_row              Sets r-th row of the matrix with a vector.
                __900_______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                                                                                 898

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.9.3         Tmatrix3__single.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 899

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.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.



                26.10            Tmatrix4 __double



                26.10.1          Description

                The Tmatrix4_double object provides a matrix of 4*4 double precision scalars.



                                                                                 900

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.10.2          Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  902       determinant           Calculates the determinant of the matrix.
                  901       get\_column           Returns the c-th column of the matrix as vector.
                  902       get\_row              Returns the r-th row of the matrix as vector.
                  901       init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  901       init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  901       init\_zero            Initializes the matrix and sets its elements to zero
                  902       inverse               Calculates the inverse of the matrix.
                  902       set\_column           Sets c-th column of the matrix with a vector.
                  902       set\_row              Sets r-th row of the matrix with a vector.
                __903_______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                26.10.3          Tmatrix4__double.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.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.



                26.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.



                26.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.



                                                                                 901

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 902

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.11            Tmatrix4 __extended



                26.11.1          Description

                The Tmatrix4_extended object provides a matrix of 4*4 extended precision scalars.



                26.11.2          Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  905       determinant           Calculates the determinant of the matrix.
                  904       get\_column           Returns the c-th column of the matrix as vector.
                  904       get\_row              Returns the r-th row of the matrix as vector.
                  904       init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  903       init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  903       init\_zero            Initializes the matrix and sets its elements to zero
                  905       inverse               Calculates the inverse of the matrix.
                  904       set\_column           Sets c-th column of the matrix with a vector.
                  904       set\_row              Sets r-th row of the matrix with a vector.
                __905_______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                26.11.3          Tmatrix4__extended.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.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.



                                                                                 903

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 904

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.12            Tmatrix4 __single



                26.12.1          Description

                The Tmatrix4_single object provides a matrix of 4*4 single precision scalars.



                26.12.2          Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                  907       determinant           Calculates the determinant of the matrix.
                  906       get\_column           Returns the c-th column of the matrix as vector.
                  906       get\_row              Returns the r-th row of the matrix as vector.
                  906       init                  Initializes the matrix, setting its elements to the values passed to
                                                  the constructor.
                  906       init\_identity        Initializes the matrix and sets its elements to the identity matrix.
                  906       init\_zero            Initializes the matrix and sets its elements to zero
                  907       inverse               Calculates the inverse of the matrix.
                  907       set\_column           Sets c-th column of the matrix with a vector.
                  907       set\_row              Sets r-th row of the matrix with a vector.
                __907_______transpose_____________Returns_the_transposition_of_the_matrix._________________________________________*
 *___________



                                                                                 905

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.12.3          Tmatrix4__single.init__zero

    Synopsis:    Initializes the matrix and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 906

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.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.



                26.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.



                26.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.



                26.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.



                                                                                 907

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.13            Tvector2 __double



                26.13.1          Description

                The Tvector2_double object provides a vector of two double precision scalars.



                26.13.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  908       init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  908       init\_one                 Initializes the vector and sets its elements to one
                  908       init\_zero                Initializes the vector and sets its elements to zero
                  908       length                    Calculates the length of the vector.
                __909_______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                26.13.3          Tvector2__double.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.13.4          Tvector2__double.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                26.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



                26.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
                (1 ) if you are able to, as it is faster.



                                                                                 908

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.14            Tvector2 __extended



                26.14.1          Description

                The Tvector2_extended object provides a vector of two extended precision scalars.



                26.14.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  909       init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  909       init\_one                 Initializes the vector and sets its elements to one
                  909       init\_zero                Initializes the vector and sets its elements to zero
                  910       length                    Calculates the length of the vector.
                __910_______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                26.14.3          Tvector2__extended.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.14.4          Tvector2__extended.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                26.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



                                                                                 909

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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
                (1 ) if you are able to, as it is faster.



                26.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.



                26.15            Tvector2 __single



                26.15.1          Description

                The Tvector2_single object provides a vector of two single precision scalars.



                26.15.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  911       init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  910       init\_one                 Initializes the vector and sets its elements to one
                  910       init\_zero                Initializes the vector and sets its elements to zero
                  911       length                    Calculates the length of the vector.
                __911_______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                26.15.3          Tvector2__single.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.15.4          Tvector2__single.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                                                                                 910

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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



                26.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
                (1 ) if you are able to, as it is faster.



                26.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.



                26.16            Tvector3 __double



                26.16.1          Description

                The Tvector3_double object provides a vector of three double precision scalars.



                26.16.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  912       init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  912       init\_one                 Initializes the vector and sets its elements to one
                  911       init\_zero                Initializes the vector and sets its elements to zero
                  912       length                    Calculates the length of the vector.
                __912_______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                26.16.3          Tvector3__double.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                                                                                 911

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.16.4          Tvector3__double.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                26.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



                26.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 (1 ) if you are able to, as it is faster.



                26.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.



                26.17            Tvector3 __extended



                26.17.1          Description

                The Tvector3_extended object provides a vector of three extended precision scalars.



                26.17.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  913       init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  913       init\_one                 Initializes the vector and sets its elements to one
                  913       init\_zero                Initializes the vector and sets its elements to zero
                  913       length                    Calculates the length of the vector.
                __913_______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                                                                                 912

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.17.3          Tvector3__extended.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.17.4          Tvector3__extended.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                26.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



                26.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 (1 ) if you are able to, as it is faster.



                26.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.



                26.18            Tvector3 __single



                26.18.1          Description

                The Tvector3_single object provides a vector of three single precision scalars.



                                                                                 913

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.18.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  914       init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  914       init\_one                 Initializes the vector and sets its elements to one
                  914       init\_zero                Initializes the vector and sets its elements to zero
                  914       length                    Calculates the length of the vector.
                __914_______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                26.18.3          Tvector3__single.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.18.4          Tvector3__single.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                26.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



                26.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 (1 ) if you are able to, as it is faster.



                26.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.



                                                                                 914

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.19            Tvector4 __double



                26.19.1          Description

                The Tvector4_double object provides a vector of four double precision scalars.



                26.19.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  915       init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  915       init\_one                 Initializes the vector and sets its elements to one
                  915       init\_zero                Initializes the vector and sets its elements to zero
                  915       length                    Calculates the length of the vector.
                __916_______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                26.19.3          Tvector4__double.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.19.4          Tvector4__double.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                26.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



                26.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 (1 ) if you are able to, as it is faster.



                                                                                 915

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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.



                26.20            Tvector4 __extended



                26.20.1          Description

                The Tvector4_extended object provides a vector of four extended precision scalars.



                26.20.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  916       init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  916       init\_one                 Initializes the vector and sets its elements to one
                  916       init\_zero                Initializes the vector and sets its elements to zero
                  917       length                    Calculates the length of the vector.
                __917_______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                26.20.3          Tvector4__extended.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.20.4          Tvector4__extended.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                26.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



                                                                                 916

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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 (1 ) if you are able to, as it is faster.



                26.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.



                26.21            Tvector4 __single



                26.21.1          Description

                The Tvector4_single object provides a vector of four single precision scalars.



                26.21.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  918       init                      Initializes the vector, setting its elements to the values passed
                                                      to the constructor.
                  917       init\_one                 Initializes the vector and sets its elements to one
                  917       init\_zero                Initializes the vector and sets its elements to zero
                  918       length                    Calculates the length of the vector.
                __918_______squared\_length___________Calculates_the_squared_length_of_the_vector._________________________________*
 *___________



                26.21.3          Tvector4__single.init__zero

    Synopsis:    Initializes the vector and sets its elements to zero

Declaration:     constructor  init_zero

    Visibility:   default



                26.21.4          Tvector4__single.init__one

    Synopsis:    Initializes the vector and sets its elements to one

Declaration:     constructor  init_one

    Visibility:   default



                                                                                 917

                __________________________________________________________CHAPTER_26.___REFERENCE_FOR_UNIT_'MATRIX'________________*
 *___________________



                26.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



                26.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 (1 ) if you are able to, as it is faster.



                26.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.



                                                                                 918




Chapter   27



Reference   for   unit   'mmx'



27.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.



27.2          Constants,  types  and  variables



27.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.



                                                             919

_______________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'MMX'______________________________*
 *___



27.2.2         Types

pmmxbyte  =  ^tmmxbyte


Pointer to tmmxbyte (920  ) array type


pmmxcardinal  =  ^tmmxcardinal


Pointer to tmmxcardinal (920  ) array type


pmmxinteger  =  ^tmmxinteger


Pointer to tmmxinteger (920  ) array type


pmmxlongint  =  ^tmmxlongint


Pointer to tmmxlongint (920  ) array type


pmmxshortint  =  ^tmmxshortint


Pointer to tmmxshortint (920  ) array type


pmmxsingle  =  ^tmmxsingle


Pointer to tmmxsingle (920  ) array type


pmmxword  =  ^tmmxword


Pointer to tmmxword (920  ) 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



                                                                 920

                _______________________________________________________________CHAPTER_27.___REFERENCE_FOR_UNIT_'MMX'______________*
 *___________________



                27.3          Procedures  and  functions



                27.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 (921  )



                27.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 (921  )



                                                                                 921




Chapter   28



Reference   for   unit   'Mouse'



28.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.



28.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;



                                                             922

___________________________________________________________CHAPTER_28.___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  ;



                                                                 923

___________________________________________________________CHAPTER_28.___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___._______________________________________________________________________________________________________________________



28.3          Constants,  types  and  variables



28.3.1         Constants

errMouseBase  =  1030


Base for mouse error codes.


errMouseInitError  =  errMouseBase  +  0


Mouse initialization error


errMouseNotImplemented  =  errMouseBase  +  1


Mouse driver not implemented.



                                                                 924

___________________________________________________________CHAPTER_28.___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.


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.



28.3.2         Types

PMouseEvent  =  ^TMouseEvent


Pointer to TMouseEvent (926  ) record.


TMouseDriver  =  record
    UseDefaultQueue  :  Boolean;
    InitDriver  :  procedure;
    DoneDriver  :  procedure;
    DetectMouse  :  function  :  Byte;
    ShowMouse  :  procedure;
    HideMouse  :  procedure;
    GetMouseX  :  function  :  Word;
    GetMouseY  :  function  :  Word;
    GetMouseButtons  :  function  :  Word;
    SetMouseXY  :  procedure(x:  Word;y:  Word);
    GetMouseEvent  :  procedure(var  MouseEvent:  TMouseEvent);
    PollMouseEvent  :  function(var  MouseEvent:  TMouseEvent)  :  Boolean;
    PutMouseEvent  :  procedure(const  MouseEvent:  TMouseEvent);
end



                                                                 925

                ___________________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



                The TMouseDriver record is used to implement a mouse driver in the SetMouseDriver (931  )
                function.  Its fields must be filled in before calling the SetMouseDriver (931  ) 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.



                28.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.



                28.4          Procedures  and  functions



                28.4.1         DetectMouse

    Synopsis:    Detect the presence of a mouse.

Declaration:     function  DetectMouse  :  Byte

    Visibility:   default

Description:     DetectMouse  detects  whether  a  mouse  is  attached  to  the  system  or  not.   If  there  is  no
                mouse, then zero is returned.  If a mouse is attached, then the number of mouse buttons is
                returnead.

                This function should be called after the mouse driver was initialized.

       Errors:   None.



                                                                                 926

                ___________________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



    See also:    InitMouse (930  ), DoneMouse (927  )


                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___.____________________________________________________________________________________________________________*
 *___________



                28.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 (926  ), InitMouse (930  )



                28.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.



                                                                                 927

                ___________________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



       Errors:   None.

    See also:    GetMouseEvent (928  ), GetMouseX (929  ), GetMouseY (929  )


                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___.____________________________________________________________________________________________________________*
 *___________



                28.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 (922  ).

                For an example, see the section on writing a custom mouse driver, mousedrv (922  )

       Errors:   None.

    See also:    SetMouseDriver (931  )



                28.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 (931  ).

       Errors:   None.

    See also:    GetMouseButtons (927  ), GetMouseX (929  ), GetMouseY (929  )



                                                                                 928

                ___________________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



                28.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 (927  ), GetMouseEvent (928  ), GetMouseY (929  )


                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___.____________________________________________________________________________________________________________*
 *___________



                28.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 (929  )

       Errors:   None.

    See also:    GetMouseButtons (927  ), GetMouseEvent (928  ), GetMouseX (929  )



                                                                                 929

                ___________________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



                28.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 (932  )


                Listing:  ./mouseex/ex5.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example5       ;


                {   Program       t o  d e m o n s t r a t et h e  HideMouse         f u n c t i o n. }


                Uses     mouse    ;


                Var
                    E v e n t  :  TMouseEvent        ;
                    V i s i b l e:  B o o l e a n;


                 b e g i n
                    I n i t M o u s e;
                    ShowMouse       ;
                    V i s i b l e:= True   ;
                    W r i t e l n(' P r e s s l e f t  mouse     b u t t o n  t o  h i d e/show    ,  r i g h t b u t t o n  q u i *
 *t s') ;
                    Repeat
                      G e t M o u s e E v e n(tE v e n t) ;
                      With    E v e n t  do
                         I f  ( B u t t o n s=M o u s e L e f t b u t t o)n and
                              ( A c t i o n=MouseActionDown            )  then
                             b e g i n
                             I f  V i s i b l e then
                                HideMouse
                             e l s e
                                ShowMouse       ;
                             V i s i b l e:=Not     V i s i b l e;
                             end  ;
                    U n t i l ( E v e n t. B u t t o n=s M o u s e R i g h t B u t t o)nand
                              ( E v e n t. A c t i o n=MouseActionDown           ) ;
                    DoneMouse       ;
                end___.____________________________________________________________________________________________________________*
 *___________



                28.4.9         InitMouse

    Synopsis:    Initialize the FPC mouse driver.

Declaration:     procedure  InitMouse

    Visibility:   default



                                                                                 930

                ___________________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



Description:     InitMouse Initializes the mouse driver.  This will allocate any data structures needed for
                the mouse to function.  All mouse functions can be used after a call to InitMouse.

                A call to InitMouse must always be followed by a call to DoneMouse (927  ) 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 (927  ), DetectMouse (926  )



                28.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 (928  ), PutMouseEvent (931  )



                28.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
                (928  ) or PollMouseEvent will then return MouseEvent.

                Please note that depending on the implementation the mouse event queue can hold only one
                value.

       Errors:   None.

    See also:    GetMouseEvent (928  ), PollMouseEvent (931  )



                28.4.12          SetMouseDriver

    Synopsis:    Set a new mouse driver.

Declaration:     procedure  SetMouseDriver(const  Driver:  TMouseDriver)

    Visibility:   default



                                                                                 931

                ___________________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'MOUSE'________________*
 *___________________



Description:     SetMouseDriver  sets  the  mouse  driver  to  Driver.  This  function  should  be  called  before
                InitMouse  (930  )  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 (922  ).

                For an example, see mousedrv (922  )

    See also:    InitMouse (930  ), DoneMouse (927  ), GetMouseDriver (928  )



                28.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 (929  ), GetMouseY (929  )


                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___.____________________________________________________________________________________________________________*
 *___________



                28.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 (930  )



                                                                                 932

            ___________________________________________________________CHAPTER_28.___REFERENCE_FOR_UNIT_'MOUSE'____________________*
 *_______________



   Errors:   None.

See also:    HideMouse (930  )



                                                                             933




Chapter   29



Reference   for   unit   'Ob jects'



29.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.



29.2          Constants,  types  and  variables



29.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 (1 ).


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)



                                                             934

________________________________________________________CHAPTER_29.___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:@


Default stream record for the TCollection (951  ) object.


RStrCollection  :  TStreamRec  =  (ObjType:  69;  VmtLink:  (^(TStrCollection));  Load:  @TStrCollection  .  Load;  Store:  @TStrCo*
 *llection  .  S@


Default stream record for the TStrCollection (990  ) object.


RStringCollection  :  TStreamRec  =  (ObjType:  51;  VmtLink:  (^(TStringCollection));  Load:  @TStringCollection  .  Load;  Store:*
 *  @TStringColl@


Default stream record for the TStringCollection (1001   ) object.


RStringList  :  TStreamRec  =  (ObjType:  52;  VmtLink:  (^(TStringList));  Load:  @TStringList  .  Load;  Store:  Nil;  Next:  Nil)


Default stream record for the TStringList (1003   ) object.


RStrListMaker  :  TStreamRec  =  (ObjType:  52;  VmtLink:  (^(TStrListMaker));  Load:  Nil;  Store:  @TStrListMaker  .  Store;  Nex*
 *t:  Nil)


Default stream record for the TStrListMaker (1004   ) 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



                                                                 935

________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___



stOpen  =  $3D02


Stream initialization mode:  Read/write access


stOpenError  =  -8


Stream error codes:  Error opening stream


stOpenRead  =  $3D00


Stream initialization mode:  Read access only


stOpenWrite  =  $3D01


Stream initialization mode:  Write access only


stPutError  =  -6


Stream error codes:  Put object error


stReadError  =  -3


Stream error codes:  Stream read error


StreamError  :  Pointer  =  Nil


Pointer to default stream error handler.


stSeekError  =  -7


Stream error codes:  Seek error in stream


stWriteError  =  -4


Stream error codes:  Stream write error


vmtHeaderSize  =  8


Size of the VMT header in an object (not used).



29.2.2         Types

AsciiZ  =  Array[0..255]  of  Char


Filename - null terminated array of characters.


FNameStr  =  String


Filename - shortstring version.



                                                                 936

________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___



LongRec  =  packed  record
   Hi  :  Word;
   Lo  :  Word;
end



Record describing a longint (in Words)


PBufStream  =  ^TBufStream


Pointer to TBufStream (947  ) object.


PByteArray  =  ^TByteArray


Pointer to TByteArray (939  )


PCharSet  =  ^TCharSet


Pointer to TCharSet (939  ).


PCollection  =  ^TCollection


Pointer to TCollection (951  ) object.


PDosStream  =  ^TDosStream


Pointer to TDosStream (966  ) object.


PItemList  =  ^TItemList


Pointer to TItemList (939  ) object.


PMemoryStream  =  ^TMemoryStream


Pointer to TMemoryStream (970  ) object.


PObject  =  ^TObject


Pointer to TObject (972  ) object.


PPoint  =  ^TPoint


Pointer to TPoint (974  ) record.


PPointerArray  =  ^TPointerArray


Pointer to TPointerArray (939  )


PRect  =  ^TRect


Pointer to TRect (974  ) object.



                                                                 937

________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___



PResourceCollection  =  ^TResourceCollection


Pointer to TResourceCollection (980  ) object.


PResourceFile  =  ^TResourceFile


Pointer to TResourceFile (982  ) object.


PSortedCollection  =  ^TSortedCollection


Pointer to TSortedCollection (985  ) object.


PStrCollection  =  ^TStrCollection


Pointer to TStrCollection (990  ) object.


PStream  =  ^TStream


Pointer type to TStream (992  )


PStreamRec  =  ^TStreamRec


Pointer to TStreamRec (939  )


PStrIndex  =  ^TStrIndex


Pointer to TStrIndex (939  ) array.


PString  =  PShortString


Pointer to a shortstring.


PStringCollection  =  ^TStringCollection


Pointer to TStringCollection (1001   ) object.


PStringList  =  ^TStringList


Pointer to TStringList (1003   ) object.


PStrListMaker  =  ^TStrListMaker


Pointer to TStrListMaker (1004   ) object.


PtrRec  =  packed  record
   Ofs  :  Word;
   Seg  :  Word;
end



Record describing a pointer to a memory location.



                                                                 938

________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________________________*
 *___



PUnSortedStrCollection  =  ^TUnSortedStrCollection


Pointer to TUnsortedStrCollection (1006   ) object.


PWordArray  =  ^TWordArray


Pointer to TWordArray (940  )


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 (951  )


TPointerArray  =  Array[0..MaxPtrs-1]  of  Pointer


Array with maxmimum allowed number of pointers


TStreamRec  =  packed  record
   ObjType  :  Sw_Word;
   VmtLink  :  pointer;
   Load  :  Pointer;
   Store  :  Pointer;
   Next  :  PStreamRec;
end



TSreamRec is used by the Objects unit streaming mechanism:  when an object is registered,
a TStreamRec record is added to a list of records.  This list is used when objects need to be
streamed from/streamed to a stream.  It contains all the information needed to stream the
object.


TStrIndex  =  Array[0..9999]  of  TStrIndexRec


Pointer array type used in a TStringList (1003   )



                                                                 939

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                TStrIndexRec  =  packed  record
                   Key  :  Sw_Word;
                   Count  :  Word;
                   Offset  :  Word;
                end



                Record type used in a TStringList (1003   ) 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)



                29.2.3         Variables

                invalidhandle  :  THandle


                Value for invalid handle.  Initial value for file stream handles or when the stream is closed.



                29.3          Procedures  and  functions



                29.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.



                29.3.2         CallPointerConstructor

    Synopsis:    Call a constructor with a pointer argument.

Declaration:     function  CallPointerConstructor(Ctor:  pointer;Obj:  pointer;VMT:  pointer;
                                                                   Param1:  pointer)  :  pointer

    Visibility:   default



                                                                                 940

                ________________________________________________________CHAPTER_29.___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  (942  ),  CallPointerMethod  (941  ),  CallVoidLocal  (942  ),  CallPointer-
                Local (941  ), CallVoidMethodLocal (943  ), CallPointerMethodLocal (941  )



                29.3.3         CallPointerLocal

    Synopsis:    Call a local nested function with a pointer argument

Declaration:     function  CallPointerLocal(Func:  pointer;Frame:  Pointer;Param1:  pointer)
                                                           :  pointer

    Visibility:   default

Description:     CallPointerLocal calls the local procedure with address Func, where Frame is the frame
                of the wrapping function.  It passes Param1 to the local function.

       Errors:   If the local function expects other parameters than a pointer,  the stack may become cor-
                rupted.

    See also:    CallPointerMethod (941  ), CallVoidMethod (942  ), CallVoidLocal (942  ), CallVoidMethodLo-
                cal (943  ), CallPointerMethodLocal (941  ), CallVoidConstructor (942  ), CallPointerConstruc-
                tor (940  )



                29.3.4         CallPointerMethod

    Synopsis:    Call a method with a single pointer argument

Declaration:     function  CallPointerMethod(Method:  pointer;Obj:  pointer;Param1:  pointer)
                                                             :  pointer

    Visibility:   default

Description:     CallPointerMethod  calls  the  method  with  address  Method  for  instance  Obj.   It  passes
                Param1 to the method as the single argument.  It returns a pointer to the instance.

       Errors:   If the method expects other parameters than a single pointer, the stack may become cor-
                rupted.

    See also:    CallVoidMethod (942  ), CallVoidLocal (942  ), CallPointerLocal (941  ), CallVoidMethodLocal
                (943  ),  CallPointerMethodLocal  (941  ),  CallVoidConstructor  (942  ),  CallPointerConstructor
                (940  )



                29.3.5         CallPointerMethodLocal

    Synopsis:    Call a local procedure of a method with a pointer argument

Declaration:     function  CallPointerMethodLocal(Func:  pointer;Frame:  Pointer;
                                                                   Obj:  pointer;Param1:  pointer)  :  pointer



                                                                                 941

                ________________________________________________________CHAPTER_29.___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  (941  ),  CallVoidMethod  (942  ),  CallPointerLocal  (941  ),  CallVoidLocal
                (942  ), CallVoidMethodLocal (943  ), CallVoidConstructor (942  ), CallPointerConstructor (940  )



                29.3.6         CallVoidConstructor

    Synopsis:    Call a constructor with no arguments

Declaration:     function  CallVoidConstructor(Ctor:  pointer;Obj:  pointer;VMT:  pointer)
                                                                :  pointer

    Visibility:   default

Description:     CallVoidConstructor calls the constructor of an object.  Ctor is the address of the con-
                structor, Obj is a pointer to the instance.  If it is Nil, then a new instance is allocated.  VMT
                is a pointer to the object's VMT. The return value is a pointer to the instance.

                Note that this can only be used on constructors that require no arguments.

       Errors:   If the constructor expects arguments, the stack may be corrupted.

    See also:    CallPointerConstructor (940  ), CallPointerMethod (941  ), CallVoidLocal (942  ), CallPointer-
                Local (941  ), CallVoidMethodLocal (943  ), CallPointerMethodLocal (941  )



                29.3.7         CallVoidLocal

    Synopsis:    Call a local nested procedure.

Declaration:     function  CallVoidLocal(Func:  pointer;Frame:  Pointer)  :  pointer

    Visibility:   default

Description:     CallVoidLocal calls the local procedure with address Func,  where Frame is the frame of
                the wrapping function.

       Errors:   If the local function expects parameters, the stack may become corrupted.

    See also:    CallPointerMethod (941  ), CallVoidMethod (942  ), CallPointerLocal (941  ), CallVoidMethod-
                Local  (943  ),  CallPointerMethodLocal  (941  ),  CallVoidConstructor  (942  ),  CallPointerCon-
                structor (940  )



                29.3.8         CallVoidMethod

    Synopsis:    Call an object method

Declaration:     function  CallVoidMethod(Method:  pointer;Obj:  pointer)  :  pointer

    Visibility:   default

Description:     CallVoidMethod calls the method with address Method for instance Obj.  It returns a pointer
                to the instance.



                                                                                 942

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   If the method expects parameters, the stack may become corrupted.

    See also:    CallPointerMethod (941  ), CallVoidLocal (942  ), CallPointerLocal (941  ), CallVoidMethodLo-
                cal (943  ), CallPointerMethodLocal (941  ), CallVoidConstructor (942  ), CallPointerConstruc-
                tor (940  )



                29.3.9         CallVoidMethodLocal

    Synopsis:    Call a local procedure of a method

Declaration:     function  CallVoidMethodLocal(Func:  pointer;Frame:  Pointer;Obj:  pointer)
                                                                :  pointer

    Visibility:   default

Description:     CallVoidMethodLocal  calls  the  local  procedure  with  address  Func,  where  Frame  is  the
                frame of the wrapping method.

       Errors:   If the local function expects parameters, the stack may become corrupted.

    See also:    CallPointerMethod  (941  ),  CallVoidMethod  (942  ),  CallPointerLocal  (941  ),  CallVoidLocal
                (942  ),  CallPointerMethodLocal  (941  ),  CallVoidConstructor  (942  ),  CallPointerConstructor
                (940  )



                29.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 (944  ).

       Errors:   None.

    See also:    NewStr (944  ), SetStr (946  )



                29.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 (944  )



                                                                                 943

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (943  )



                29.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 (943  ), SetStr (946  )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.3.14          RegisterObjects

    Synopsis:    Register standard objects.

Declaration:     procedure  RegisterObjects

    Visibility:   default



                                                                                 944

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



Description:     RegisterObjects registers the following objects for streaming:


                     1.TCollection, see TCollection (951  ).

                     2.TStringCollection, see TStringCollection (1001   ).

                     3.TStrCollection, see TStrCollection (990  ).


       Errors:   None.

    See also:    RegisterType (945  )



                29.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     ) ;



                                                                                 945

            ________________________________________________________CHAPTER_29.___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___.________________________________________________________________________________________________________________*
 *_______



            29.3.16          SetStr

Synopsis:    Allocate a copy of a shortstring on the heap.



                                                                             946

                ________________________________________________________CHAPTER_29.___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 (944  ), 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 (943  ), NewStr (944  )



                29.4          TBufStream



                29.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.



                29.4.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  948       Close            Flush data and Close the file.
                  948       Done             Close the file and cleans up the instance.
                  948       Flush            FLush data from buffer, and write it to stream.
                  947       Init             Initialize an instance of  TBufStream and open the file.
                  950       Open             Open the file if it is closed.
                  950       Read             Read data from the file to a buffer in memory.
                  949       Seek             Set current position in file.
                  949       Truncate         Flush buffer, and truncate the file at current position.
                __950_______Write____________Write_data_to_the_file_from_a_buffer_in_memory._______________________________________*
 *___________



                29.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.



                                                                                 947

                ________________________________________________________CHAPTER_29.___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 (1 ).

       Errors:   On error, Status is set to stInitError, and ErrorInfo is set to the dos error code.

    See also:    TDosStream.Init (1 ), TBufStream.Done (1 )



                29.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 (1 ).

       Errors:   None.

    See also:    TDosStream.Done (1 ), TBufStream.Init (1 ), TBufStream.Close (1 )



                29.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
                (1 ) it does not clean up the instance of  TBufStream

                For an example see TBufStream.Flush (1 ).

       Errors:   None.

    See also:    TStream.Close (1 ), TBufStream.Init (1 ), TBufStream.Done (1 )



                29.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  (1 )  for  more  info  on  the
                errors.



                                                                                 948

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



    See also:    TStream.Close (1 ), TBufStream.Init (1 ), TBufStream.Done (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ).

       Errors:   Errors can be those of Flush (1 ) or TDosStream.Truncate (1 ).

    See also:    TStream.Truncate (1 ), TDosStream.Truncate (1 ), TStream.GetSize (1 )



                29.4.8         TBufStream.Seek

    Synopsis:    Set current position in file.

Declaration:     procedure  Seek(Pos:  LongInt);    Virtual



                                                                                 949

                ________________________________________________________CHAPTER_29.___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 (1 );

       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 (1 ), TStream.GetPos (1 )



                29.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 (1 ) call.

                For an example, see TDosStream.Open (1 ).

       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 (1 ), TBufStream.Close (1 )



                29.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 (1 ).

       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 (1 ), TBufStream.Write (1 )



                29.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



                                                                                 950

                ________________________________________________________CHAPTER_29.___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 (1 ).

       Errors:   In  case  of  an  error,  Status  is  set  to  StWriteError,  and  ErrorInfo  gets  the  OS  specific
                error.

    See also:    TStream.Write (1 ), TBufStream.Read (1 )



                29.5          TCollection



                29.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.



                29.5.2         Method  overview

                __Page______Property__________Description__________________________________________________________________________*
 *___________
                  953       At                Return the item at a certain index.
                  962       AtDelete          Delete item at certain position.
                  961       AtFree            Free an item at the indicates position, calling it's destructor.
                  964       AtInsert          Insert an element at a certain position in the collection.
                  964       AtPut             Set collection item, overwriting an existing value.
                  960       Delete            Delete an item from the collection, but does not destroy it.
                  958       DeleteAll         Delete all elements from the collection.  Objects are not destroyed.
                  953       Done              Clean up collection, release all memory.
                  963       Error             Set error code.
                  956       FirstThat         Return first item which matches a test.
                  962       ForEach           Execute procedure for each item in the list.
                  959       Free              Free item from collection, calling it's destructor.
                  957       FreeAll           Release all objects from the collection.
                  961       FreeItem          Destroy a non-nil item.
                  955       GetItem           Read one item off the stream.
                  954       IndexOf           Find the position of a certain item.
                  951       Init              Instantiate a new collection.
                  960       Insert            Insert a new item in the collection at the end.
                  955       LastThat          Return last item which matches a test.
                  952       Load              Initialize a new collection and load collection from a stream.
                  957       Pack              Remove all >Nil pointers from the collection.
                  965       PutItem           Put one item on the stream
                  963       SetLimit          Set maximum number of elements in the collection.
                __965_______Store_____________Write_collection_to_a_stream.________________________________________________________*
 *___________



                29.5.3         TCollection.Init

    Synopsis:    Instantiate a new collection.



                                                                                 951

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



Declaration:     constructor  Init(ALimit:  Sw_Integer;ADelta:  Sw_Integer)

    Visibility:  default

Description:     Init initializes a new instance of a collection.  It sets the (initial) maximum number of items
                in the collection to ALimit.  ADelta is the increase size :  The number of memory places that
                will be allocatiod in case ALimit is reached, and another element is added to the collection.

                For an example, see TCollection.ForEach (1 ).

       Errors:   None.

    See also:    TCollection.Load (1 ), TCollection.Done (1 )



                29.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 (1 ).

    See also:    TCollection.Init (1 ), TCollection.GetItem (1 ), TCollection.Done (1 )


                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    ) ;



                                                                                 952

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ).

       Errors:   None.

    See also:    TCollection.Init (1 ), TCollection.FreeAll (1 )



                29.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 (1 )


                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 ) ;



                                                                                 953

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ), TCollection.GetItem (1 ), TCollection.Insert (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 954

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ).

    See also:    TStream.Get (1 ), TCollection.Store (1 )



                29.5.9         TCollection.LastThat

    Synopsis:    Return last item which matches a test.

Declaration:     function  LastThat(Test:  Pointer)  :  Pointer

    Visibility:   default

Description:     This function returns the last item in the collection for which Test returns a non-nil result.
                Test is a function that accepts 1 argument:  a pointer to an object, and that returns a pointer
                as a result.

       Errors:   None.

    See also:    TCollection.FirstThat (1 )


                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   ;



                                                                                 955

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.5.10          TCollection.FirstThat

    Synopsis:    Return first item which matches a test.

Declaration:     function  FirstThat(Test:  Pointer)  :  Pointer

    Visibility:   default

Description:     This function returns the first item in the collection for which Test returns a non-nil result.
                Test is a function that accepts 1 argument:  a pointer to an object, and that returns a pointer
                as a result.

       Errors:   None.

    See also:    TCollection.LastThat (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 956

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.5.12          TCollection.FreeAll

    Synopsis:    Release all objects from the collection.

Declaration:     procedure  FreeAll

    Visibility:   default



                                                                                 957

                ________________________________________________________CHAPTER_29.___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 (1 ), TCollection.FreeItem (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ), DeletAll doesn't call the destructor of the objects.

       Errors:   None.

    See also:    TCollection.FreeAll (1 ), TCollection.Delete (1 )


                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}



                                                                                 958

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 )


                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.' ) ;



                                                                                 959

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ), TCollection.AtPut (1 )



                29.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 (1 ) call is provided.

       Errors:   If the Item is not in the collection, Error will be called with coIndexError.

    See also:    TCollection.AtDelete (1 ), TCollection.Free (1 )


                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') ;



                                                                                 960

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ) is called with CoIndexError.

    See also:    TCollection.Free (1 ), TCollection.AtDelete (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.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.



                                                                                 961

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   None.

    See also:    TCollection.Free (1 ), TCollection.AtFree (1 )



                29.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 (1 ) is called with CoIndexError.

    See also:    TCollection.Delete (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.5.20          TCollection.ForEach

    Synopsis:    Execute procedure for each item in the list.

Declaration:     procedure  ForEach(Action:  Pointer)

    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.



                                                                                 962

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   None.

    See also:    TCollection.FirstThat (1 ), TCollection.LastThat (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ).

       Errors:   None.

    See also:    TCollection.Init (1 )



                29.5.22          TCollection.Error

    Synopsis:    Set error code.

Declaration:     procedure  Error(Code:  Integer;Info:  Integer);    Virtual



                                                                                 963

                ________________________________________________________CHAPTER_29.___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 (940  )



                29.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 (1 ).

       Errors:   If  Index isn't valid then Error (1 ) is called with CoIndexError.



                29.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  (1 )  is  called  with  CoIndexError.  If  the  collection  fails  to
                expand, then coOverFlow is passd to Error.

    See also:    TCollection.Insert (1 )


                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   ;



                                                                                 964

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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
                (1 ).

                For an example, see TCollection.Load (1 ).

       Errors:   Errors returned are those by TStream.Put (1 ).

    See also:    TCollection.Load (1 ), TCollection.PutItem (1 )



                29.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 (1 ).

    See also:    Store (1 ), GetItem (1 )



                                                                                 965

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.6          TDosStream



                29.6.1         Description

                TDosStream is a stream that stores it's contents in a file.  it overrides a couple of methods of
                TStream (992  ) for this.

                In addition to the fields inherited from TStream (see TStream (992  )), 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 (947  ).



                29.6.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  967       Close            Close the file.
                  966       Done             Closes the file and cleans up the instance.
                  966       Init             Instantiate a new instance of TDosStream.
                  969       Open             Open the file stream
                  969       Read             Read data from the stream to a buffer.
                  968       Seek             Set file position.
                  967       Truncate         Truncate the file on the current position.
                __970_______Write____________Write_data_from_a_buffer_to_the_stream._______________________________________________*
 *___________



                29.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 (1 ).

       Errors:   On error, Status (1 ) is set to stInitError, and ErrorInfo is set to the dos error code.

    See also:    TDosStream.Done (1 )



                29.6.4         TDosStream.Done

    Synopsis:    Closes the file and cleans up the instance.

Declaration:     destructor  Done;    Virtual

    Visibility:   default



                                                                                 966

                ________________________________________________________CHAPTER_29.___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 (1 ).

       Errors:   None.

    See also:    TDosStream.Init (1 ), TDosStream.Close (1 )



                29.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 (1 ) it does not
                clean up the instance of  TDosStream

                For an example, see TDosStream.Open (1 ).

       Errors:   None.

    See also:    TStream.Close (1 ), TDosStream.Init (1 ), TDosStream.Done (1 )



                29.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 (1 ), TStream.GetSize (1 )


                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  ) ;



                                                                                 967

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ), TStream.GetPos (1 )


                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') ;



                                                                                 968

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ) 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 (1 ), TDosStream.Close (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.6.9         TDosStream.Read

    Synopsis:    Read data from the stream to a buffer.



                                                                                 969

                ________________________________________________________CHAPTER_29.___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 (1 ).

       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 (1 ), TDosStream.Write (1 )



                29.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 (1 ).

       Errors:   In  case  of  an  error,  Status  is  set  to  StWriteError,  and  ErrorInfo  gets  the  OS  specific
                error.

    See also:    TStream.Write (1 ), TDosStream.Read (1 )



                29.7          TMemoryStream



                29.7.1         Description

                The TMemoryStream object implements a stream that stores it's data in memory.  The data
                is stored on the heap, with the possibility to specify the maximum amout of data, and the
                the size of the memory blocks being used.


    See also:    TStream (992  )



                29.7.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  971       Done             Clean up memory and destroy the object instance.
                  970       Init             Initialize memory stream, reserves memory for stream data.
                  972       Read             Read data from the stream to a location in memory.
                  971       Truncate         Set the stream size to the current position.
                __972_______Write____________Write_data_to_the_stream._____________________________________________________________*
 *___________



                29.7.3         TMemoryStream.Init

    Synopsis:    Initialize memory stream, reserves memory for stream data.

Declaration:     constructor  Init(ALimit:  LongInt;ABlockSize:  Word)



                                                                                 970

                ________________________________________________________CHAPTER_29.___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 (1 ).

       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 (1 )



                29.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 (1 ).

       Errors:   None.

    See also:    TMemoryStream.Init (1 )



                29.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 (1 )


                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          ;



                                                                                 971

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ).

       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 (1 ), TMemoryStream.Write (1 )



                29.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 (1 )) as needed.

                For an example, see TStream.Read (1 ).

       Errors:   If the stream cannot allocate more memory, then the status is set to stWriteError

    See also:    TStream.Write (1 ), TMemoryStream.Read (1 )



                29.8          TOb ject



                29.8.1         Description

                This type serves as the basic object for all other objects in the Objects unit.



                                                                                 972

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.8.2         Method  overview

                __Page______Property___________Description_________________________________________________________________________*
 *___________
                  974       Done               Destroy an object.
                  973       Free               Destroy an object and release all memory.
                  973       Init               Construct (initialize) a new object
                __974_______Is\_Object_________Check_whether_a_pointer_points_to_an_object.________________________________________*
 *___________



                29.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 (1 )

       Errors:   None.

    See also:    TObject.Free (1 ), TObject.Done (1 )



                29.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 (1 ), TObject.Done (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 973

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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.



                29.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 (1 ) method.

                The destructore Done does not free the memory occupied by the object.

       Errors:   None.

    See also:    TObject.Free (1 ), TObject.Init (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.9          TPoint



                29.9.1         Description

                Record describing a point in a 2 dimensional plane.



                29.10            TRect



                29.10.1          Description

                Describes a rectangular region in a plane.



                                                                                 974

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.10.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  980       Assign          Set rectangle corners.
                  976       Contains        Determine if a point is inside the rectangle
                  976       Copy            Copy cornerpoints from another rectangle.
                  975       Empty           Is the surface of the rectangle zero
                  976       Equals          Do the corners of the rectangles match
                  979       Grow            Expand rectangle with certain size.
                  978       Intersect       Reduce rectangle to intersection with another rectangle
                  978       Move            Move rectangle along a vector.
                __977_______Union___________Enlarges_rectangle_to_encompas_another_rectangle.______________________________________*
 *___________



                29.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 (1 ), TRect.Contains (1 )


                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



                                                                                 975

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 )

       Errors:   None.

    See also:    TRect.Empty (1 ), TRect.Contains (1 )



                29.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 (1 ), TRect.Equals (1 )



                29.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.



                                                                                 976

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   None.

    See also:    TRect.Assign (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 )


                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



                                                                                 977

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.10.9          TRect.Move

    Synopsis:    Move rectangle along a vector.

Declaration:     procedure  Move(ADX:  Sw_Integer;ADY:  Sw_Integer)

    Visibility:   default



                                                                                 978

                ________________________________________________________CHAPTER_29.___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 (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 )


                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;



                                                                                 979

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ).

       Errors:   None.

    See also:    TRect.Copy (1 )



                29.11            TResourceCollection



                29.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.



                                                                                 980

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.11.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  981       FreeItem        Release memory occupied by item.
                  981       GetItem         Read an item from the stream.
                  981       KeyOf           Return the key of an item in the collection.
                __982_______PutItem_________Write_an_item_to_the_stream.___________________________________________________________*
 *___________



                29.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 (1 )



                29.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 (1 ) method.

       Errors:   Errors returned are those by TStream.Read (1 )

    See also:    TCollection.Load (1 ), TStream.Read (1 )



                29.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 (1 )



                                                                                 981

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ) method.

       Errors:   Errors returned are those by TStream.Write (1 ).

    See also:    TCollection.Store (1 )



                29.12            TResourceFile



                29.12.1          Description

                TResourceFile (982  ) represents the resources in a binary file image.



                29.12.2          Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  983       Count            Number of resources in the file
                  984       Delete           Delete a resource from the file
                  983       Done             Destroy the instance and remove it from memory.
                  984       Flush            Writes the resources to the stream.
                  983       Get              Return a resource by key name.
                  982       Init             Instantiate a new instance.
                  983       KeyAt            Return the key of the item at a certain position.
                  984       Put              Set a resource by key name.
                __984_______SwitchTo_________Write_resources_to_a_new_stream.______________________________________________________*
 *___________



                29.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 (1 )



                                                                                 982

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 )



                29.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 (1 )



                29.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 (1 )



                29.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



                                                                                 983

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ) and TStream.Write (1 ).

    See also:    TResourceFile.Flush (1 )



                29.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 (1 ) and TStream.Write (1 ).

    See also:    TResourceFile.SwitchTo (1 )



                29.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 (1 )



                29.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.



                                                                                 984

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   Errors returned may be those by TStream.Put (1 ) and TStream.Seek

    See also:    Get (1 )



                29.13            TSortedCollection



                29.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 (1 ) method.

                Because the collection is ordered, TSortedCollection overrides some TCollection methods,
                to provide faster routines for lookup.

                The Compare (1 ) 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.



                29.13.2          Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  987       Compare          Compare two items in the collection.
                  986       IndexOf          Return index of an item in the collection.
                  985       Init             Instantiates a new instance of a TSortedCollection
                  989       Insert           Insert new item in collection.
                  986       KeyOf            Return the key of an item
                  986       Load             Instantiates a new instance of a TSortedCollection and loads it from
                                             stream.
                  987       Search           Search for item with given key.
                __990_______Store____________Write_the_collection_to_the_stream.___________________________________________________*
 *___________



                29.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 (1 )) 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 (1 ), TCollection.Done (1 )



                                                                                 985

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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  (1 ))  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 (1 ).

       Errors:   None.

    See also:    TSortedCollection.Init (1 ), TCollection.Done (1 )



                29.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 (1 ), TSortedCollection.Compare (1 )



                29.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 (1 )

       Errors:   None.

    See also:    TSortedCollection.Search (1 ), TSortedCollection.Compare (1 )



                                                                                 986

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ) method and in
                the Insert (1 ) 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 (1 ), TSortedCollection.Search (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.13.8          TSortedCollection.Search

    Synopsis:    Search for item with given key.

Declaration:     function  Search(Key:  Pointer;var  Index:  Sw_Integer)  :  Boolean;    Virtual

    Visibility:   default



                                                                                 987

                ________________________________________________________CHAPTER_29.___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 (1 ) function to implement this search.

                If the item is found, Search returns True, otherwise False is returned.

       Errors:   None.

    See also:    TCollection.IndexOf (1 )


                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;
                    D i s p o s e(M ,Done    ) ;



                                                                                 988

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                    D i s p o s e(C ,Done    ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ), 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 (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 989

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ), and then writing the Duplicates flag to the stream.

                After a Store, the collection can be loaded from the stream with the constructor Load (1 )

                For an example, see TCollection.Load (1 ).

       Errors:   Errors can be those of TStream.Put (1 ).

    See also:    TSortedCollection.Load (1 )



                29.14            TStrCollection



                29.14.1          Description

                The TStrCollection object manages a sorted collection of null-terminated strings (pchar
                strings).  To this end, it overrides the Compare (1 ) method of  TSortedCollection, and it
                introduces methods to read/write strings from a stream.



                29.14.2          Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  990       Compare          Compare two strings in the collection.
                  991       FreeItem         Free null-terminated string from the collection.
                  991       GetItem          Read a null-terminated string from the stream.
                __992_______PutItem__________Write_a_null-terminated_string_to_the_stream._________________________________________*
 *___________



                29.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 (1 )


                Listing:  ./objectex/ex38.pp



                                                                                 990

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ).

    See also:    TStrCollection.PutItem (1 )



                29.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.



                                                                                 991

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   None.

    See also:    TCollection.FreeItem (1 )



                29.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 (1 ).

    See also:    TStrCollection.GetItem (1 )



                29.15            TStream



                29.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 (938  ), TDosStream (966  ), TMemoryStream (970  )



                                                                                 992

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.15.2          Method  overview

                __Page______Property___________Description_________________________________________________________________________*
 *___________
                  997       Close              Close the stream
                  1000      CopyFrom           Copy data from another stream.
                  999       Error              Set stream status
                  997       Flush              Flush the stream data from the buffer, if any.
                  993       Get                Read an object definition from the stream.
                  995       GetPos             Return current position in the stream
                  995       GetSize            Return the size of the stream.
                  993       Init               Constructor for TStream instance
                  996       Open               Open the stream
                  998       Put                Write an object to the stream.
                  999       Read               Read data from stream to buffer.
                  996       ReadStr            Read a shortstring from the stream.
                  997       Reset              Reset the stream
                  999       Seek               Set stream position.
                  994       StrRead            Read a null-terminated string from the stream.
                  998       StrWrite           Write a null-terminated string to the stream.
                  998       Truncate           Truncate the stream size on current position.
                  1000      Write              Write a number of bytes to the stream.
                __999_______WriteStr___________Write_a_pascal_string_to_the_stream.________________________________________________*
 *___________



                29.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.



                29.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 (1 ) is set, and NIL is returned.

    See also:    TStream.Put (1 )


                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      }



                                                                                 993

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ), TStream.ReadStr (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                 994

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ), TStream.GetSize (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ), TStream.GetPos (1 )


                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;



                                                                                 995

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.15.9          TStream.Open

    Synopsis:    Open the stream



                                                                                 996

                ________________________________________________________CHAPTER_29.___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 (1 ).

       Errors:   None.

    See also:    TStream.Close (1 ), TStream.Reset (1 )



                29.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 (1 ).

       Errors:   None.

    See also:    TStream.Open (1 ), TStream.Reset (1 )



                29.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 (1 ), TStream.Close (1 )



                29.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 (1 ).

       Errors:   None.

    See also:    TStream.Truncate (1 )



                                                                                 997

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ).

       Errors:   None.

    See also:    TStream.Seek (1 )



                29.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 (945  ).

                After the object has been written, it can be read again with Get (1 ).

                For an example, see TStream.Get (1 );

       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 (1 )



                29.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 (1 ).

       Errors:   None.

    See also:    TStream.WriteStr (1 ), TStream.StrRead (1 ), TStream.ReadStr (1 )



                                                                                 998

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ).

       Errors:   None.

    See also:    TStream.StrWrite (1 ), TStream.StrRead (1 ), TStream.ReadStr (1 )



                29.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 (1 ).

       Errors:   If  Pos is larger than the stream size, Status is set to StSeekError.

    See also:    TStream.GetPos (1 ), TStream.GetSize (1 )



                29.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.



                29.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.



                                                                                 999

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



       Errors:   No checking is done to see if  Buf is large enough to contain Count bytes.

    See also:    TStream.Write (1 ), TStream.ReadStr (1 ), TStream.StrRead (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 ).

       Errors:   No checking is done to see if  Buf actually contains Count bytes.

    See also:    TStream.Read (1 ), TStream.WriteStr (1 ), TStream.StrWrite (1 )



                29.15.21           TStream.CopyFrom

    Synopsis:    Copy data from another stream.

Declaration:     procedure  CopyFrom(var  S:  TStream;Count:  LongInt)

    Visibility:   default



                                                                                1000

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



Description:     CopyFrom reads Count bytes from stream S and stores them in the current stream.  It uses
                the  Read  (1 )  method  to  read  the  data,  and  the  Write  (1 )  method  to  write  in  the  current
                stream.

       Errors:   None.

    See also:    Read (1 ), Write (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                29.16            TStringCollection



                29.16.1          Description

                The TStringCollection object manages a sorted collection of pascal strings.  To this end,
                it overrides the Compare (1 ) method of  TSortedCollection, and it introduces methods to
                read/write strings from a stream.



                29.16.2          Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  1002      Compare          Compare two strings in the collection.
                  1003      FreeItem         Dispose a string in the collection from memory.
                  1002      GetItem          Get string from the stream.
                __1003______PutItem__________Write_a_string_to_the_stream._________________________________________________________*
 *___________



                                                                                1001

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ).

    See also:    TStringCollection.PutItem (1 )



                29.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 (1 )


                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 ) ) ;



                                                                                1002

                ________________________________________________________CHAPTER_29.___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___.____________________________________________________________________________________________________________*
 *___________



                29.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 (1 )



                29.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 (1 ).

    See also:    TStringCollection.GetItem (1 )



                29.17            TStringList



                29.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  (945  )  function,  you  cannot  register  the
                TStrListMaker object.



                29.17.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  1004      Done            Clean up the instance
                  1004      Get             Return a string by key name
                __1004______Load____________Load_stringlist_from_stream.___________________________________________________________*
 *___________



                                                                                1003

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 )



                29.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 (1 ), TObject.Done (1 )



                29.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 (1 )



                29.18            TStrListMaker



                29.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 (945  )
                function, you cannot register the TStringList object.



                                                                                1004

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.18.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  1005      Done            Clean up the instance and free all related memory.
                  1005      Init            Instantiate a new instance of  TStrListMaker
                  1005      Put             Add a new string to the list with associated key.
                __1006______Store___________Write_the_strings_to_the_stream._______________________________________________________*
 *___________



                29.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 (1 ), TStrListMaker.Done (1 )



                29.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 (1 ), TStrListMaker.Init (1 )



                29.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 (1 ) method.

       Errors:   None.

    See also:    TStrListMaker.Store (1 )



                                                                                1005

                ________________________________________________________CHAPTER_29.___REFERENCE_FOR_UNIT_'OBJECTS'_________________*
 *___________________



                29.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 (1 ), TStrListMaker.Put (1 )



                29.19            TUnSortedStrCollection



                29.19.1          Description

                The TUnSortedStrCollection object manages an unsorted list of strings.  To this end,  it
                overrides the TStringCollection.Insert (1 ) method to add strings at the end of the collection,
                rather than in the alphabetically correct position.

                Take  care,  the  Search  (1 )  and  IndexOf  (1 )  methods  will  not  work  on  an  unsorted  string
                collection.



                29.19.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __1006______Insert__________Insert_a_new_string_in_the_collection._________________________________________________*
 *___________



                29.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 (1 )


                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;



                                                                                1006

________________________________________________________CHAPTER_29.___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___._______________________________________________________________________________________________________________________



                                                                1007




Chapter   30



Reference   for   unit   'ob jpas'



30.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.



30.2          Constants,  types  and  variables



30.2.1         Constants

MaxInt  =  MaxLongint


Maximum value for Integer (1008   ) type.



30.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 (1008   )


PInteger  =  ^Integer


Pointer to Integer (1008   ) type.


PIntegerArray  =  ^IntegerArray


Pointer to TIntegerArray (1009   ) type.



                                                            1008

__________________________________________________________CHAPTER_30.___REFERENCE_FOR_UNIT_'OBJPAS'________________________________*
 *___



PointerArray  =  Array[0..512*1024*1024-2]  of  Pointer


Generic Array of pointers.


PPointerArray  =  ^PointerArray


Pointer to PointerArray (1009   )


PString  =  PAnsiString


Pointer to ansistring type.


TBoundArray  =  Array  of  Integer


Array of integer, used in interfaces.


TIntegerArray  =  IntegerArray


Alias for IntegerArray (1008   )


TPointerArray  =  PointerArray


Alias for PointerArray (1009   )



                                                                1009




Chapter   31



Reference   for   unit   'oldlinux'



31.1          Overview


This document describes the LINUX unit for Free Pascal.  The unit was written by Michael
van Canneyt.  It works only on the Linux/X86 operating system.



31.2          Utility  routines


Auxiliary functions that are useful in connection with the other functions.



                                                       Table 31.1:

                __Name________________________________Description______________________________________________
                  CreateShellArgV (1072   )            Create an array of pchars from string
                  EpochToLocal (1075   )               Convert epoch time to local time
                  FD_Clr (1086   )                     Clear item of select filedescriptors
                  FD_IsSet (1086   )                   Check item of select filedescriptors
                  FD_Set (1086   )                     Set item of select filedescriptors
                  FD_ZERO (1086   )                    Clear all items in select filedecriptors
                  LocalToEpoch (1105   )               Convert local time to epoch time
                  MMap (1108   )                       Map a file into memory
                  MUnMap (1109   )                     Unmap previously mapped memory file
                  Octal (1111   )                      Convert octal to digital
                  S_ISBLK (1128   )                    Check file mode for block device
                  S_ISCHR (1128   )                    Check file mode for character device
                  S_ISDIR (1128   )                    Check file mode for directory
                  S_ISFIFO (1128   )                   Check file mode for FIFO
                  S_ISLNK (1129   )                    Check file mode for symboloc link
                  S_ISREG (1129   )                    Check file mode for regular file
                  S_ISSOCK (1130   )                   Check file mode for socket
                  StringToPPchar (1124   )             Create an array of pchars from string



                                                            1010

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



31.3          Terminal  functions


Functions for controlling the terminal to which the process is connected.



                                                       Table 31.2:

                  _Name_____________________________Description_______________________________________________
                    CFMakeRaw (1067   )              Set terminal to raw mode
                    CFSetISpeed (1067   )            Set terminal reading speed
                    CFSetOSpeed (1067   )            Set terminal writing speed
                    IOCtl (1102   )                  General IO control call
                    IsATTY (1104   )                 See if filedescriptor is a terminal
                    TCDrain (1130   )                Wait till all output was written
                    TCFlow (1130   )                 Suspend transmission or receipt of data
                    TCFlush (1131   )                Discard data written to terminal
                    TCGetAttr (1131   )              Get terminal attributes
                    TCGetPGrp (1132   )              Return PID of foreground process
                    TCSendBreak (1132   )            Send data for specific time
                    TCSetAttr (1132   )              Set terminal attributes
                    TCSetPGrp (1133   )              Set foreground process
                    TTYName (1134   )                Name of tty file



31.4          System  information


Functions for retrieving system information such as date and time.



                                                       Table 31.3:

                  _Name____________________________________Description________________________________________
                    GetDate (1093   )                      Return system date
                    GetDateTime (1093   )                  Return system date and time
                    GetDomainName (1094   )                Return system domain name
                    GetEpochTime (1095   )                 Return epoch time
                    GetHostName (1097   )                  Return system host name
                    GetLocalTimezone (1098   )             Return system timezone
                    GetTime (1100   )                      Return system time
                    GetTimeOfDay (1100   )                 Return system time
                    GetTimezoneFile (1101   )              Return name of timezone file
                    ReadTimezoneFile (1116   )             Read timezone file contents
                    SysInfo (1126   )                      Return general system information
                    Uname (1134   )                        Return system information



31.5          Signals


Functions for managing and responding to signals.



                                                                1011

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



                                                       Table 31.4:

                    __Name____________________________Description_________________________________________
                      Alarm (1063   )                 Send alarm signal to self
                      Kill (1104   )                  Send arbitrary signal to process
                      pause (1113   )                 Wait for signal to arrive
                      SigAction (1120   )             Set signal action
                      Signal (1121   )                Set signal action
                      SigPending (1122   )            See if signals are waiting
                      SigProcMask (1123   )           Set signal processing mask
                      SigRaise (1123   )              Send signal to self
                      SigSuspend (1124   )            Sets signal mask and waits for signal
                      NanoSleep (1110   )             Waits for a specific amount of time



31.6          Process  handling


Functions for managing processes and programs.



                                                       Table 31.5:

       __Name_________________________Description______________________________________________________________________
         Clone (1070   )              Create a thread
         Execl (1075   )              Execute process with command-line list
         Execle (1076   )             Execute process with command-line list and environment
         Execlp (1077   )             Search in path and execute process with command list
         Execv (1078   )              Execute process
         Execve (1079   )             Execute process with environment
         Execvp (1080   )             Search in path and execute process
         Fork (1088   )               Spawn child process
         GetEGid (1094   )            Get effective group id
         GetEnv (1095   )             Get environment variable
         GetEUid (1096   )            Get effective user id
         GetGid (1097   )             Get group id
         GetPid (1098   )             Get process id
         GetPPid (1099   )            Get parent process id
         GetPriority (1099   )        Get process priority
         GetUid (1101   )             Get user id
         Nice (1111   )               Change priority of process
         SetPriority (1119   )        Change priority of process
         Shell (1120   )              Execute shell command
         WaitPid (1136   )            Wait for child process to terminate



31.7          Directory  handling  routines


Functions for reading and searching directories.



                                                                1012

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



                                                       Table 31.6:

                    __Name______________________Description________________________________________________
                      CloseDir (1072   )        Close directory handle
                      Glob (1101   )            Return files matching a search expression
                      GlobFree (1102   )        Free result of Glob
                      OpenDir (1112   )         Open directory for reading
                      ReadDir (1114   )         Read directory entry
                      SeekDir (1116   )         Seek directory
                      TellDir (1133   )         Seek directory



31.8          Pipes,  FIFOs  and  streams


Functions for creating and managing pipes.



                                                       Table 31.7:

              __Name____________________________Description______________________________________________________
                AssignPipe (1064   )            Create a pipe
                AssignStream (1065   )          Create pipes to program's input and output
                MkFifo (1108   )                Make a fifo
                PClose (1113   )                Close a pipe
                POpen (1113   )                 Open a pipe for to program's input or output



31.9          General  File  handling  routines


Functions for handling files on disk.



                                                                1013

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



                                                       Table 31.8:

                         __Name________________________Description____________________________________
                           Access (1062   )            Check access rights on file
                           BaseName (1066   )          Return name part of file
                           Chown (1069   )             Change owner of file
                           Chmod (1067   )             Change access rights on file
                           DirName (1073   )           Return directory part of file
                           FSplit (1090   )            Split filename in parts
                           FExpand (1087   )           Return full-grown filename
                           FLock (1087   )             Set lock on a file
                           FNMatch (1088   )           Match filename to searchpattern
                           FSearch (1089   )           Search for a file in a path
                           FSStat (1091   )            Return filesystem information
                           FStat (1092   )             Return file information
                           FRename (1089   )           Rename file
                           LStat (1106   )             Return information on a link
                           Link (1104   )              Create a link
                           ReadLink (1115   )          Read contents of a symbolic link
                           SymLink (1125   )           Create a symbolic link
                           Umask (1134   )             Set the file creation mask
                           UnLink (1135   )            Remove a file
                           Utime (1135   )             Change file timestamps



31.10            File  Input/Output  routines


Functions for handling file input/output.



                                                       Table 31.9:

                       __Name_________________________Description______________________________________
                         Dup (1073   )                Duplicate a file handle
                         Dup2 (1074   )               Copy one file handle to another
                         Fcntl (1081   )              General file control
                         fdClose (1082   )            Close file descriptor
                         fdFlush (1082   )            Flush file descriptor
                         fdOpen (1082   )             Open new file descriptor
                         fdRead (1083   )             Read from file descriptor
                         fdSeek (1085   )             Position in file
                         fdTruncate (1085   )         Truncate file
                         fdWrite (1085   )            Write to file descriptor
                         GetFS (1096   )              Get file descriptor of pascal file
                         Select (1116   )             Wait for input from file descriptor
                         SelectText (1118   )         Wait for input from pascal file



                                                                1014

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



31.11            Constants,  types  and  variables



31.11.1          Constants

B0  =  $0000000



B110  =  $0000003



B115200  =  $0001002



B1200  =  $0000009



B134  =  $0000004



B150  =  $0000005



B1800  =  $000000A



B19200  =  $000000E



B200  =  $0000006



B230400  =  $0001003



B2400  =  $000000B



B300  =  $0000007



B38400  =  $000000F



B460800  =  $0001004



B4800  =  $000000C



B50  =  $0000001



B57600  =  $0001001



B600  =  $0000008



                                                                1015

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



B75  =  $0000002



B9600  =  $000000D



BRKINT  =  $0000002



BS0  =  $0000000



BS1  =  $0002000



BSDLY  =  $0002000



CBAUD  =  $000100F



CBAUDEX  =  $0001000



CIBAUD  =  $100F0000



CLOCAL  =  $0000800



CLONE_FILES  =  $00000400


Clone (1070   ) option:  open files shared between processes


CLONE_FS  =  $00000200


Clone (1070   ) option:  fs info shared between processes


CLONE_PID  =  $00001000


Clone (1070   ) option:  PID shared between processes


CLONE_SIGHAND  =  $00000800


Clone (1070   ) option:  signal handlers shared between processes


CLONE_VM  =  $00000100


Clone (1070   ) option:  VM shared between processes


CMSPAR  =  $40000000



CR0  =  $0000000



                                                                1016

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



CR1  =  $0000200



CR2  =  $0000400



CR3  =  $0000600



CRDLY  =  $0000600



CREAD  =  $0000080



CRTSCTS  =  $80000000



CS5  =  $0000000



CS6  =  $0000010



CS7  =  $0000020



CS8  =  $0000030



CSIGNAL  =  $000000ff


Clone (1070   ) option:  Signal mask to be sent at exit


CSIZE  =  $0000030



CSTOPB  =  $0000040



ECHO  =  $0000008



ECHOCTL  =  $0000200



ECHOE  =  $0000010



ECHOK  =  $0000020



ECHOKE  =  $0000800



                                                                1017

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



ECHONL  =  $0000040



ECHOPRT  =  $0000400



EXTA  =  B19200



EXTB  =  B38400



FF0  =  $0000000



FF1  =  $0008000



FFDLY  =  $0008000



FIOASYNC  =  $5452



FIOCLEX  =  $5451



FIONBIO  =  $5421



FIONCLEX  =  $5450



FIONREAD  =  $541B



FLUSHO  =  $0001000



fs_ext  =  $137d


File system type (FSStat (1091   )):  (ext) Extended


fs_ext2  =  $ef53


File system type (FSStat (1091   )):  (ext2) Second extended


fs_iso  =  $9660


File system type (FSStat (1091   )):  ISO 9660


fs_minix  =  $137f


File system type (FSStat (1091   )):  Minix



                                                                1018

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



fs_minix_30  =  $138f


File system type (FSStat (1091   )):  Minix 3.0


fs_minux_V2  =  $2468


File system type (FSStat (1091   )):  Minix V2


fs_msdos  =  $4d44


File system type (FSStat (1091   )):  MSDOS (FAT)


fs_nfs  =  $6969


File system type (FSStat (1091   )):  NFS


fs_old_ext2  =  $ef51


File system type (FSStat (1091   )):  (ext2) Old second extended


fs_proc  =  $9fa0


File system type (FSStat (1091   )):  PROC fs


fs_xia  =  $012FD16D


File system type (FSStat (1091   )):  XIA


F_GetFd  =  1


FCntl (1081   ) command:  Get close-on-exec flag


F_GetFl  =  3


FCntl (1081   ) command:  Get filedescriptor flags


F_GetLk  =  5


FCntl (1081   ) command:  Get lock


F_GetOwn  =  9


FCntl (1081   ) command:  get owner of filedescriptor events


F_OK  =  0


Access (1062   ) call test:  file exists.


F_SetFd  =  2


FCntl (1081   ) command:  Set close-on-exec flag



                                                                1019

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



F_SetFl  =  4


FCntl (1081   ) command:  Set filedescriptor flags


F_SetLk  =  6


FCntl (1081   ) command:  Set lock


F_SetLkW  =  7


FCntl (1081   ) command:  Test lock


F_SetOwn  =  8


FCntl (1081   ) command:  Set owner of filedescriptor events


HUPCL  =  $0000400



ICANON  =  $0000002



ICRNL  =  $0000100



IEXTEN  =  $0008000



IGNBRK  =  $0000001



IGNCR  =  $0000080



IGNPAR  =  $0000004



IMAXBEL  =  $0002000



INLCR  =  $0000040



INPCK  =  $0000010



IOCtl_TCGETS  =  $5401


IOCTL call number:  get Terminal Control settings


ISIG  =  $0000001



ISTRIP  =  $0000020



                                                                1020

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



IUCLC  =  $0000200



IXANY  =  $0000800



IXOFF  =  $0001000



IXON  =  $0000400



LOCK_EX  =  2


FLock (1087   ) Exclusive lock


LOCK_NB  =  4


FLock (1087   ) Non-blocking operation


LOCK_SH  =  1


FLock (1087   ) Shared lock


LOCK_UN  =  8


FLock (1087   ) unlock


MAP_ANONYMOUS  =  $20


MMap (1108   ) map type:  Don't use a file


MAP_DENYWRITE  =  $800


MMap (1108   ) option:  Ignored.


MAP_EXECUTABLE  =  $1000


MMap (1108   ) option:  Ignored.


MAP_FIXED  =  $10


MMap (1108   ) map type:  Interpret addr exactly


MAP_GROWSDOWN  =  $100


MMap (1108   ) option:  Memory grows downward (like a stack)


MAP_LOCKED  =  $2000


MMap (1108   ) option:  lock the pages in memory.



                                                                1021

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



MAP_NORESERVE  =  $4000


MMap (1108   ) option:  Do not reserve swap pages for this memory.


MAP_PRIVATE  =  2


MMap (1108   ) map type:  Changes are private


MAP_SHARED  =  $1


MMap (1108   ) map type:  Share changes


MAP_TYPE  =  $f


MMap (1108   ) map type:  Bitmask for type of mapping


MINSIGSTKSZ  =  2048



NCC  =  8


Number of control characters in termio (1058   ) record.


NCCS  =  32


Number of control characters in termios (1058   ) record.


NL0  =  $0000000



NL1  =  $0000100



NLDLY  =  $0000100



NOFLSH  =  $0000080



OCRNL  =  $0000008



OFDEL  =  $0000080



OFILL  =  $0000040



OLCUC  =  $0000002



ONLCR  =  $0000004



                                                                1022

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



ONLRET  =  $0000020



ONOCR  =  $0000010



Open_Accmode  =  3


Bitmask to determine access mode in open flags.


Open_Append  =  2  shl  9


File open mode:  Append to file


Open_Creat  =  1  shl  6


File open mode:  Create if file does not yet exist.


Open_Direct  =  4  shl  12


File open mode:  Minimize caching effects


Open_Directory  =  2  shl  15


File open mode:  File must be directory.


Open_Excl  =  2  shl  6


File open mode:  Open exclusively


Open_LargeFile  =  1  shl  15


File open mode:  Open for 64-bit I/O


Open_NDelay  =  Open_NonBlock


File open mode:  Alias for Open_NonBlock (1023   )


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



                                                                1023

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



File open mode:  Read only


Open_RdWr  =  2


File open mode:  Read/Write


Open_Sync  =  1  shl  12


File open mode:  Write to disc at once


Open_Trunc  =  1  shl  9


File open mode:  Truncate file to length 0


Open_WrOnly  =  1


File open mode:  Write only


OPOST  =  $0000001



PARENB  =  $0000100



PARMRK  =  $0000008



PARODD  =  $0000200



PENDIN  =  $0004000



Prio_PGrp  =  1


Get/set process group priority


Prio_Process  =  0


Get/Set process priority


Prio_User  =  2


Get/set user priority


PROT_EXEC  =  $4


MMap (1108   ) memory access:  page can be executed


PROT_NONE  =  $0


MMap (1108   ) memory access:  page can not be accessed



                                                                1024

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



PROT_READ  =  $1


MMap (1108   ) memory access:  page can be read


PROT_WRITE  =  $2


MMap (1108   ) memory access:  page can be written


P_IN  =  1


Input file descriptor of pipe pair.


P_OUT  =  2


Output file descriptor of pipe pair.


R_OK  =  4


Access (1062   ) call test:  read allowed


SA_INTERRUPT  =  $20000000


Sigaction options:  ?


SA_NOCLDSTOP  =  1


Sigaction options:  Do not receive notification when child processes stop


SA_NOMASK  =  $40000000


Sigaction options:  Do not prevent the signal from being received when it is handled.


SA_ONESHOT  =  $80000000


Sigaction options:  Restore the signal action to the default state.


SA_ONSTACK  =  SA_STACK


Socket option


SA_RESTART  =  $10000000


Sigaction options:  Provide behaviour compatible with BSD signal semantics


SA_SHIRQ  =  $04000000


Sigaction options:  ?


SA_STACK  =  $08000000


Sigaction options:  Call the signal handler on an alternate signal stack.



                                                                1025

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Seek_Cur  =  1


Seek option:  Set position relative to current position.


Seek_End  =  2


Seek option:  Set position relative to end of file.


Seek_set  =  0


Seek option:  Set absolute position.


SIGABRT  =  6


Signal:  ABRT (Abort)


SIGALRM  =  14


Signal:  ALRM (Alarm clock)


SIGBUS  =  7


Signal:  BUS (bus error)


SIGCHLD  =  17


Signal:  CHLD (child status changed)


SIGCONT  =  18


Signal:  CONT (Continue)


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)



                                                                1026

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



SIGIOT  =  6


Signal:  IOT (IOT trap)


SIGKILL  =  9


Signal:  KILL (unblockable)


SIGPIPE  =  13


Signal:  PIPE (Broken pipe


SIGPOLL  =  SIGIO


Signal:  POLL (Pollable event)


SIGPROF  =  27


Signal:  PROF (Profiling alarm)


SIGPWR  =  30


Signal:  PWR (power failure restart)


SIGQUIT  =  3


Signal:  QUIT


SIGSEGV  =  11


Signal:  SEGV (Segmentation violation)


SIGSTKFLT  =  16


Signal:  STKFLT (Stack Fault)


SIGSTKSZ  =  8192


Signal Stack size error


SIGSTOP  =  19


Signal:  STOP (Stop, unblockable)


SIGTerm  =  15


Signal:  TERM (Terminate)


SIGTRAP  =  5


Signal:  TRAP (Trace trap)



                                                                1027

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



SIGTSTP  =  20


Signal:  TSTP (keyboard stop)


SIGTTIN  =  21


Signal:  TTIN (Terminal input, background)


SIGTTOU  =  22


Signal:  TTOU (Terminal output, background)


SIGUNUSED  =  31


Signal:  Unused


SIGURG  =  23


Signal:  URG (Socket urgent condition)


SIGUSR1  =  10


Signal:  USR1 (User-defined signal 1)


SIGUSR2  =  12


Signal:  USR2 (User-defined signal 2)


SIGVTALRM  =  26


Signal:  VTALRM (Virtual alarm clock)


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



                                                                1028

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



SIG_ERR  =  -1


Signal handler:  error


SIG_IGN  =  1


Signal handler:  Ignore signal


SIG_SETMASK  =  2


Sigprocmask flags:  Set of blocked signals is given.


SIG_UNBLOCK  =  1


Sigprocmask flags:  Remove signals from the set set of blocked signals.


SI_PAD_SIZE  =  128  /  (longint)  -  3


Signal information record pad bytes size.  Do not use.


SS_DISABLE  =  2


Socket options


SS_ONSTACK  =  1


Socket options


STAT_IFBLK  =  $6000


File (stat (1057   ) record) mode:  Block device


STAT_IFCHR  =  $2000


File (stat (1057   ) record) mode:  Character device


STAT_IFDIR  =  $4000


File (stat (1057   ) record) mode:  Directory


STAT_IFIFO  =  $1000


File (stat (1057   ) record) mode:  FIFO


STAT_IFLNK  =  $a000


File (stat (1057   ) record) mode:  Link


STAT_IFMT  =  $f000


File (stat (1057   ) record) mode:  File type bit mask



                                                                1029

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



STAT_IFREG  =  $8000


File (stat (1057   ) record) mode:  Regular file


STAT_IFSOCK  =  $c000


File (stat (1057   ) record) mode:  Socket


STAT_IRGRP  =  STAT_IROTH  shl  3


File (stat (1057   ) record) mode:  Group read permission


STAT_IROTH  =  $4


File (stat (1057   ) record) mode:  Other read permission


STAT_IRUSR  =  STAT_IROTH  shl  6


File (stat (1057   ) record) mode:  Owner read permission


STAT_IRWXG  =  STAT_IRWXO  shl  3


File (stat (1057   ) record) mode:  Group permission bits mask


STAT_IRWXO  =  $7


File (stat (1057   ) record) mode:  Other permission bits mask


STAT_IRWXU  =  STAT_IRWXO  shl  6


File (stat (1057   ) record) mode:  Owner permission bits mask


STAT_ISGID  =  $0400


File (stat (1057   ) record) mode:  GID bit set


STAT_ISUID  =  $0800


File (stat (1057   ) record) mode:  UID bit set


STAT_ISVTX  =  $0200


File (stat (1057   ) record) mode:  Sticky bit set


STAT_IWGRP  =  STAT_IWOTH  shl  3


File (stat (1057   ) record) mode:  Group write permission


STAT_IWOTH  =  $2


File (stat (1057   ) record) mode:  Other write permission



                                                                1030

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



STAT_IWUSR  =  STAT_IWOTH  shl  6


File (stat (1057   ) record) mode:  Owner write permission


STAT_IXGRP  =  STAT_IXOTH  shl  3


File (stat (1057   ) record) mode:  Others execute permission


STAT_IXOTH  =  $1


File (stat (1057   ) record) mode:  Others execute permission


STAT_IXUSR  =  STAT_IXOTH  shl  6


File (stat (1057   ) record) mode:  Others execute permission


syscall_nr_access  =  33



syscall_nr_acct  =  51



syscall_nr_adjtimex  =  124



syscall_nr_afs_syscall  =  137



syscall_nr_alarm  =  27



syscall_nr_bdflush  =  134



syscall_nr_break  =  17



syscall_nr_brk  =  45



syscall_nr_chdir  =  12



syscall_nr_chmod  =  15



syscall_nr_chown  =  16



syscall_nr_chroot  =  61



syscall_nr_clone  =  120



                                                                1031

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



syscall_nr_close  =  6



syscall_nr_creat  =  8



syscall_nr_create_module  =  127



syscall_nr_delete_module  =  129



syscall_nr_dup  =  41



syscall_nr_dup2  =  63



syscall_nr_execve  =  11



syscall_nr_exit  =  1



syscall_nr_fchdir  =  133



syscall_nr_fchmod  =  94



syscall_nr_fchown  =  95



syscall_nr_fcntl  =  55



syscall_nr_fdatasync  =  148



syscall_nr_flock  =  143



syscall_nr_fork  =  2



syscall_nr_fstat  =  108



syscall_nr_fstatfs  =  100



syscall_nr_fsync  =  118



syscall_nr_ftime  =  35



                                                                1032

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



syscall_nr_ftruncate  =  93



syscall_nr_getdents  =  141



syscall_nr_getegid  =  50



syscall_nr_geteuid  =  49



syscall_nr_getgid  =  47



syscall_nr_getgroups  =  80



syscall_nr_getitimer  =  105



syscall_nr_getpgid  =  132



syscall_nr_getpgrp  =  65



syscall_nr_getpid  =  20



syscall_nr_getppid  =  64



syscall_nr_getpriority  =  96



syscall_nr_getresuid  =  165



syscall_nr_getrlimit  =  76



syscall_nr_getrusage  =  77



syscall_nr_getsid  =  147



syscall_nr_gettimeofday  =  78



syscall_nr_getuid  =  24



syscall_nr_get_kernel_syms  =  130



                                                                1033

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



syscall_nr_gtty  =  32



syscall_nr_idle  =  112



syscall_nr_init_module  =  128



syscall_nr_ioctl  =  54



syscall_nr_ioperm  =  101



syscall_nr_iopl  =  110



syscall_nr_ipc  =  117



syscall_nr_kill  =  37



syscall_nr_link  =  9



syscall_nr_lock  =  53



syscall_nr_lseek  =  19



syscall_nr_lstat  =  107



syscall_nr_mkdir  =  39



syscall_nr_mknod  =  14



syscall_nr_mlock  =  150



syscall_nr_mlockall  =  152



syscall_nr_mmap  =  90



syscall_nr_modify_ldt  =  123



syscall_nr_mount  =  21



                                                                1034

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



syscall_nr_mprotect  =  125



syscall_nr_mpx  =  56



syscall_nr_mremap  =  163



syscall_nr_msync  =  144



syscall_nr_munlock  =  151



syscall_nr_munlockall  =  153



syscall_nr_munmap  =  91



syscall_nr_nanosleep  =  162



syscall_nr_nice  =  34



syscall_nr_oldfstat  =  28



syscall_nr_oldlstat  =  84



syscall_nr_oldolduname  =  59



syscall_nr_oldstat  =  18



syscall_nr_olduname  =  109



syscall_nr_open  =  5



syscall_nr_pause  =  29



syscall_nr_personality  =  136



syscall_nr_phys  =  52



syscall_nr_pipe  =  42



                                                                1035

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



syscall_nr_poll  =  168



syscall_nr_prof  =  44



syscall_nr_profil  =  98



syscall_nr_ptrace  =  26



syscall_nr_query_module  =  167



syscall_nr_quotactl  =  131



syscall_nr_read  =  3



syscall_nr_readdir  =  89



syscall_nr_readlink  =  85



syscall_nr_readv  =  145



syscall_nr_reboot  =  88



syscall_nr_rename  =  38



syscall_nr_rmdir  =  40



syscall_nr_sched_getparam  =  155



syscall_nr_sched_getscheduler  =  157



syscall_nr_sched_get_priority_max  =  159



syscall_nr_sched_get_priority_min  =  160



syscall_nr_sched_rr_get_interval  =  161



syscall_nr_sched_setparam  =  154



                                                                1036

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



syscall_nr_sched_setscheduler  =  156



syscall_nr_sched_yield  =  158



syscall_nr_select  =  82



syscall_nr_setdomainname  =  121



syscall_nr_setfsgid  =  139



syscall_nr_setfsuid  =  138



syscall_nr_setgid  =  46



syscall_nr_setgroups  =  81



syscall_nr_sethostname  =  74



syscall_nr_setitimer  =  104



syscall_nr_setpgid  =  57



syscall_nr_setpriority  =  97



syscall_nr_setregid  =  71



syscall_nr_setresuid  =  164



syscall_nr_setreuid  =  70



syscall_nr_setrlimit  =  75



syscall_nr_setsid  =  66



syscall_nr_settimeofday  =  79



syscall_nr_setuid  =  23



                                                                1037

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



syscall_nr_setup  =  0



syscall_nr_sgetmask  =  68



syscall_nr_sigaction  =  67



syscall_nr_sigaltstack  =  186



syscall_nr_signal  =  48



syscall_nr_sigpending  =  73



syscall_nr_sigprocmask  =  126



syscall_nr_sigreturn  =  119



syscall_nr_sigsuspend  =  72



syscall_nr_socketcall  =  102



syscall_nr_ssetmask  =  69



syscall_nr_stat  =  106



syscall_nr_statfs  =  99



syscall_nr_stime  =  25



syscall_nr_stty  =  31



syscall_nr_swapoff  =  115



syscall_nr_swapon  =  87



syscall_nr_symlink  =  83



syscall_nr_sync  =  36



                                                                1038

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



syscall_nr_sysfs  =  135



syscall_nr_sysinfo  =  116



syscall_nr_syslog  =  103



syscall_nr_time  =  13



syscall_nr_times  =  43



syscall_nr_truncate  =  92



syscall_nr_ulimit  =  58



syscall_nr_umask  =  60



syscall_nr_umount  =  22



syscall_nr_uname  =  122



syscall_nr_unlink  =  10



syscall_nr_uselib  =  86



syscall_nr_ustat  =  62



syscall_nr_utime  =  30



syscall_nr_vhangup  =  111



syscall_nr_vm86  =  166



syscall_nr_vm86old  =  113



syscall_nr_wait4  =  114



syscall_nr_waitpid  =  7



                                                                1039

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



syscall_nr_write  =  4



syscall_nr_writev  =  146



syscall_nr__llseek  =  140



syscall_nr__newselect  =  142



syscall_nr__sysctl  =  149



Sys_E2BIG  =  7



Sys_EACCES  =  13



Sys_EADDRINUSE  =  98



Sys_EADDRNOTAVAIL  =  99



Sys_EADV  =  68



Sys_EAFNOSUPPORT  =  97



Sys_EAGAIN  =  11



Sys_EALREADY  =  114



Sys_EBADE  =  52



Sys_EBADF  =  9



Sys_EBADFD  =  77



Sys_EBADMSG  =  74



Sys_EBADR  =  53



Sys_EBADRQC  =  56



                                                                1040

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Sys_EBADSLT  =  57



Sys_EBFONT  =  59



Sys_EBUSY  =  16



Sys_ECHILD  =  10



Sys_ECHRNG  =  44



Sys_ECOMM  =  70



Sys_ECONNABORTED  =  103



Sys_ECONNREFUSED  =  111



Sys_ECONNRESET  =  104



Sys_EDEADLK  =  35



Sys_EDEADLOCK  =  58



Sys_EDESTADDRREQ  =  89



Sys_EDOM  =  33



Sys_EDOTDOT  =  73



Sys_EDQUOT  =  122



Sys_EEXIST  =  17



Sys_EFAULT  =  14



Sys_EFBIG  =  27



Sys_EHOSTDOWN  =  112



                                                                1041

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Sys_EHOSTUNREACH  =  113



Sys_EIDRM  =  43



Sys_EILSEQ  =  84



Sys_EINPROGRESS  =  115



Sys_EINTR  =  4



Sys_EINVAL  =  22



Sys_EIO  =  5



Sys_EISCONN  =  106



Sys_EISDIR  =  21



Sys_EISNAM  =  120



Sys_EL2HLT  =  51



Sys_EL2NSYNC  =  45



Sys_EL3HLT  =  46



Sys_EL3RST  =  47



Sys_ELIBACC  =  79



Sys_ELIBBAD  =  80



Sys_ELIBEXEC  =  83



Sys_ELIBMAX  =  82



Sys_ELIBSCN  =  81



                                                                1042

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Sys_ELNRNG  =  48



Sys_ELOOP  =  40



Sys_EMFILE  =  24



Sys_EMLINK  =  31



Sys_EMSGSIZE  =  90



Sys_EMULTIHOP  =  72



Sys_ENAMETOOLONG  =  36



Sys_ENAVAIL  =  119



Sys_ENETDOWN  =  100



Sys_ENETRESET  =  102



Sys_ENETUNREACH  =  101



Sys_ENFILE  =  23



Sys_ENOANO  =  55



Sys_ENOBUFS  =  105



Sys_ENOCSI  =  50



Sys_ENODATA  =  61



Sys_ENODEV  =  19



Sys_ENOENT  =  2



Sys_ENOEXEC  =  8



                                                                1043

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Sys_ENOLCK  =  37



Sys_ENOLINK  =  67



Sys_ENOMEM  =  12



Sys_ENOMSG  =  42



Sys_ENONET  =  64



Sys_ENOPKG  =  65



Sys_ENOPROTOOPT  =  92



Sys_ENOSPC  =  28



Sys_ENOSR  =  63



Sys_ENOSTR  =  60



Sys_ENOSYS  =  38



Sys_ENOTBLK  =  15



Sys_ENOTCONN  =  107



Sys_ENOTDIR  =  20



Sys_ENOTEMPTY  =  39



Sys_ENOTNAM  =  118



Sys_ENOTSOCK  =  88



Sys_ENOTTY  =  25



Sys_ENOTUNIQ  =  76



                                                                1044

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Sys_ENXIO  =  6



Sys_EOPNOTSUPP  =  95



Sys_EOVERFLOW  =  75



Sys_EPERM  =  1



Sys_EPFNOSUPPORT  =  96



Sys_EPIPE  =  32



Sys_EPROTO  =  71



Sys_EPROTONOSUPPORT  =  93



Sys_EPROTOTYPE  =  91



Sys_ERANGE  =  34



Sys_EREMCHG  =  78



Sys_EREMOTE  =  66



Sys_EREMOTEIO  =  121



Sys_ERESTART  =  85



Sys_EROFS  =  30



Sys_ERROR_MAX  =  $fff



Sys_ESHUTDOWN  =  108



Sys_ESOCKTNOSUPPORT  =  94



Sys_ESPIPE  =  29



                                                                1045

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Sys_ESRCH  =  3



Sys_ESRMNT  =  69



Sys_ESTALE  =  116



Sys_ESTRPIPE  =  86



Sys_ETIME  =  62



Sys_ETIMEDOUT  =  110



Sys_ETOOMANYREFS  =  109



Sys_ETXTBSY  =  26



Sys_EUCLEAN  =  117



Sys_EUNATCH  =  49



Sys_EUSERS  =  87



Sys_EWOULDBLOCK  =  Sys_EAGAIN



Sys_EXDEV  =  18



Sys_EXFULL  =  54



TAB0  =  $0000000



TAB1  =  $0000800



TAB2  =  $0001000



TAB3  =  $0001800



TABDLY  =  $0001800



                                                                1046

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



TCFLSH  =  $540B



TCGETA  =  $5405



TCGETS  =  $5401



TCIFLUSH  =  0



TCIOFF  =  2



TCIOFLUSH  =  2



TCION  =  3



TCOFLUSH  =  1



TCOOFF  =  0



TCOON  =  1



TCSADRAIN  =  1



TCSAFLUSH  =  2



TCSANOW  =  0



TCSBRK  =  $5409



TCSBRKP  =  $5425



TCSETA  =  $5406



TCSETAF  =  $5408



TCSETAW  =  $5407



TCSETS  =  $5402



                                                                1047

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



TCSETSF  =  $5404



TCSETSW  =  $5403



TCXONC  =  $540A



TIOCCONS  =  $541D



TIOCEXCL  =  $540C



TIOCGETD  =  $5424



TIOCGICOUNT  =  $545D



TIOCGLCKTRMIOS  =  $5456



TIOCGPGRP  =  $540F



TIOCGSERIAL  =  $541E



TIOCGSOFTCAR  =  $5419



TIOCGWINSZ  =  $5413



TIOCINQ  =  FIONREAD



TIOCLINUX  =  $541C



TIOCMBIC  =  $5417



TIOCMBIS  =  $5416



TIOCMGET  =  $5415



TIOCMIWAIT  =  $545C



TIOCMSET  =  $5418



                                                                1048

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



TIOCM_CAR  =  $040



TIOCM_CD  =  TIOCM_CAR



TIOCM_CTS  =  $020



TIOCM_DSR  =  $100



TIOCM_DTR  =  $002



TIOCM_LE  =  $001



TIOCM_OUT1  =  $2000



TIOCM_OUT2  =  $4000



TIOCM_RI  =  TIOCM_RNG



TIOCM_RNG  =  $080



TIOCM_RTS  =  $004



TIOCM_SR  =  $010



TIOCM_ST  =  $008



TIOCNOTTY  =  $5422



TIOCNXCL  =  $540D



TIOCOUTQ  =  $5411



TIOCPKT  =  $5420



TIOCPKT_DATA  =  0



TIOCPKT_DOSTOP  =  32



                                                                1049

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



TIOCPKT_FLUSHREAD  =  1



TIOCPKT_FLUSHWRITE  =  2



TIOCPKT_NOSTOP  =  16



TIOCPKT_START  =  8



TIOCPKT_STOP  =  4



TIOCSCTTY  =  $540E



TIOCSERCONFIG  =  $5453



TIOCSERGETLSR  =  $5459



TIOCSERGETMULTI  =  $545A



TIOCSERGSTRUCT  =  $5458



TIOCSERGWILD  =  $5454



TIOCSERSETMULTI  =  $545B



TIOCSERSWILD  =  $5455



TIOCSETD  =  $5423



TIOCSLCKTRMIOS  =  $5457



TIOCSPGRP  =  $5410



TIOCSSERIAL  =  $541F



TIOCSSOFTCAR  =  $541A



TIOCSTI  =  $5412



                                                                1050

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



TIOCSWINSZ  =  $5414



TIOCTTYGSTRUCT  =  $5426



TOSTOP  =  $0000100



VDISCARD  =  13



VEOF  =  4



VEOL  =  11



VEOL2  =  16



VERASE  =  2



VINTR  =  0



VKILL  =  3



VLNEXT  =  15



VMIN  =  6



VQUIT  =  1



VREPRINT  =  12



VSTART  =  8



VSTOP  =  9



VSUSP  =  10



VSWTC  =  7



VT0  =  $0000000



                                                                1051

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



VT1  =  $0004000



VTDLY  =  $0004000



VTIME  =  5



VWERASE  =  14



Wait_Any  =  -1


WaitPID (1136   ):  Wait on any process


Wait_Clone  =  $80000000


WaitPID (1136   ):  Wait on clone processes only.


Wait_MyPGRP  =  0


WaitPID (1136   ):  Wait processes from current process group


Wait_NoHang  =  1


WaitPID (1136   ):  Do not wait


Wait_UnTraced  =  2


WaitPID (1136   ):  Also report stopped but untraced processes


WNOHANG  =  $1


Waitpid (1136   ) option:  Do not wait for processes to terminate.


WUNTRACED  =  $2


Waitpid (1136   ) option:  Also report children wich were stopped but not yet reported


W_OK  =  2


Access (1062   ) call test:  write allowed


XCASE  =  $0000004



XTABS  =  $0001800



X_OK  =  1


Access (1062   ) call test:  execute allowed


__WCLONE  =  $80000000


Waitpid option:  Wait for clone children only



                                                                1052

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



31.11.2          Types

ComStr  =  string


Command-line string type.


dev_t  =  Word


Device descriptor type


dirent  =  packed  record
    ino  :  LongInt;
    off  :  LongInt;
    reclen  :  Word;
    name  :  Array[0..255]  of  Char;
end



Record used in the ReadDir (1114   ) function to return files in a directory.


DirStr  =  string


Filename directory part string type.


ExtStr  =  string


Filename extension part string type.


fdSet  =  Array[0..7]  of  LongInt


Array containing file descriptor bitmask for the Select (1116   ) call.


NameStr  =  string


Filename name part string type.


PathStr  =  string


Filename path part string type.


PDir  =  ^TDir


Pointer to TDir (1058   ) record


pdirent  =  ^dirent


Pointer to Dirent (1053   ) record.


pfdset  =  ^fdSet


Pointer to FDSet (1053   ) array.



                                                                1053

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



pfpstate  =  ^tfpstate


Pointer to tfpstate (1059   ) record.


pglob  =  ^tglob


Pointer to TGlob (1059   ) record.


PSigActionRec  =  ^SigActionRec


Pointer to SigActionRec (1055   ) record.


PSigAltStack  =  ^SigAltStack


Pointer to SigAltStack (1055   ) record


PSigContextRec  =  ^SigContextRec


Pointer to SigContextRec (1056   ) record


PSignalHandler  =  ^SignalHandler


Pointer to SignalHandler (1056   ) type.


PSignalRestorer  =  ^SignalRestorer


Pointer to SignalRestorer (1056   ) type


PSigSet  =  ^SigSet


Pointer to signal set.


pstack_t  =  ^stack_t


Pointer to stack_t (1056   ) record


PStat  =  ^Stat


Pointer to Stat (1057   ) record.


PStatFS  =  ^Statfs


Pointer to StatFS (1057   ) record.


PSysCallRegs  =  ^SysCallRegs


Pointer to SysCallRegs (1057   ) record.


PSysInfo  =  ^TSysinfo


Pointer to TSysInfo (1060   ) record.



                                                                1054

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



ptimeval  =  ^timeval


Pointer to TTimeVal (1060   ) record


ptimezone  =  ^timezone


Pointer to TimeZone (1059   ) record.


PUTimeBuf  =  ^UTimeBuf


Pointer to UTimeBuf (1061   ) record


PUTSName  =  ^utsname


Pointer to UTSName (1061   ) record.


SigActionRec  =  packed  record
   Handler  :  record
   end;
   Sa_Mask  :  SigSet;
   Sa_Flags  :  LongInt;
   Sa_restorer  :  SignalRestorer;
end



Record used in SigAction (1120   ) call.


SigAltStack  =  record
   ss_sp  :  pointer;
   ss_flags  :  LongInt;
   ss_size  :  Size_T;
end



Alternate stack registers record


SigContextRec  =  record
   gs  :  Word;
   __gsh  :  Word;
   fs  :  Word;
   __fsh  :  Word;
   es  :  Word;
   __esh  :  Word;
   ds  :  Word;
   __dsh  :  Word;
   edi  :  Cardinal;
   esi  :  Cardinal;
   ebp  :  Cardinal;
   esp  :  Cardinal;
   ebx  :  Cardinal;
   edx  :  Cardinal;
   ecx  :  Cardinal;



                                                                1055

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



   eax  :  Cardinal;
   trapno  :  Cardinal;
   err  :  Cardinal;
   eip  :  Cardinal;
   cs  :  Word;
   __csh  :  Word;
   eflags  :  Cardinal;
   esp_at_signal  :  Cardinal;
   ss  :  Word;
   __ssh  :  Word;
   fpstate  :  pfpstate;
   oldmask  :  Cardinal;
   cr2  :  Cardinal;
end



The above records contain information about the processor state and process state at the
moment a signal is sent to your program.


SignalHandler  =  procedure(Sig:  LongInt)  of  object


Function prototype for the Signal (1121   ) call.


SignalRestorer  =  procedure  of  object


Signal restorer function prototype


SigSet  =  LongInt


Signal set type


Size_T  =  Cardinal


Size type


stack_t  =  SigAltStack


Alias for SigAltStack (1055   ) type


Stat  =  packed  record
   dev  :  dev_t;
   pad1  :  Word;
   ino  :  LongInt;
   mode  :  Word;
   nlink  :  Word;
   uid  :  Word;
   gid  :  Word;
   rdev  :  dev_t;
   pad2  :  Word;
   size  :  LongInt;
   blksize  :  LongInt;
   blocks  :  LongInt;



                                                                1056

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



   atime  :  LongInt;
   unused1  :  LongInt;
   mtime  :  LongInt;
   unused2  :  LongInt;
   ctime  :  LongInt;
   unused3  :  LongInt;
   unused4  :  LongInt;
   unused5  :  LongInt;
end



Record describing an inode (file) in the fstat (1092   ) call.


Statfs  =  packed  record
   fstype  :  LongInt;
   bsize  :  LongInt;
   blocks  :  LongInt;
   bfree  :  LongInt;
   bavail  :  LongInt;
   files  :  LongInt;
   ffree  :  LongInt;
   fsid  :  LongInt;
   namelen  :  LongInt;
   spare  :  Array[0..6]  of  LongInt;
end



Record describing a file system in the fsstat (1091   ) call.


SysCallRegs  =  record
   reg1  :  LongInt;
   reg2  :  LongInt;
   reg3  :  LongInt;
   reg4  :  LongInt;
   reg5  :  LongInt;
   reg6  :  LongInt;
end



Register describing system calls.


TCloneFunc  =  function(args:  pointer)  :  LongInt  of  object


Clone function prototype.


TDir  =  packed  record
   fd  :  Integer;
   loc  :  LongInt;
   size  :  Integer;
   buf  :  pdirent;
   nextoff  :  LongInt;
   dd_max  :  Integer;
   lock  :  pointer;
end



                                                                1057

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Record used in OpenDir (1112   ) and ReadDir (1114   ) calls


TDirEnt  =  dirent


Alias for DirEnt (1053   ) record


Termio  =  packed  record
   c_iflag  :  Word;
   c_oflag  :  Word;
   c_cflag  :  Word;
   c_lflag  :  Word;
   c_line  :  Word;
   c_cc  :  Array[0..NCC-1]  of  Char;
end



Terminal I/O description record (small)


Termios  =  record
   c_iflag  :  Cardinal;
   c_oflag  :  Cardinal;
   c_cflag  :  Cardinal;
   c_lflag  :  Cardinal;
   c_line  :  Char;
   c_cc  :  Array[0..NCCS-1]  of  Byte;
   c_ispeed  :  LongInt;
   c_ospeed  :  LongInt;
end



Terminal I/O description record


TFDSet  =  fdSet


Alias for FDSet (1053   ) type.


tfpreg  =  record
   significand  :  Array[0..3]  of  Word;
   exponent  :  Word;
end



Record describing floating point register in signal handler.


tfpstate  =  record
   cw  :  Cardinal;
   sw  :  Cardinal;
   tag  :  Cardinal;
   ipoff  :  Cardinal;
   cssel  :  Cardinal;
   dataoff  :  Cardinal;
   datasel  :  Cardinal;



                                                                1058

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



   st  :  Array[0..7]  of  tfpreg;
   status  :  Cardinal;
end



Record describing floating point unit in signal handler.


tglob  =  record
   name  :  pchar;
   next  :  pglob;
end



Record containing one entry in the result of Glob (1101   )


timespec  =  packed  record
   tv_sec  :  LongInt;
   tv_nsec  :  LongInt;
end



Time interval for the NanoSleep (1110   ) function.


timeval  =  packed  record
   sec  :  LongInt;
   usec  :  LongInt;
end



Record specifying a time inteval.


timezone  =  packed  record
   minuteswest  :  LongInt;
   dsttime  :  LongInt;
end



Record describing a timezone


tmmapargs  =  record
   address  :  LongInt;
   size  :  LongInt;
   prot  :  LongInt;
   flags  :  LongInt;
   fd  :  LongInt;
   offset  :  LongInt;
end



Record containing mmap args.


Tpipe  =  Array[1..2]  of  LongInt



                                                                1059

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Array describing a pipe pair of filedescriptors.


TSigAction  =  procedure(Sig:  LongInt;SigContext:  SigContextRec)  of  object


Function prototype for SigAction (1120   ) call.


TStat  =  Stat


Alias for Stat (1057   ) record.


TStatFS  =  Statfs


Alias for StatFS (1057   ) type.


TSysCallRegs  =  SysCallRegs


Alias for SysCallRegs (1057   ) record


TSysinfo  =  packed  record
   uptime  :  LongInt;
   loads  :  Array[1..3]  of  LongInt;
   totalram  :  LongInt;
   freeram  :  LongInt;
   sharedram  :  LongInt;
   bufferram  :  LongInt;
   totalswap  :  LongInt;
   freeswap  :  LongInt;
   procs  :  Integer;
   s  :  string;
end



Record with system information, used by the SysInfo (1126   ) call.


TTermio  =  Termio


Alias for TermIO (1058   ) record


TTermios  =  Termios


Alias for Termios (1058   ) record.


TTimeVal  =  timeval


Alias for TimeVal (1059   ) record.


TTimeZone  =  timezone


Alias for TimeZone (1059   ) record.


TUTimeBuf  =  UTimeBuf



                                                                1060

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



Alias for UTimBuf (1061   ) record.


TUTSName  =  utsname


Alias for UTSName (1061   ) record.


TWinSize  =  winsize


Alias for WinSize (1061   ) record.


UTimBuf  =  packed  record
   actime  :  LongInt;
   modtime  :  LongInt;
end



Record used in Utime (1135   ) to set file access and modificaton times.


UTimeBuf  =  UTimBuf


Alias for UTimBuf (1061   ) record.


utsname  =  packed  record
   sysname  :  Array[0..64]  of  Char;
   nodename  :  Array[0..64]  of  Char;
   release  :  Array[0..64]  of  Char;
   version  :  Array[0..64]  of  Char;
   machine  :  Array[0..64]  of  Char;
   domainname  :  Array[0..64]  of  Char;
end



The  elements  of  this  record  are  null-terminated  C  style  strings,  you  cannot  access  them
directly.


winsize  =  packed  record
   ws_row  :  Word;
   ws_col  :  Word;
   ws_xpixel  :  Word;
   ws_ypixel  :  Word;
end



Record describing terminal window size.



31.11.3          Variables

ErrNo  :  LongInt


Error number of last operation.


LinuxError  :  LongInt



                                                                1061

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                Linuxerror is the variable in which the procedures in the linux unit report errors.


                tzdaylight  :  Boolean


                Indicates whether daylight savings time is active.


                tzname  :  Array[boolean]  of  pchar


                Timezone name.


                tzseconds  :  LongInt


                Seconds west of GMT



                31.12            Procedures  and  functions



                31.12.1          Access

    Synopsis:    Check file access

Declaration:     function  Access(Path:  PathStr;mode:  Integer)  :  Boolean

    Visibility:   default

Description:     Access tests user's access rights on the specified file.  Mode is a mask existing of one or more
                of the following:


                R__OK     User has read rights.

                W__OK      User has write rights.

                X__OK     User has execute rights.

                F__OK    File exists.


                The test is done with the real user ID, instead of the effective user ID. If access is denied, or
                an error occurred, False is returned.

       Errors:   LinuxError is used to report errors:


                sys__eaccess     The requested access is denied, either to the file or one of the directories in its
                       path.

                sys__einval    Mode was incorrect.

                sys__enoent      A directory component in Path doesn't exist or is a dangling symbolic link.

                sys__enotdir      A directory component in Path is not a directory.

                sys__enomem        Insufficient kernel memory.

                sys__eloop     Path has a circular symbolic link.


    See also:    Chown (1069   ), Chmod (1067   )


                Listing:  ./olinuxex/ex26.pp



                                                                                1062

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 6;


                {   Program       t o  d e m o n s t r a t et h e  A c c e s s f u n c t i o n.  }


                Uses     o l d l i n u x;


                 b e g i n
                    i f  A c c e s s (  '/ e t c/ p a s s w d',W_OK    )  then
                        b e g i n
                        W r i t e l n(  'B e t t e r c h e c k  y o u r s y s t e m. ') ;
                        W r i t e l n(  'I  c a n   w r i t e t o  t h e  / e t c/ p a s s w d f i l e  ! ') ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.2          Alarm

    Synopsis:    Schedule an alarm signal to be delivered

Declaration:     function  Alarm(Sec:  LongInt)  :  LongInt

    Visibility:   default

Description:     Alarm schedules an alarm signal to be delivered to your process in Sec seconds.  When Sec
                seconds have elapsed, Linux will send a SIGALRM signal to the current process.  If Sec is zero,
                then no new alarm will be set.  Whatever the value of  Sec, any previous alarm is cancelled.

                The function returns the number of seconds till the previously scheduled alarm was due to
                be delivered, or zero if there was none.

    See also:    SigAction (1120   )


                Listing:  ./olinuxex/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     o l d l i n u x;


                 P r o c e d u r eA l a r m H a n d l e(rS i g  :  l o n g i n t) ;c d e c l;


                 b e g i n
                    W r i t e l n ( 'Got    t o   a l a r m h a n d l e r') ;
                end   ;


                 b e g i n
                    W r i t e l n(' S e t t i n g a l a r m h a n d l e r') ;
                    S i g n a l(SIGALRM      ,@ A l a r m H a n d l e)r;
                    W r i t e l n ( ' S c h e d u l i n gAlarm     i n  1 0   s e c o n d s') ;
                    Alarm    ( 1 0 ) ;
                    W r i t e l n ( 'P a u s i n g' ) ;
                    P a u s e;
                    W r i t e l n ( 'P a u s e  r e t u r n e d') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1063

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.3          AssignPipe

    Synopsis:    Create a set of pipe file handlers

Declaration:     function  AssignPipe(var  pipe_in:  LongInt;var  pipe_out:  LongInt)
                                                 :  Boolean
                function  AssignPipe(var  pipe_in:  text;var  pipe_out:  text)  :  Boolean
                function  AssignPipe(var  pipe_in:  File;var  pipe_out:  File)  :  Boolean

    Visibility:   default

Description:     AssignePipe creates a pipe,  i.e.  two file objects,  one for input,  one for output.  What is
                written to Pipe_out, can be read from Pipe_in.

                This call is overloaded.  The in and out pipe can take three forms:  an typed or untyped file,
                a text file or a file descriptor.

                If a text file is passed then reading and writing from/to the pipe can be done through the
                usual Readln(Pipe_in,...)  and Writeln(Pipe_out,...)  procedures.

                The function returns True if everything went succesfully, False otherwise.

       Errors:   In case the function fails and returns False, LinuxError is used to report errors:


                sys__emfile     Too many file descriptors for this process.

                sys__enfile    The system file table is full.


    See also:    POpen (1113   ), MkFifo (1108   )


                Listing:  ./olinuxex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 6;


                {   Program       t o  d e m o n s t r a t et h e  A s s i g n P i p ef u n c t i o n.  }


                Uses     o l d l i n u x;


                Var     p i p i,p i p o  :  T e x t ;
                        s  :   S t r i n g;


                 b e g i n
                    W r i t e l n ( ' A s s i g n i n gP i p e s. ') ;
                    I f  Not    a s s i g n p i p e(p i p i,p i p o)   then
                        W r i t e l n('E r r o r  a s s i g n i n gp i p e s  ! ', L i n u x E r r o)r;
                    W r i t e l n ( ' W r i t i n gt o   p i p e,  and    f l u s h i n g.' ) ;
                    W r i t e l n ( p i p o, 'T h i s  i s  a   t e x t s t r i n'g) ;c l o s e( p i p o) ;
                    W r i t e l n ( 'R e a d i n g f r o m  p i p e. ' ) ;
                    While     not    e o f ( p i p i)  do
                        b e g i n
                       Readln       ( p i p i,s ) ;
                        W r i t e l n(  'Read     f r o m p i p e  :   ' ,s ) ;
                       end   ;
                    c l o s e ( p i p i) ;
                    w r i t e l n ( ' C l o s e d p i p e s.' ) ;
                    w r i t e l n
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1064

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.4          AssignStream

    Synopsis:    Assign stream for in and output to a program

Declaration:     function  AssignStream(var  StreamIn:  text;var  Streamout:  text;
                                                   const  Prog:  string)  :  LongInt
                function  AssignStream(var  StreamIn:  Text;var  StreamOut:  Text;
                                                   var  StreamErr:  Text;const  prog:  string)  :  LongInt

    Visibility:   default

Description:     AssignStream creates a 2 or 3 pipes, i.e.  two (or three) file objects, one for input, one for
                output,(and one for standard error) the other ends of these pipes are connected to standard
                input and output (and standard error) of  Prog.  Prog is the name of a program (including
                path) with options, which will be executed.

                What is written to StreamOut, will go to the standard input of  Prog.  Whatever is written
                by Prog to it's standard output can be read from StreamIn.  Whatever is written by Prog
                to it's standard error read from StreamErr, if present.

                Reading  and  writing  happens  through  the  usual  Readln(StreamIn,...)   and  Writeln
                (StreamOut,...)  procedures.

 Remark:         You should not  use Reset or Rewrite on a file opened with POpen.  This will close the file
                before re-opening it again, thereby closing the connection with the program.

                The function returns the process ID of the spawned process, or -1 in case of error.

       Errors:   In case of error (return value -1) LinuxError is used to report errors:


                sys__emfile     Too many file descriptors for this process.

                sys__enfile    The system file table is full.


                Other errors include the ones by the fork and exec programs

    See also:    AssignPipe (1064   ), POpen (1113   )


                Listing:  ./olinuxex/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     o l d l i n u x;


                Var     S i, So   :  T e x t ;
                       S   :   S t r i n g;
                        i  :   l o n g i n t;


                 b e g i n
                    i f  not    ( p a r a m s t r(1)=  '- s o n ' )  then
                        b e g i n
                        W r i t e l n(  'C a l l i n g s o n' ) ;
                        A s s i g n s t r e a m(S i ,So  , '. / e x 3 8-  s o n ') ;
                        i f  l i n u x e r r o<r>0   then
                           b e g i n
                           w r i t e l n ( 'A s s i g n S t r e a mf a i l e d ! ' ) ;
                           h a l t( 1 ) ;
                           end  ;
                        W r i t e l n(  'S p e a k i n g t o  s o n' ) ;
                       For     i: = 1  t o  1 0  do



                                                                                1065

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                           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___.____________________________________________________________________________________________________________*
 *___________



                31.12.5          Basename

    Synopsis:    Return basename of a file

Declaration:     function  Basename(const  path:  PathStr;const  suf:  PathStr)  :  PathStr

    Visibility:   default

Description:     Returns the filename part of  Path, stripping off  Suf if it exists.  The filename part is the
                whole  name  if  Path  contains  no  slash,  or  the  part  of  Path  after  the  last  slash.   The  last
                character of the result is not a slash, unless the directory is the root directory.

       Errors:   None.

    See also:    DirName (1073   ), FExpand (1087   )


                Listing:  ./olinuxex/ex48.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 8;


                {   Program       t o  d e m o n s t r a t et h e  BaseName        f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    S   :   S t r i n g;


                 b e g i n
                    S := FExpand     ( Paramstr      ( 0 ) ) ;



                                                                                1066

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                    W r i t e l n ( ' T h i s p r o g r a m i s   c a l l e d :  ' ,Basename      ( S , ' ') ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.6          CFMakeRaw

    Synopsis:    Sets flags in Termios (1058   ) record.

Declaration:     procedure  CFMakeRaw(var  tios:  Termios)

    Visibility:   default

Description:     CFMakeRaw sets the flags in the Termios structure Tios to a state so that the terminal will
                function in Raw Mode.

                For an example, see TCGetAttr (1131   ).

       Errors:   None.

    See also:    CFSetOSpeed (1067   ), CFSetISpeed (1067   )



                31.12.7          CFSetISpeed

    Synopsis:    Set input baud rate in Termios (1058   ) record

Declaration:     procedure  CFSetISpeed(var  tios:  Termios;speed:  Cardinal)

    Visibility:   default

Description:     CFSetISpeed Sets the input baudrate in the TermIOS structure Tios to Speed.

       Errors:   None.

    See also:    CFSetOSpeed (1067   ), CFMakeRaw (1067   )



                31.12.8          CFSetOSpeed

    Synopsis:    Set output baud rate in Termios (1058   ) record

Declaration:     procedure  CFSetOSpeed(var  tios:  Termios;speed:  Cardinal)

    Visibility:   default

Description:     CFSetOSpeed Sets the output baudrate in the Termios structure Tios to Speed.

       Errors:   None.

    See also:    CFSetISpeed (1067   ), CFMakeRaw (1067   )



                31.12.9          Chmod

    Synopsis:    Change file permission bits

Declaration:     function  Chmod(path:  PathStr;Newmode:  LongInt)  :  Boolean

    Visibility:   default

Description:     Chmod  Sets  the  Mode  bits  of  the  file  in  Path  to  NewMode.  Newmode  can  be  specified  by
                'or'-ing the following:



                                                                                1067

            ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'______________________*
 *_______________



            S__ISUID     Set user ID on execution.

            S__ISGID     Set Group ID on execution.

            S__ISVTX      Set sticky bit.

            S__IRUSR      Read by owner.

            S__IWUSR       Write by owner.

            S__IXUSR      Execute by owner.

            S__IRGRP       Read by group.

            S__IWGRP        Write by group.

            S__IXGRP       Execute by group.

            S__IROTH       Read by others.

            S__IWOTH        Write by others.

            S__IXOTH       Execute by others.

            S__IRWXO        Read, write, execute by others.

            S__IRWXG        Read, write, execute by groups.

            S__IRWXU        Read, write, execute by user.

   Errors:   Errors are returned in LinuxError.

            sys__eperm     The effective UID doesn't match the ownership of the file, and is not zero.  Owner
                  or group were not specified correctly.

            sys__eaccess     One of the directories in Path has no search (=execute) permission.

            sys__enoent     A  directory  entry  in  Path  does  not  exist  or  is  a  symbolic  link  pointing  to  a
                  non-existent directory.

            sys__enomem        Insufficient kernel memory.

            sys__erofs   The file is on a read-only filesystem.

            sys__eloop    Path  has  a  reference  to  a  circular  symbolic  link,  i.e.   a  symbolic  link,  whose
                  expansion points to itself.

See also:    Chown (1069   ), Access (1062   ), Octal (1111   )


            Listing:__./olinuxex/ex23.pp___________________________________________________________________________________________*
 *_______

            Program       E x a m p l e 2 3;


            {   Program       t o  d e m o n s t r a t et h e  Chmod      f u n c t i o n. }


            Uses     o l d l i n u x;


            Var    F   :  T e x t ;


             b e g i n
                {   C r e a t e a   f i l e }
                A s s i g n ( f , 't e s t e x 2 1') ;
                R e w r i t e (F  ) ;
                W r i t e l n ( f , '#!/  b i n/ s h ' ) ;
                W r i t e l n ( f , 'e c h o Some      t e x t f o r  t h i s  f i l e' ) ;
                C l o s e ( F ) ;
                {   O c t a l( ) makes      t h e  c o r r e c t number      f r o m  a
                   number       t h a t LOOKS      o c t a l }
                Chmod     (  't e s t e x 2 1', o c t a l ( 7 7 7 ) ) ;
                {   F i l e i s  now     e x e c u t a b l e }
                e x e c l (  '. / t e s t e x 2 1') ;
            end___.________________________________________________________________________________________________________________*
 *_______



                                                                            1068

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.10           Chown

    Synopsis:    Change owner of file

Declaration:     function  Chown(path:  PathStr;NewUid:  LongInt;NewGid:  LongInt)  :  Boolean

    Visibility:   default

Description:     Chown sets the User ID and Group ID of the file in Path to NewUid, NewGid The function
                returns True if the call was succesfull, False if the call failed.

       Errors:   Errors are returned in LinuxError.


                sys__eperm      The effective UID doesn't match the ownership of the file, and is not zero.  Owner
                       or group were not specified correctly.

                sys__eaccess     One of the directories in Path has no search (=execute) permission.

                sys__enoent      A  directory  entry  in  Path  does  not  exist  or  is  a  symbolic  link  pointing  to  a
                       non-existent directory.

                sys__enomem        Insufficient kernel memory.

                sys__erofs    The file is on a read-only filesystem.

                sys__eloop     Path  has  a  reference  to  a  circular  symbolic  link,  i.e.   a  symbolic  link,  whose
                       expansion points to itself.


    See also:    Chmod (1067   ), Access (1062   )


                Listing:  ./olinuxex/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     o l d l i n u x;


                Var    UID   ,GID     :  L o n g i n t;
                       F   :  T e x t ;


                 b e g i n


                    W r i t e l n ( ' T h i s w i l l  o n l y  work     i f you     a r e  r o o t. ') ;
                    Write     (  'E n t e r a   UID    :   ') ; r e a d l n(UID  ) ;
                    Write     (  'E n t e r a   GID    :   ') ; r e a d l n(GID  ) ;
                    A s s i g n ( f , 't e s t. t x t' ) ;
                    R e w r i t e ( f ) ;
                    W r i t e l n ( f , 'The    owner     o f   t h i s  f i l e s h o u l d become       :  ' ) ;
                    W r i t e l n ( f , 'UID    :   ', UID  ) ;
                    W r i t e l n ( f , 'GID    :   ', GID  ) ;
                    C l o s e ( F ) ;
                    i f  not    Chown      ( 't e s t. t x t' ,UID   ,GID   )  then
                        i f  L i n u x E r r o=rSys _EPERM       then
                           W r i t e l n ( 'You    a r e  n o t  r o o t  ! ' )
                        e l s e
                           W r i t e l n ( 'Chmod      f a i l e d w i t h  e x i t  c o d e :   ' ,L i n u x E r r o r)
                    e l s e
                        W r i t e l n(  'Changed       owner      s u c c e s s f u l l y!' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1069

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.11           Clone

    Synopsis:    Clone current process (create new thread)

Declaration:     function  Clone(func:  TCloneFunc;sp:  pointer;flags:  LongInt;
                                       args:  pointer)  :  LongInt

    Visibility:   default

Description:     Clone creates a child process which is a copy of the parent process,  just like Fork (1088   )
                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:    Fork (1088   )


                Listing:  ./olinuxex/ex71.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       TestC    { l o n e} ;


                 u s e s
                    o l d l i n u x,  E r r o r s,  c r t;


                 c o n s t
                    Ready      :  B o o l e a n=    f a l s e;
                    a C h a r  :  Char          =   'a ' ;


                 f u n c t i o nC l o n e P r o c( Arg   :  P o i n t e r ) :  L o n g I n t;  C d e c l;
                 b e g i n
                    WriteLn     ( ' H e l l o f r o m  t h e  c l o n e  ', PChar    (Arg   ) ) ;
                    r e p e a t



                                                                                1070

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



       Write    ( a C h a r) ;
        S e l e c t( 0 ,N i l,N i l ,N i l ,N i l ) ;
    u n t i l Ready    ;
    WriteLn     (   'C l o n e  f i n i s h e d.' ) ;
    C l o n e P r o c: =  1 ;
end   ;


 v a r
    PID    :   L o n g I n t;


 p r o c e d u r eMainProc      ;
 b e g i n
    WriteLn     ( ' c l o n e d p r o c e s s PID  :   ' ,  PID    ) ;
    WriteLn     ( ' P r e s s<  ESC  >   t o  k i l l  . . .  '  ) ;
    r e p e a t
       Write    ( ' . ') ;
        S e l e c t( 0 ,N i l,N i l ,N i l ,N i l ) ;
        i f  KeyPressed         then
           c a s e  ReadKey       o f
              # 2 7 :  Ready     : =   t r u e;
               'a ' :  a C h a r : =   'A  ';
               'A ' :  a C h a r : =   ' a ';
               'b ' :  a C h a r : =   'b  ';
               'B ' :  a C h a r : =   'B  ';
           end  ;
    u n t i l Ready    ;
    WriteLn     ( ' Ready    . ') ;
end   ;


 c o n s t
    S t a c k S z e=  1 6 3 8 4 ;
    t h e F l a g s=   CLONE_VM      + CLONE_FS     + CLONE _FILES       + CLONE_SIGHAND          ;
    aMsg            :  PChar     =   ' Oops     ! ';


 v a r
    t h e S t a c k :  P o i n t e r;
    E x i t S t a t :  L o n g I n t;


 b e g i n
    GetMem    ( t h e S t a c k,S t a c k S z e) ;
    PID    : =  C l o n e( @ C l o n e P r o,c
                           P o i n t e r( L o n g I n t(t h e S t a c k)+ S t a c k S z e) ,
                           t h e F l a g s,
                          aMsg    ) ;
    i f  PID    <  0   then
       WriteLn      ( 'E r r o r  :  ' ,  L i n u x E r r o r,  '  when     c l o n i n g.')
    e l s e
        b e g i n
       MainProc       ;
        c a s e WaitPID      ( 0 ,@ E x i t S t a t,W a i t _U n t r a c e do r  w a i t _c l o n e)  o f
           -1:    WriteLn     ( ' e r r o r:' , L i n u x E r r o,r' ;  ' , S t r E r r o(rL i n u x E r r o r) ) ;
             0 :  WriteLn     ( ' e r r o r:' , L i n u x E r r o,r' ;  ' , S t r E r r o(rL i n u x E r r o r) ) ;
        e l s e
           WriteLn     ( ' C l o n e e x i t e d w i t h :  ' ,E x i t S t a t s h r  8 ) ;
       end   ;
       end   ;
    FreeMem     (   t h e S t a c k, S t a c k S z e ) ;
end___._______________________________________________________________________________________________________________________



                                                                1071

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.12           CloseDir

    Synopsis:    Close directory file descriptor

Declaration:     function  CloseDir(p:  PDir)  :  Integer

    Visibility:   default

Description:     CloseDir closes the directory pointed to by p.  It returns zero if the directory was closed
                succesfully, -1 otherwise.

                For an example, see OpenDir (1112   ).

       Errors:   Errors are returned in LinuxError.

    See also:    OpenDir (1112   ), ReadDir (1114   ), SeekDir (1116   ), TellDir (1133   )



                31.12.13           CreateShellArgV

    Synopsis:    Create an array of null-terminated strings

Declaration:     function  CreateShellArgV(const  prog:  string)  :  ppchar
                function  CreateShellArgV(const  prog:  Ansistring)  :  ppchar

    Visibility:   default

Description:     CreateShellArgV creates an array of 3 PChar pointers that can be used as arguments to
                ExecVE the first elements in the array will contain /bin/sh, the second will contain -c, and
                the third will contain prog.

                The function returns a pointer to this array, of type PPChar.

       Errors:   None.

    See also:    Shell (1120   )


                Listing:  ./olinuxex/ex61.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x 6 1 ;


                {   Example       p r o g r a m t o  d e m o n s t r a t et h e  C r e a t e S h e l l A r g Vf u n c t i o n}


                 u s e s o l d l i n u x;


                Var
                    S :  S t r i n g;
                    PP   :   PPchar    ;
                      I  :   l o n g i n t;


                 b e g i n
                    S :=  's c r i p t-  a  - b  - c  - d  -  e   f g h i j k';
                    PP :=  C r e a t e S h e l l A r g(VS) ;
                    I : = 0 ;
                    I f  PP <>  N i l  then
                       While      PP  [i ]<>  N i l  do
                           b e g i n
                           W r i t e l n ( 'Got    :  "  ' ,PP  [ i] , '" ' ) ;
                           I n c( i ) ;
                           end  ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1072

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.14           Dirname

    Synopsis:    Extract directory part from filename

Declaration:     function  Dirname(const  path:  PathStr)  :  PathStr

    Visibility:   default

Description:     Returns the directory part of  Path.  The directory is the part of  Path before the last slash,
                or  empty  if  there  is  no  slash.   The  last  character  of  the  result  is  not  a  slash,  unless  the
                directory is the root directory.

       Errors:   None.

    See also:    BaseName (1066   ), FExpand (1087   )


                Listing:  ./olinuxex/ex47.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 7;


                {   Program       t o  d e m o n s t r a t et h e  DirName       f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    S   :   S t r i n g;


                 b e g i n
                    S := FExpand     ( Paramstr      ( 0 ) ) ;
                    W r i t e l n ( ' T h i s p r o g r a m i s  i n   d i r e c t o r y:   ' ,Dirname     ( S ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.15           Dup

    Synopsis:    Duplicate a file handle

Declaration:     function  Dup(oldfile:  LongInt;var  newfile:  LongInt)  :  Boolean
                function  Dup(var  oldfile:  text;var  newfile:  text)  :  Boolean
                function  Dup(var  oldfile:  File;var  newfile:  File)  :  Boolean

    Visibility:   default

Description:     Makes  NewFile  an  exact  copy  of  OldFile,  after  having  flushed  the  buffer  of  OldFile  in
                case it is a Text file or untyped file.  Due to the buffering mechanism of Pascal, this has not
                the  same  functionality  as  the  dup  call  in  C.  The  internal  Pascal  buffers  are  not  the  same
                after  this  call,  but  when  the  buffers  are  flushed  (e.g.  after  output),  the  output  is  sent  to
                the same file.  Doing an lseek will, however, work as in C, i.e.  doing a lseek will change the
                fileposition in both files.

                The function returns False in case of an error, True if successful.

       Errors:   In case of errors, Linuxerror is used to report errors.


                sys__ebadf     OldFile hasn't been assigned.

                sys__emfile     Maximum number of open files for the process is reached.


    See also:    Dup2 (1074   )


                Listing:  ./olinuxex/ex31.pp



                                                                                1073

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 1;


                {   Program       t o  d e m o n s t r a t et h e  Dup    f u n c t i o n. }


                 u s e s o l d l i n u x;


                 v a r  f  :   t e x t;


                 b e g i n
                    i f  not    dup    ( o u t p u t,f )  then
                        W r i t e l n(  'Dup    F a i l e d ! ' ) ;
                    w r i t e l n ( ' T h i s i s   w r i t t e nt o   s t d o u t.' ) ;
                    w r i t e l n ( f , 'T h i s  i s  w r i t t e n t o  t h e  dup    f i l e,  and     f l u s h e d') ;f l u s *
 *h(f ) ;
                    w r i t e l n
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.16           Dup2

    Synopsis:    Duplicate one filehandle to another

Declaration:     function  Dup2(oldfile:  LongInt;newfile:  LongInt)  :  Boolean
                function  Dup2(var  oldfile:  text;var  newfile:  text)  :  Boolean
                function  Dup2(var  oldfile:  File;var  newfile:  File)  :  Boolean

    Visibility:   default

Description:     Makes NewFile an exact copy of OldFile, after having flushed the buffer of OldFile in the
                case of text or untyped files.

                NewFile can be an assigned file.  If newfile was open, it is closed first.  Due to the buffering
                mechanism of Pascal, this has not the same functionality as the dup2 call in C. The internal
                Pascal buffers are not the same after this call, but when the buffers are flushed (e.g.  after
                output), the output is sent to the same file.  Doing an lseek will, however, work as in C, i.e.
                doing a lseek will change the fileposition in both files.

                The function returns True if succesful, false otherwise.

       Errors:   In case of error, Linuxerror is used to report errors.


                sys__ebadf     OldFile hasn't been assigned.

                sys__emfile     Maximum number of open files for the process is reached.


    See also:    Dup (1073   )


                Listing:  ./olinuxex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 1;


                {   Program       t o  d e m o n s t r a t et h e  Dup    f u n c t i o n. }


                 u s e s o l d l i n u x;


                 v a r  f  :   t e x t;
                        i  :   l o n g i n t;


                 b e g i n
                    A s s i g n ( f , 't e x t. t x t' ) ;



                                                                                1074

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                    R e w r i t e (F  ) ;
                    For    i : = 1  t o  1 0  do    w r i t e l n( F , 'L i n e  :   ' ,i ) ;
                    i f  not    dup2     ( o u t p u t,f )  then
                        W r i t e l n(  'Dup2     F a i l e d ! ' ) ;
                    w r i t e l n ( ' T h i s i s   w r i t t e nt o   s t d o u t.' ) ;
                    w r i t e l n ( f , 'T h i s  i s  w r i t t e n t o  t h e  dup    f i l e,  and     f l u s h e d') ;
                    f l u s h( f) ;
                    w r i t e l n;
                    {  Remove       f i l e.  Comment       t h i s  i f  you    want     t o  c h e c k  f l u s h i n g.}
                    U n l i n k ( ' t e x t. t x t' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.17           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:    GetEpochTime (1095   ), LocalToEpoch (1105   ), GetTime (1100   ), GetDate (1093   )


                Listing:  ./olinuxex/ex3.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example3       ;


                {   Program       t o  d e m o n s t r a t et h e  E p o c h T o L o c a lf u n c t i o n. }


                Uses     o l d l i n u x;


                Var    Year    ,month    , day  , h o u r,m i n u t e, s e c o n d s :  Word   ;


                 b e g i n
                    E p o c h T o L o c a l(GetEpochTime          ,Year   , month    ,day   ,h o u r, m i n u t e,s e c o n d s) ;
                    W r i t e l n ( ' C u r r e n td a t e  :   ' ,Day  : 2 , '/ ' ,Month    : 2 , '/ ' ,Y e a r : 4 ) ;
                    W r i t e l n ( ' C u r r e n tt i m e  :   ' ,Hour   : 2 , ': ' ,m i n u t e: 2 ,' : ' ,s e c o n d s: 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.18           Execl

    Synopsis:    Execute process (using argument list)

Declaration:     procedure  Execl(const  Todo:  string)
                procedure  Execl(const  Todo:  Ansistring)

    Visibility:   default



                                                                                1075

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



Description:     Replaces the currently running program with the program, specified in path.  Path is split
                into a command and it's options.  The executable in path is NOT searched in the path.  The
                current environment is passed to the program.  On success, execl does not return.

       Errors:   Errors are reported in LinuxError:


                sys__eacces    File is not a regular file,  or has no execute permission.  A compononent of the
                      path has no search permission.

                sys__eperm     The file system is mounted noexec.

                sys__e2big    Argument list too big.

                sys__enoexec      The magic number in the file is incorrect.

                sys__enoent     The file does not exist.

                sys__enomem        Not enough memory for kernel, or to split command line.

                sys__enotdir     A component of the path is not a directory.

                sys__eloop    The path contains a circular reference (via symlinks).


    See also:    Execve (1079   ), Execv (1078   ), Execvp (1080   ), Execle (1076   ), Execlp (1077   ), Fork (1088   )


                Listing:  ./olinuxex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;


                {   Program       t o  d e m o n s t r a t et h e  E x e c l  f u n c t i o n. }


                Uses     o l d l i n u x,  s t r i n g s;


                 b e g i n
                    {   E x e c u t e 'l s  - l ' ,  w i t h  c u r r e n t e n v i r o n m e n.t }
                    {   'l s '  i s  NOT     l o o k e d f o r  i n PATH      e n v i r o n m e n tv a r i a b l e.}
                    E x e c l (  '/ b i n/ l s -  l ') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.19           Execle

    Synopsis:    Execute process (using argument list, environment)

Declaration:     procedure  Execle(Todo:  string;Ep:  ppchar)
                procedure  Execle(Todo:  AnsiString;Ep:  ppchar)

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  Path is split
                into a command and it's options.  The executable in path is searched in the path, if it isn't
                an absolute filename.  The environment in ep is passed to the program.  On success, execle
                does not return.

       Errors:   Errors are reported in LinuxError:


                sys__eacces     File is not a regular file,  or has no execute permission.  A compononent of the
                       path has no search permission.

                sys__eperm      The file system is mounted noexec.

                sys__e2big     Argument list too big.

                sys__enoexec       The magic number in the file is incorrect.



                                                                                1076

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                sys__enoent     The file does not exist.

                sys__enomem        Not enough memory for kernel, or to split command line.

                sys__enotdir     A component of the path is not a directory.

                sys__eloop    The path contains a circular reference (via symlinks).


    See also:    Execve (1079   ), Execv (1078   ), Execvp (1080   ), Execl (1075   ), Execlp (1077   ), Fork (1088   )


                Listing:  ./olinuxex/ex11.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 1;


                {   Program       t o  d e m o n s t r a t et h e  E x e c l e f u n c t i o n.  }


                Uses     o l d l i n u x,  s t r i n g s;


                 b e g i n
                    {   E x e c u t e 'l s  - l ' ,  w i t h  c u r r e n t e n v i r o n m e n.t }
                    {   '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___.____________________________________________________________________________________________________________*
 *___________



                31.12.20           Execlp

    Synopsis:    Execute process (using argument list, environment; search path)

Declaration:     procedure  Execlp(Todo:  string;Ep:  ppchar)
                procedure  Execlp(Todo:  Ansistring;Ep:  ppchar)

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  Path is split
                into a command and it's options.  The executable in path is searched in the path, if it isn't an
                absolute filename.  The current environment is passed to the program.  On success, execlp
                does not return.

       Errors:   Errors are reported in LinuxError:


                sys__eacces     File is not a regular file,  or has no execute permission.  A compononent of the
                       path has no search permission.

                sys__eperm      The file system is mounted noexec.

                sys__e2big     Argument list too big.

                sys__enoexec       The magic number in the file is incorrect.

                sys__enoent      The file does not exist.

                sys__enomem        Not enough memory for kernel, or to split command line.

                sys__enotdir      A component of the path is not a directory.

                sys__eloop     The path contains a circular reference (via symlinks).


    See also:    Execve (1079   ), Execv (1078   ), Execvp (1080   ), Execle (1076   ), Execl (1075   ), Fork (1088   )


                Listing:  ./olinuxex/ex12.pp



                                                                                1077

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 2;


                {   Program       t o  d e m o n s t r a t et h e  E x e c l p f u n c t i o n.  }


                Uses     o l d l i n u x,  s t r i n g s;


                 b e g i n
                    {   E x e c u t e 'l s  - l ' ,  w i t h  c u r r e n t e n v i r o n m e n.t }
                    {   'l s '  i s   l o o k e d f o r  i n PATH      e n v i r o n m e n tv a r i a b l e.}
                    {  e n v p  i s   d e f i n e d i n  t h e  s y s t e m u n i t.}
                    E x e c l p ( ' l s -  l ' ,e n v p) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.21           Execv

    Synopsis:    Execute process

Declaration:     procedure  Execv(const  path:  PathStr;args:  ppchar)
                procedure  Execv(const  path:  AnsiString;args:  ppchar)

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  It gives the
                program the options in args.  This is a pointer to an array of pointers to null-terminated
                strings.  The last pointer in this array should be nil.  The current environment is passed to
                the program.  On success, execv does not return.

       Errors:   Errors are reported in LinuxError:


                sys__eacces     File is not a regular file,  or has no execute permission.  A compononent of the
                       path has no search permission.

                sys__eperm      The file system is mounted noexec.

                sys__e2big     Argument list too big.

                sys__enoexec       The magic number in the file is incorrect.

                sys__enoent      The file does not exist.

                sys__enomem        Not enough memory for kernel.

                sys__enotdir      A component of the path is not a directory.

                sys__eloop     The path contains a circular reference (via symlinks).


    See also:    Execve (1079   ), Execvp (1080   ), Execle (1076   ), Execl (1075   ), Execlp (1077   ), Fork (1088   )


                Listing:  ./olinuxex/ex8.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example8       ;


                {   Program       t o  d e m o n s t r a t et h e  E x e c v  f u n c t i o n. }


                Uses     o l d l i n u x,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' / b i n/ l s' ;
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                                                                                1078

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    PP  [ 0 ] : =Arg0  ;
                    PP  [ 1 ] : =Arg1  ;
                    PP  [ 3 ] : =N i l;
                    {   E x e c u t e ' /b i n/ l s -  l ' ,  w i t h  c u r r e n t e n v i r o n m e n t}
                    E x e c v (  '/ b i n/ l s ', pp ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.22           Execve

    Synopsis:    Execute process using environment

Declaration:     procedure  Execve(Path:  PathStr;args:  ppchar;ep:  ppchar)
                procedure  Execve(Path:  AnsiString;args:  ppchar;ep:  ppchar)
                procedure  Execve(path:  pchar;args:  ppchar;ep:  ppchar)

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  It gives the
                program the options in args, and the environment in ep.  They are pointers to an array of
                pointers to null-terminated strings.  The last pointer in this array should be nil.  On success,
                execve does not return.

       Errors:   Errors are reported in LinuxError:


                sys__eacces     File is not a regular file,  or has no execute permission.  A compononent of the
                       path has no search permission.

                sys__eperm      The file system is mounted noexec.

                sys__e2big     Argument list too big.

                sys__enoexec       The magic number in the file is incorrect.

                sys__enoent      The file does not exist.

                sys__enomem        Not enough memory for kernel.

                sys__enotdir      A component of the path is not a directory.

                sys__eloop     The path contains a circular reference (via symlinks).


    See also:    Execve (1079   ),  Execv (1078   ),  Execvp (1080   ),  Execle (1076   ),  Execl (1075   ),  Execlp (1077   ),
                Fork (1088   )


                Listing:  ./olinuxex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;


                {   Program       t o  d e m o n s t r a t et h e  E x e c v e f u n c t i o n.  }


                Uses     o l d l i n u x,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' / b i n/ l s' ;
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                                                                                1079

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                 b e g i n
                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    PP  [ 0 ] : =Arg0  ;
                    PP  [ 1 ] : =Arg1  ;
                    PP  [ 3 ] : =N i l;
                    {   E x e c u t e ' /b i n/ l s -  l ' ,  w i t h  c u r r e n t e n v i r o n m e n t}
                    {  Envp     i s   d e f i n e d i n  s y s t e m.i n c  }
                    ExecVe      ( ' / b i n/ l s' ,pp  , e n v p) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.23           Execvp

    Synopsis:    Execute process, search path

Declaration:     procedure  Execvp(Path:  PathStr;Args:  ppchar;Ep:  ppchar)
                procedure  Execvp(Path:  AnsiString;Args:  ppchar;Ep:  ppchar)

    Visibility:   default

Description:     Replaces the currently running program with the program, specified in path.  The executable
                in  path  is  searched  in  the  path,  if  it  isn't  an  absolute  filename.  It  gives  the  program  the
                options in args.  This is a pointer to an array of pointers to null-terminated strings.  The
                last pointer in this array should be nil.  The current environment is passed to the program.
                On success, execvp does not return.

       Errors:   Errors are reported in LinuxError:


                sys__eacces     File is not a regular file,  or has no execute permission.  A compononent of the
                       path has no search permission.

                sys__eperm      The file system is mounted noexec.

                sys__e2big     Argument list too big.

                sys__enoexec       The magic number in the file is incorrect.

                sys__enoent      The file does not exist.

                sys__enomem        Not enough memory for kernel.

                sys__enotdir      A component of the path is not a directory.

                sys__eloop     The path contains a circular reference (via symlinks).


    See also:    Execve (1079   ), Execv (1078   ), Execle (1076   ), Execl (1075   ), Execlp (1077   ), Fork (1088   )


                Listing:  ./olinuxex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;


                {   Program       t o  d e m o n s t r a t et h e  E x e c v p f u n c t i o n.  }


                Uses     o l d l i n u x,  s t r i n g s;


                Const      Arg0     :  PChar     =   ' l s ';
                           Arg1     :  P c h a r =   '-  l ';


                Var    PP    :  PPchar     ;



                 b e g i n



                                                                                1080

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                    GetMem      ( PP  , 3 *S i z e O f(P c h a r) ) ;
                    PP  [ 0 ] : =Arg0  ;
                    PP  [ 1 ] : =Arg1  ;
                    PP  [ 3 ] : =N i l;
                    {   E x e c u t e 'l s  - l ' ,  w i t h  c u r r e n t e n v i r o n m e n.t }
                    {   'l s '  i s   l o o k e d f o r  i n PATH      e n v i r o n m e n tv a r i a b l e.}
                    {  Envp     i s   d e f i n e d i n  t h e  s y s t e m u n i t.  }
                    E x e c v p ( ' l s ', pp , e n v p) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.24           ExitProcess

    Synopsis:    Exit the current process

Declaration:     procedure  ExitProcess(val:  LongInt)

    Visibility:   default

Description:     ExitProcess exits the currently running process, and report Val as the exit status.

 Remark:         If this call is executed,  the normal unit finalization code will not be executed.  This may
                lead to unexpected errors and stray files on your system.  It is therefore recommended to use
                the Halt call instead.

       Errors:   None.

    See also:    Fork (1088   ), ExecVE (1079   )



                31.12.25           Fcntl

    Synopsis:    File control operations.

Declaration:     function  Fcntl(Fd:  LongInt;Cmd:  LongInt)  :  LongInt
                procedure  Fcntl(Fd:  LongInt;Cmd:  LongInt;Arg:  LongInt)
                function  Fcntl(var  Fd:  Text;Cmd:  LongInt)  :  LongInt
                procedure  Fcntl(var  Fd:  Text;Cmd:  LongInt;Arg:  LongInt)

    Visibility:   default

Description:     Read a file's attributes.  Fd is an assigned file, or a valid file descriptor.  Cmd speciefies what
                to do, and is one of the following:


                F__GetFd      Read the close_on_exec flag.  If the low-order bit is 0, then the file will remain open
                       across execve calls.

                F__GetFl     Read the descriptor's flags.

                F__GetOwn        Get the Process ID of the owner of a socket.

                F__SetFd     Set the close_on_exec flag of  Fd.  (only the least siginificant bit is used).

                F__GetLk      Return the flock record that prevents this process from obtaining the lock, or set
                       the l_type field of the lock of there is no obstruction.  Arg is a pointer to a flock record.

                F__SetLk     Set the lock or clear it (depending on l_type in the flock structure).  if the lock is
                       held by another process, an error occurs.

                F__GetLkw       Same as for F__Setlk, but wait until the lock is released.

                F__SetOwn       Set the Process or process group that owns a socket.


       Errors:   LinuxError is used to report errors.



                                                                                1081

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                sys__ebadf    Fd has a bad file descriptor.

                sys__eagain or sys__eaccess           For F__SetLk, if the lock is held by another process.



                31.12.26           fdClose

    Synopsis:    Close file descriptor

Declaration:     function  fdClose(fd:  LongInt)  :  Boolean

    Visibility:   default

Description:     fdClose closes a file with file descriptor Fd.  The function returns True if the file was closed
                successfully, False otherwise.

                For an example, see fdOpen (1082   ).

       Errors:   Errors are returned in LinuxError.

    See also:    fdOpen (1082   ), fdRead (1083   ), fdWrite (1085   ), fdTruncate (1085   ), fdFlush (1082   ), fdSeek
                (1085   )



                31.12.27           fdFlush

    Synopsis:    Flush kernel file buffer

Declaration:     function  fdFlush(fd:  LongInt)  :  Boolean

    Visibility:   default

Description:     fdflush flushes the Linux kernel file buffer, so the file is actually written to disk.  This is
                NOT the same as the internal buffer, maintained by Free Pascal.  The function returns True
                if the call was successful, false if an error occurred.

                For an example, see fdRead (1083   ).

       Errors:   Errors are returned in LinuxError.

    See also:    fdOpen (1082   ),  fdClose (1082   ),  fdRead (1083   ),  fdWrite (1085   ),  fdTruncate (1085   ),  fdSeek
                (1085   )



                31.12.28           fdOpen

    Synopsis:    Open file and return file descriptor

Declaration:     function  fdOpen(pathname:  string;flags:  LongInt)  :  LongInt
                function  fdOpen(pathname:  string;flags:  LongInt;mode:  LongInt)  :  LongInt
                function  fdOpen(pathname:  pchar;flags:  LongInt)  :  LongInt
                function  fdOpen(pathname:  pchar;flags:  LongInt;mode:  LongInt)  :  LongInt

    Visibility:   default

Description:     fdOpen opens a file in PathName with flags flags One of the following:


                Open__RdOnly          File is opened Read-only

                Open__WrOnly           File is opened Write-only

                Open__RdWr          File is opened Read-Write


                The flags may beOR-ed with one of the following constants:



                                                                                1082

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                Open__Creat       File is created if it doesn't exist.

                Open__Excl      If the file is opened with Open_Creat and it already exists, the call wil fail.

                Open__NoCtty         If the file is a terminal device, it will NOT become the process' controlling
                      terminal.

                Open__Trunc        If the file exists, it will be truncated.

                Open__Append          the  file  is  opened  in  append  mode.   Before  each  write,  the  file  pointer  is
                      positioned at the end of the file.

                Open__NonBlock           The file is opened in non-blocking mode.  No operation on the file descrip-
                      tor will cause the calling process to wait till.

                Open__NDelay         Idem as Open_NonBlock

                Open__Sync       The file is opened for synchronous IO. Any write operation on the file will not
                      return untill the data is physically written to disk.

                Open__NoFollow          if the file is a symbolic link, the open fails.  (linux 2.1.126 and higher only)

                Open__Directory         if the file is not a directory, the open fails.  (linux 2.1.126 and higher only)


                PathName can be of type PChar or String.  The optional mode argument specifies the per-
                missions  to  set  when  opening  the  file.   This  is  modified  by  the  umask  setting.   The  real
                permissions are Mode  and  not  umask.  The return value of the function is the filedescriptor,
                or a negative value if there was an error.

       Errors:   Errors are returned in LinuxError.

    See also:    fdClose (1082   ), fdRead (1083   ), fdWrite (1085   ), fdTruncate (1085   ), fdFlush (1082   ), fdSeek
                (1085   )


                Listing:  ./olinuxex/ex19.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 9;


                {   Program       t o  d e m o n s t r a t et h e  fdOpen     ,  f d w r i t e and    f d C L o s e f u n c t i o n*
 * s. }


                Uses     o l d l i n u x;


                Const      L i n e  :  S t r i n g[ 8 0 ]  =  ' T h i s  i s  e a s y w r i t i n g ! ' ;


                Var    FD    :  L o n g i n t;


                 b e g i n
                    FD :=  fdOpen      ( ' T e s t.d a t ' ,Open _WrOnly         o r  O p e n _C r e a t) ;
                    i f  FD  >0   then
                        b e g i n
                        i f  l e n g t h(L i n e)<>  f d w r i t e (FD  , L i n e[ 1 ] ,Length    ( L i n e) )  then
                           W r i t e l n ( ' E r r o r when     w r i t i n g t o  f i l e !  ') ;
                        f d C l o s e(FD ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.29           fdRead

    Synopsis:    Read data from file descriptor

Declaration:     function  fdRead(fd:  LongInt;var  buf;size:  LongInt)  :  LongInt



                                                                                1083

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



    Visibility:  default

Description:     fdRead reads at most size bytes from the file descriptor fd, and stores them in buf.  The
                function returns the number of bytes actually read, or -1 if an error occurred.  No checking
                on the length of  buf is done.

       Errors:   Errors are returned in LinuxError.

    See also:    fdOpen (1082   ), fdClose (1082   ), fdWrite (1085   ), fdTruncate (1085   ), fdFlush (1082   ), fdSeek
                (1085   )


                Listing:__./olinuxex/ex20.pp_______________________________________________________________________________________*
 *___________

                Program       E x a m p l e 2 0;


                {   Program       t o  d e m o n s t r a t et h e  f d R e a d and    f d T r u n c a t e f u n c t i o n.s }


                Uses     o l d l i n u x;


                Const      Data     :  s t r i n g[ 1 0 ]  =  ' 1 2 3 4 5 6 8 7 8 9'0;


                Var    FD    :  L o n g i n t;
                        l  :   l o n g i n t;


                 b e g i n
                    FD :=  fdOpen    (  't e s t. d a t' ,o p e n _w r o n l y o r   o p e n _c r e a t,o c t a l( 6 6 6 ) ) ;
                    i f  f d >0   then
                        b e g i n
                       {   F i l l  f i l e w i t h  d a t a  }
                        f o r  l: = 1  t o  1 0  do
                           i f  f d W r i t e ( FD  ,Data   [ 1 ] , 1 0 ) < > 1 0then
                              b e g i n
                               w r i t e l n(  'E r r o r when     w r i t i n g ! ' ) ;
                               h a l t( 1 ) ;
                              end   ;
                        f d C l o s e(FD ) ;
                       FD  := fdOpen     ( ' t e s t.d a t ', o p e n _r d o n l y) ;
                       {   Read     d a t a  a g a i n }
                        I f FD  >0   then
                           b e g i n
                           For    l : = 1  t o  5  do
                               i f  f d R e a d (FD  , Data   [ 1 ] , 1 0 ) < > 1 0then
                                  b e g i n
                                  W r i t e l n ( ' E r r o r when     R e a d i n g ! ') ;
                                  H a l t( 2 ) ;
                                  end  ;
                           f d C L o s e(FD  ) ;
                           {   T r u n c a t i n gf i l e a t  6 0   b y t e s }
                           {  F o r   t r u n c a t i n,g  f i l e must     be   open     o r  w r i t e }
                           FD :=  fdOpen    (  't e s t. d a t' ,o p e n _w r o n l y,o c t a l( 6 6 6 ) ) ;
                           i f  FD  >0   then
                              b e g i n
                               i f  not    f d T r u n c a t(eFD  , 6 0 ) then
                                    W r i t e l n(' E r r o r when     t r u n c a t i n g! ') ;
                               f d C l o s e( FD  ) ;
                              end   ;
                           end  ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1084

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.30           fdSeek

    Synopsis:    Set file pointer position.

Declaration:     function  fdSeek(fd:  LongInt;pos:  LongInt;seektype:  LongInt)  :  LongInt

    Visibility:   default

Description:     fdSeek sets the current fileposition of file fd to Pos, starting from SeekType, which can be
                one of the following:


                Seek__Set     Pos is the absolute position in the file.

                Seek__Cur      Pos is relative to the current position.

                Seek__end     Pos is relative to the end of the file.


                The function returns the new fileposition, or -1 of an error occurred.

                For an example, see fdOpen (1082   ).

       Errors:   Errors are returned in LinuxError.

    See also:    fdOpen (1082   ), fdWrite (1085   ), fdClose (1082   ), fdRead (1083   ), fdTruncate (1085   ), fdFlush
                (1082   )



                31.12.31           fdTruncate

    Synopsis:    Truncate file on certain size.

Declaration:     function  fdTruncate(fd:  LongInt;size:  LongInt)  :  Boolean

    Visibility:   default

Description:     fdTruncate  sets  the  length  of  a  file  in  fd  on  size  bytes,  where  size  must  be  less  than
                or  equal  to  the  current  length  of  the  file  in  fd.  The  function  returns  True  if  the  call  was
                successful, false if an error occurred.

       Errors:   Errors are returned in LinuxError.

    See also:    fdOpen (1082   ), fdClose (1082   ), fdRead (1083   ), fdWrite (1085   ), fdFlush (1082   ), fdSeek (1085   )



                31.12.32           fdWrite

    Synopsis:    Write data to file descriptor

Declaration:     function  fdWrite(fd:  LongInt;const  buf;size:  LongInt)  :  LongInt

    Visibility:   default

Description:     fdWrite writes at most size bytes from buf to file descriptor fd.  The function returns the
                number of bytes actually written, or -1 if an error occurred.

       Errors:   Errors are returned in LinuxError.

    See also:    fdOpen (1082   ),  fdClose (1082   ),  fdRead (1083   ),  fdTruncate (1085   ),  fdSeek (1085   ),  fdFlush
                (1082   )



                                                                                1085

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.33           FD__Clr

    Synopsis:    Clears a filedescriptor in a set

Declaration:     procedure  FD_Clr(fd:  LongInt;var  fds:  fdSet)

    Visibility:   default

Description:     FD_Clr clears file descriptor fd in filedescriptor set fds.

                For an example, see Select (1116   ).

       Errors:   None.

    See also:    Select (1116   ), SelectText (1118   ), GetFS (1096   ), FD_ZERO (1086   ), FD_Set (1086   ), FD_IsSet
                (1086   )



                31.12.34           FD__IsSet

    Synopsis:    Check whether a filedescriptor is set

Declaration:     function  FD_IsSet(fd:  LongInt;var  fds:  fdSet)  :  Boolean

    Visibility:   default

Description:     FD_Set Checks whether file descriptor fd in filedescriptor set fds is set.

                For an example, see Select (1116   ).

       Errors:   None.

    See also:    Select (1116   ), SelectText (1118   ), GetFS (1096   ), FD_ZERO (1086   ), FD_Clr (1086   ), FD_Set
                (1086   )



                31.12.35           FD__Set

    Synopsis:    Set a filedescriptor in a set

Declaration:     procedure  FD_Set(fd:  LongInt;var  fds:  fdSet)

    Visibility:   default

Description:     FD_Set sets file descriptor fd in filedescriptor set fds.

                For an example, see Select (1116   ).

       Errors:   None.

    See also:    Select (1116   ), SelectText (1118   ), GetFS (1096   ), FD_ZERO (1086   ), FD_Clr (1086   ), FD_IsSet
                (1086   )



                31.12.36           FD__Zero

    Synopsis:    Clear all file descriptors in set

Declaration:     procedure  FD_Zero(var  fds:  fdSet)

    Visibility:   default

Description:     FD_ZERO clears all the filedescriptors in the file descriptor set fds.

                For an example, see Select (1116   ).



                                                                                1086

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



       Errors:   None.

    See also:    Select  (1116   ),  SelectText  (1118   ),  GetFS  (1096   ),  FD_Clr  (1086   ),  FD_Set  (1086   ),  FD_IsSet
                (1086   )



                31.12.37           FExpand

    Synopsis:    Expand filename to fully qualified path

Declaration:     function  FExpand(const  Path:  PathStr)  :  PathStr

    Visibility:   default

Description:     FExpand expands Path to a full path,  starting from root,  eliminating directory references
                such as .  and ..  from the result.

       Errors:   None

    See also:    BaseName (1066   ), DirName (1073   )


                Listing:  ./olinuxex/ex45.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 5;


                {   Program       t o  d e m o n s t r a t et h e  FExpand       f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n ( ' T h i s p r o g r a m i s  i n   :  ' ,FExpand      (Paramstr       ( 0 ) ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.38           Flock

    Synopsis:    Lock a file (advisory lock)

Declaration:     function  Flock(fd:  LongInt;mode:  LongInt)  :  Boolean
                function  Flock(var  T:  text;mode:  LongInt)  :  Boolean
                function  Flock(var  F:  File;mode:  LongInt)  :  Boolean

    Visibility:   default

Description:     FLock  implements  file  locking.   it  sets  or  removes  a  lock  on  the  file  F.  F  can  be  of  type
                Text or File, or it can be a linux filedescriptor (a longint) Mode can be one of the following
                constants :


                LOCK__SH         sets a shared lock.

                LOCK__EX         sets an exclusive lock.

                LOCK__UN         unlocks the file.

                LOCK__NB         This  can  be  OR-ed  together  with  the  other.   If  this  is  done  the  application
                       doesn't block when locking.


                The function returns True if successful, False otherwise.

       Errors:   If an error occurs, it is reported in LinuxError.

    See also:    Fcntl (1081   )



                                                                                1087

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.39           FNMatch

    Synopsis:    Check whether filename matches wildcard specification

Declaration:     function  FNMatch(const  Pattern:  string;const  Name:  string)  :  Boolean

    Visibility:   default

Description:     FNMatch  returns  True  if  the  filename  in  Name  matches  the  wildcard  pattern  in  Pattern,
                False otherwise.

                Pattern can contain the wildcards * (match zero or more arbitrary characters) or ?  (match
                a single character).

       Errors:   None.

    See also:    FSearch (1089   ), FExpand (1087   )


                Listing:  ./olinuxex/ex69.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 9;


                {   Program       t o  d e m o n s t r a t et h e  FNMatch       f u n c t i o n. }


                Uses     o l d l i n u x;


                    P r o c e d u r eTestMatch       ( P a t t e r n,Name     :  S t r i n g) ;


                    b e g i n
                       Write      ( '"  ',Name    , '"   ' ) ;
                        I f  FNMatch       (P a t t e r n,Name    )  then
                           Write     (  'm a t c h e s')
                        e l s e
                           Write     (  'd o e s  n o t  match    ') ;
                        W r i t e l n('  " ' ,P a t t e r n,' " . ') ;
                    end  ;


                 b e g i n
                    TestMatch       ( '* ' , 'F i l e N a m e') ;
                    TestMatch       ( '. * ' , 'F i l e N a m e') ;
                    TestMatch       ( '* a * ' ,' F i l e N a m e') ;
                    TestMatch       ( '? i l e* ' , 'F i l e N a m e') ;
                    TestMatch       ( '? ' , 'F i l e N a m e') ;
                    TestMatch       ( '. ? ' , 'F i l e N a m e') ;
                    TestMatch       ( '? a * ' ,' F i l e N a m e') ;
                    TestMatch       ( '? ? *me  ? ' ,' F i l e N a m e') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.40           Fork

    Synopsis:    Create child process

Declaration:     function  Fork  :  LongInt

    Visibility:   default

Description:     Fork creates a child process which is a copy of the parent process.  Fork returns the process
                ID in the parent process, and zero in the child's process.  (you can get the parent's PID with
                GetPPid (1099   )).



                                                                                1088

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



       Errors:   On error, -1 is returned to the parent, and no child is created.


                sys__eagain     Not enough memory to create child process.


    See also:    Execve (1079   ), Clone (1070   )



                31.12.41           FReName

    Synopsis:    Rename file

Declaration:     function  FReName(OldName:  Pchar;NewName:  Pchar)  :  Boolean
                function  FReName(OldName:  string;NewName:  string)  :  Boolean

    Visibility:   default

Description:     FRename  renames  the  file  OldName  to  NewName.   NewName  can  be  in  a  different  directory
                than OldName, but it cannot be on another partition (device).  Any existing file on the new
                location will be replaced.

                If the operation fails, then the OldName file will be preserved.

                The function returns True on succes, False on failure.

       Errors:   On error, errors are reported in LinuxError.  Possible errors include:


                sys__eisdir    NewName exists and is a directory, but OldName is not a directory.

                sys__exdev     NewName and OldName are on different devices.

                sys__enotempty or sys__eexist               NewName is an existing, non-empty directory.

                sys__ebusy     OldName or NewName is a directory and is in use by another process.

                sys__einval    NewName is part of  OldName.

                sys__emlink      OldPath  or  NewPath  already  have  tha  maximum  amount  of  links  pointing  to
                       them.

                sys__enotdir      part of  OldName or NewName is not directory.

                sys__efault    For the pchar case:  One of the pointers points to an invalid address.

                sys__eaccess     access is denied when attempting to move the file.

                sys__enametoolong           Either OldName or NewName is too long.

                sys__enoent      a directory component in OldName or NewName didn't exist.

                sys__enomem        not enough kernel memory.

                sys__erofs    NewName or OldName is on a read-only file system.

                sys__eloop     too many symbolic links were encountered trying to expand OldName or NewName

                sys__enospc      the filesystem has no room for the new directory entry.


    See also:    UnLink (1135   )



                31.12.42           FSearch

    Synopsis:    Search for file in search path.

Declaration:     function  FSearch(const  path:  PathStr;dirlist:  string)  :  PathStr

    Visibility:   default



                                                                                1089

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



Description:     FSearch searches in DirList, a colon separated list of directories, for a file named Path.  It
                then returns a path to the found file.

       Errors:   An empty string if no such file was found.

    See also:    BaseName (1066   ), DirName (1073   ), FExpand (1087   ), FNMatch (1088   )


                Listing:  ./olinuxex/ex46.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 6;


                {   Program       t o  d e m o n s t r a t et h e  F S e a r c h f u n c t i o n. }


                Uses     o l d l i n u x,s t r i n g s;


                 b e g i n
                    W r i t e l n ( ' l s  i s  i n  :   ' ,F S e a r c h ( ' l s' , s t r p a s(G e t e n v('PATH    ' ) ) ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.43           FSplit

    Synopsis:    Split filename into path, name and extension

Declaration:     procedure  FSplit(const  Path:  PathStr;var  Dir:  DirStr;var  Name:  NameStr;
                                           var  Ext:  ExtStr)

    Visibility:   default

Description:     FSplit splits a full file name into 3 parts :  A Path, a Name and an extension (in ext).  The
                extension is taken to be all letters after the last dot (.).

       Errors:   None.

    See also:    FSearch (1089   )


                Listing:  ./olinuxex/ex67.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 7;


                 u s e s o l d l i n u x;


                {   Program       t o  d e m o n s t r a t et h e  F S p l i t f u n c t i o n.  }


                 v a r
                    Path   ,Name    ,E x t   :  s t r i n g;


                 b e g i n
                    F S p l i t(ParamStr      ( 1 ) ,Path   ,Name    , E x t) ;
                    WriteLn     ( ' S p l i t  ', ParamStr      ( 1 ) ,'  i n : ') ;
                    WriteLn     ( ' Path            :  ' ,Path    ) ;
                    WriteLn     ( 'Name             :  ' ,Name    ) ;
                    WriteLn     ( ' E x t e n s i o n: ' ,E x t ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1090

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.44           FSStat

    Synopsis:    Retrieve filesystem information.

Declaration:     function  FSStat(Path:  PathStr;var  Info:  Statfs)  :  Boolean
                function  FSStat(Fd:  LongInt;var  Info:  Statfs)  :  Boolean

    Visibility:   default

Description:     FSStat returns in Info information about the filesystem on which the file Path resides, or
                on which the file with file descriptor fd resides.  Info is of type statfs.  The function returns
                True if the call was succesfull, False if the call failed.

       Errors:   LinuxError is used to report errors.

                sys__enotdir      A component of  Path is not a directory.

                sys__einval    Invalid character in Path.

                sys__enoent      Path does not exist.

                sys__eaccess     Search permission is denied for component inPath.

                sys__eloop     A circular symbolic link was encountered in Path.

                sys__eio   An error occurred while reading from the filesystem.

    See also:    FStat (1092   ), LStat (1106   )


                Listing:__./olinuxex/ex30.pp_______________________________________________________________________________________*
 *___________

                program       E x a m p l e 3 0;


                {   Program       t o  d e m o n s t r a t et h e  F S S t a t f u n c t i o n.  }


                 u s e s o l d l i n u x;


                 v a r  s  :   s t r i n g;
                        i n f o :   s t a t f s;


                 b e g i n
                    w r i t e l n ( ' I n f o a b o u t  c u r r e n t p a r t i t i o n:   ') ;
                    s :=  '. ' ;
                    w h i l e s <>  'q  '  do
                        b e g i n
                        i f  not    f s s t a t ( s ,i n f o)   then
                             b e g i n
                             w r i t e l n(' F s t a t f a i l e d.  E r r n o :   ' , l i n u x e r r o)r;
                             h a l t ( 1 ) ;
                             end  ;
                        w r i t e l n;
                        w r i t e l n(  'R e s u l t o f   f s s t a ton    f i l e  ' '' ,s , ' ' '. ' ) ;
                        w r i t e l n(  'f s t y p e   :   ', i n f o. f s t y p e) ;
                        w r i t e l n(  'b s i z e     :   ', i n f o. b s i z e) ;
                        w r i t e l n(  'b f r e e     :   ', i n f o. b f r e e) ;
                        w r i t e l n(  'b a v a i l   :   ', i n f o. b a v a i l) ;
                        w r i t e l n(  'f i l e s     :   ', i n f o. f i l e s) ;
                        w r i t e l n(  'f f r e e     :   ', i n f o. f f r e e) ;
                        w r i t e l n(  'f s i d       :   ', i n f o. f s i d) ;
                        w r i t e l n(  'Namelen       :   ', i n f o. n a m e l e n) ;
                        w r i t e ( 'Type     name     o f   f i l e t o  do    f s s t a t.  (q   q u i t s)  : ') ;
                        r e a d l n (s )
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1091

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.45           FStat

    Synopsis:    Retrieve information about a file

Declaration:     function  FStat(Path:  PathStr;var  Info:  Stat)  :  Boolean
                function  FStat(Fd:  LongInt;var  Info:  Stat)  :  Boolean
                function  FStat(var  F:  Text;var  Info:  Stat)  :  Boolean
                function  FStat(var  F:  File;var  Info:  Stat)  :  Boolean

    Visibility:   default

Description:     FStat gets information about the file specified in one of the following:


                Path    a file on the filesystem.

                Fd   a valid file descriptor.

                F  an opened text file or untyped file.


                and  stores  it  in  Info,  which  is  of  type  stat.   The  function  returns  True  if  the  call  was
                succesfull, False if the call failed.

       Errors:   LinuxError is used to report errors.


                sys__enoent      Path does not exist.


    See also:    FSStat (1091   ), LStat (1106   )


                Listing:  ./olinuxex/ex28.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 2 8;


                {   Program       t o  d e m o n s t r a t et h e  F S t a t  f u n c t i o n. }


                 u s e s o l d l i n u x;


                 v a r  f  :   t e x t;
                        i  :   b y t e;
                        i n f o :   s t a t;


                 b e g i n
                    {  Make     a   f i l e }
                    a s s i g n ( f , 't e s t. f i l' ) ;
                    r e w r i t e ( f ) ;
                    f o r  i : = 1  t o  1 0  do    w r i t e l n( f , ' T e s t l i n e#   ' ,i ) ;
                    c l o s e ( f ) ;
                    {  Do    t h e  c a l l on   made      f i l e.  }
                    i f  not    f s t a t  ( 't e s t. f i l' , i n f o)  then
                         b e g i n
                         w r i t e l n( 'F s t a t  f a i l e d. E r r n o  :   ', l i n u x e r r o)r;
                         h a l t  ( 1 ) ;
                         end   ;
                    w r i t e l n;
                    w r i t e l n ( ' R e s u l t o f  f s t a t on    f i l e  '' t e s t. f i l' '. ' ) ;
                    w r i t e l n ( ' I n o d e     :  ' , i n f o.i n o ) ;
                    w r i t e l n ( 'Mode           :  ' , i n f o.mode   ) ;
                    w r i t e l n ( ' n l i n k     :  ' , i n f o.n l i n k) ;
                    w r i t e l n ( ' u i d         :  ' , i n f o.u i d ) ;
                    w r i t e l n ( ' g i d         :  ' , i n f o.g i d ) ;
                    w r i t e l n ( ' r d e v       :  ' , i n f o.r d e v) ;
                    w r i t e l n ( ' S i z e       :  ' , i n f o.s i z e) ;



                                                                                1092

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                    w r i t e l n ( ' B l k s i z e :  ' , i n f o.b l k s z e) ;
                    w r i t e l n ( ' B l o c k s   :  ' , i n f o.b l o c k s) ;
                    w r i t e l n ( 'a t i m e      :  ' , i n f o.a t i m e) ;
                    w r i t e l n ( 'mtime          :  ' , i n f o.mtime    ) ;
                    w r i t e l n ( ' c t i m e     :  ' , i n f o.c t i m e) ;
                    {  Remove       f i l e }
                    e r a s e ( f ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.46           GetDate

    Synopsis:    Return the system date

Declaration:     procedure  GetDate(var  Year:  Word;var  Month:  Word;var  Day:  Word)

    Visibility:   default

Description:     Returns the current date.

       Errors:   None

    See also:    GetEpochTime (1095   ), GetTime (1100   ), GetDateTime (1093   ), EpochToLocal (1075   )


                Listing:  ./olinuxex/ex6.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                {   Program       t o  d e m o n s t r a t et h e  G e t D a t e f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    Year    ,  Month    ,  Day    :  Word    ;


                 b e g i n
                  G e t D a t e ( Year   ,  Month    ,  Day   ) ;
                  W r i t e l n ( ' Date     :  ' ,Day   : 2 ,'/  ', Month    : 2 ,'/  ', Y e a r: 4 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.47           GetDateTime

    Synopsis:    Return system date and time

Declaration:     procedure  GetDateTime(var  Year:  Word;var  Month:  Word;var  Day:  Word;
                                                   var  hour:  Word;var  minute:  Word;var  second:  Word)

    Visibility:   default

Description:     Returns  the  current  date  and  time.  The  time  is  corrected  for  the  local  time  zone.  This
                procedure is equivalent to the GetDate (1093   ) and GetTime calls.

       Errors:   None

    See also:    GetEpochTime (1095   ), GetTime (1100   ), EpochToLocal (1075   ), GetDate (1093   )


                Listing:  ./olinuxex/ex60.pp



                                                                                1093

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example6       ;


                {   Program       t o  d e m o n s t r a t et h e  GetDateTime          f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    Year    ,  Month    ,  Day   ,  Hour   ,  min   ,  s e c  :  Word    ;


                 b e g i n
                  GetDateTime          ( Year   ,  Month    ,  Day   ,  Hour    ,  min  ,   s e c) ;
                  W r i t e l n ( ' Date     :  ' ,Day   : 2 ,'/  ', Month    : 2 ,'/  ', Y e a r: 4 ) ;
                  W r i t e l n ( ' Time     :  ' ,Hour    : 2 ,' :' ,Min   : 2 ,' : ' ,S e c: 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.48           GetDomainName

    Synopsis:    Return current domain name

Declaration:     function  GetDomainName  :  string

    Visibility:   default

Description:     Get the domain name of the machine on which the process is running.  An empty string is
                returned if the domain is not set.

       Errors:   None.

    See also:    GetHostName (1097   )


                Listing:  ./olinuxex/ex39.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 9;


                {   Program       t o  d e m o n s t r a t et h e  GetDomainName            f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n ( 'Domain      name     o f   t h i s m a c h i n e  i s  :  ' ,GetDomainName          ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.49           GetEGid

    Synopsis:    Return effective group ID

Declaration:     function  GetEGid  :  LongInt

    Visibility:   default

Description:     Get the effective group ID of the currently running process.

       Errors:   None.

    See also:    GetGid (1097   )


                Listing:  ./olinuxex/ex18.pp



                                                                                1094

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  d e m o n s t r a t et h e  G e t G i d and    G e t E G i d f u n c t i o n s. }


                Uses     o l d l i n u x;


                 b e g i n
                  w r i t e l n ( ' Group     I d  =   ' ,g e t g i d, '  E f f e c t i v eg r o u p  I d  =   ' ,g e t e g i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.50           GetEnv

    Synopsis:    Return value of environment variable.

Declaration:     function  GetEnv(P:  string)  :  Pchar

    Visibility:   default

Description:     GetEnv  returns  the  value  of  the  environment  variable  in  P.  If  the  variable  is  not  defined,
                nil is returned.  The value of the environment variable may be the empty string.  A PChar
                is  returned  to  accomodate  for  strings  longer  than  255  bytes,  TERMCAP  and  LS_COLORS,  for
                instance.

       Errors:   None.


                Listing:  ./olinuxex/ex41.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 1;


                {   Program       t o  d e m o n s t r a t et h e  GetEnv      f u n c t i o n.  }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n ( 'Path     i s   :  ' ,G e t e n v( 'PATH    ') ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.51           GetEpochTime

    Synopsis:    Return the current unix time

Declaration:     function  GetEpochTime  :  LongInt

    Visibility:   default

Description:     returns  the  number  of  seconds  since  00:00:00  gmt,  january  1,  1970.  it  is  adjusted  to  the
                local time zone, but not to DST.

       Errors:   no errors

    See also:    EpochToLocal (1075   ), GetTime (1100   )


                Listing:  ./olinuxex/ex1.pp



                                                                                1095

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   Program       t o  d e m o n s t r a t et h e  GetEpochTime           f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    Write     (  'S e c s  p a s t t h e   s t a r t o f  t h e  Epoch     ( 0 0 : 0 0  1 / 1 / 1 9 8 0 )  : ' ) ;
                    W r i t e l n ( GetEpochTime         ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.52           GetEUid

    Synopsis:    Return effective user ID

Declaration:     function  GetEUid  :  LongInt

    Visibility:   default

Description:     Get the effective user ID of the currently running process.

       Errors:   None.

    See also:    GetUid (1101   )


                Listing:  ./olinuxex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   Program       t o  d e m o n s t r a t et h e  G e t U i d and    GetEUid       f u n c t i o n s. }


                Uses     o l d l i n u x;


                 b e g i n
                    w r i t e l n ( 'U s e r  I d  =   ' ,g e t u i d, '  E f f e c t i v e u s e r I d  =   ' , g e t e u i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.53           GetFS

    Synopsis:    Return file selector

Declaration:     function  GetFS(var  T:  Text)  :  LongInt
                function  GetFS(var  F:  File)  :  LongInt

    Visibility:   default

Description:     GetFS returns the file selector that the kernel provided for your file.  In principle you don'
                need this file selector.  Only for some calls it is needed, such as the Select (1116   ) call or so.

       Errors:   In case the file was not opened, then -1 is returned.

    See also:    Select (1116   )


                Listing:  ./olinuxex/ex34.pp



                                                                                1096

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   Program       t o  d e m o n s t r a t et h e  S e l e c t T e x tf u n c t i o n.  }


                Uses     o l d l i n u x;


                Var     t v  :  TimeVal      ;


                 b e g i n
                    W r i t e l n ( ' P r e s s t h e < ENTER    >   t o  c o n t i n u e t h e  p r o g r a m.' ) ;
                    {  Wait     u n t i l  F i l e  d e s c r i p t o r0  ( = I n p u t)  c h a n g e s }
                    S e l e c t T e x t( I n p u t, n i l) ;
                    {  Get     r i d  o f < ENTER    >   i n  b u f f e r }
                    r e a d l n;
                    W r i t e l n ( ' P r e s s< ENTER    >   k e y  i n  l e s s  t h a n 2   s e c o n d s. . .') ;
                    t v .s e c : = 2 ;
                    t v .u s e c: = 0 ;
                    i f  S e l e c t T e x t( I n p u t, @tv  ) >0   then
                        W r i t e l n(  'Thank     you    ! ' )
                    e l s e
                        W r i t e l n(  'Too    l a t e  ! ') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.54           GetGid

    Synopsis:    Return real group ID

Declaration:     function  GetGid  :  LongInt

    Visibility:   default

Description:     Get the real group ID of the currently running process.

       Errors:   None.

    See also:    GetEGid (1094   )


                Listing:  ./olinuxex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  d e m o n s t r a t et h e  G e t G i d and    G e t E G i d f u n c t i o n s. }


                Uses     o l d l i n u x;


                 b e g i n
                  w r i t e l n ( ' Group     I d  =   ' ,g e t g i d, '  E f f e c t i v eg r o u p  I d  =   ' ,g e t e g i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.55           GetHostName

    Synopsis:    Return host name

Declaration:     function  GetHostName  :  string

    Visibility:   default



                                                                                1097

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



Description:     Get  the  hostname  of  the  machine  on  which  the  process  is  running.   An  empty  string  is
                returned if hostname is not set.

       Errors:   None.

    See also:    GetDomainName (1094   )


                Listing:  ./olinuxex/ex40.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 0;


                {   Program       t o  d e m o n s t r a t et h e  GetHostName          f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n ( 'Name     o f   t h i s m a c h i n e i s  :   ' ,GetHostName         ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.56           GetLocalTimezone

    Synopsis:    Return local timzeone information

Declaration:     procedure  GetLocalTimezone(timer:  LongInt;var  leap_correct:  LongInt;
                                                           var  leap_hit:  LongInt)
                procedure  GetLocalTimezone(timer:  LongInt)

    Visibility:   default

Description:     GetLocalTimeZone returns the local timezone information.  It also initializes the TZSeconds
                variable, which is used to correct the epoch time to local time.

                There should never be any need to call this function directly.  It is called by the initialization
                routines of the Linux unit.

    See also:    GetTimezoneFile (1101   ), ReadTimezoneFile (1116   )



                31.12.57           GetPid

    Synopsis:    Return current process ID

Declaration:     function  GetPid  :  LongInt

    Visibility:   default

Description:     Get the Process ID of the currently running process.

       Errors:   None.

    See also:    GetPPid (1099   )


                Listing:  ./olinuxex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   Program       t o  d e m o n s t r a t et h e  G e t P i d,  G e t P P i d f u n c t i o n. }


                Uses     o l d l i n u x;



                                                                                1098

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                 b e g i n
                    W r i t e l n ( ' P r o c e s sI d  =   ' , g e t p i d,'  P a r e n t  p r o c e s s I d =   ' , g e t p p i d*
 *) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.58           GetPPid

    Synopsis:    Return parent process ID

Declaration:     function  GetPPid  :  LongInt

    Visibility:   default

Description:     Get the Process ID of the parent process.

       Errors:   None.

    See also:    GetPid (1098   )


                Listing:  ./olinuxex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   Program       t o  d e m o n s t r a t et h e  G e t P i d,  G e t P P i d f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n ( ' P r o c e s sI d  =   ' , g e t p i d,'  P a r e n t  p r o c e s s I d =   ' , g e t p p i d*
 *) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.59           GetPriority

    Synopsis:    Return process priority

Declaration:     function  GetPriority(Which:  Integer;Who:  Integer)  :  Integer

    Visibility:   default

Description:     GetPriority returns the priority with which a process is running.  Which process(es) is deter-
                mined by the Which and Who variables.  Which can be one of the pre-defined Prio_Process,
                Prio_PGrp,  Prio_User,  in which case Who is the process ID, Process group ID or User ID,
                respectively.

                For an example, see Nice (1111   ).

       Errors:   Error checking must be done on LinuxError, since a priority can be negative.


                sys__esrch    No process found using which and who.

                sys__einval    Which was not one of  Prio_Process, Prio_Grp or Prio_User.


    See also:    SetPriority (1119   ), Nice (1111   )



                                                                                1099

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.60           GetTime

    Synopsis:    Return current system time

Declaration:     procedure  GetTime(var  hour:  Word;var  min:  Word;var  sec:  Word;
                                            var  msec:  Word;var  usec:  Word)
                procedure  GetTime(var  hour:  Word;var  min:  Word;var  sec:  Word;
                                            var  sec100:  Word)
                procedure  GetTime(var  hour:  Word;var  min:  Word;var  sec:  Word)

    Visibility:   default

Description:     Returns the current time of the day, adjusted to local time.  Upon return, the parameters
                are filled with

                hour    Hours since 00:00 today.

                min   minutes in current hour.

                sec  seconds in current minute.

                sec100    hundreds of seconds in current second.

                msec    milliseconds in current second.

                usec   microseconds in current second.

       Errors:   None

    See also:    GetEpochTime (1095   ), GetDate (1093   ), GetDateTime (1093   ), EpochToLocal (1075   )


                Listing:__./olinuxex/ex5.pp________________________________________________________________________________________*
 *___________

                Program       Example5       ;


                {   Program       t o  d e m o n s t r a t et h e  GetTime       f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    Hour    ,  Minute     ,  S e c o n d :  Word    ;


                 b e g i n
                    GetTime       ( Hour   ,  Minute     ,  S e c o n d) ;
                    W r i t e l n ( 'Time     :   ' ,Hour   : 2 , ': ' ,M i n u t e: 2 ,' : ' ,S e c o n d: 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.61           GetTimeOfDay

    Synopsis:    Return kernel time of day in GMT

Declaration:     procedure  GetTimeOfDay(var  tv:  timeval)
                function  GetTimeOfDay  :  LongInt

    Visibility:   default

Description:     GetTimeOfDay  returns  the  number  of  seconds  since  00:00,  January  1  1970,  GMT  in  a
                timeval  record.   This  time  NOT  corrected  any  way,  not  taking  into  account  timezones,
                daylight savings time and so on.

                It is simply a wrapper to the kernel system call.  To get the local time, GetTime (1100   ).

       Errors:   None.

    See also:    GetTime (1100   ), GetTimeOfDay (1100   )



                                                                                1100

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.62           GetTimezoneFile

    Synopsis:    Return name of timezone information file

Declaration:     function  GetTimezoneFile  :  string

    Visibility:   default

Description:     GetTimezoneFile returns the location of the current timezone file.  The location of file is
                determined as follows:


                     1.If  /etc/timezone exists, it is read, and the contents of this file is returned.  This should
                       work on Debian systems.

                     2.If  /usr/lib/zoneinfo/localtime  exists,  then  it  is  returned.  (this  file  is  a  symlink  to  the
                       timezone file on SuSE systems)

                     3.If  /etc/localtime exists, then it is returned.  (this file is a symlink to the timezone file
                       on RedHat systems)


       Errors:   If no file was found, an empty string is returned.

    See also:    ReadTimezoneFile (1116   )



                31.12.63           GetUid

    Synopsis:    Return current user ID

Declaration:     function  GetUid  :  LongInt

    Visibility:   default

Description:     Get the real user ID of the currently running process.

       Errors:   None.

    See also:    GetEUid (1096   )


                Listing:  ./olinuxex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   Program       t o  d e m o n s t r a t et h e  G e t U i d and    GetEUid       f u n c t i o n s. }


                Uses     o l d l i n u x;


                 b e g i n
                    w r i t e l n ( 'U s e r  I d  =   ' ,g e t u i d, '  E f f e c t i v e u s e r I d  =   ' , g e t e u i d) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.64           Glob

    Synopsis:    Find filenames matching a wildcard pattern

Declaration:     function  Glob(const  path:  PathStr)  :  pglob

    Visibility:   default



                                                                                1101

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



Description:     Glob  returns  a  pointer  to  a  glob  structure  which  contains  all  filenames  which  exist  and
                match the pattern in Path.  The pattern can contain wildcard characters, which have their
                usual meaning.

       Errors:   Returns nil on error, and LinuxError is set.


                sys__enomem        No memory on heap for glob structure.

                others   As returned by the opendir call, and sys_readdir.


    See also:    GlobFree (1102   )


                Listing:  ./olinuxex/ex49.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 9;


                {   Program       t o  d e m o n s t r a t et h e  G l o b  and    G l o b F r e e f u n c t i o n.s }


                Uses     o l d l i n u x;


                Var    G1  ,G2    :  PGlob    ;


                 b e g i n
                    G1 :=  G l o b  ( '* ' ) ;
                    i f  L i n u x E r r o r=0  then
                        b e g i n
                       G2  := G1  ;
                        W r i t e l n(  'F i l e s  i n  t h i s  d i r e c t o r y:   ') ;
                       While      g2 <>  N i l  do
                           b e g i n
                           W r i t e l n ( g2 ^ .name    ) ;
                           g2 :=  g2  ^ .n e x t;
                           end  ;
                        G l o b F r e e( g1  ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.65           Globfree

    Synopsis:    Free result of Glob (1101   ) call

Declaration:     procedure  Globfree(var  p:  pglob)

    Visibility:   default

Description:     Releases the memory, occupied by a pglob structure.  P is set to nil.

                For an example, see Glob (1101   ).

       Errors:   None

    See also:    Glob (1101   )



                31.12.66           IOCtl

    Synopsis:    General kernel IOCTL call.

Declaration:     function  IOCtl(Handle:  LongInt;Ndx:  LongInt;Data:  Pointer)  :  Boolean



                                                                                1102

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



    Visibility:  default

Description:     This is a general interface to the Unix/ linux ioctl call.  It performs various operations on the
                filedescriptor Handle.  Ndx describes the operation to perform.  Data points to data needed
                for the Ndx function.  The structure of this data is function-dependent, so we don't elaborate
                on this here.  For more information on this, see various manual pages under linux.

       Errors:   Errors are reported in LinuxError.  They are very dependent on the used function, that's
                why we don't list them here


                Listing:__./olinuxex/ex54.pp_______________________________________________________________________________________*
 *___________

                Program       E x a m p l e 5 4;


                 u s e s o l d l i n u x;


                {   Program       t o  d e m o n s t r a t et h e  I O C t l  f u n c t i o n. }


                 v a r
                    t i o s  :  T e r m i o s;
                 b e g i n
                    I O C t l( 1 ,TCGETS     ,@ t i o s) ;
                    WriteLn     ( ' I n p u t F l a g s    :  $ ' ,h e x s t r( t i o s.c _i f l a g, 8 ) ) ;
                    WriteLn     ( ' Output      F l a g s  :  $ ' ,h e x s t r( t i o s.c _o f l a g, 8 ) ) ;
                    WriteLn     ( ' L i n e  F l a g s     :  $ ' ,h e x s t r( t i o s.c _l f l a g, 8 ) ) ;
                    WriteLn     ( ' C o n t r o l F l a g s:  $ ' ,h e x s t r( t i o s.c _c f l a g, 8 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.67           IOperm

    Synopsis:    Set permission on IO ports

Declaration:     function  IOperm(From:  Cardinal;Num:  Cardinal;Value:  LongInt)  :  Boolean

    Visibility:   default

Description:     IOperm  sets  permissions  on  Num  ports  starting  with  port  From  to  Value.   The  function
                returns True if the call was successfull, False otherwise.

                Note:


                      oThis works ONLY as root.

                      oOnly the first 0x03ff ports can be set.

                      oWhen doing a Fork (1088   ), the permissions are reset.  When doing a Execve (1079   ) they
                       are kept.


       Errors:   Errors are returned in LinuxError



                31.12.68           IoPL

    Synopsis:    Set I/O privilege level

Declaration:     function  IoPL(Level:  LongInt)  :  Boolean

    Visibility:   default

Description:     IoPL sets the I/O privilige level.  It is intended for completeness only, one should normally
                not use it.



                                                                                1103

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.69           IsATTY

    Synopsis:    Check if filehandle is a TTY (terminal)

Declaration:     function  IsATTY(Handle:  LongInt)  :  Boolean
                function  IsATTY(var  f:  text)  :  Boolean

    Visibility:   default

Description:     Check if the filehandle described by f is a terminal.  f can be of type


                     1.longint for file handles;

                     2.Text for text variables such as input etc.


                Returns True if  f is a terminal, False otherwise.

       Errors:   No errors are reported

    See also:    IOCtl (1102   ), TTYName (1134   )



                31.12.70           Kill

    Synopsis:    Send a signal to a process

Declaration:     function  Kill(Pid:  LongInt;Sig:  LongInt)  :  Integer

    Visibility:   default

Description:     Send a signal Sig to a process or process group.  If Pid>0 then the signal is sent to Pid, if it
                equals -1, then the signal is sent to all processes except process 1.  If Pid<-1 then the signal is
                sent to process group -Pid.  The return value is zero, except in case three, where the return
                value is the number of processes to which the signal was sent.

       Errors:   LinuxError is used to report errors:


                sys__einval    An invalid signal is sent.

                sys__esrch    The Pid or process group don't exist.

                sys__eperm      The effective userid of the current process doesn't math the one of process Pid.


    See also:    SigAction (1120   ), Signal (1121   )



                31.12.71           Link

    Synopsis:    Create a hard link to a file

Declaration:     function  Link(OldPath:  PathStr;NewPath:  PathStr)  :  Boolean

    Visibility:   default

Description:     Link makes NewPath point to the same file als OldPath.  The two files then have the same
                inode  number.  This  is  known  as  a  'hard'  link.  The  function  returns  True  if  the  call  was
                succesfull, False if the call failed.

       Errors:   Errors are returned in LinuxError.


                sys__exdev     OldPath and NewPath are not on the same filesystem.

                sys__eperm      The filesystem containing oldpath and newpath doesn't support linking files.



                                                                                1104

            ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'______________________*
 *_______________



            sys__eaccess     Write access for the directory containing  Newpath is disallowed,  or one of the
                  directories in OldPath or {NewPath} has no search (=execute) permission.

            sys__enoent     A  directory  entry  in  OldPath  or  NewPath  does  not  exist  or  is  a  symbolic  link
                  pointing to a non-existent directory.

            sys__enotdir     A directory entry in OldPath or NewPath is nor a directory.

            sys__enomem        Insufficient kernel memory.

            sys__erofs   The files are on a read-only filesystem.

            sys__eexist    NewPath already exists.

            sys__emlink     OldPath has reached maximal link count.

            sys__eloop    OldPath or NewPath has a reference to a circular symbolic link,  i.e.  a symbolic
                  link, whose expansion points to itself.

            sys__enospc     The device containing NewPath has no room for another entry.

            sys__eperm     OldPath points to .  or ..  of a directory.


See also:    SymLink (1125   ), UnLink (1135   )


            Listing:  ./olinuxex/ex21.pp
            _______________________________________________________________________________________________________________________*
 *_______
            Program       E x a m p l e 2 1;


            {   Program       t o  d e m o n s t r a t et h e  L i n k  and    U n L i n k f u n c t i o n s. }


            Uses     o l d l i n u x;


            Var    F   :  T e x t ;
                   S   :   S t r i n g;
             b e g i n
                A s s i g n ( F , 't e s t. t x t' ) ;
                R e w r i t e (F  ) ;
                W r i t e l n (F  , 'T h i s  i s  w r i t t e n t o  t e s t. t x t' ) ;
                C l o s e( f) ;
                {  new   . t x t and     t e s t.t x t  a r e  now    t h e  same     f i l e }
                i f  not    L i n k  ( ' t e s t.t x t ', 'new   . t x t' )  then
                    w r i t e l n(  'E r r o r when     l i n k i n g ! ' ) ;
                {  Removing        t e s t. t x t  s t i l l  l e a v e snew   . t x t }
                I f  not    U n l i n k (  't e s t. t x t' )  then
                    W r i t e l n(  'E r r o r when     u n l i n k i n g ! ') ;
                A s s i g n ( f , 'new   .t x t ') ;
                R e s e t ( F ) ;
                While     not    EOF   ( f)  do
                    b e g i n
                   Readln     (F  ,S ) ;
                    W r i t e l n(  '>   ' ,s ) ;
                   end   ;
              C l o s e  ( f) ;
              {   Remove      new  . t x t  a l s o }
               I f not     U n l i n k ( 'new   .t x t ')   then
                  W r i t e l n ( 'E r r o r  when     u n l i n k i n g! ' ) ;
            end___.________________________________________________________________________________________________________________*
 *_______



            31.12.72           LocalToEpoch

Synopsis:    Convert local time to epoch (unix) time



                                                                            1105

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



Declaration:     function  LocalToEpoch(year:  Word;month:  Word;day:  Word;hour:  Word;
                                                  minute:  Word;second:  Word)  :  LongInt

    Visibility:  default

Description:     Converts  the  Local  time  to  epoch  time  (=Number  of  seconds  since  00:00:00  ,  January  1,
                1970 ).

       Errors:   None

    See also:    GetEpochTime (1095   ), EpochToLocal (1075   ), GetTime (1100   ), GetDate (1093   )


                Listing:  ./olinuxex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   Program       t o  d e m o n s t r a t et h e  L o c a l T o E p o c hf u n c t i o n. }


                Uses     o l d l i n u x;


                Var     y e a r,month    , day  , h o u r,m i n u t e, s e c o n d :  Word   ;


                 b e g i n
                    Write     (  'Y e a r       :   ') ; r e a d l n(Y e a r) ;
                    Write     (  'Month         :   ') ; r e a d l n(Month    ) ;
                    Write     (  'Day           :   ') ; r e a d l n(Day  ) ;
                    Write     (  'Hour          :   ') ; r e a d l n(Hour   ) ;
                    Write     (  'M i n u t e   :   ') ; r e a d l n(M i n u t e) ;
                    Write     (  'S e o n d s   :   ') ; r e a d l n(S e c o n d) ;
                    Write     (  'T h i s  i s  :   ') ;
                    Write     ( L o c a l T o E p o c(hy e a r,month    , day  , h o u r, m i n u t e,s e c o n d) ) ;
                    W r i t e l n ( '  s e c o n d s p a s t  0 0 : 0 0  1 / 1 / 1 9 8 0') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.73           Lstat

    Synopsis:    Return information about symbolic link.  Do not follow the link

Declaration:     function  Lstat(Filename:  PathStr;var  Info:  Stat)  :  Boolean

    Visibility:   default

Description:     LStat gets information about the link specified in Path, and stores it in Info, which is of
                type stat.  Contrary to FStat, it stores information about the link, not about the file the
                link points to.  The function returns True if the call was succesfull, False if the call failed.

       Errors:   LinuxError is used to report errors.


                sys__enoent      Path does not exist.


    See also:    FStat (1092   ), FSStat (1091   )


                Listing:  ./olinuxex/ex29.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 2 9;


                {   Program       t o  d e m o n s t r a t et h e  L S t a t  f u n c t i o n. }



                                                                                1106

______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________________________*
 *___



 u s e s o l d l i n u x;


 v a r  f  :   t e x t;
        i  :   b y t e;
        i n f o :   s t a t;


 b e g i n
    {  Make     a   f i l e }
    a s s i g n ( f , 't e s t. f i l' ) ;
    r e w r i t e ( f ) ;
    f o r  i : = 1  t o  1 0  do    w r i t e l n( f , ' T e s t l i n e#   ' ,i ) ;
    c l o s e ( f ) ;
    {  Do    t h e  c a l l on   made      f i l e.  }
    i f  not    f s t a t  ( 't e s t. f i l' , i n f o)  then
         b e g i n
         w r i t e l n( 'F s t a t  f a i l e d. E r r n o  :   ', l i n u x e r r o)r;
         h a l t  ( 1 ) ;
         end   ;
    w r i t e l n;
    w r i t e l n ( ' R e s u l t o f  f s t a t on    f i l e  '' t e s t. f i l' '. ' ) ;
    w r i t e l n ( ' I n o d e     :  ' , i n f o.i n o ) ;
    w r i t e l n ( 'Mode           :  ' , i n f o.mode   ) ;
    w r i t e l n ( ' n l i n k     :  ' , i n f o.n l i n k) ;
    w r i t e l n ( ' u i d         :  ' , i n f o.u i d ) ;
    w r i t e l n ( ' g i d         :  ' , i n f o.g i d ) ;
    w r i t e l n ( ' r d e v       :  ' , i n f o.r d e v) ;
    w r i t e l n ( ' S i z e       :  ' , i n f o.s i z e) ;
    w r i t e l n ( ' B l k s i z e :  ' , i n f o.b l k s z e) ;
    w r i t e l n ( ' B l o c k s   :  ' , i n f o.b l o c k s) ;
    w r i t e l n ( 'a t i m e      :  ' , i n f o.a t i m e) ;
    w r i t e l n ( 'mtime          :  ' , i n f o.mtime    ) ;
    w r i t e l n ( ' c t i m e     :  ' , i n f o.c t i m e) ;


    I f  not    SymLink       ( ' t e s t. f i l' ,' t e s t. l n k' )  then
        w r i t e l n(  'L i n k  f a i l e d !  E r r n o  : ' ,l i n u x e r r o r) ;


    i f  not     l s t a t ( 't e s t. l n k' , i n f o)  then
         b e g i n
         w r i t e l n( 'L S t a t  f a i l e d. E r r n o  :   ', l i n u x e r r o)r;
         h a l t  ( 1 ) ;
         end   ;
    w r i t e l n;
    w r i t e l n ( ' R e s u l t o f  f s t a t on    f i l e  '' t e s t. l n k' '. ' ) ;
    w r i t e l n ( ' I n o d e     :  ' , i n f o.i n o ) ;
    w r i t e l n ( 'Mode           :  ' , i n f o.mode   ) ;
    w r i t e l n ( ' n l i n k     :  ' , i n f o.n l i n k) ;
    w r i t e l n ( ' u i d         :  ' , i n f o.u i d ) ;
    w r i t e l n ( ' g i d         :  ' , i n f o.g i d ) ;
    w r i t e l n ( ' r d e v       :  ' , i n f o.r d e v) ;
    w r i t e l n ( ' S i z e       :  ' , i n f o.s i z e) ;
    w r i t e l n ( ' B l k s i z e :  ' , i n f o.b l k s z e) ;
    w r i t e l n ( ' B l o c k s   :  ' , i n f o.b l o c k s) ;
    w r i t e l n ( 'a t i m e      :  ' , i n f o.a t i m e) ;
    w r i t e l n ( 'mtime          :  ' , i n f o.mtime    ) ;
    w r i t e l n ( ' c t i m e     :  ' , i n f o.c t i m e) ;
    {  Remove       f i l e and     l i n k }
    e r a s e ( f ) ;
    u n l i n k ( ' t e s t. l n k' ) ;



                                                                1107

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.74           mkFifo

    Synopsis:    Create FIFO (named pipe) in file system

Declaration:     function  mkFifo(pathname:  string;mode:  LongInt)  :  Boolean

    Visibility:   default

Description:     MkFifo creates named a named pipe in the filesystem, with name PathName and mode Mode.

       Errors:   LinuxError is used to report errors:


                sys__emfile     Too many file descriptors for this process.

                sys__enfile    The system file table is full.


    See also:    POpen (1113   ), MkFifo (1108   )



                31.12.75           MMap

    Synopsis:    Create memory map of a file

Declaration:     function  MMap(const  m:  tmmapargs)  :  LongInt

    Visibility:   default

Description:     MMap maps or unmaps files or devices into memory.  The different fields of the argument m
                determine what and how the mmap maps this:


                address     Address where to mmap the device.  This address is a hint, and may not be followed.

                size  Size (in bytes) of area to be mapped.

                prot   Protection of mapped memory.  This is a OR-ed combination of the following constants:

                       PROT__EXEC            The memory can be executed.

                       PROT__READ            The memory can be read.

                       PROT__WRITE             The memory can be written.

                       PROT__NONE            The memory can not be accessed.

                flags  Contains some options for the mmap call.  It is an OR-ed combination of the following
                       constants:

                       MAP__FIXED            Do not map at another address than the given address.  If the address
                             cannot be used, MMap will fail.

                       MAP__SHARED              Share this map with other processes that map this object.

                       MAP__PRIVATE              Create a private map with copy-on-write semantics.

                       MAP__ANONYMOUS                     fd does not have to be a file descriptor.

                       One of the options MAP_SHARED and MAP_PRIVATE must be present, but not both at the
                       same time.

                fd File descriptor from which to map.

                offset   Offset to be used in file descriptor fd.


                The function returns a pointer to the mapped memory, or a -1 in case of en error.

       Errors:   On error, -1 is returned and LinuxError is set to the error code:



                                                                                1108

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                Sys__EBADF         fd is not a valid file descriptor and MAP_ANONYMOUS was not specified.

                Sys__EACCES          MAP_PRIVATE was specified,  but fd is not open for reading.  Or MAP_SHARED
                      was asked and PROT_WRITE is set, fd is not open for writing

                Sys__EINVAL         One of the record fields Start, length or offset is invalid.

                Sys__ETXTBUSY             MAP_DENYWRITE was set but the object specified by fd is open for writing.

                Sys__EAGAIN          fd is locked, or too much memory is locked.

                Sys__ENOMEM            Not enough memory for this operation.


    See also:    MUnMap (1109   )


                Listing:  ./olinuxex/ex66.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 6;


                {   Program       t o  d e m o n s t r a t et h e  MMap     f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    S   :   S t r i n g;
                       f d , Len    :  L o n g i n t;
                        a r g s :   tmmapargs       ;
                       P   :  PChar    ;


                 b e g i n
                    S :=  'T h i s  i s  a   s t r i n g'#0;
                    Len  :=  Length    ( S ) ;
                    f d:=  fdOpen    (  't e s t f i l e.t x t' ,O p e n _w r O n l y o r   o p e n _c r e a t) ;
                    I f  f d=-1     then
                       H a l t ( 1 ) ;
                    I f  f d W r i t e(f d ,S [ 1 ] ,Len  )=-1     then
                       H a l t ( 2 ) ;
                    f d C l o s e(f d ) ;
                    fdOpen    (  't e s t f i l e.t x t' ,O p e n _r d O n l y) ;
                    i f  f d=-1     then
                       H a l t ( 3 ) ;
                    a r g s. a d d r e s s: = 0 ;
                    a r g s. o f f s e t: = 0 ;
                    a r g s. s i z e:= Len  +1;
                    a r g s. f d:=  Fd ;
                    a r g s. f l a g s:= MAP_PRIVATE        ;
                    a r g s. p r o t:= PROT_READ         o r  PROT_WRITE       ;
                    P := P c h a r(mmap    ( a r g s) ) ;
                    I f  l o n g i n t(P )=-1     then
                       H a l t ( 4 ) ;
                    W r i t e l n(' Read     i n memory         : ',P  ) ;
                    f d c l o s e(f d ) ;
                    i f  Not    MUnMap     (P , Len  )  Then
                       H a l t( L i n u x E r r o r) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.76           MUnMap

    Synopsis:    Unmap previously mapped memory block

Declaration:     function  MUnMap(P:  Pointer;Size:  LongInt)  :  Boolean



                                                                                1109

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



    Visibility:  default

Description:     MUnMap  unmaps  the  memory  block  of  size  Size,  pointed  to  by  P,  which  was  previously
                allocated with MMap (1108   ).

                The function returns True if successful, False otherwise.

                For an example, see MMap (1108   ).

       Errors:   In case of error the function returns False and LinuxError is set to an error value.  See
                MMap (1108   ) for possible error values.

    See also:    MMap (1108   )



                31.12.77           NanoSleep

    Synopsis:    Suspend process for a short time

Declaration:     function  NanoSleep(const  req:  timespec;var  rem:  timespec)  :  LongInt

    Visibility:   default

Description:     NanoSleep suspends the process till a time period as specified in req has passed.  Then the
                function  returns.  If  the  call  was  interrupted  (e.g.  by  some  signal)  then  the  function  may
                return earlier, and rem will contain the remaining time till the end of the intended period.
                In this case the return value will be -1, and LinuxError will be set to EINTR

                If the function returns without error, the return value is zero.

       Errors:   If the call was interrupted, -1 is returned, and LinuxError is set to EINTR. If invalid time
                values were specified, then -1 is returned and LinuxError is set to EINVAL.

    See also:    Pause (1113   ), Alarm (1063   )


                Listing:  ./olinuxex/ex72.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 7 2;


                {   Program       t o  d e m o n s t r a t et h e  N a n o S l e e p f u n c t i o n. }


                 u s e s o l d l i n u x;


                Var
                    Req  , Rem    :  TimeSpec       ;
                    Res    :   L o n g i n t;


                 b e g i n
                    With     Req    do
                        b e g i n
                        t v _s e c: = 1 0 ;
                        t v _n s e c: = 1 0 0 ;
                       end   ;
                    Write    ( 'N a n o S l e e p r e t u r n e d :  ' ) ;
                    F l u s h(Output     ) ;
                    Res  : = (N a n o S l e e p(Req  , rem  ) ) ;
                    W r i t e l n(r e s) ;
                    I f  ( r e s<>0)     then
                       With     rem    do
                           b e g i n
                           W r i t e l n(' R e m a i n i n gs e c o n d s        :   ' ,t v _s e c ) ;



                                                                                1110

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                           W r i t e l n(' R e m a i n i n gn a n o s e c o n d s:   ' ,t v _n s e c) ;
                           end  ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.78           Nice

    Synopsis:    Set process priority

Declaration:     procedure  Nice(N:  Integer)

    Visibility:   default

Description:     Nice adds -N to the priority of the running process.  The lower the priority numerically, the
                less the process is favored.  Only the superuser can specify a negative N, i.e.  increase the rate
                at which the process is run.

       Errors:   Errors are returned in LinuxError


                sys__eperm      A non-superuser tried to specify a negative N, i.e.  do a priority increase.


    See also:    GetPriority (1099   ), SetPriority (1119   )


                Listing:  ./olinuxex/ex15.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 5;


                {   Program       t o  d e m o n s t r a t et h e  N i c e  and    Get  / S e t P r i o r i t yf u n c t i o n s. }


                Uses     o l d l i n u x;


                 b e g i n
                    w r i t e l n ( ' S e t t i n g p r i o r i t yt o  5 ' ) ;
                    s e t p r i o r i t y( p r i o _p r o c e s s,g e t p i d, 5 ) ;
                    w r i t e l n ( 'New     p r i o r i t y=   ' ,g e t p r i o r i t y( p r i o _p r o c e s s,g e t p i d) ) ;
                    w r i t e l n ( 'D o i n g  n i c e 1 0 ' ) ;
                    n i c e  ( 1 0 ) ;
                    w r i t e l n ( 'New     P r i o r i t y=   ' ,g e t p r i o r i t y( p r i o _p r o c e s s,g e t p i d) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.79           Octal

    Synopsis:    Convert octal to decimal value

Declaration:     function  Octal(l:  LongInt)  :  LongInt

    Visibility:   default

Description:     Octal will convert a number specified as an octal number to it's decimal value.

                This is useful for the Chmod (1067   ) call, where permissions are specified as octal numbers.

       Errors:   No checking is performed whether the given number is a correct Octal number.  e.g.  speci-
                fying 998 is possible; the result will be wrong in that case.

    See also:    Chmod (1067   )


                Listing:  ./olinuxex/ex68.pp



                                                                                1111

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 8;


                {   Program       t o  d e m o n s t r a t et h e  O c t a l  f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n('Mode     7 7 7  :   ' ,  O c t a l( 7 7 7 ) ) ;
                    W r i t e l n('Mode     6 4 4  :   ' ,  O c t a l( 6 4 4 ) ) ;
                    W r i t e l n('Mode     7 5 5  :   ' ,  O c t a l( 7 5 5 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.80           OpenDir

    Synopsis:    Open directory for reading

Declaration:     function  OpenDir(f:  pchar)  :  PDir
                function  OpenDir(f:  string)  :  PDir

    Visibility:   default

Description:     OpenDir opens the directory f, and returns a pdir pointer to a Dir record, which can be
                used to read the directory structure.  If the directory cannot be opened, nil is returned.

       Errors:   Errors are returned in LinuxError.

    See also:    CloseDir (1072   ), ReadDir (1114   ), SeekDir (1116   ), TellDir (1133   )


                Listing:  ./olinuxex/ex35.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 5;


                {   Program       t o  d e m o n s t r a t et h e
                    OpenDir     , R e a d D i r,  S e e k D i r and    T e l l D i r f u n c t i o n.s  }


                Uses     o l d l i n u x;


                Var    T h e D i r  :  P D i r;
                        A D i r e n t :  P D i r e n t;
                        E n t r y :   L o n g i n t;


                 b e g i n
                    T h e D i r:= OpenDir     ( ' . / .' ) ;
                    Repeat
                        E n t r y:= T e l l D i r(T h e D i r) ;
                        A D i r e n t:=R e a d D i r ( T h e D i r) ;
                        I f  A D i r e n<t>  N i l then
                           With     A D i r e n t^ do
                              b e g i n
                               W r i t e l n(  'E n t r y No    :  ' , E n t r y) ;
                               W r i t e l n(  'I n o d e       :  ' , i n o) ;
                               W r i t e l n(  'O f f s e t     :  ' , o f f) ;
                               W r i t e l n(  'R e c l e n     :  ' , r e c l e n) ;
                               W r i t e l n(  'Name            :  ' , p c h a r(@name    [ 0 ] ) ) ;
                              end   ;
                    U n t i l  A D i r e n=t N i l;
                    Repeat



                                                                                1112

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                       Write      ( ' E n t r y No  .  you    w o u l d  l i k e t o  s e e  a g a i n ( - 1   t o  s t o p) :  ' )*
 * ;
                       ReadLn       ( E n t r y) ;
                        I f  E n t r y<>-1    then
                           b e g i n
                           S e e k D i r ( TheDir    , E n t r y) ;
                           A D i r e n t:= R e a d D i r( T h e D i r) ;
                           I f  A D i r e n t<> N i l  then
                              With     A D i r e n t^  do
                                  b e g i n
                                  W r i t e l n ( 'E n t r y  No   :   ' ,E n t r y) ;
                                  W r i t e l n ( 'I n o d e       :   ' ,i n o ) ;
                                  W r i t e l n ( ' O f f s e t    :   ' ,o f f ) ;
                                  W r i t e l n ( 'R e c l e n     :   ' ,r e c l e n) ;
                                  W r i t e l n ( 'Name            :   ' ,p c h a r(@name     [ 0 ] ) ) ;
                                  end  ;
                       end   ;
                    U n t i l  E n t r y=-1;
                    C l o s e D i r (T h e D i r) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.81           Pause

    Synopsis:    Wait for a signal

Declaration:     procedure  Pause

    Visibility:   default

Description:     Pause puts the process to sleep and waits until the application receives a signal.  If a signal
                handler is installed for the received sigal, the handler will be called and after that pause will
                return control to the process.

                For an example, see Alarm (1063   ).



                31.12.82           PClose

    Synopsis:    Close file opened with POpen (1113   )

Declaration:     function  PClose(var  F:  text)  :  LongInt
                function  PClose(var  F:  File)  :  LongInt

    Visibility:   default

Description:     PClose closes a file opened with POpen (1113   ).  It waits for the command to complete, and
                then returns the exit status of the command.

                For an example, see POpen (1113   )

       Errors:   LinuxError is used to report errors.  If it is different from zero, the exit status is not valid.

    See also:    POpen (1113   )



                31.12.83           POpen

    Synopsis:    Pipe file to standard input/output of program

Declaration:     procedure  POpen(var  F:  text;const  Prog:  string;rw:  Char)
                procedure  POpen(var  F:  File;const  Prog:  string;rw:  Char)



                                                                                1113

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



    Visibility:  default

Description:     POpen runs the command specified in Cmd, and redirects the standard in or output of the
                command to the other end of the pipe F. The parameter rw indicates the direction of the
                pipe.  If it is set to 'W', then F can be used to write data, which will then be read by the
                command from stdinput.  If it is set to 'R', then the standard output of the command can
                be read from F. F should be reset or rewritten prior to using it.  F can be of type Text or
                File.  A file opened with POpen can be closed with Close, but also with PClose (1113   ).  The
                result is the same, but PClose returns the exit status of the command Cmd.

       Errors:   Errors  are  reported  in  LinuxError  and  are  essentially  those  of  the  Execve,  Dup  and  As-
                signPipe commands.

    See also:    AssignPipe (1064   ), PClose (1113   )


                Listing:  ./olinuxex/ex37.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 7;


                {   Program       t o  d e m o n s t r a t et h e  Popen      f u n c t i o n. }


                 u s e s o l d l i n u x;


                 v a r  f  :   t e x t;
                        i  :   l o n g i n t;


                 b e g i n
                    w r i t e l n ( ' C r e a t i n ga   s h e l l s c r i p t t o   w h i c h e c h o e s i t s  a r g u m e n t s*
 *') ;
                    w r i t e l n ( 'and     i n p u t b a c k  t o  s t d o u t') ;
                    a s s i g n ( f , 't e s t 2 1 a') ;
                    r e w r i t e ( f ) ;
                    w r i t e l n ( f , '#!/  b i n/ s h ' ) ;
                    w r i t e l n ( f , 'e c h o  t h i s  i s  t h e  c h i l d s p e a k i n g. . . . ' ) ;
                    w r i t e l n ( f , 'e c h o  g o t  a r g u m e n t s\ * "$ *"\*   ' ) ;
                    w r i t e l n ( f , 'c a t ') ;
                    w r i t e l n ( f , 'e x i t 2  ') ;
                    w r i t e l n ( f ) ;
                    c l o s e ( f ) ;
                    chmod     (  't e s t 2 1 a', o c t a l ( 7 5 5 ) ) ;
                    popen     ( f , ' . /t e s t 2 1 a a r g 1  a r g 2' ,'W  ' ) ;
                    i f  l i n u x e r r o<r>0    then
                         w r i t e l n ( ' e r r o r f r o m  POpen     :   L i n u x e r r o r:   ' ,  L i n u x e r r o)r;
                    f o r  i : = 1  t o  1 0  do
                        w r i t e l n( f , 'T h i s  i s   w r i t t e nt o   t h e  p i p e,  and    s h o u l d a p p e a r on   *
 * s t d o u t.' ) ;
                    F l u s h( f) ;
                    W r i t e l n ( 'The     s c r i p t e x i t e d w i t h  s t a t u s :   ', P C l o s e ( f ) ) ;
                    w r i t e l n;
                    w r i t e l n ( ' P r e s s<  r e t u r n>  t o  r e m o v e s h e l l  s c r i p t.' ) ;
                    r e a d l n;
                    a s s i g n ( f , 't e s t 2 1 a') ;
                    e r a s e ( f )
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.84           ReadDir

    Synopsis:    Read entry from directory



                                                                                1114

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



Declaration:     function  ReadDir(p:  PDir)  :  pdirent

    Visibility:  default

Description:     ReadDir reads the next entry in the directory pointed to by p.  It returns a pdirent pointer
                to a structure describing the entry.  If the next entry can't be read, Nil is returned.

                For an example, see OpenDir (1112   ).

       Errors:   Errors are returned in LinuxError.

    See also:    CloseDir (1072   ), OpenDir (1112   ), SeekDir (1116   ), TellDir (1133   )



                31.12.85           ReadLink

    Synopsis:    Read destination of symbolic link

Declaration:     function  ReadLink(name:  pchar;linkname:  pchar;maxlen:  LongInt)  :  LongInt
                function  ReadLink(name:  PathStr)  :  PathStr

    Visibility:   default

Description:     ReadLink  returns  the  file  the  symbolic  link  name  is  pointing  to.   The  first  form  of  this
                function accepts a buffer linkname of length maxlen where the filename will be stored.  It
                returns the actual number of characters stored in the buffer.

                The second form of the function returns simply the name of the file.

       Errors:   On error, the first form of the function returns -1; the second one returns an empty string.
                LinuxError is set to report errors:


                SYS__ENOTDIR              A part of the path in Name is not a directory.

                SYS__EINVAL           maxlen is not positive, or the file is not a symbolic link.

                SYS__ENAMETOOLONG                        A pathname, or a component of a pathname, was too long.

                SYS__ENOENT             the link name does not exist.

                SYS__EACCES            No permission to search a directory in the path

                SYS__ELOOP           Too many symbolic links were encountered in translating the pathname.

                SYS__EIO       An I/O error occurred while reading from the file system.

                SYS__EFAULT           The buffer is not part of the the process's memory space.

                SYS__ENOMEM              Not enough kernel memory was available.


    See also:    SymLink (1125   )


                Listing:  ./olinuxex/ex62.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 2;


                {   Program       t o  d e m o n s t r a t et h e  R e a d L i n k f u n c t i o n. }


                Uses     o l d l i n u x;


                Var    F   :  T e x t ;
                       S   :   S t r i n g;


                 b e g i n
                    A s s i g n ( F , 't e s t. t x t' ) ;
                    R e w r i t e (F  ) ;



                                                                                1115

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                    W r i t e l n (F  , 'T h i s  i s  w r i t t e n t o  t e s t. t x t' ) ;
                    C l o s e( f) ;
                    {  new   . t x t and     t e s t.t x t  a r e  now    t h e  same     f i l e }
                    i f  not    SymLink       ( ' t e s t. t x t' ,' new  . t x t' )  then
                        w r i t e l n(  'E r r o r when     s y m l i n k i n g! ' ) ;
                    S := R e a d L i n k(' new  . t x t' ) ;
                    I f  S=  ' '  then
                        W r i t e l n(  'E r r o r  r e a d i n g l i n k ! ' )
                    E l s e
                        W r i t e l n(  'L i n k  p o i n t s t o  :   ' ,S ) ;
                  {  Now     r e m o v e l i n k s }
                   I f not     U n l i n k ( 'new   .t x t ')   then
                      W r i t e l n ( 'E r r o r  when     u n l i n k i n g! ' ) ;
                   I f not     U n l i n k ( 't e s t. t x t' )  then
                      W r i t e l n ( 'E r r o r  when     u n l i n k i n g! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.86           ReadTimezoneFile

    Synopsis:    Read the timezone file and initialize time routines

Declaration:     procedure  ReadTimezoneFile(fn:  string)

    Visibility:   default

Description:     ReadTimeZoneFile reads the timezone file fn and initializes the local time routines based
                on the information found there.

                There should be no need to call this function.  The initialization routines of the linux unit
                call this routine at unit startup.

       Errors:   None.

    See also:    GetTimezoneFile (1101   ), GetLocalTimezone (1098   )



                31.12.87           SeekDir

    Synopsis:    Seek to position in directory

Declaration:     procedure  SeekDir(p:  PDir;off:  LongInt)

    Visibility:   default

Description:     SeekDir sets the directory pointer to the off-th entry in the directory structure pointed to
                by p.

                For an example, see OpenDir (1112   ).

       Errors:   Errors are returned in LinuxError.

    See also:    CloseDir (1072   ), ReadDir (1114   ), OpenDir (1112   ), TellDir (1133   )



                31.12.88           Select

    Synopsis:    Wait for events on file descriptors



                                                                                1116

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



Declaration:     function  Select(N:  LongInt;readfds:  pfdset;writefds:  pfdset;
                                        exceptfds:  pfdset;TimeOut:  ptimeval)  :  LongInt
                function  Select(N:  LongInt;readfds:  pfdset;writefds:  pfdset;
                                        exceptfds:  pfdset;TimeOut:  LongInt)  :  LongInt

    Visibility:  default

Description:     Select checks one of the file descriptors in the FDSets to see if its status changed.

                readfds,  writefds  and  exceptfds  are  pointers  to  arrays  of  256  bits.  If  you  want  a  file
                descriptor  to  be  checked,  you  set  the  corresponding  element  in  the  array  to  1.  The  other
                elements in the array must be set to zero.  Three arrays are passed :  The entries in readfds
                are checked to see if characters become available for reading.  The entries in writefds are
                checked to see if it is OK to write to them, while entries in exceptfds are cheked to see if
                an exception occorred on them.

                You can use the functions FD_ZERO (1086   )FD_Clr (1086   ), FD_Set (1086   ) or FD_IsSet (1086   )
                to manipulate the individual elements of a set.

                The pointers can be Nil.

                N is the largest index of a nonzero entry plus 1.  (= the largest file-descriptor + 1).

                TimeOut can be used to set a time limit.  If  TimeOut can be two types :


                     1.TimeOut  is  of  type  PTime  and  contains  a  zero  time,  the  call  returns  immediately.  If
                       TimeOut is Nil, the kernel will wait forever, or until a status changed.

                     2.TimeOut is of type Longint.  If it is -1, this has the same effect as a Timeout of type
                       PTime which is Nil.  Otherwise, TimeOut contains a time in milliseconds.


                When the TimeOut is reached,  or one of the file descriptors has changed,  the Select call
                returns.  On return, it will have modified the entries in the array which have actually changed,
                and it returns the number of entries that have been changed.  If the timout was reached, and
                no decsriptor changed, zero is returned; The arrays of indexes are undefined after that.  On
                error, -1 is returned.

       Errors:   On error, the function returns -1, and Errors are reported in LinuxError :


                SYS__EBADF           An invalid descriptor was specified in one of the sets.

                SYS__EINTR          A non blocked signal was caught.

                SYS__EINVAL           N is negative or too big.

                SYS__ENOMEM              Select was unable to allocate memory for its internal tables.


    See also:    SelectText (1118   ), GetFS (1096   ), FD_ZERO (1086   ), FD_Clr (1086   ), FD_Set (1086   ), FD_IsSet
                (1086   )


                Listing:  ./olinuxex/ex33.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   Program       t o  d e m o n s t r a t et h e  S e l e c t f u n c t i o n.  }


                Uses     o l d l i n u x;


                Var    FDS     :  FDSet    ;


                 b e g i n
                    FD _Zero      (FDS   ) ;
                    FD _Set     ( 0 ,FDS   ) ;



                                                                                1117

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                    W r i t e l n ( ' P r e s s t h e < ENTER    >   t o  c o n t i n u e t h e  p r o g r a m.' ) ;
                    {  Wait     u n t i l  F i l e  d e s c r i p t o r0  ( = I n p u t)  c h a n g e s }
                    S e l e c t ( 1 ,@FDS    ,n i l ,n i l ,n i l ) ;
                    {  Get     r i d  o f < ENTER    >   i n  b u f f e r }
                    r e a d l n;
                    W r i t e l n ( ' P r e s s< ENTER    >   k e y  i n  l e s s  t h a n 2   s e c o n d s. . .') ;
                    FD _Zero      (FDS   ) ;
                    FD _Set     ( 0 ,FDS   ) ;
                    i f  S e l e c t ( 1 ,@FDS    , n i l, n i l, 2 0 0 0 ) > 0then
                        W r i t e l n(  'Thank     you    ! ' )
                       {   FD _ISSET     ( 0 ,FDS   )  w o u l d be    t r u e h e r e .  }
                    e l s e
                        W r i t e l n(  'Too    l a t e  ! ') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.89           SelectText

    Synopsis:    Wait for event on typed ontyped file.

Declaration:     function  SelectText(var  T:  Text;TimeOut:  ptimeval)  :  LongInt
                function  SelectText(var  T:  Text;TimeOut:  LongInt)  :  LongInt

    Visibility:   default

Description:     SelectText executes the Select (1116   ) call on a file of type Text.  You can specify a timeout
                in TimeOut.  The SelectText call determines itself whether it should check for read or write,
                depending on how the file was opened :  With Reset it is checked for reading, with Rewrite
                and Append it is checked for writing.

       Errors:   See Select (1116   ).  SYS_EBADF can also mean that the file wasn't opened.

    See also:    Select (1116   ), GetFS (1096   )



                31.12.90           SetDate

    Synopsis:    Set the current system date.

Declaration:     function  SetDate(Year:  Word;Month:  Word;Day:  Word)  :  Boolean

    Visibility:   default

Description:     SetDate sets the system date to year, month, day.  This is the kernel date, so it is in GMT.
                The time is not touched.  The function returns True if the call was executed corretly, False
                otherwise.

 Remark:         You must be root to execute this call.

       Errors:   Errors are returned in LinuxError (1062   )

    See also:    GetDate (1093   ), SetTime (1119   ), SetDateTime (1118   )



                31.12.91           SetDateTime

    Synopsis:    Set the current system date and time

Declaration:     function  SetDateTime(Year:  Word;Month:  Word;Day:  Word;hour:  Word;
                                                 minute:  Word;second:  Word)  :  Boolean



                                                                                1118

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



    Visibility:  default

Description:     SetDate sets the system date and time to year,  month,  day,  hour,  min,  Sec.  This is the
                kernel date/time,  so it is in GMT. The time is not touched.  The function returns True if
                the call was executed corretly, False otherwise.

 Remark:         You must be root to execute this call.

       Errors:   Errors are returned in LinuxError (1062   )

    See also:    SetDate (1118   ), SetTime (1119   ), GetDateTime (1093   )



                31.12.92           SetPriority

    Synopsis:    Set process priority

Declaration:     procedure  SetPriority(Which:  Integer;Who:  Integer;What:  Integer)

    Visibility:   default

Description:     SetPriority sets the priority with which a process is running.  Which process(es) is deter-
                mined by the Which and Who variables.  Which can be one of the pre-defined constants:


                Prio__Process       Who is interpreted as process ID

                Prio__PGrp       Who is interpreted as process group ID

                Prio__User      Who is interpreted as user ID


                Prio is a value in the range -20 to 20.

                For an example, see Nice (1111   ).

       Errors:   Error checking must be done on LinuxError, since a priority can be negative.


                sys__esrch    No process found using which and who.

                sys__einval    Which was not one of  Prio_Process, Prio_Grp or Prio_User.

                sys__eperm      A process was found, but neither its effective or real user ID match the effective
                       user ID of the caller.

                sys__eacces     A non-superuser tried to a priority increase.


    See also:    GetPriority (1099   ), Nice (1111   )



                31.12.93           SetTime

    Synopsis:    Set the current system time.

Declaration:     function  SetTime(Hour:  Word;Min:  Word;Sec:  Word)  :  Boolean

    Visibility:   default

Description:     SetTime sets the system time to hour, min, Sec.  This is the kernel time, so it is in GMT.
                The date is not touched.  The function returns True if the call was executed corretly, False
                otherwise.

 Remark:         You must be root to execute this call.

       Errors:   Errors are returned in LinuxError (1062   )

    See also:    GetTime (1100   ), SetDate (1118   ), SetDateTime (1118   )



                                                                                1119

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.94           Shell

    Synopsis:    Execute and feed command to system shell

Declaration:     function  Shell(const  Command:  string)  :  LongInt
                function  Shell(const  Command:  AnsiString)  :  LongInt

    Visibility:   default

Description:     Shell invokes the bash shell (/bin/sh),  and feeds it the command Command (using the -c
                option).  The function then waits for the command to complete, and then returns the exit
                status  of  the  command,  or  127  if  it  could  not  complete  the  Fork  (1088   )  or  Execve  (1079   )
                calls.

       Errors:   Errors are reported in LinuxError.

    See also:    POpen (1113   ), Fork (1088   ), Execve (1079   )


                Listing:  ./olinuxex/ex56.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 5 6;


                 u s e s o l d l i n u x;


                {   Program       t o  d e m o n s t r a t et h e  S h e l l  f u n c t i o n}


                Var    S   :   L o n g i n t;


                 b e g i n
                    W r i t e l n ( 'Output       o f  l s -  l  * . pp  ') ;
                    S := S h e l l  ( 'l s  - l   * .pp  ' ) ;
                    W r i t e l n ( 'Command        e x i t e d w w i t h s t a t u s :   ' ,S ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.95           SigAction

    Synopsis:    Install signal handler

Declaration:     procedure  SigAction(Signum:  LongInt;Act:  PSigActionRec;
                                                OldAct:  PSigActionRec)

    Visibility:   default

Description:     Changes  the  action  to  take  upon  receipt  of  a  signal.   Act  and  Oldact  are  pointers  to  a
                SigActionRec record.  SigNum specifies the signal, and can be any signal except SIGKILL
                or SIGSTOP.

                If Act is non-nil, then the new action for signal SigNum is taken from it.  If OldAct is non-nil,
                the old action is stored there.  Sa_Handler may be SIG_DFL for the default action or SIG_IGN
                to ignore the signal.  Sa_Mask Specifies which signals should be ignord during the execution
                of the signal handler.  Sa_Flags Speciefies a series of flags which modify the behaviour of the
                signal handler.  You can 'or' none or more of the following :


                SA__NOCLDSTOP                If signum is SIGCHLD do not receive notification when child processes
                       stop.

                SA__ONESHOT or SA__RESETHAND                               Restore the signal action to the default state once
                       the signal handler has been called.

                SA__RESTART            For compatibility with BSD signals.



                                                                                1120

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                SA__NOMASK or SA__NODEFER                           Do  not  prevent  the  signal  from  being  received  from
                      within its own signal handler.


       Errors:   LinuxError is used to report errors.


                sys__einval    an invalid signal was specified, or it was SIGKILL or SIGSTOP.

                sys__efault    Act,OldAct point outside this process address space

                sys__eintr   System call was interrupted.


    See also:    SigProcMask (1123   ), SigPending (1122   ), SigSuspend (1124   ), Kill (1104   )


                Listing:  ./olinuxex/ex57.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 5 7;


                {   Program       t o  d e m o n s t r a t et h e  S i g A c t i o n f u n c t i o n.}


                {
                do    a   k i l l- USR1      p i d f r o m  a n o t h e r t e r m i n a l t o  s e e  what     h a p p e n s.
                 r e p l a c e p i d  w i t h t h e  r e a l  p i d  o f  t h i s  p r o g r a m.
                You    c a n   g e t  t h i s p i d  by   r u n n i n g  'ps  ' .
                }


                 u s e s o l d l i n u x;


                Var
                      oa , na   :   P S i g A c t i o n R e;c


                 P r o c e d u r eDoSig    ( s i g  :  L o n g i n t) ;c d e c l;


                 b e g i n
                      w r i t e l n(' R e c e i v i n gs i g n a l:  ' , s i g) ;
                end   ;


                 b e g i n
                      new  ( na ) ;
                      new  ( oa ) ;
                      na ^ . H a n d l e r.s h:=  @DoSig    ;
                      na ^ . Sa _Mask    : = 0 ;
                      na ^ . S a _F l a g s: = 0 ;
                      na ^ . S a _R e s t o r e r:=N i l ;
                      S i g A c t i o(nS i g U s r 1,na  ,oa  ) ;
                      i f  L i n u x E r r o<r>0   then
                         b e g i n
                         w r i t e l n( 'E r r o r:  ' , l i n u x e r r o,r' . ') ;
                         h a l t( 1 ) ;
                         end   ;
                      W r i t e l n ( 'Send     USR1     s i g n a l o r  p r e s s < ENTER    >  t o   e x i t' ) ;
                      r e a d l n;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.96           Signal

    Synopsis:    Install signal handler (deprecated)

Declaration:     function  Signal(Signum:  LongInt;Handler:  SignalHandler)  :  SignalHandler



                                                                                1121

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



    Visibility:  default

Description:     Signal installs a new signal handler for signal SigNum.  This call has the same functionality
                as the SigAction call.  The return value for Signal is the old signal handler, or nil on error.

       Errors:   LinuxError is used to report errors :


                SIG__ERR       An error occurred.


    See also:    SigAction (1120   ), Kill (1104   )


                Listing:  ./olinuxex/ex58.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 5 8;


                {   Program       t o  d e m o n s t r a t et h e  S i g n a l f u n c t i o n.}


                {
                do    a   k i l l- USR1      p i d f r o m  a n o t h e r t e r m i n a l t o  s e e  what     h a p p e n s.
                 r e p l a c e p i d  w i t h t h e  r e a l  p i d  o f  t h i s  p r o g r a m.
                You    c a n   g e t  t h i s p i d  by   r u n n i n g  'ps  ' .
                }


                 u s e s o l d l i n u x;


                 P r o c e d u r eDoSig    ( s i g  :  L o n g i n t) ;c d e c l;


                 b e g i n
                      w r i t e l n(' R e c e i v i n gs i g n a l:  ' , s i g) ;
                end   ;


                 b e g i n
                      S i g N a l(S i g U s r 1,@DoSig     ) ;
                      i f  L i n u x E r r o<r>0   then
                         b e g i n
                         w r i t e l n( 'E r r o r:  ' , l i n u x e r r o,r' . ') ;
                         h a l t( 1 ) ;
                         end   ;
                      W r i t e l n ( 'Send     USR1     s i g n a l o r  p r e s s < ENTER    >  t o   e x i t' ) ;
                      r e a d l n;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.97           SigPending

    Synopsis:    Return set of currently pending signals

Declaration:     function  SigPending  :  SigSet

    Visibility:   default

Description:     Sigpending allows the examination of pending signals (which have been raised while blocked.)
                The signal mask of pending signals is returned.

       Errors:   None

    See also:    SigAction (1120   ), SigProcMask (1123   ), SigSuspend (1124   ), Signal (1121   ), Kill (1104   )



                                                                                1122

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.98           SigProcMask

    Synopsis:    Set list of blocked signals

Declaration:     procedure  SigProcMask(How:  LongInt;SSet:  PSigSet;OldSSet:  PSigSet)

    Visibility:   default

Description:     Changes the list of currently blocked signals.  The behaviour of the call depends on How :


                SIG__BLOCK           The set of blocked signals is the union of the current set and the SSet argu-
                       ment.

                SIG__UNBLOCK              The signals in SSet are removed from the set of currently blocked signals.

                SIG__SETMASK              The list of blocked signals is set so SSet.


                If  OldSSet is non-nil, then the old set is stored in it.

       Errors:   LinuxError is used to report errors.


                sys__efault    SSet or OldSSet point to an adress outside the range of the process.

                sys__eintr    System call was interrupted.


    See also:    SigAction (1120   ), SigPending (1122   ), SigSuspend (1124   ), Kill (1104   )



                31.12.99           SigRaise

    Synopsis:    Raise a signal (send to current process)

Declaration:     procedure  SigRaise(Sig:  Integer)

    Visibility:   default

Description:     SigRaise sends a Sig signal to the current process.

       Errors:   None.

    See also:    Kill (1104   ), GetPid (1098   )


                Listing:  ./olinuxex/ex65.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       e x a m p l e 6 4;


                {   Program       t o  d e m o n s t r a t et h e  S i g R a i s e f u n c t i o n.}


                 u s e s o l d l i n u x;


                Var
                      oa , na   :   P S i g A c t i o n R e;c


                 P r o c e d u r eDoSig    ( s i g  :  L o n g i n t) ;c d e c l;


                 b e g i n
                      w r i t e l n(' R e c e i v i n gs i g n a l:  ' , s i g) ;
                end   ;


                 b e g i n
                      new  ( na ) ;
                      new  ( oa ) ;
                      na ^ . h a n d l e r.s h:=  @DoSig    ;



                                                                                1123

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                      na ^ . Sa _Mask    : = 0 ;
                      na ^ . S a _F l a g s: = 0 ;
                      na ^ . S a _R e s t o r e r:=N i l ;
                      S i g A c t i o(nS i g U s r 1,na  ,oa  ) ;
                      i f  L i n u x E r r o<r>0   then
                         b e g i n
                         w r i t e l n( 'E r r o r:  ' , l i n u x e r r o,r' . ') ;
                         h a l t( 1 ) ;
                         end   ;
                      W r i t e l n('S e n d i n g USR1     ( ' ,s i g u s r 1, ')   s i g n a l t o  s e l f. ' ) ;
                      S i g R a i s e(s i g u s r 1) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.100            SigSuspend

    Synopsis:    Set signal mask and suspend process till signal is received

Declaration:     procedure  SigSuspend(Mask:  SigSet)

    Visibility:   default

Description:     SigSuspend temporarily replaces the signal mask for the process with the one given in Mask,
                and then suspends the process until a signal is received.

       Errors:   None

    See also:    SigAction (1120   ), SigProcMask (1123   ), SigPending (1122   ), Signal (1121   ), Kill (1104   )



                31.12.101            StringToPPChar

    Synopsis:    Split string in list of null-terminated strings

Declaration:     function  StringToPPChar(var  S:  string)  :  ppchar
                function  StringToPPChar(var  S:  AnsiString)  :  ppchar
                function  StringToPPChar(S:  Pchar)  :  ppchar

    Visibility:   default

Description:     StringToPPChar splits the string S in words, replacing any whitespace with zero characters.
                It returns a pointer to an array of pchars that point to the first letters of the words in S.
                This array is terminated by a Nil pointer.

                The function does not add a zero character to the end of the string unless it ends on whites-
                pace.

                The function reserves memory on the heap to store the array of PChar; The caller is respon-
                sible for freeing this memory.

                This function can be called to create arguments for the various Exec calls.

       Errors:   None.

    See also:    CreateShellArgV (1072   ), Execve (1079   ), Execv (1078   )


                Listing:  ./olinuxex/ex70.pp



                                                                                1124

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 0;


                {   Program       t o  d e m o n s t r a t et h e  S t r i n g T o P P c h a rf u n c t i o.n  }


                Uses     o l d l i n u x;


                Var    S   :   S t r i n g;
                       P   :  PPChar     ;
                        I  :   l o n g i n t;


                 b e g i n
                    //   r e m a r k  w h i t e s p a c ea t  end  .
                    S :=  'T h i s  i s  a   s t r i n g w i t h w o r d s.   ';
                    P := S t r i n g T o P P C h a(rS) ;
                    I : = 0 ;
                    While     P [ i]<>   N i l  do
                        b e g i n
                        W r i t e l n('Word     ' ,i , '   :  ' ,P [ i ] ) ;
                        I n c( I) ;
                       end   ;
                    FreeMem     ( P , i* S i z e O f(P c h a r) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.102            SymLink

    Synopsis:    Create a symbolic link

Declaration:     function  SymLink(OldPath:  PathStr;NewPath:  PathStr)  :  Boolean

    Visibility:   default

Description:     SymLink makes Newpath point to the file in OldPath, which doesn't necessarily exist.  The
                two files DO NOT have the same inode number.  This is known as a 'soft' link.

                The  permissions  of  the  link  are  irrelevant,  as  they  are  not  used  when  following  the  link.
                Ownership of the file is only checked in case of removal or renaming of the link.

                The function returns True if the call was succesfull, False if the call failed.

       Errors:   Errors are returned in LinuxError.


                sys__eperm      The filesystem containing oldpath and newpath does not support linking files.

                sys__eaccess     Write access for the directory containing  Newpath is disallowed,  or one of the
                       directories in OldPath or NewPath has no search (=execute) permission.

                sys__enoent      A  directory  entry  in  OldPath  or  NewPath  does  not  exist  or  is  a  symbolic  link
                       pointing to a non-existent directory.

                sys__enotdir      A directory entry in OldPath or NewPath is nor a directory.

                sys__enomem        Insufficient kernel memory.

                sys__erofs    The files are on a read-only filesystem.

                sys__eexist    NewPath already exists.

                sys__eloop     OldPath or NewPath has a reference to a circular symbolic link,  i.e.  a symbolic
                       link, whose expansion points to itself.

                sys__enospc      The device containing NewPath has no room for another entry.



                                                                                1125

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



    See also:    Link (1104   ), UnLink (1135   ), ReadLink (1115   )


                Listing:  ./olinuxex/ex22.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 2;


                {   Program       t o  d e m o n s t r a t et h e  SymLink       and    U n L i n k f u n c t i o n s. }


                Uses     o l d l i n u x;


                Var    F   :  T e x t ;
                       S   :   S t r i n g;


                 b e g i n
                    A s s i g n ( F , 't e s t. t x t' ) ;
                    R e w r i t e (F  ) ;
                    W r i t e l n (F  , 'T h i s  i s  w r i t t e n t o  t e s t. t x t' ) ;
                    C l o s e( f) ;
                    {  new   . t x t and     t e s t.t x t  a r e  now    t h e  same     f i l e }
                    i f  not    SymLink       ( ' t e s t. t x t' ,' new  . t x t' )  then
                        w r i t e l n(  'E r r o r when     s y m l i n k i n g! ' ) ;
                    {  Removing        t e s t. t x t  s t i l l  l e a v e snew   . t x t
                        P o i n t i n gnow    t o  a   non  - e x i s t e n t f i l e !   }
                    I f  not    U n l i n k (  't e s t. t x t' )  then
                        W r i t e l n(  'E r r o r when     u n l i n k i n g ! ') ;
                    A s s i g n ( f , 'new   .t x t ') ;
                    {   T h i s s h o u l d  f a i l,  s i n c e t h e  s y m b o l i c l i n k
                        p o i n t s t o  a  non  -  e x i s t e n tf i l e!  }
                    { $ i- }
                    R e s e t ( F ) ;
                    { $ i+ }
                    I f  I O R e s u l t=0  then
                        W r i t e l n(  'T h i s  s h o u l d n''t   h a p p e n') ;
                  {  Now     r e m o v e new  . t x t  a l s o }
                   I f not     U n l i n k ( 'new   .t x t ')   then
                      W r i t e l n ( 'E r r o r  when     u n l i n k i n g! ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.103            SysCall

    Synopsis:    Execute system call.

Declaration:     function  SysCall(callnr:  LongInt;var  regs:  SysCallRegs)  :  LongInt

    Visibility:   default

Description:     SysCall can be used to execute a direct system call.  The call parameters must be encoded
                in regs and the call number must be specified by callnr.  The call result is returned, and
                any modified registers are in regs

       Errors:   None.

    See also:    SysCallregs (1057   )



                31.12.104            Sysinfo

    Synopsis:    Return kernel system information



                                                                                1126

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



Declaration:     function  Sysinfo(var  Info:  TSysinfo)  :  Boolean

    Visibility:  default

Description:     SysInfo returns system information in Info.  Returned information in Info includes:


                uptime     Number of seconds since boot.

                loads   1, 5 and 15 minute load averages.

                totalram     total amount of main memory.

                freeram     amount of free memory.

                sharedram       amount of shared memory.

                bufferram      amount of memory used by buffers.

                totalswap      total amount of swapspace.

                freeswap     amount of free swapspace.

                procs   number of current processes.


       Errors:   None.

    See also:    Uname (1134   )


                Listing:  ./olinuxex/ex64.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 6 4;


                {   Example       t o  d e m o n s t r a t et h e  S y s I n f o f u n c t i o n }


                Uses     o l d l i n u x;


                 F u n c t i o nMb  (L   :   L o n g i n t)  :  l o n g i n t;


                 b e g i n
                    Mb :=  L   d i v ( 1 0 2 4 * 1 0 2 4 ) ;
                end   ;


                Var     I n f o :   T S y s I n f o;
                       D ,M  ,S e c s ,H   :  l o n g i n t;


                 b e g i n
                    I f  Not    S y s I n f o(I n f o)   then
                       H a l t ( 1 ) ;
                    With     I n f o do
                        b e g i n
                       D :=  Uptime      d i v  ( 3 6 0 0 * 2 4 ) ;
                       UpTime     := UpTime      mod    ( 3 6 0 0 * 2 4 ) ;
                       h :=  u p t i m e d i v  3 6 0 0 ;
                        u p t i m e:=u p t i m e mod    3 6 0 0 ;
                       m :=  u p t i m e d i v  6 0 ;
                        s e c s:= u p t i m e mod    6 0 ;
                        W r i t e l n('Uptime       :  ' ,d , ' d a y s,  ' ,h , '   h o u r s,  ' ,m , '  min   ,  ' ,s e c s ,'  *
 * s. ' ) ;
                        W r i t e l n('L o a d s    :  ' ,L o a d s[ 1 ] ,' / ' ,L o a d s[ 2 ] ,'/  ', L o a d s[ 3 ] ) ;
                        W r i t e l n('T o t a l Ram       :  ' ,Mb  ( t o t a l r a m) ,'Mb . ' ) ;
                        W r i t e l n('F r e e  Ram        :  ' ,Mb  ( f r e e r a m) ,'Mb  . ') ;
                        W r i t e l n('S h a r e d Ram     :  ' ,Mb  ( s h a r e d r a)m, 'Mb  . ' ) ;
                        W r i t e l n('B u f f e r Ram     :  ' ,Mb  ( b u f f e r r a)m, 'Mb  . ' ) ;
                        W r i t e l n('T o t a l Swap      :  ' ,Mb  ( t o t a l s w a)p, 'Mb  . ' ) ;
                        W r i t e l n('F r e e  Swap       :  ' ,Mb  ( f r e e s w a p) ,'Mb . ' ) ;



                                                                                1127

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.105            S__ISBLK

    Synopsis:    Is file a block device

Declaration:     function  S_ISBLK(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISBLK checks the file mode m to see whether the file is a block device file.  If so it returns
                True.

    See also:    FStat (1092   ), S_ISLNK (1129   ), S_ISREG (1129   ), S_ISDIR (1128   ), S_ISCHR (1128   ), S_ISFIFO
                (1128   ), S_ISSOCK (1130   )



                31.12.106            S__ISCHR

    Synopsis:    Is file a character device

Declaration:     function  S_ISCHR(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISCHR  checks  the  file  mode  m  to  see  whether  the  file  is  a  character  device  file.  If  so  it
                returns True.

    See also:    FStat (1092   ), S_ISLNK (1129   ), S_ISREG (1129   ), S_ISDIR (1128   ), S_ISBLK (1128   ), S_ISFIFO
                (1128   ), S_ISSOCK (1130   )



                31.12.107            S__ISDIR

    Synopsis:    Is file a directory

Declaration:     function  S_ISDIR(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISDIR checks the file mode m to see whether the file is a directory.  If so it returns True

    See also:    FStat (1092   ), S_ISLNK (1129   ), S_ISREG (1129   ), S_ISCHR (1128   ), S_ISBLK (1128   ), S_ISFIFO
                (1128   ), S_ISSOCK (1130   )



                31.12.108            S__ISFIFO

    Synopsis:    Is file a FIFO

Declaration:     function  S_ISFIFO(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISFIFO  checks  the  file  mode  m  to  see  whether  the  file  is  a  fifo  (a  named  pipe).  If  so  it
                returns True.

    See also:    FStat (1092   ), S_ISLNK (1129   ), S_ISREG (1129   ), S_ISCHR (1128   ), S_ISBLK (1128   ), S_ISDIR
                (1128   ), S_ISSOCK (1130   )



                                                                                1128

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.109            S__ISLNK

    Synopsis:    Is file a symbolic link

Declaration:     function  S_ISLNK(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISLNK checks the file mode m to see whether the file is a symbolic link.  If so it returns
                True

    See also:    FStat (1092   ), S_ISFIFO (1128   ), S_ISREG (1129   ), S_ISCHR (1128   ), S_ISBLK (1128   ), S_ISDIR
                (1128   ), S_ISSOCK (1130   )


                Listing:  ./olinuxex/ex53.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 3;


                {   Program       t o  d e m o n s t r a t et h e  S _ISLNK      f u n c t i o n. }


                Uses     o l d l i n u x;


                Var     I n f o :   S t a t;


                 b e g i n
                    i f  L S t a t  (p a r a m s t r( 1 ) ,i n f o)  then
                        b e g i n
                        i f  S _ISLNK    ( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e i s  a   l i n k' ) ;
                        i f  S _ISREG    ( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e i s  a   r e g u l a r f i l e' ) ;
                        i f  S _I S D I R( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e i s  a   d i r e c t o r y') ;
                        i f  S _ISCHR    ( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e i s  a   c h a r a c t e rd e v i c e  f i l e') ;
                        i f  S _ISBLK    ( i n f o.mode    )  then
                           W r i t e l n ( ' F i l e i s  a   b l o c k d e v i c e  f i l e') ;
                        i f  S _I S F I F O( i n f o.mode   )   then
                           W r i t e l n ( ' F i l e i s  a   named     p i p e  ( FIFO   ) ') ;
                        i f  S _ISSOCK     ( i n f o.mode   )   then
                           W r i t e l n ( ' F i l e i s  a   s o c k e t') ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.110            S__ISREG

    Synopsis:    Is file a regular file

Declaration:     function  S_ISREG(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISREG checks the file mode m to see whether the file is a regular file.  If so it returns True

    See also:    FStat (1092   ), S_ISFIFO (1128   ), S_ISLNK (1129   ), S_ISCHR (1128   ), S_ISBLK (1128   ), S_ISDIR
                (1128   ), S_ISSOCK (1130   )



                                                                                1129

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.111            S__ISSOCK

    Synopsis:    Is file a unix socket

Declaration:     function  S_ISSOCK(m:  Word)  :  Boolean

    Visibility:   default

Description:     S_ISSOCK checks the file mode m to see whether the file is a socket.  If so it returns True.

    See also:    FStat (1092   ), S_ISFIFO (1128   ), S_ISLNK (1129   ), S_ISCHR (1128   ), S_ISBLK (1128   ), S_ISDIR
                (1128   ), S_ISREG (1129   )



                31.12.112            TCDrain

    Synopsis:    Terminal control:  Wait till all data was transmitted

Declaration:     function  TCDrain(fd:  LongInt)  :  Boolean

    Visibility:   default

Description:     TCDrain waits until all data to file descriptor Fd is transmitted.

                The function returns True if the call was succesfull, False otherwise.

       Errors:   Errors are reported in LinuxError

    See also:    TCFlow  (1130   ),  TCFlush  (1131   ),  TCGetAttr  (1131   ),  TCGetPGrp  (1132   ),  TCSendBreak
                (1132   ), TCSetAttr (1132   ), TCSetPGrp (1133   ), TTYName (1134   ), IsATTY (1104   )



                31.12.113            TCFlow

    Synopsis:    Terminal control:  Suspend transmission of data

Declaration:     function  TCFlow(fd:  LongInt;act:  LongInt)  :  Boolean

    Visibility:   default

Description:     TCFlow  suspends/resumes  transmission  or  reception  of  data  to  or  from  the  file  descriptor
                Fd, depending on the action Act.

                This can be one of the following pre-defined values:


                TCOOFF         suspend reception/transmission

                TCOON         resume reception/transmission

                TCIOFF        transmit a stop character to stop input from the terminal

                TCION       transmit start to resume input from the terminal.


                The function returns True if the call was succesfull, False otherwise.

       Errors:   Errors are reported in LinuxError.

    See also:    TCDrain (1130   ), TCFlush (1131   ), TCGetAttr (1131   ), TCGetPGrp (1132   ), TCSendBreak
                (1132   ), TCSetAttr (1132   ), TCSetPGrp (1133   ), TTYName (1134   ), IsATTY (1104   )



                                                                                1130

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.114            TCFlush

    Synopsis:    Terminal control:  Discard data buffer

Declaration:     function  TCFlush(fd:  LongInt;qsel:  LongInt)  :  Boolean

    Visibility:   default

Description:     TCFlush discards all data sent or received to/from file descriptor fd.  QSel indicates which
                queue should be discard.  It can be one of the following pre-defined values :


                TCIFLUSH           input buffer

                TCOFLUSH            output buffer

                TCIOFLUSH             both input and output buffers


                The function returns True if the call was succesfull, False otherwise.

       Errors:   Errors are reported in LinuxError.

    See also:    TCDrain  (1130   ),  TCFlow  (1130   ),  TCGetAttr  (1131   ),  TCGetPGrp  (1132   ),  TCSendBreak
                (1132   ), TCSetAttr (1132   ), TCSetPGrp (1133   ), TTYName (1134   ), IsATTY (1104   )



                31.12.115            TCGetAttr

    Synopsis:    Terminal Control:  Get terminal attributes

Declaration:     function  TCGetAttr(fd:  LongInt;var  tios:  Termios)  :  Boolean

    Visibility:   default

Description:     TCGetAttr gets the terminal parameters from the terminal referred to by the file descriptor
                fd and returns them in a TermIOS structure tios.  The function returns True if the call was
                succesfull, False otherwise.

       Errors:   Errors are reported in LinuxError

    See also:    TCDrain  (1130   ),  TCFlow  (1130   ),  TCFlush  (1131   ),  TCGetPGrp  (1132   ),  TCSendBreak
                (1132   ), TCSetAttr (1132   ), TCSetPGrp (1133   ), TTYName (1134   ), IsATTY (1104   )


                Listing:  ./olinuxex/ex55.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 5;


                 u s e s o l d l i n u x;


                {   Program       t o  d e m o n s t r a t et h e  T C G e t A t t r/T C S e t A t t/rCFMakeRaw         f u n c t i*
 * o n.s }


                 p r o c e d u r eShowTermios        ( v a r  t i o s: T e r m i o s) ;
                 b e g i n
                    WriteLn     ( ' I n p u t F l a g s    :  $ ' ,h e x s t r( t i o s.c _i f l a g, 8 ) + # 1 3 ) ;
                    WriteLn     ( ' Output      F l a g s  :  $ ' ,h e x s t r( t i o s.c _o f l a g, 8 ) ) ;
                    WriteLn     ( ' L i n e  F l a g s     :  $ ' ,h e x s t r( t i o s.c _l f l a g, 8 ) ) ;
                    WriteLn     ( ' C o n t r o l F l a g s:  $ ' ,h e x s t r( t i o s.c _c f l a g, 8 ) ) ;
                end   ;


                 v a r
                    o l d i o s,
                    t i o s  :  T e r m i o s;
                 b e g i n



                                                                                1131

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                    WriteLn     ( ' Old    a t t r i b u t e:s' ) ;
                    T C G e t A t t r( 1 ,t i o s) ;
                    ShowTermios        ( t i o s) ;
                    o l d i o s:= t i o s;
                    W r i t e l n(' S e t t i n g raw    t e r m i n a lmode    ') ;
                    CFMakeRaw       ( t i o s) ;
                    T C S e t A t t r( 1T,CSANOW     , t i o s) ;
                    WriteLn     ( ' C u r r e n t a t t r i b u t e:s' ) ;
                    T C G e t A t t r( 1 ,t i o s) ;
                    ShowTermios        ( t i o s) ;
                    T C S e t A t t r( 1T,CSANOW     , o l d i o s) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.116            TCGetPGrp

    Synopsis:    Terminal control:  Get process group

Declaration:     function  TCGetPGrp(fd:  LongInt;var  id:  LongInt)  :  Boolean

    Visibility:   default

Description:     TCGetPGrp returns the process group ID of a foreground process group in Id The function
                returns True if the call was succesfull, False otherwise.

       Errors:   Errors are reported in LinuxError

    See also:    TCDrain (1130   ), TCFlow (1130   ), TCFlush (1131   ), TCGetAttr (1131   ), TCSendBreak (1132   ),
                TCSetAttr (1132   ), TCSetPGrp (1133   ), TTYName (1134   ), IsATTY (1104   )



                31.12.117            TCSendBreak

    Synopsis:    Terminal control:  Send break

Declaration:     function  TCSendBreak(fd:  LongInt;duration:  LongInt)  :  Boolean

    Visibility:   default

Description:     TCSendBreak Sends zero-valued bits on an asynchrone serial connection decsribed by file-
                descriptor Fd, for duration Duration.  The function returns True if the action was performed
                successfully, False otherwise.

       Errors:   Errors are reported in LinuxError.

    See also:    TCDrain (1130   ), TCFlow (1130   ), TCFlush (1131   ), TCGetAttr (1131   ), TCGetPGrp (1132   ),
                TCSetAttr (1132   ), TCSetPGrp (1133   ), TTYName (1134   ), IsATTY (1104   )



                31.12.118            TCSetAttr

    Synopsis:    Terminal control:  Set attributes

Declaration:     function  TCSetAttr(fd:  LongInt;OptAct:  LongInt;const  tios:  Termios)
                                                :  Boolean

    Visibility:   default



                                                                                1132

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



Description:     TCSetAttr  sets  the  terminal  parameters  you  specify  in  a  TermIOS  structureTios  for  the
                terminal referred to by the file descriptor Fd.

                OptAct specifies an optional action when the set need to be done, this could be one of the
                following pre-defined values:


                TCSANOW            set immediately.

                TCSADRAIN             wait for output.

                TCSAFLUSH            wait for output and discard all input not yet read.


                The function Returns True if the call was succesfull, False otherwise.

                For an example, see TCGetAttr (1131   ).

       Errors:   Errors are reported in LinuxError.

    See also:    TCDrain (1130   ), TCFlow (1130   ), TCFlush (1131   ), TCGetAttr (1131   ), TCGetPGrp (1132   ),
                TCSendBreak (1132   ), TCSetPGrp (1133   ), TTYName (1134   ), IsATTY (1104   )



                31.12.119            TCSetPGrp

    Synopsis:    Terminal control:  Set process group

Declaration:     function  TCSetPGrp(fd:  LongInt;id:  LongInt)  :  Boolean

    Visibility:   default

Description:     TCSetPGrp  Sets  the  Process  Group  Id  to  Id.   The  function  returns  True  if  the  call  was
                successful, False otherwise.

                For an example, see TCGetPGrp (1132   ).

       Errors:   Errors are returned in LinuxError.

    See also:    TCDrain (1130   ), TCFlow (1130   ), TCFlush (1131   ), TCGetAttr (1131   ), TCGetPGrp (1132   ),
                TCSendBreak (1132   ), TCSetAttr (1132   ), TTYName (1134   ), IsATTY (1104   )



                31.12.120            TellDir

    Synopsis:    Return current location in a directory

Declaration:     function  TellDir(p:  PDir)  :  LongInt

    Visibility:   default

Description:     TellDir returns the current location in the directory structure pointed to by p.  It returns
                -1 on failure.

                For an example, see OpenDir (1112   ).

       Errors:   Errors are returned in LinuxError.

    See also:    CloseDir (1072   ), ReadDir (1114   ), SeekDir (1116   ), OpenDir (1112   )



                                                                                1133

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.121            TTYname

    Synopsis:    Terminal control:  Get terminal name

Declaration:     function  TTYname(Handle:  LongInt)  :  string
                function  TTYname(var  F:  Text)  :  string

    Visibility:   default

Description:     TTYNameReturns the name of the terminal pointed to by f.  f must be a terminal.  f can be
                of type:

                     1.longint for file handles;

                     2.Text for text variables such as input etc.

       Errors:   Returns an empty string in case of an error.  Linuxerror may be set to indicate what error
                occurred, but this is uncertain.

    See also:    TCDrain (1130   ), TCFlow (1130   ), TCFlush (1131   ), TCGetAttr (1131   ), TCGetPGrp (1132   ),
                TCSendBreak (1132   ), TCSetAttr (1132   ), TCSetPGrp (1133   ), IsATTY (1104   ), IOCtl (1102   )



                31.12.122            Umask

    Synopsis:    Set file creation mask.

Declaration:     function  Umask(Mask:  Integer)  :  Integer

    Visibility:   default

Description:     Change the file creation mask for the current user to Mask.  The current mask is returned.

    See also:    Chmod (1067   )


                Listing:__./olinuxex/ex27.pp_______________________________________________________________________________________*
 *___________

                Program       E x a m p l e 2 7;


                {   Program       t o  d e m o n s t r a t et h e  Umask      f u n c t i o n. }


                Uses     o l d l i n u x;


                 b e g i n
                    W r i t e l n ( 'Old    Umask      was    :   ', Umask    (O c t a l( 1 1 1 ) ) ) ;
                    WRiteln       ( 'New    Umask      i s    :   ', O c t a l( 1 1 1 ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.123            Uname

    Synopsis:    Return system name.

Declaration:     function  Uname(var  unamerec:  utsname)  :  Boolean

    Visibility:   default

Description:     Uname  gets  the  name  and  configuration  of  the  current  linux  kernel,  and  returns  it  in
                unamerec.

       Errors:   LinuxError is used to report errors.

    See also:    GetHostName (1097   ), GetDomainName (1094   )



                                                                                1134

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.124            UnLink

    Synopsis:    Unlink (i.e.  remove) a file.

Declaration:     function  UnLink(Path:  PathStr)  :  Boolean
                function  UnLink(Path:  pchar)  :  Boolean

    Visibility:   default

Description:     UnLink decreases the link count on file Path.  Path can be of type PathStr or PChar.  If the
                link count is zero,  the file is removed from the disk.  The function returns True if the call
                was succesfull, False if the call failed.

                For an example, see Link (1104   ).

       Errors:   Errors are returned in LinuxError.


                sys__eaccess     You have no write access right in the directory containing Path, or you have no
                       search permission in one of the directory components of  Path.

                sys__eperm      The directory containing pathname has the sticky-bit set and the process's effec-
                       tive uid is neither the uid of the file to be deleted nor that of the directory containing
                       it.

                sys__enoent      A component of the path doesn't exist.

                sys__enotdir      A directory component of the path is not a directory.

                sys__eisdir    Path refers to a directory.

                sys__enomem        Insufficient kernel memory.

                sys__erofs    Path is on a read-only filesystem.


    See also:    Link (1104   ), SymLink (1125   )



                31.12.125            Utime

    Synopsis:    Set access and modification times of a file (touch).

Declaration:     function  Utime(const  path:  PathStr;utim:  UTimeBuf)  :  Boolean

    Visibility:   default

Description:     Utime  sets  the  access  and  modification  times  of  a  file.   the  utimbuf  record  contains  2
                fields, actime, and modtime, both of type Longint.  They should be filled with an epoch-like
                time, specifying, respectively, the last access time, and the last modification time.  For some
                filesystem (most notably, FAT), these times are the same.

       Errors:   Errors are returned in LinuxError.


                sys__eaccess     One of the directories in Path has no search (=execute) permission.

                sys__enoent      A  directory  entry  in  Path  does  not  exist  or  is  a  symbolic  link  pointing  to  a
                       non-existent directory.


                Other errors may occur, but aren't documented.

    See also:    GetEpochTime (1095   ), Chown (1069   ), Access (1062   )


                Listing:  ./olinuxex/ex25.pp



                                                                                1135

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 5;


                {   Program       t o  d e m o n s t r a t et h e  UTime      f u n c t i o n. }


                Uses     o l d l i n u x;


                Var     u t i m :   u t i m b u f;
                        y e a r,month    , day  , h o u r,m i n u t e, s e c o n d :  Word   ;


                 b e g i n
                    {   S e t  a c c e s s and    m o d i f i c a t i o nt i m e o f  e x e c u t a b l e s o u r c e}
                    GetTime       ( h o u r,m i n u t e, s e c o n d) ;
                    G e t D a t e ( y e a r,month    , day  ) ;
                    u t i m. a c t i m e:= L o c a l T o E p o c(hy e a r,month    ,day   ,h o u r ,m i n u t e,s e c o n d) ;
                    u t i m. modtime     := u t i m .a c t i m e;
                    i f  not    Utime    ( 'e x 2 5 .pp  ' ,u t i m)   then
                        w r i t e l n(  'C a l l  t o  UTime      f a i l e d ! ')
                    e l s e
                        b e g i n
                       Write      ( 'S e t   a c c e s s and    m o d i f i c a t i o nt i m e s t o  :   ') ;
                       Write      ( Hour   : 2 ,' : ', m i n u t e: 2 ,': ' , s e c o n d,' ,  ' ) ;
                        W r i t e l n( Day   : 2 ,'/ ' ,month    : 2 , '/ ' , y e a r: 4 ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                31.12.126            WaitPid

    Synopsis:    Wait for a process to terminate

Declaration:     function  WaitPid(Pid:  LongInt;Status:  pointer;Options:  LongInt)
                                            :  LongInt

    Visibility:   default

Description:     WaitPid waits for a child process with process ID Pid to exit.  The value of Pid can be one
                of the following:

                Pid < -1    Causes  WaitPid  to  wait  for  any  child  process  whose  process  group  ID  equals  the
                       absolute value of  pid.

                Pid = -1      Causes WaitPid to wait for any child process.

                Pid = 0      Causes WaitPid to wait for any child process whose process group ID equals the
                       one of the calling process.

                Pid > 0     Causes WaitPid to wait for the child whose process ID equals the value of  Pid.

                The Options parameter can be used to specify further how WaitPid behaves:

                WNOHANG              Causes Waitpid to return immediately if no child hasexited.

                WUNTRACED                Causes WaitPid to return also for children which are stopped, but whose
                       status has not yet been reported.

                ____WCLONE         Causes WaitPid also to wait for threads created by the Clone (1070   ) call.

                Upon return, it returns the exit status of the process, or -1 in case of failure.

                For an example, see Fork (1088   ).

       Errors:   Errors are returned in LinuxError.

    See also:    Fork (1088   ), Execve (1079   )



                                                                                1136

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.127            WaitProcess

    Synopsis:    Wait for process to terminate.

Declaration:     function  WaitProcess(Pid:  LongInt)  :  LongInt

    Visibility:   default

Description:     WaitProcess  waits  for  process  PID  to  exit.   WaitProcess  is  equivalent  to  the  WaitPID
                (1136   ) call:


                WaitPid(PID,@result,0)


                Handles of Signal interrupts (errno=EINTR), and returns the Exitcode of Process PID (>=0)
                or -Status if it was terminated

       Errors:   None.

    See also:    WaitPID  (1136   ),  WTERMSIG  (1138   ),  WSTOPSIG  (1138   ),  WIFEXITED  (1137   ),  WIF-
                STOPPED (1138   ), WIFSIGNALED (1138   ), W_EXITCODE (1139   ), W_STOPCODE (1139   ),
                WEXITSTATUS (1137   )



                31.12.128            WEXITSTATUS

    Synopsis:    Extract the exit status from the WaitPID (1136   ) result.

Declaration:     function  WEXITSTATUS(Status:  Integer)  :  Integer

    Visibility:   default

Description:     WEXITSTATUS can be used to extract the exit status from Status, the result of the WaitPID
                (1136   ) call.

    See also:    WaitPID (1136   ), WaitProcess (1137   ), WTERMSIG (1138   ), WSTOPSIG (1138   ), WIFEX-
                ITED (1137   ), WIFSTOPPED (1138   ), WIFSIGNALED (1138   ), W_EXITCODE (1139   ), W_STOPCODE
                (1139   )



                31.12.129            WIFEXITED

    Synopsis:    Check whether the process exited normally

Declaration:     function  WIFEXITED(Status:  Integer)  :  Boolean

    Visibility:   default

Description:     WIFEXITED checks Status and returns True if the status indicates that the process termi-
                nated normally, i.e.  was not stopped by a signal.

    See also:    WaitPID  (1136   ),  WaitProcess  (1137   ),  WTERMSIG  (1138   ),  WSTOPSIG  (1138   ),  WIF-
                STOPPED (1138   ), WIFSIGNALED (1138   ), W_EXITCODE (1139   ), W_STOPCODE (1139   ),
                WEXITSTATUS (1137   )



                                                                                1137

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.130            WIFSIGNALED

    Synopsis:    Check whether the process was exited by a signal.

Declaration:     function  WIFSIGNALED(Status:  Integer)  :  Boolean

    Visibility:   default

Description:     WIFSIGNALED returns True if Status indicates that the process exited because it received a
                signal.

    See also:    WaitPID (1136   ), WaitProcess (1137   ), WTERMSIG (1138   ), WSTOPSIG (1138   ), WIFEX-
                ITED (1137   ), WIFSTOPPED (1138   ), W_EXITCODE (1139   ), W_STOPCODE (1139   ), WEX-
                ITSTATUS (1137   )



                31.12.131            WIFSTOPPED

    Synopsis:    Check whether the process is currently stopped.

Declaration:     function  WIFSTOPPED(Status:  Integer)  :  Boolean

    Visibility:   default

Description:     WIFSTOPPED  checks  Status  and  returns  true  if  the  process  is  currently  stopped.  This  is
                only possible if WUNTRACED was specified in the options of WaitPID (1136   ).

    See also:    WaitPID (1136   ), WaitProcess (1137   ), WTERMSIG (1138   ), WSTOPSIG (1138   ), WIFEX-
                ITED (1137   ), WIFSIGNALED (1138   ), W_EXITCODE (1139   ), W_STOPCODE (1139   ), WEX-
                ITSTATUS (1137   )



                31.12.132            WSTOPSIG

    Synopsis:    Return the exit code from the process.

Declaration:     function  WSTOPSIG(Status:  Integer)  :  Integer

    Visibility:   default

Description:     WSTOPSIG is an alias for WEXITSTATUS (1137   ).

    See also:    WaitPID  (1136   ),  WaitProcess  (1137   ),  WTERMSIG  (1138   ),  WIFEXITED  (1137   ),  WIF-
                STOPPED (1138   ), WIFSIGNALED (1138   ), W_EXITCODE (1139   ), W_STOPCODE (1139   ),
                WEXITSTATUS (1137   )



                31.12.133            WTERMSIG

    Synopsis:    Return the signal that caused a process to exit.

Declaration:     function  WTERMSIG(Status:  Integer)  :  Integer

    Visibility:   default

Description:     WTERMSIG extracts from Status the signal number which caused the process to exit.

    See also:    WaitPID  (1136   ),  WaitProcess  (1137   ),  WSTOPSIG  (1138   ),  WIFEXITED  (1137   ),  WIF-
                STOPPED (1138   ), WIFSIGNALED (1138   ), W_EXITCODE (1139   ), W_STOPCODE (1139   ),
                WEXITSTATUS (1137   )



                                                                                1138

                ______________________________________________________CHAPTER_31.___REFERENCE_FOR_UNIT_'OLDLINUX'__________________*
 *___________________



                31.12.134            W__EXITCODE

    Synopsis:    Construct an exit status based on an return code and signal.

Declaration:     function  W_EXITCODE(ReturnCode:  Integer;Signal:  Integer)  :  Integer

    Visibility:   default

Description:     W_EXITCODE combines ReturnCode and Signal to a status code fit for WaitPid.

    See also:    WaitPID (1136   ), WaitProcess (1137   ), WTERMSIG (1138   ), WSTOPSIG (1138   ), WIFEX-
                ITED (1137   ), WIFSTOPPED (1138   ), WIFSIGNALED (1138   ), W_STOPCODE (1139   ), WEX-
                ITSTATUS (1137   )



                31.12.135            W__STOPCODE

    Synopsis:    Construct an exit status based on a signal.

Declaration:     function  W_STOPCODE(Signal:  Integer)  :  Integer

    Visibility:   default

Description:     W_STOPCODE constructs an exit status based on Signal, which will cause WIFSIGNALED
                (1138   ) to return True

    See also:    WaitPID (1136   ), WaitProcess (1137   ), WTERMSIG (1138   ), WSTOPSIG (1138   ), WIFEX-
                ITED (1137   ), WIFSTOPPED (1138   ), WIFSIGNALED (1138   ), W_EXITCODE (1139   ), WEX-
                ITSTATUS (1137   )



                                                                                1139




Chapter   32



Reference   for   unit   'ports'



32.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.



32.2          Constants,  types  and  variables



32.2.1         Variables

port  :  tport


Default instance of type TPort (1141   ).  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 (1141   ).  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



                                                            1140

                ____________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'PORTS'_______________*
 *___________________



                portl  :  tportl


                Default instance of type TPortL (1142   ).  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 (1142   ).  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



                32.3          tport



                32.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 (1140   ), TPortW (1142   ), TPortL (1142   )



                32.3.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __1141______pp______________rw___________Access_integer-sized_port_by_port_number__________________________________*
 *___________



                32.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



                                                                                1141

                ____________________________________________________________CHAPTER_32.___REFERENCE_FOR_UNIT_'PORTS'_______________*
 *___________________



                32.4          tportl



                32.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 (1141   ), TPort (1141   ), TPortL (1142   )



                32.4.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __1142______pp______________rw___________Access_Longint-sized_port_by_port_number__________________________________*
 *___________



                32.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



                32.5          tportw



                32.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 (1141   ), TPort (1141   ), TPortL (1142   )



                32.5.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __1142______pp______________rw___________Access_word-sized_port_by_port_number_____________________________________*
 *___________



                32.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



                                                                                1142




                Chapter   33



                Reference   for   unit   'printer'



                33.1          Overview


                This chapter describes the PRINTER unit for Free Pascal.  It was written for dos by Florian
                Klaempfl,  and  it  was  written  for  linux  by  Michael  Van  Canneyt,  and  has  been  ported  to
                Windows  and  os/2  as  well.   Its  basic  functionality  is  the  same  for  al  supported  systems,
                although there are minor differences on linux/unix.



                33.2          Constants,  types  and  variables



                33.2.1         Variables

                Lst  :  text


                Lst is the standard printing device.
                On linux, Lst is set up using AssignLst('/tmp/PID.lst').



                33.3          Procedures  and  functions



                33.3.1         AssignLst

    Synopsis:    Assign text file to printing device

Declaration:     procedure  AssignLst(var  F:  text;ToFile:  string)

    Visibility:   default

Description:     AssignLst Assigns to F a printing device - Unix only.  ToFile is a string with the following
                form:


                      o'_filename  options' :  This sets up a pipe with the program filename, with the given
                       options, such as in the popen() call.

                      o'filename' : Prints to file filename.  Filename can contain the string 'PID' (No Quotes),
                       which will be replaced by the PID of your program.  When closing lst, the file will be
                       sent to lpr and deleted.  (lpr should be in PATH)

                      o{'filename_'}  Idem  as  previous,  only  the  file  is  NOT  sent  to  lpr,  nor  is  it  deleted.
                       (useful for opening /dev/printer or for later printing)



                                                                            1143

                ________________________________________________________CHAPTER_33.___REFERENCE_FOR_UNIT_'PRINTER'_________________*
 *___________________



    See also:    lst (1143   )


                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___.____________________________________________________________________________________________________________*
 *___________



                33.3.2         InitPrinter

    Synopsis:    Initialize the printer

Declaration:     procedure  InitPrinter(const  PrinterName:  string)

    Visibility:   default

Description:     Initialize the printer



                33.3.3         IsLstAvailable

    Synopsis:    Determine whether printer is available.

Declaration:     function  IsLstAvailable  :  Boolean

    Visibility:   default

Description:     Determine whether printer is available.



                                                                                1144




Chapter   34



Reference   for   unit   'Sockets'



34.1          Used  units



                                    Table 34.1:  Used units by unit 'Sockets'


                                                 __Name______________Page____
                                                   baseunix           102
                                                   System            1230
                                                   UnixType          1715



34.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.



34.3          Constants,  types  and  variables



34.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



                                                            1145

________________________________________________________CHAPTER_34.___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



                                                                1146

________________________________________________________CHAPTER_34.___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



                                                                1147

________________________________________________________CHAPTER_34.___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



                                                                1148

________________________________________________________CHAPTER_34.___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.



                                                                1149

________________________________________________________CHAPTER_34.___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.



                                                                1150

________________________________________________________CHAPTER_34.___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 ?



                                                                1151

________________________________________________________CHAPTER_34.___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



                                                                1152

________________________________________________________CHAPTER_34.___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



                                                                1153

________________________________________________________CHAPTER_34.___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



                                                                1154

________________________________________________________CHAPTER_34.___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



                                                                1155

________________________________________________________CHAPTER_34.___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



                                                                1156

________________________________________________________CHAPTER_34.___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



                                                                1157

________________________________________________________CHAPTER_34.___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



                                                                1158

________________________________________________________CHAPTER_34.___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



                                                                1159

________________________________________________________CHAPTER_34.___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



                                                                1160

________________________________________________________CHAPTER_34.___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 (1171   ) call.


SOCK_RAW  =  3


Type of socket:  raw socket


SOCK_RDM  =  4


Type of socket:  reliably-delivered message


SOCK_SEQPACKET  =  5



                                                                1161

________________________________________________________CHAPTER_34.___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



                                                                1162

________________________________________________________CHAPTER_34.___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



                                                                1163

________________________________________________________CHAPTER_34.___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



                                                                1164

________________________________________________________CHAPTER_34.___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



                                                                1165

________________________________________________________CHAPTER_34.___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



34.3.2         Types

in6_addr  =  packed  record
end



Record used to describe a general IPV6 address.


in_addr  =  packed  record
end



General inet socket address.


linger  =  packed  record
    l_onoff  :  cint;
    l_linger  :  cint;
end



This record is used in the fpsetsockopt (1180   ) call to specify linger options.


PIn6Addr  =  pin6_addr


Pointer to in6_addr (1166   ) type.


pin6_addr  =  ^in6_addr


Pointer to Tin6_addr (1168   )


PInAddr  =  pin_addr


Alias for pin_addr (1167   )



                                                                1166

________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



PInetSockAddr  =  psockaddr_in


Pointer to sockaddr_in (1167   )


PInetSockAddr6  =  psockaddr_in6


Pointer to sockaddr_in6 (1168   ) type


pin_addr  =  ^in_addr


Pointer to in_addr (1166   ) record.


plinger  =  ^linger


Pointer to linger (1166   ) type.


psockaddr  =  ^sockaddr


Pointer to TSockAddr (1168   )


psockaddr_in  =  ^sockaddr_in


Pointer to sockaddr_in (1167   )


psockaddr_in6  =  ^sockaddr_in6


Pointer to sockaddr_in6 (1168   )


psockaddr_un  =  ^sockaddr_un


Pointer to sockaddr_un (1168   ) type.


sa_family_t  =  cushort


Address family type


sockaddr  =  packed  record
end



sockaddr is used to store a general socket addres for the Bind (1171   ), Recv (102  ) and Send
(102  ) calls.


sockaddr_in  =  packed  record
end



sockaddr_in is used to store a INET socket addres for the Bind (1171   ), Recv (102  ) and Send
(102  ) calls.



                                                                1167

________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



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 (1168   )


sockaddr_un  =  packed  record
   sun_family  :  sa_family_t;
   sun_path  :  Array[0..107]  of  Char;
end



sockaddr_un  is  used  to  store  a  UNIX  socket  addres  for  the  Bind  (1171   ),  Recv  (102  )  and
Send (102  ) calls.


TIn6Addr  =  in6_addr


Alias for in6_addr (1166   ) type.


Tin6_addr  =  in6_addr


Alias for sockaddr_in6 (1168   )


TInAddr  =  in_addr


Alias for in_addr (1166   ) record type.


TInetSockAddr  =  sockaddr_in


Alias for sockaddr_in (1167   )


TInetSockAddr6  =  sockaddr_in6


Alias for sockaddr_in6 (1168   )


TIn_addr  =  in_addr


Alias for in_addr (1166   ) record type.


TLinger  =  linger


Alias for linger (1166   )


TSockAddr  =  sockaddr



TSockArray  =  Array[1..2]  of  LongInt



                                                                1168

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                Type returned by the SocketPair (102  ) call.


                Tsocket  =  LongInt


                Alias for easy kylix porting


                TSockLen  =  BaseUnix.TSocklen


                The actual type of  TSockLen depends on the platform.


                TSockPairArray  =  Array[0..1]  of  LongInt


                Array of sockets, used in SocketPair (102  ) call.


                TUnixSockAddr  =  packed  record
                   family  :  sa_family_t;
                   path  :  Array[0..107]  of  Char;
                end



                Alias for sockaddr_un (1168   )



                34.4          Procedures  and  functions



                34.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 (1169   ) command, with the Text or File parameters are
                equivalent  to  subsequently  calling  the  regular  Accept  (1169   )  function  and  the  Sock2Text
                (1185   ) or Sock2File (1185   ) functions.  These functions return True if successful, False oth-
                erwise.

       Errors:   On error, -1 is returned, and errors are reported in SocketError, and include the following:


                SYS__EBADF           The socket descriptor is invalid.



                                                                                1169

            ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_____________________*
 *_______________



            SYS__ENOTSOCK               The descriptor is not a socket.

            SYS__EOPNOTSUPP                  The socket type doesn't support the Listen operation.

            SYS__EFAULT           Addr points outside your address space.

            SYS__EWOULDBLOCK                     The requested operation would block the process.


See also:    Listen (102  ), Connect (1171   ), Bind (1171   )


            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 Vreman
                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___.________________________________________________________________________________________________________________*
 *_______



                                                                            1170

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                34.4.2         Bind

    Synopsis:    Bind a socket to an address (deprecated).

Declaration:     function  Bind(Sock:  LongInt;const  addr:  string)  :  Boolean

    Visibility:   default

Description:     Bind binds the socket Sock to address Addr.  Addr has length Addrlen.  The function returns
                True if the call was succesful, False if not.

                The form of the Bind command with the TUnixSockAddr (1169   ) is equivalent to subsequently
                calling Str2UnixSockAddr (1186   ) and the regular Bind function.  The function returns True
                if successfull, False otherwise.

       Errors:   Errors are returned in SocketError and include the following:


                SYS__EBADF           The socket descriptor is invalid.

                SYS__EINVAL           The socket is already bound to an address,

                SYS__EACCESS             Address is protected and you don't have permission to open it.


                More arrors can be found in the Unix man pages.

    See also:    Socket (1145   )



                34.4.3         CloseSocket

    Synopsis:    Closes a socket handle.

Declaration:     function  CloseSocket(Sock:  LongInt)  :  LongInt

    Visibility:   default

Description:     CloseSocket closes a socket handle.  It returns 0 if the socket was closed succesfully, -1 if
                it failed.

       Errors:   On error, -1 is returned.

    See also:    Socket (1145   )



                34.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



                                                                                1171

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



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 (1171   ) command with the Text or File arguments are equivalent
                to subsequently calling the regular Connect function and the Sock2Text (1185   ) or Sock2File
                (1185   ) functions.  These functions return True if successfull, False otherwise.

                The Connect function returns a file descriptor if the call was successfull, -1 in case of error.

       Errors:   On error, -1 is returned and errors are reported in SocketError.

    See also:    Listen (102  ), Bind (1171   ), Accept (1169   )


                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  :  ' ) ;
                    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) ;



                                                                                1172

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                34.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.



                                                                                1173

            ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_____________________*
 *_______________



   Errors:   On error, -1 is returned, and errors are reported in SocketError, and include the following:


            SYS__EBADF          The socket descriptor is invalid.

            SYS__ENOTSOCK               The descriptor is not a socket.

            SYS__EOPNOTSUPP                  The socket type doesn't support the Listen operation.

            SYS__EFAULT           Addr points outside your address space.

            SYS__EWOULDBLOCK                     The requested operation would block the process.


See also:    fpListen (1178   ), fpConnect (1175   ), fpBind (1175   )


            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 Vreman
                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) ;



                                                                            1174

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                         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___.____________________________________________________________________________________________________________*
 *___________



                34.4.6         fpbind

    Synopsis:    Bind a socket to an address.

Declaration:     function  fpbind(s:  cint;addrx:  psockaddr;addrlen:  TSockLen)  :  cint

    Visibility:   default

Description:     fpBind  binds  the  socket  s  to  address  Addrx.   Addrx  has  length  Addrlen.   The  function
                returns 0 if the call was succesful, -1 if not.

       Errors:   Errors are returned in SocketError and include the following:


                SYS__EBADF           The socket descriptor is invalid.

                SYS__EINVAL           The socket is already bound to an address,

                SYS__EACCESS             Address is protected and you don't have permission to open it.


                More arrors can be found in the Unix man pages.

    See also:    Socket (1145   )



                34.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 (1178   ), fpBind (1175   ), fpAccept (1173   )


                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;



                                                                                1175

________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________________________*
 *___



    h a l t( 1 0 0 ) ;
end   ;



Var
    SAddr           :  T I n e t S o c k A d d;r
    B u f f e r     :  s t r i n g [ 2 5 5 ] ;
    S               :  L o n g i n t;
    Sin  , S o u t  :  T e x t;
    i               :  i n t e g e r;


 b e g i n
    S := 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
        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) ;



                                                                1176

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                    r e s e t( s i n) ;
                    w r i t e l n ( s o u t,p a r a m s t r( 1 ) ) ;
                    f l u s h( s o u t) ;
                    w h i l e not    e o f ( s i n)  do
                        b e g i n
                        r e a d l n (Sin   , l i n e) ;
                        w r i t e l n( l i n e) ;
                       end   ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                34.4.8         fpgetpeername

    Synopsis:    Return the name (address) of the connected peer.

Declaration:     function  fpgetpeername(s:  cint;name:  psockaddr;namelen:  psocklen)  :  cint

    Visibility:   default

Description:     fpGetPeerName  returns  the  name  of  the  entity  connected  to  the  specified  socket  S.  The
                Socket must be connected for this call to work.

                Name should point to enough space to store the name, the amount of space pointed to should
                be set in Namelen.  When the function returns succesfully, Name will be filled with the name,
                and Name will be set to the length of  Name.

       Errors:   Errors are reported in SocketError, and include the following:


                SYS__EBADF           The socket descriptor is invalid.

                SYS__ENOBUFS              The system doesn't have enough buffers to perform the operation.

                SYS__ENOTSOCK                The descriptor is not a socket.

                SYS__EFAULT           Addr points outside your address space.

                SYS__ENOTCONN                 The socket isn't connected.


    See also:    fpConnect (1175   ), fpSocket (1181   )



                34.4.9         fpgetsockname

    Synopsis:    Return name of socket.

Declaration:     function  fpgetsockname(s:  cint;name:  psockaddr;namelen:  psocklen)  :  cint

    Visibility:   default

Description:     fpGetSockName  returns  the  current  name  of  the  specified  socket  S.  Name  should  point  to
                enough space to store the name, the amount of space pointed to should be set in Namelen.
                When the function returns succesfully, Name will be filled with the name, and Namelen will
                be set to the length of  Name.

       Errors:   Errors are reported in SocketError, and include the following:


                SYS__EBADF           The socket descriptor is invalid.

                SYS__ENOBUFS              The system doesn't have enough buffers to perform the operation.



                                                                                1177

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                SYS__ENOTSOCK               The descriptor is not a socket.

                SYS__EFAULT           Addr points outside your address space.


    See also:    fpBind (1175   )



                34.4.10          fpgetsockopt

    Synopsis:    Get current socket options

Declaration:     function  fpgetsockopt(s:  cint;level:  cint;optname:  cint;optval:  pointer;
                                                   optlen:  psocklen)  :  cint

    Visibility:   default

Description:     fpGetSockOpt gets the connection option optname, for socket S. The socket may be obtained
                from different levels, indicated by Level, which can be one of the following:


                SOL__SOCKET            From the socket itself.

                XXX     set  Level  to  XXX,  the  protocol  number  of  the  protocol  which  should  interpret  the
                       option.


                The options are stored in the memory location pointed to by optval.  optlen should point
                to the initial length of  optval,  and on return will contain the actual length of the stored
                data.

                On success, 0 is returned.  On Error, -1 is returned.

       Errors:   Errors are reported in SocketError, and include the following:


                SYS__EBADF           The socket descriptor is invalid.

                SYS__ENOTSOCK                The descriptor is not a socket.

                SYS__EFAULT           OptVal points outside your address space.


    See also:    fpSetSockOpt (1180   )



                34.4.11          fplisten

    Synopsis:    Listen for connections on a socket.

Declaration:     function  fplisten(s:  cint;backlog:  cint)  :  cint

    Visibility:   default

Description:     fpListen listens for up to backlog connections from socket S. The socket S must be of type
                SOCK_STREAM or Sock_SEQPACKET.

                The function returns 0 if a connection was accepted, -1 if an error occurred.

       Errors:   Errors are reported in SocketError, and include the following:


                SYS__EBADF           The socket descriptor is invalid.

                SYS__ENOTSOCK                The descriptor is not a socket.

                SYS__EOPNOTSUPP                   The socket type doesn't support the Listen operation.


    See also:    fpSocket (1181   ), fpBind (1175   ), fpConnect (1175   )



                                                                                1178

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                34.4.12          fprecv

    Synopsis:    Receive data on socket

Declaration:     function  fprecv(s:  cint;buf:  pointer;len:  size_t;flags:  cint)  :  ssize_t

    Visibility:   default

Description:     fpRecv reads at most len bytes from socket S into address buf.  The socket must be in a
                connected state.  Flags can be one of the following:


                1 Process out-of band data.

                4 Bypass routing, use a direct interface.

                ??  Wait for full request or report an error.


                The functions returns the number of bytes actually read from the socket, or -1 if a detectable
                error occurred.

       Errors:   Errors are reported in SocketError, and include the following:


                SYS__EBADF           The socket descriptor is invalid.

                SYS__ENOTCONN                 The socket isn't connected.

                SYS__ENOTSOCK                The descriptor is not a socket.

                SYS__EFAULT           The address is outside your address space.

                SYS__EMSGSIZE              The message cannot be sent atomically.

                SYS__EWOULDBLOCK                      The requested operation would block the process.

                SYS__ENOBUFS              The system doesn't have enough free buffers available.


    See also:    Send (102  )



                34.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 (1181   ), fprecv (1179   )



                                                                                1179

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                34.4.14          fpsend

    Synopsis:    Send data through socket

Declaration:     function  fpsend(s:  cint;msg:  pointer;len:  size_t;flags:  cint)  :  ssize_t

    Visibility:   default

Description:     fpSend  sends  Len  bytes  starting  from  address  Msg  to  socket  S.  S  must  be  in  a  connected
                state.  Options can be passed in Flags.

                The function returns the number of bytes sent, or -1 if a detectable error occurred.

                Flags can be one of the following:


                1 Process out-of band data.

                4 Bypass routing, use a direct interface.


       Errors:   Errors are reported in SocketError, and include the following:


                SYS__EBADF           The socket descriptor is invalid.

                SYS__ENOTSOCK                The descriptor is not a socket.

                SYS__EFAULT           The address is outside your address space.

                SYS__EMSGSIZE              The message cannot be sent atomically.

                SYS__EWOULDBLOCK                      The requested operation would block the process.

                SYS__ENOBUFS              The system doesn't have enough free buffers available.


    See also:    fpRecv (1179   )



                34.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 (1181   ), fpSend (1180   ), fpRecvFrom (1179   )



                34.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.



                                                                                1180

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                XXX     set  Level  to  XXX,  the  protocol  number  of  the  protocol  which  should  interprete  the
                      option.


                The actual option is stored in a buffer pointed to by optval, with length optlen.

                For more information on this call, refer to the unix manual page setsockopt

       Errors:   Errors are reported in SocketError, and include the following:


                SYS__EBADF          The socket descriptor is invalid.

                SYS__ENOTSOCK               The descriptor is not a socket.

                SYS__EFAULT           OptVal points outside your address space.


    See also:    fpGetSockOpt (1178   )



                34.4.17          fpshutdown

    Synopsis:    Close one end of full duplex connection.

Declaration:     function  fpshutdown(s:  cint;how:  cint)  :  cint

    Visibility:   default

Description:     fpShutDown closes one end of a full duplex socket connection, described by S. The parameter
                How determines how the connection will be shut down, and can be one of the following:


                0 Further receives are disallowed.

                1 Further sends are disallowed.

                2 Sending nor receiving are allowed.


                On succes, the function returns 0, on error -1 is returned.

       Errors:   SocketError is used to report errors, and includes the following:


                SYS__EBADF           The socket descriptor is invalid.

                SYS__ENOTCONN                 The socket isn't connected.

                SYS__ENOTSOCK                The descriptor is not a socket.


    See also:    fpSocket (1181   ), fpConnect (1175   )



                34.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  (1175   )  call.   If  unsuccesfull,  the
                function returns -1.

                for an example, see Accept (1169   ).

       Errors:   Errors are returned in SocketError, and include the follwing:



                                                                                1181

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                SYS__EPROTONOSUPPORT                          The protocol type or the specified protocol is not supported
                      within this domain.

                SYS__EMFILE           The per-process descriptor table is full.

                SYS__ENFILE          The system file table is full.

                SYS__EACCESS            Permission to create a socket of the specified type and/or protocol is de-
                      nied.

                SYS__ENOBUFS             Insufficient buffer space is available.  The socket cannot be created until
                      sufficient resources are freed.


    See also:    SocketPair (102  )



                34.4.19          fpsocketpair

    Synopsis:    Create socket pair.

Declaration:     function  fpsocketpair(d:  cint;xtype:  cint;protocol:  cint;sv:  pcint)
                                                     :  cint

    Visibility:   default

Description:     fpSocketPair creates 2 sockets in domain D, from type xType and using protocol Protocol.
                The  pair  is  returned  in  sv,  and  they  are  indistinguishable.  The  function  returns  -1  upon
                error and 0 upon success.

       Errors:   Errors are reported in SocketError, and are the same as in Socket (1145   )

    See also:    Str2UnixSockAddr (1186   )



                34.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 (1183   ), but with the bytes in correct order.

    See also:    NetAddrToStr (1183   ), StrToHostAddr (1186   ), StrToNetAddr (1187   )



                34.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 (1184   ), but with the bytes in correct order.

    See also:    NetAddrToStr (1183   ), StrToHostAddr (1186   ), StrToNetAddr (1187   ), StrToHostAddr6 (1186   )



                                                                                1182

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                34.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 (1184   ), NToHS (1184   ), HToNS (1183   ), ShortHostToNet (1185   ), ShortNetToHost
                (1185   )



                34.4.23          htonl

    Synopsis:    Convert long integer from host ordered to network ordered

Declaration:     function  htonl(host:  LongInt)  :  LongInt

    Visibility:   default

Description:     htonl makes sure that the bytes in host are ordered in the correct way for sending over the
                network and returns the correctly ordered result.

    See also:    htons (1183   ), ntohl (1184   ), ntohs (1184   )



                34.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 (1183   ), ntohl (1184   ), ntohs (1184   )



                34.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 (1182   ), StrToNetAddr (1187   ), StrToHostAddr (1186   )



                                                                                1183

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                34.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 (1184   ), but with the bytes in correct order.

    See also:    NetAddrToStr (1183   ), StrToHostAddr (1186   ), StrToNetAddr (1187   ), StrToHostAddr6 (1186   )



                34.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 (1183   ), NToHS (1184   ), HToNS (1183   ), ShortHostToNet (1185   ), ShortNetToHost
                (1185   )



                34.4.28          NToHl

    Synopsis:    Convert long integer from network ordered to host ordered

Declaration:     function  NToHl(Net:  LongInt)  :  LongInt

    Visibility:   default

Description:     ntohs  makes  sure  that  the  bytes  in  Net,  received  from  the  network,  are  ordered  in  the
                correct way for handling by the host machinen, and returns the correctly ordered result.

    See also:    htonl (1183   ), htons (1183   ), ntohs (1184   )



                34.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 (1183   ), htons (1183   ), ntohl (1184   )



                                                                                1184

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                34.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 (1185   ), HostToNet (1183   ), NToHS (1184   ), HToNS (1183   )



                34.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 (1185   ), HostToNet (1183   ), NToHS (1184   ), HToNS (1183   )



                34.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:    Socket (1145   ), Sock2Text (1185   )



                34.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:    Socket (1145   ), Sock2File (1185   )



                                                                                1185

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                34.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.



                34.4.35          Str2UnixSockAddr

    Synopsis:    Convert path to TUnixSockAddr (1169   )

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 (1171   ) call.

       Errors:   None.

    See also:    Socket (1145   ), Bind (1171   )



                34.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 (1183   ), HostAddrToStr (1182   ), StrToNetAddr (1187   )



                34.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 (1184   ), HostAddrToStr6 (1182   ), StrToHostAddr (1186   )



                                                                                1186

                ________________________________________________________CHAPTER_34.___REFERENCE_FOR_UNIT_'SOCKETS'_________________*
 *___________________



                34.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 (1183   ), HostAddrToStr (1182   ), StrToHostAddr (1186   )



                34.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 (1184   ), HostAddrToStr6 (1182   ), StrToHostAddr6 (1186   )



                                                                                1187




                Chapter   35



                Reference   for   unit   'strings'



                35.1          Overview


                This chapter describes the STRINGS unit for Free Pascal.  This unit is system independent,
                and therefore works on all supported platforms.



                35.2          Procedures  and  functions



                35.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 (1197   ), StrPCopy (1198   )



                35.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 (1193   )


                Listing:  ./stringex/ex11.pp



                                                                            1188

                _________________________________________________________CHAPTER_35.___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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1194   ).

       Errors:   None.

    See also:    StrLComp (1194   ), StrIComp (1192   ), StrLIComp (1195   )



                35.2.4         strcopy

    Synopsis:    Copy a null-terminated string

Declaration:     function  strcopy(dest:  pchar;source:  pchar)  :  pchar

    Visibility:   default

Description:     Copy the null terminated string in Source to Dest,  and returns a pointer to Dest.  Dest
                needs enough room to contain Source, i.e.  StrLen(Source)+1 bytes.

       Errors:   No length checking is performed.

    See also:    StrPCopy (1198   ), StrLCopy (1194   ), StrECopy (1190   )


                Listing:  ./stringex/ex4.pp



                                                                                1189

                _________________________________________________________CHAPTER_35.___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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1197   )


                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___.____________________________________________________________________________________________________________*
 *___________



                35.2.6         strecopy

    Synopsis:    Copy a null-terminated string, return a pointer to the end.



                                                                                1190

                _________________________________________________________CHAPTER_35.___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 (1194   ), StrCopy (1189   )


                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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1195   )


                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  ! ' )



                                                                                1191

                _________________________________________________________CHAPTER_35.___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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1194   ), StrComp (1189   ), StrLIComp (1195   )


                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___.____________________________________________________________________________________________________________*
 *___________



                35.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.



                                                                                1192

                _________________________________________________________CHAPTER_35.___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 (1193   ), strpos (1199   )



                35.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 (1200   ) 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 (1200   ), strriscan (1199   )



                35.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 (1188   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1193

                _________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                35.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 (1189   ), StrIComp (1192   ), StrLIComp (1195   )


                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___.____________________________________________________________________________________________________________*
 *___________



                35.2.13          strlcopy

    Synopsis:    Copy a null-terminated string, limited in length.

Declaration:     function  strlcopy(dest:  pchar;source:  pchar;maxlen:  SizeInt)  :  pchar

    Visibility:   default

Description:     Copies MaxLen characters from Source to Dest, and makes Dest a null terminated string.

       Errors:   No length checking is performed.

    See also:    StrCopy (1189   ), StrECopy (1190   )


                Listing:  ./stringex/ex5.pp



                                                                                1194

                _________________________________________________________CHAPTER_35.___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___.____________________________________________________________________________________________________________*
 *___________



                35.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.

       Errors:   None.

    See also:    StrNew (1197   )


                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___.____________________________________________________________________________________________________________*
 *___________



                35.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



                                                                                1195

                _________________________________________________________CHAPTER_35.___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 (1192   )

       Errors:   None.

    See also:    StrLComp (1194   ), StrComp (1189   ), StrIComp (1192   )



                35.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 (1200   )


                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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1194   ), StrCopy (1189   )



                                                                                1196

                _________________________________________________________CHAPTER_35.___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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1189   ), StrDispose (1190   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1197

                _________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                35.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 (1198   )


                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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1198   )


                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;



                                                                                1198

                _________________________________________________________CHAPTER_35.___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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1200   ), StrRScan (1200   )


                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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1200   ) 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 (1200   ), striscan (1193   )



                                                                                1199

                _________________________________________________________CHAPTER_35.___REFERENCE_FOR_UNIT_'STRINGS'________________*
 *___________________



                35.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 (1200   ).

       Errors:   None.

    See also:    StrScan (1200   ), StrPos (1199   )



                35.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 (1200   ), StrPos (1199   )


                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___.____________________________________________________________________________________________________________*
 *___________



                35.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 (1196   )

       Errors:   None.

    See also:    StrLower (1196   )



                                                                                1200




Chapter   36



Reference   for   unit   'strutils'



36.1          Used  units



                                    Table 36.1:  Used units by unit 'strutils'


                                                  __Name___________Page_____
                                                    System         1230
                                                    SysUtils       1450



36.2          Constants,  types  and  variables



36.2.1         Resource  strings

SErrAmountStrings  =  '''Amount  of  search  and  replace  strings  don''''t  match'''


Error message used in stringsreplace function



36.2.2         Constants

AnsiResemblesProc  :  TCompareTextProc  =  @SoundexProc


This procedural variable is standard set to SoundexProc (1225   ) but can be overriden with a
user-defined algorithm.  This algorithm should return True if  AText resembles AOtherText,
or False otherwise.  The standard routine compares the soundexes of the two strings and
returns True if they are equal.


Brackets  =  ['(',  ')',  '[',  ']',  '-',  '"']


Set of characters that contain all possible bracket characters


DigitChars  =  ['0'..'9']


Set of digit characters


StdSwitchChars  =  ['-',  '/']



                                                            1201

_______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________________________*
 *___



Standard characters for the SwitchChars argument of GetCmdLineArg (1214   ).


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 (1224   ) call.



36.2.3         Types

  =  1..MaxInt


Various string handling routines


  =  1..8


Various string handling routines


TCompareTextProc  =  function(const  AText:  string;const  AOther:  string)
                                                :  Boolean


Function prototype for comparing two string in AnsiResemblesText (1207   )


TStringSeachOption  =  TStringSearchOption


There  is  an  typo  error  in  the  original  Borland  StrUtils  unit.  This  type  just  refers  to  the
correct TStringSearchOption (1202   ) and is provided for compatibility only.


TStringSearchOption  =  (soDown,soMatchCase,soWholeWord)



                    Table 36.2:  Enumeration values for type TStringSearchOption


                                __Value__________________Explanation__________________________
                                  soDown                 Search in down direction.
                                  soMatchCase            Match case
                                  soWholeWord            Search whole words only.



Possible options for SearchBuf (1224   ) call.


TStringSearchOptions  =  Set  of  TStringSearchOption


Set of options for SearchBuf (1224   ) call.



                                                                1202

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.3          Procedures  and  functions



                36.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 (1203   ), PadLeft (1219   ), PadRight (1220   ), PadCenter (1219   )



                36.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 (1203   )



                36.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 (1203   ), AnsiEndsStr (1204   ), AnsiIndexStr (1204   ), AnsiStartsStr (1208   )



                36.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



                                                                                1203

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



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 (1203   ), AnsiEndsText (1204   ), AnsiIndexText (1205   ), AnsiStartsText (1208   )



                36.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 (1204   ), AnsiStartsStr (1208   ), AnsiIndexStr (1204   ), AnsiContainsStr (1203   )



                36.3.6         AnsiEndsText

    Synopsis:    Check whether a string ends with a certain substring, ignoring case.

Declaration:     function  AnsiEndsText(const  ASubText:  string;const  AText:  string)
                                                     :  Boolean

    Visibility:   default

Description:     AnsiEndsStr checks AText to see whether it ends with ASubText , and returns True if it
                does, False if not.  The check is performed case-insensitive.  Basically, it checks whether the
                position of  ASubText equals the length of  AText minus the length of  ASubText plus one.

       Errors:   None

    See also:    AnsiStartsText (1208   ), AnsiEndsStr (1204   ), AnsiIndexText (1205   ), AnsiContainsText (1203   )



                36.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  )
                                                     :  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 (1205   ), AnsiMatchStr (1205   ), AnsiMatchText (1205   )



                                                                                1204

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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  )
                                                      :  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 (1204   ), AnsiMatchStr (1205   ), AnsiMatchText (1205   )



                36.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  (1206   ),  AnsiRightStr  (1207   ),  LeftStr  (1217   ),  RightStr  (1223   ),  MidStr  (1218   ),
                LeftBStr (1217   ), RightBStr (1222   ), MidBStr (1218   )



                36.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  )
                                                     :  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 (1204   ) and checks whether it returns -1 or not.



                36.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  )
                                                      :  Boolean

    Visibility:   default



                                                                                1205

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



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 (1205   ) and checks whether it returns -1 or not.



                36.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  (1205   ),  AnsiRightStr  (1207   ),  LeftStr  (1217   ),  RightStr  (1223   ),  MidStr  (1218   ),
                LeftBStr (1217   ), RightBStr (1222   ), MidBStr (1218   )



                36.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 (1202   ) can be used for this.



                36.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 (1207   ), SearchBuf (1224   )



                                                                                1206

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1206   ), SearchBuf (1224   )



                36.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 (1201   ) 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 (1201   ), SoundexProc (1225   )



                36.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.



                36.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.



                                                                                1207

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    AnsiLeftStr  (1205   ),  AnsiMidStr  (1206   ),  LeftStr  (1217   ),  RightStr  (1223   ),  MidStr  (1218   ),
                LeftBStr (1217   ), RightBStr (1222   ), MidBStr (1218   )



                36.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 (1204   ), AnsiStartsStr (1208   ), AnsiIndexStr (1204   ), AnsiContainsStr (1203   )



                36.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 (1204   ), AnsiStartsStr (1208   ), AnsiIndexText (1205   ), AnsiContainsText (1203   )



                36.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 (1215   )



                                                                                1208

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1209   ) with the space (ASCII code 32) as the symbol
                argument.

       Errors:   None.

    See also:    Copy2Symb (1209   ), Copy2SpaceDel (1209   )



                36.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  (1210   )  with  the  space  (ASCII  code  32)  as  the
                symbol argument.

       Errors:   None.

    See also:    Copy2SymbDel (1210   ), Copy2Space (1209   )



                36.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 (1209   ), Copy2SymbDel (1210   )



                                                                                1209

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1209   ), Copy2Symb (1209   )



                36.3.26          Dec2Numb

    Synopsis:    Convert a decimal number to a string representation, using given a base.

Declaration:     function  Dec2Numb(N:  LongInt;Len:  Byte;Base:  Byte)  :  string

    Visibility:   default

Description:     Dec2Numb  converts  N  to  its  representation  using  base  Base.   The  resulting  string  is  left-
                padded with zeroes till it has length Len.  Base must be in the range 2-36 to be meaningful,
                but no checking on this is performed.

       Errors:   If  Base   is  out  of  range,  the  resulting  string  will  contain  unreadable  (non-alphanumeric)
                characters.

    See also:    Hex2Dec (1214   ), IntToBin (1215   ), intToRoman (1216   ), RomanToInt (1223   )



                36.3.27          DecodeSoundexInt

    Synopsis:    Decodes the integer representation of a soundex code and returns the original soundex code.

Declaration:     function  DecodeSoundexInt(AValue:  Integer)  :  string

    Visibility:   default

Description:     DecodeSoundexInt  converts  the  integer  value  AValue  to  a  soundex  string.   It  performs
                the reverse operation of the SoundexInt (1225   ) function.  The result is the soundex string
                corresponding to AValue.  .

       Errors:   None.

    See also:    SoundexInt (1225   ), DecodeSoundexWord (1210   ), Soundex (1224   )



                36.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



                                                                                1210

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



Description:     DecodeSoundexWord  converts  the  integer  value  AValue  to  a  soundex  string.   It  performs
                the reverse operation of the SoundexWord (1226   ) function.  The result is the soundex string
                corresponding to AValue .

       Errors:   None.

    See also:    SoundexInt (1225   ), DecodeSoundexInt (1210   ), Soundex (1224   )



                36.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 (1211   ), DelSpace1 (1211   )



                36.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 (1211   ), DelSpace1 (1211   )



                36.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 (1211   ), DelSpace (1211   )



                                                                                1211

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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.



                36.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 (1213   ), an empty string is a valid return value, i.e.  a part can
                be empty.

                The pre-defined constant StdWordDelims (1202   ) can be used for the Delims argument.  The
                pre-defined  constant  Brackets  (1201   )  would  be  better  suited  the  Delims  argument  e.g.  in
                case factors in a mathematical expression are searched.

       Errors:   None.

    See also:    ExtractSubStr (1212   ), ExtractWord (1213   ), ExtractWordPos (1213   )



                36.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 (1202   ) can be used for the Delims argument.



                                                                                1212

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    ExtractDelimited (1212   ), ExtractWord (1213   ), ExtractWordPos (1213   )



                36.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  (1212   ),  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 (1202   ) can be used for the WordDelims argument.

       Errors:   None.

    See also:    ExtractWordPos  (1213   ),  ExtractSubStr  (1212   ),  ExtractDelimited  (1212   ),  IsWordPresent
                (1217   ), WordCount (1228   ), WordPosition (1228   )



                36.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.

                Unlike  ExtractDelimited  (1212   ),  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 (1202   ) can be used for the WordDelims argument.

       Errors:   None.

    See also:    ExtractWord  (1213   ),  ExtractSubStr  (1212   ),  IsWordPresent  (1217   ),  WordCount  (1228   ),
                WordPosition (1228   )



                                                                                1213

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1224   )



                36.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 (1202   ) 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 (1202   )



                36.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 (1210   ), IntToBin (1215   ), intToRoman (1216   ), RomanToInt (1223   )



                                                                                1214

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1208   )



                36.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 (1205   ), AnsiMatchText (1205   )



                36.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

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 (1214   ), IntToRoman (1216   )



                                                                                1215

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1223   ), Hex2Dec (1214   ), IntToBin (1215   )



                36.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 (1216   ), FindPart (1214   ), IsWordPresent (1217   )



                36.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 (1224   ), FindPart (1214   )



                                                                                1216

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1224   ) function with the soWholeWords option
                specified.

       Errors:   None.

    See also:    SearchBuf (1224   )



                36.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 (1217   ), AnsiLeftStr (1205   ), RightBStr (1222   ), MidBStr (1218   )



                36.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 (1217   ), AnsiLeftStr (1205   ), RightStr (1223   ), MidStr (1218   )



                                                                                1217

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1217   ), AnsiMidStr (1206   ), RightBStr (1222   ), MidStr (1218   )



                36.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 (1217   ), AnsiMidStr (1206   ), RightStr (1223   ), MidBStr (1218   )



                36.3.51          NPos

    Synopsis:    Returns the position of the N-th occurence of a substring in a string.

Declaration:     function  NPos(const  C:  string;S:  string;N:  Integer)  :  Integer

    Visibility:   default

Description:     NPos checks S for the position of the N-th occurrence of  C. If  C occurs less than N times in
                S, or does not occur in S at all, 0 is returned.  If  N is less than 1, zero is returned.

       Errors:   None.

    See also:    WordPosition (1228   ), FindPart (1214   )



                                                                                1218

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1214   ), Numb2USA (1219   )



                36.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.



                36.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 (1219   ), PadRight (1220   ), AddChar (1203   ), AddCharR (1203   )



                36.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 (1219   ), PadCenter (1219   ), AddChar (1203   ), AddCharR (1203   )



                                                                                1219

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.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 (1219   ), PadCenter (1219   ), AddChar (1203   ), AddCharR (1203   )



                36.3.57          PosEx

    Synopsis:    Search for the occurance of a character in a string, starting at a certain position.

Declaration:     function  PosEx(const  SubStr:  string;const  S:  string;Offset:  Cardinal)
                                         :  Integer
                function  PosEx(const  SubStr:  string;const  S:  string)  :  Integer
                function  PosEx(c:  Char;const  S:  string;Offset:  Cardinal)  :  Integer

    Visibility:   default

Description:     PosEx returns the position of the first occurrence of the character C or the substring SubStr
                in the string S, starting the search at position Offset (default 1).  If  C or SubStr does not
                occur in S after the given Offset, zero is returned.  The position Offset is also searched.

       Errors:   None.

    See also:    NPos (1218   ), AnsiContainsText (1203   ), AnsiContainsStr (1203   )



                36.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 (1220   ), PosSetEx (1220   ), #rtl.system.pos (1383   ), RPosEx (1223   )



                36.3.59          PosSetEx

    Synopsis:    Return  the  position  in  a  string  of  any  character  out  of  a  set  of  characters,  starting  at  a
                certain position



                                                                                1220

                _______________________________________________________CHAPTER_36.___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 (1220   ), PosSet (1220   ), #rtl.system.pos (1383   ), RPosEx (1223   )



                36.3.60          RandomFrom

    Synopsis:    Choose a random string from an array of strings.

Declaration:     function  RandomFrom(const  AValues:  Array  of  )  :  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 (1205   ), AnsiMatchText (1205   )



                36.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 (1595   ) which used whitespace as the set.

       Errors:   None.

    See also:    TrimLeft (1595   ), RemoveTrailingChars (1222   ), RemovePadChars (1221   ), TrimLeftSet (1227   )



                36.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 (1594   ) which used whitespace as the set.



                                                                                1221

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    Trim  (1594   ),  RemoveLeadingChars  (1221   ),  RemoveTrailingChars  (1222   ),  TrimSet  (1228   ),
                TrimLeftSet (1227   ), TrimRightSet (1227   )



                36.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 (1596   ) which used whitespace as the set.

    See also:    TrimRight (1595   ), RemoveLeadingChars (1221   ), TrimRightSet (1227   )



                36.3.64          ReverseString

    Synopsis:    Reverse characters in a string

Declaration:     function  ReverseString(const  AText:  string)  :  string

    Visibility:   default

Description:     ReverseString returns a string, made up of the characters in string AText, in reverse order.

       Errors:   None.

    See also:    RandomFrom (1221   )



                36.3.65          RightBStr

    Synopsis:    Copy a given number of characters (bytes), counting from the right of a string.

Declaration:     function  RightBStr(const  AText:  AnsiString;const  AByteCount:  Integer)
                                                :  AnsiString

    Visibility:   default

Description:     RightBStr  returns  a  string  containing  the  rightmost  AByteCount  bytes  from  the  string
                AText.  If  AByteCount is larger than the length (in bytes) of  AText, only as many bytes as
                available are returned.

       Errors:   None.

    See also:    LeftBStr (1217   ), AnsiRightStr (1207   ), RightStr (1223   ), MidBStr (1218   )



                                                                                1222

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.3.66          RightStr

    Synopsis:    Copy a given number of characters, counting from the right of a string.

Declaration:     function  RightStr(const  AText:  AnsiString;const  ACount:  Integer)
                                              :  AnsiString
                function  RightStr(const  AText:  WideString;const  ACount:  Integer)
                                              :  WideString

    Visibility:   default

Description:     RightStr returns a string containing the rightmost ACount characters from the string AText
                .  If  ACount is larger than the length (in characters) of  AText , only as many characters as
                available are returned.

       Errors:   None.

    See also:    LeftStr (1217   ), AnsiRightStr (1207   ), RightBStr (1222   ), MidStr (1218   )



                36.3.67          RomanToInt

    Synopsis:    Convert a string with a Roman number to it's decimal value.

Declaration:     function  RomanToInt(const  S:  string)  :  LongInt

    Visibility:   default

Description:     RomanToInt returns the decimal equivalent of the Roman numerals in the string S. Invalid
                characters are dropped from S. A negative numeral is supported as well.

       Errors:   None.

    See also:    IntToRoman (1216   ), Hex2Dec (1214   ), Numb2Dec (1219   )



                36.3.68          RPos

    Synopsis:    Find last occurrence of substring or character in a string

Declaration:     function  RPos(c:  Char;const  S:  AnsiString)  :  Integer;    Overload
                function  RPos(const  Substr:  AnsiString;const  Source:  AnsiString)
                                       :  Integer;    Overload

    Visibility:   default

Description:     RPos looks in S for the character C or the string SubStr.  It starts looking at the end of the
                string, and searches towards the beginning of the string.  If a match is found, it returns the
                position of the match.

    See also:    RPosEx (1223   )



                36.3.69          RPosex

    Synopsis:    Find last occurrence substring or character in a string, starting at a certain position

Declaration:     function  RPosEX(C:  Char;const  S:  AnsiString;offs:  Cardinal)  :  Integer
                                         ;    Overload
                function  RPosex(const  Substr:  AnsiString;const  Source:  AnsiString;
                                         offs:  Cardinal)  :  Integer;    Overload



                                                                                1223

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



    Visibility:  default

Description:     RPos looks in S for the character C or the string SubStr.  It starts looking at position Offs
                (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 (1223   )



                36.3.70          SearchBuf

    Synopsis:    Search a buffer for a certain string.

Declaration:     function  SearchBuf(Buf:  PChar;BufLen:  Integer;SelStart:  Integer;
                                              SelLength:  Integer;SearchString:  string;
                                              Options:  TStringSearchOptions)  :  PChar
                function  SearchBuf(Buf:  PChar;BufLen:  Integer;SelStart:  Integer;
                                              SelLength:  Integer;SearchString:  string)  :  PChar

    Visibility:   default

Description:     SearchBuf searches the buffer Buf for the occurrence of  SearchString.  At must Buflen
                characters  are  searched,  and  the  search  is  started  at  SelStart+SelLength.  If  a  match  is
                found,  a  pointer  to  the  position  of  the  match  is  returned.  The  parameter  Options  (1202   )
                specifies how the search is conducted.  It is a set of the following options:



                                                                       Table 36.3:



                __Option_________________Effect____________________________________________________________________________________*
 *___________________
                  soDown                 Searches forward, starting at the end of the selection.  Default is searching up
                  soMatchCase            Observe case when searching.  Default is to ignore case.
                  soWholeWord            Match only whole words.  Default also returns parts of words



                The standard constant WordDelimiters (1202   ) 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 (1214   ), ExtractWord (1213   ), ExtractWordPos (1213   ), ExtractSubStr (1212   ), Is-
                WordPresent (1217   )



                36.3.71          Soundex

    Synopsis:    Compute the soundex of a string

Declaration:     function  Soundex(const  AText:  string;ALength:  TSoundexLength)  :  string
                function  Soundex(const  AText:  string)  :  string

    Visibility:   default

Description:     Soundex computes a soundex code for AText.  The resulting code will at most have ALength
                characters.  The soundex code is computed according to the US system of soundex computing,
                which may result in inaccurate results in other languages.

       Errors:   None.



                                                                                1224

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



    See also:    SoundexCompare  (1225   ),  SoundexInt  (1225   ),  SoundexProc  (1225   ),  SoundexWord  (1226   ),
                SoundexSimilar (1226   )



                36.3.72          SoundexCompare

    Synopsis:    Compare soundex values of 2 strings.

Declaration:     function  SoundexCompare(const  AText:  string;const  AOther:  string;
                                                      ALength:  TSoundexLength)  :  Integer
                function  SoundexCompare(const  AText:  string;const  AOther:  string)
                                                        :  Integer

    Visibility:   default

Description:     SoundexCompare  computes  the  soundex  codes  of  AText  and  AOther  and  feeds  these  to
                CompareText.  It will return -1 if the soundex code of  AText is less than the soundex code
                of AOther, 0 if they are equal, and 1 if the code of AOther is larger than the code of AText.

       Errors:   None.

    See also:    Soundex (1224   ), SoundexInt (1225   ), SoundexProc (1225   ), SoundexWord (1226   ), SoundexSim-
                ilar (1226   )



                36.3.73          SoundexInt

    Synopsis:    Soundex value as an integer.

Declaration:     function  SoundexInt(const  AText:  string;ALength:  TSoundexIntLength)
                                                 :  Integer
                function  SoundexInt(const  AText:  string)  :  Integer

    Visibility:   default

Description:     SoundexInt computes the Soundex (1224   ) code (with length ALength, default 4) of AText,
                and converts the code to an integer value.

       Errors:   None.

    See also:    Soundex (1224   ), SoundexCompare (1225   ), SoundexProc (1225   ), SoundexWord (1226   ), SoundexSim-
                ilar (1226   )



                36.3.74          SoundexProc

    Synopsis:    Default AnsiResemblesText implementation.

Declaration:     function  SoundexProc(const  AText:  string;const  AOther:  string)  :  Boolean

    Visibility:   default

Description:     SoundexProc is the standard implementation for the AnsiResemblesText (1207   ) 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 (1224   ), SoundexCompare (1225   ), SoundexInt (1225   ), SoundexWord (1226   ), SoundexSim-
                ilar (1226   )



                                                                                1225

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.3.75          SoundexSimilar

    Synopsis:    Check whether 2 strings have equal soundex values

Declaration:     function  SoundexSimilar(const  AText:  string;const  AOther:  string;
                                                      ALength:  TSoundexLength)  :  Boolean
                function  SoundexSimilar(const  AText:  string;const  AOther:  string)
                                                        :  Boolean

    Visibility:   default

Description:     SoundexSimilar  returns  True  if  the  soundex  codes  (with  length  ALength)  of  AText  and
                AOther are equal, and False if they are not.

       Errors:   None.

    See also:    Soundex (1224   ), SoundexCompare (1225   ), SoundexInt (1225   ), SoundexProc (1225   ), Soundex-
                Word (1226   ), Soundex (1224   )



                36.3.76          SoundexWord

    Synopsis:    Calculate a word-sized soundex value

Declaration:     function  SoundexWord(const  AText:  string)  :  Word

    Visibility:   default

Description:     SoundexInt computes the Soundex (1224   ) code (with length 4) of AText , and converts the
                code to a word-sized value.

       Errors:   None.

    See also:    Soundex (1224   ), SoundexCompare (1225   ), SoundexInt (1225   ), SoundexProc (1225   ), SoundexSim-
                ilar (1226   )



                36.3.77          StringsReplace

    Synopsis:    Replace occurrences of a set of strings to another set of strings

Declaration:     function  StringsReplace(const  S:  string;OldPattern:  Array  of  ;
                                                      NewPattern:  Array  of  ;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 (1573   ).

                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 (1573   ), TReplaceFlags (1470   )



                                                                                1226

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.3.78          StuffString

    Synopsis:    Replace part of a string with another string.

Declaration:     function  StuffString(const  AText:  string;AStart:  Cardinal;
                                                 ALength:  Cardinal;const  ASubText:  string)  :  string

    Visibility:   default

Description:     StuffString  returns  a  copy  of  AText  with  the  segment  starting  at  AStart  with  length
                ALength, replaced with the string ASubText.  Basically it deletes the segment of  Atext and
                inserts the new text in it's place.

       Errors:   No  checking  on  the  validity  of  the  AStart  and  ALength  parameters  is  done.   Providing
                invalid values may result in access violation errors.

    See also:    FindPart  (1214   ),  DelChars  (1211   ),  DelSpace  (1211   ),  ExtractSubStr  (1212   ),  DupeString
                (1212   )



                36.3.79          Tab2Space

    Synopsis:    Convert tab characters to a number of spaces

Declaration:     function  Tab2Space(const  S:  string;Numb:  Byte)  :  string

    Visibility:   default

Description:     Tab2Space  returns  a  copy  of  S  with  all  tab  characters  (ASCII  character  9)  converted  to
                Numb spaces.

       Errors:   None.

    See also:    StuffString (1227   ), FindPart (1214   ), ExtractWord (1213   ), DelChars (1211   ), DelSpace (1211   ),
                DelSpace1 (1211   ), DupeString (1212   )



                36.3.80          TrimLeftSet

    Synopsis:    Remove any leading characters in a set from a string and returns the result

Declaration:     function  TrimLeftSet(const  S:  string;const  CSet:  TSysCharSet)  :  string

    Visibility:   default

Description:     TrimLeftSet  performs  the  same  action  as  RemoveLeadingChars  (1221   ),  but  returns  the
                resulting string.

       Errors:   None.

    See also:    TrimLeft (1595   ), RemoveLeadingChars (1221   ), RemoveTrailingChars (1222   ), RemovePad-
                Chars (1221   ), TrimSet (1228   ), TrimRightSet (1227   )



                36.3.81          TrimRightSet

    Synopsis:    Remove any trailing characters in a set from a string and returns the result

Declaration:     function  TrimRightSet(const  S:  string;const  CSet:  TSysCharSet)  :  string

    Visibility:   default



                                                                                1227

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



Description:     TrimLeftSet  performs  the  same  action  as  RemoveTrailingChars  (1222   ),  but  returns  the
                resulting string.

       Errors:   None.

    See also:    TrimRight (1596   ), RemoveLeadingChars (1221   ), RemoveTrailingChars (1222   ), RemovePad-
                Chars (1221   ), TrimSet (1228   ), TrimLeftSet (1227   )



                36.3.82          TrimSet

    Synopsis:    Remove any leading or trailing characters in a set from a string and returns the result

Declaration:     function  TrimSet(const  S:  string;const  CSet:  TSysCharSet)  :  string

    Visibility:   default

Description:     TrimSet  performs  the  same  action  as  RemovePadChars  (1221   ),  but  returns  the  resulting
                string.

       Errors:   None.

    See also:    Trim (1594   ), RemoveLeadingChars (1221   ), RemoveTrailingChars (1222   ), RemovePadChars
                (1221   ), TrimRightSet (1227   ), TrimLeftSet (1227   )



                36.3.83          WordCount

    Synopsis:    Count the number of words in a string.

Declaration:     function  WordCount(const  S:  string;const  WordDelims:  TSysCharSet)
                                                :  Integer

    Visibility:   default

Description:     WordCount returns the number of words in the string  S. A word is a non-empty string of
                characters bounded by one of the characters in WordDelims.

                The pre-defined StdWordDelims (1202   ) constant can be used for the WordDelims argument.

       Errors:   None.

    See also:    WordPosition (1228   ), StdWordDelims (1202   ), ExtractWord (1213   ), ExtractWordPos (1213   )



                36.3.84          WordPosition

    Synopsis:    Search position of Nth word in a string.

Declaration:     function  WordPosition(const  N:  Integer;const  S:  string;
                                                   const  WordDelims:  TSysCharSet)  :  Integer

    Visibility:   default

Description:     WordPosition returns the position (in characters) of the N-th word in the string S. A word
                is a non-empty string of characters bounded by one of the characters in WordDelims.  If N is
                out of range, zero is returned.

                The pre-defined StdWordDelims (1202   ) constant can be used for the WordDelims argument.

       Errors:   None

    See also:    WordCount (1228   ), StdWordDelims (1202   ), ExtractWord (1213   ), ExtractWordPos (1213   )



                                                                                1228

                _______________________________________________________CHAPTER_36.___REFERENCE_FOR_UNIT_'STRUTILS'_________________*
 *___________________



                36.3.85          XorDecode

    Synopsis:    Decode a string encoded with XorEncode (1229   )

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 (1229   ) 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 (1229   ), XorString (1229   )



                36.3.86          XorEncode

    Synopsis:    Encode a string by XOR-ing its characters using characters of a given key, representing the
                result as hex values.

Declaration:     function  XorEncode(const  Key:  string;const  Source:  string)  :  string

    Visibility:   default

Description:     XorEncode encodes the string Source by XOR-ing each character in Source with the corre-
                sponding character in Key (repeating Key as often as necessary) and representing the resulting
                ASCII code as a hexadecimal number (of length 2).  The result is therefore twice as long as
                the original string, and every 2 bytes represent an ASCII code.

                Feeding the resulting string with the same key  Key to the XorDecode (1229   ) 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 (1229   ), XorString (1229   ), Hex2Dec (1214   )



                36.3.87          XorString

    Synopsis:    Encode a string by XOR-ing its characters using characters of a given key.

Declaration:     function  XorString(const  Key:  ShortString;const  Src:  ShortString)
                                                :  ShortString

    Visibility:   default

Description:     XorString  encodes  the  string  Src  by  XOR-ing  each  character  in  Source  with  the  corre-
                sponding  character  in  Key,  repeating  Key  as  often  as  necessary.  The  resulting  string  may
                contain unreadable characters and may even contain null characters.  For this reason it may
                be a better idea to use the XorEncode (1229   ) 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 (1229   ), XorDecode (1229   )



                                                                                1229




Chapter   37



Reference   for   unit   'System'



37.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.



37.2          A  string  consisting  of  widechars.


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.



37.3          Miscellaneous  functions


Functions that do not belong in one of the other categories.



                                                            1230

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                                                       Table 37.1:

                    __Name______________________Description________________________________________________
                      Assert (1289   )          Conditionally abort program with error
                      Break (1294   )           Abort current loop
                      Continue (1305   )        Next cycle in current loop
                      Exclude (1317   )         Exclude an element from a set
                      Exit (1318   )            Exit current function or procedure
                      Include (1336   )         Include an element into a set
                      LongJmp (1349   )         Jump to execution point
                      Ord (1380   )             Return ordinal value of enumerated type
                      Pred (1384   )            Return previous value of ordinal type
                      SetJmp (1402   )          Mark execution point for jump
                      SizeOf (1408   )          Return size of variable or type
                      Succ (1414   )            Return next value of ordinal type



37.4          Operating  System  functions


Functions that are connected to the operating system.



                                                       Table 37.2:

         __Name__________________________Description__________________________________________________________________
           Chdir (1297   )               Change working directory
           Getdir (1328   )              Return current working directory
           Halt (1332   )                Halt program execution
           Paramcount (1381   )          Number of parameters with which program was called
           Paramstr (1382   )            Retrieve parameters with which program was called
           Mkdir (1351   )               Make a directory
           Rmdir (1393   )               Remove a directory
           Runerror (1398   )            Abort program execution with error condition



37.5          String  handling


All things connected to string handling.



                                                                1231

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                                                       Table 37.3:

           __Name____________________________Description____________________________________________________________
             BinStr (1292   )                Construct binary representation of integer
             Chr (1298   )                   Convert ASCII code to character
             Concat (1304   )                Concatenate two strings
             Copy (1306   )                  Copy part of a string
             Delete (1309   )                Delete part of a string
             HexStr (1333   )                Construct hexadecimal representation of integer
             Insert (1341   )                Insert one string in another
             Length (1346   )                Return length of string
             Lowercase (1350   )             Convert string to all-lowercase
             OctStr (1354   )                Construct octal representation of integer
             Pos (1383   )                   Calculate position of one string in another
             SetLength (1403   )             Set length of a string
             SetString (1404   )             Set contents and length of a string
             Str (1411   )                   Convert number to string representation
             StringOfChar (1412   )          Create string consisting of a number of characters
             Upcase (1424   )                Convert string to all-uppercase
             Val (1426   )                   Convert string to number



37.6          Mathematical  routines


Functions connected to calculating and coverting numbers.



                                                       Table 37.4:

          __Name_________________________Description________________________________________________________________
            Abs (1285   )                Calculate absolute value
            Arctan (1288   )             Calculate inverse tangent
            Cos (1306   )                Calculate cosine of angle
            Dec (1307   )                Decrease value of variable
            Exp (1319   )                Exponentiate
            Frac (1326   )               Return fractional part of floating point value
            Hi (1333   )                 Return high byte/word of value
            Inc (1335   )                Increase value of variable
            Int (1342   )                Calculate integer part of floating point value
            Ln (1347   )                 Calculate logarithm
            Lo (1348   )                 Return low byte/word of value
            Odd (1354   )                Is a value odd or even ?
            Pi (1382   )                 Return the value of pi
            Power (1 )                   Raise float to integer power
            Random (1385   )             Generate random number
            Randomize (1386   )          Initialize random number generator
            Round (1396   )              Round floating point value to nearest integer number
            Sin (1408   )                Calculate sine of angle
            Sqr (1410   )                Calculate the square of a value
            Sqrt (1410   )               Calculate the square root of a value
            Swap (1415   )               Swap high and low bytes/words of a variable
            Trunc (1420   )              Truncate a floating point value



                                                                1232

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



37.7          Memory  management  functions


Functions concerning memory issues.



                                                       Table 37.5:

    __Name_______________________________________Description_______________________________________________________________
      Addr (1286   )                              Return address of variable
      Assigned (1290   )                          Check if a pointer is valid
      CompareByte (1299   )                       Compare 2 memory buffers byte per byte
      CompareChar (1300   )                       Compare 2 memory buffers byte per byte
      CompareDWord (1302   )                      Compare 2 memory buffers byte per byte
      CompareWord (1303   )                       Compare 2 memory buffers byte per byte
      CSeg (1307   )                              Return code segment
      Dispose (1310   )                           Free dynamically allocated memory
      DSeg (1311   )                              Return data segment
      FillByte (1321   )                          Fill memory region with 8-bit pattern
      FillChar (1321   )                          Fill memory region with certain character
      FillDWord (1322   )                         Fill memory region with 32-bit pattern
      FillQWord (1323   )                         Fill memory region with 64-bit pattern
      FillWord (1323   )                          Fill memory region with 16-bit pattern
      Freemem (1326   )                           Release allocated memory
      Getmem (1328   )                            Allocate new memory
      GetMemoryManager (1329   )                  Return current memory manager
      High (1334   )                              Return highest index of open array or enumerated
      IndexByte (1336   )                         Find byte-sized value in a memory range
      IndexChar (1337   )                         Find char-sized value in a memory range
      IndexDWord (1338   )                        Find DWord-sized (32-bit) value in a memory range
      IndexQWord (1339   )                        Find QWord-sized value in a memory range
      IndexWord (1339   )                         Find word-sized value in a memory range
      IsMemoryManagerSet (1345   )                Is the memory manager set
      Low (1350   )                               Return lowest index of open array or enumerated
      Move (1351   )                              Move data from one location in memory to another
      MoveChar0 (1352   )                         Move data till first zero character
      New (1352   )                               Dynamically allocate memory for variable
      Ofs (1355   )                               Return offset of variable
      Ptr (1384   )                               Combine segment and offset to pointer
      ReAllocMem (1390   )                        Resize a memory block on the heap
      Seg (1401   )                               Return segment
      SetMemoryManager (1403   )                  Set a memory manager
      Sptr (1409   )                              Return current stack pointer
      SSeg (1411   )                              Return stack segment register value



37.8          File  handling  functions


Functions concerning input and output from and to file.



                                                                1233

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                                                       Table 37.6:

               __Name_________________________Description_______________________________________________________
                 Append (1287   )             Open a file in append mode
                 Assign (1289   )             Assign a name to a file
                 Blockread (1293   )          Read data from a file into memory
                 Blockwrite (1294   )         Write data from memory to a file
                 Close (1298   )              Close a file
                 Eof (1314   )                Check for end of file
                 Eoln (1315   )               Check for end of line
                 Erase (1316   )              Delete file from disk
                 Filepos (1319   )            Position in file
                 Filesize (1320   )           Size of file
                 Flush (1325   )              Write file buffers to disk
                 IOresult (1344   )           Return result of last file IO operation
                 Read (1386   )               Read from file into variable
                 Readln (1388   )             Read from file into variable and goto next line
                 Rename (1391   )             Rename file on disk
                 Reset (1391   )              Open file for reading
                 Rewrite (1392   )            Open file for writing
                 Seek (1399   )               Set file position
                 SeekEof (1400   )            Set file position to end of file
                 SeekEoln (1401   )           Set file position to end of line
                 SetTextBuf (1404   )         Set size of file buffer
                 Truncate (1420   )           Truncate the file at position
                 Write (1430   )              Write variable to file
                 WriteLn (1430   )            Write variable to file and append newline



37.9          Constants,  types  and  variables



37.9.1         Constants

AbstractErrorProc  :  TAbstractErrorProc  =  Nil


If set, the AbstractErrorProc constant is used when an abstract error occurs.  If it is not
set, then the standard error handling is done:  A stack dump is performed, and the program
exits with error code 211.

The SysUtils unit sets this procedure and raises an exception in its handler.


AllFilesMask  =  '*'


AllFilesMask is the wildcard that can be used to return all files in a directory.  On windows
and dos based systems, this will be '*.*', while for unix systems, this will be '*'.


AllowDirectorySeparators  :  Set  of  Char  =  ['"',  '/']


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:



                                                                1234

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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.


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
(1275   ) 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.



                                                                1235

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



DriveSeparator  =  ''


On systems that support driveletters, the DriveSeparator constant denotes the character
that separates the drive indicator from the directory part in a filename path.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


Erroraddr  :  pointer  =  Nil


Address where the last error occurred.


Errorcode  :  Word  =  0


Last error code.


ErrorProc  :  TErrorProc  =  Nil


If set,  the ErrorProc constant is used when a run-time error occurs.  If it is not set,  then
the standard error handling is done:  a stack dump is performed, and the program exits with
the indicated error code.

The SysUtils unit sets this procedure and raises an exception in its handler.


ExceptProc  :  TExceptProc  =  Nil


This  constant  points  to  the  current  exception  handling  procedure.   This  routine  is  called
when  an  unhandled  exception  occurs,  i.e.   an  exception  that  is  not  stopped  by  a  except
block.

If the handler is not set, the RTL will emit a run-time error 217 when an unhandler exception
occurs.

It is set by the sysutils (1450   ) unit.


ExitProc  :  pointer  =  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)


Interface call result:  Interface not implemented


E_UNEXPECTED  =  ($8000FFFF)



                                                                1236

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Interface call result:  Unexpected error


Filemode  :  Byte  =  2


Default file mode for untyped files.


FileNameCaseSensitive  :  Boolean  =  True


FileNameCaseSensitive is True if case is important when using filenames on the current
OS. In this case, the OS will treat files with different cased names as different files.  Note that
this may depend on the filesystem:  Unix operating systems that access a DOS or Windows
partition  will  have  this  constant  set  to  true,  but  when  writing  to  the  DOS  partition,  the
casing is ignored.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


float_flag_denormal  =  2


IEC/IEEE floating-point exception flag:  ?


float_flag_divbyzero  =  4


IEC/IEEE floating-point exception flag:  Division by zero error


float_flag_inexact  =  32


IEC/IEEE floating-point exception flag:  ?


float_flag_invalid  =  1


IEC/IEEE floating-point exception flag:  Invalid operation error


float_flag_overflow  =  8


IEC/IEEE floating-point exception flag:  Overflow error


float_flag_underflow  =  16


IEC/IEEE floating-point exception flag:  Underflow error


float_round_down  =  1


Round down


float_round_nearest_even  =  0


Round to nearest even number


float_round_to_zero  =  3


Round in the direction of zero (down for positive, up for negative)



                                                                1237

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



float_round_up  =  2


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


FPC compiler internal procedure index:  addr


fpc_in_arctan_real  =  130


FPC compiler internal procedure index:  arctan (real)


fpc_in_assert_x_y  =  41


FPC compiler internal procedure index:  assert


fpc_in_assigned_x  =  19


FPC compiler internal procedure index:  assigned


fpc_in_bitsizeof_x  =  61


FPC compiler internal procedure index:  bitsizeof



                                                                1238

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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


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



                                                                1239

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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_dispose_x  =  47


FPC compiler internal procedure index:  dispose


fpc_in_exclude_x_y  =  38


FPC compiler internal procedure index:  exclude


fpc_in_exit  =  48


FPC compiler internal procedure index:  exit


fpc_in_exp_real  =  124


FPC internal compiler routine:  in_exp_real


fpc_in_fillchar_x  =  55


FPC internal compiler routine:  in_fillchar_x


fpc_in_finalize_x  =  45


FPC compiler internal procedure index:  finalize


fpc_in_frac_real  =  122


FPC internal compiler routine:  in_frac_real


fpc_in_get_caller_addr  =  57


FPC internal compiler routine:  in_get_caller_addr


fpc_in_get_caller_frame  =  58


FPC internal compiler routine:  in_get_caller_frame



                                                                1240

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



fpc_in_get_frame  =  56


FPC internal compiler routine:  in_get_frame


fpc_in_high_x  =  28


FPC compiler internal procedure index:  high


fpc_in_hi_long  =  4


FPC compiler internal procedure index:  hi (long)


fpc_in_hi_qword  =  107


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



                                                                1241

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



fpc_in_lo_long  =  3


FPC compiler internal procedure index:  lo (long)


fpc_in_lo_qword  =  106


FPC compiler internal procedure index:  lo (qword)


fpc_in_lo_word  =  1


FPC compiler internal procedure index:  lo (word)


fpc_in_mmx_pcmpeqb  =  200


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



                                                                1242

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



fpc_in_pack_x_y_z  =  59


FPC compiler internal procedure index:  pack


fpc_in_pi_real  =  126


FPC internal compiler routine:  in_pi_real


fpc_in_pred_x  =  30


FPC compiler internal procedure index:  pred


fpc_in_prefetch_var  =  109


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



                                                                1243

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



fpc_in_ror_x_x  =  66



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_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



                                                                1244

__________________________________________________________CHAPTER_37.___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_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



growheapsize1  :  PtrUInt  =  256  *  1024


Grow rate for block less than 256 Kb.



                                                                1245

               __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'_________________*
 *__________________



               growheapsize2  :  PtrUInt  =  1024  *  1024


               Grow rate for block larger than 256 Kb.


               growheapsizesmall  :  PtrUInt  =  32  *  1024


               Fixed size small blocks grow rate


               InitProc  :  Pointer  =  Nil


               InitProc is a routine that can be called after all units were initialized.  It can be set by units
               to execute code that can be initialized after all units were initialized.

Remark:         When setting the value of InitProc, the previous value should always be saved, and called
               when the installed initialization routine has finished executing.


               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 (1332   ) call.


               maxint  =  maxsmallint


               Maximum integer value.


               MaxKeptOSChunks  :  DWord  =  4



                                                                               1246

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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.


RaiseMaxFrameCount  :  LongInt  =  16



                                                                1247

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Maximum number of frames to include in TExceptObject (1268   )


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".


RT_ICON  =  (3)



                                                                1248

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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,  2@


This array is used by the Error (1316   ) routine to to convert a TRuntimeError (1273   ) enu-
meration type to a process exit code.


SafeCallErrorProc  :  TSafeCallErrorProc  =  Nil


SafeCallErrorProc is a Handler called in case of a safecall calling convention error.  Error
is  the  error  number  (passed  by  the  Windows  operating  system)  and  Addr  is  the  address
where the error occurred.


sLineBreak  =  LineEnding


sLineBreak is an alias for LineEnding (1246   ) and is supplied for Delphi compatibility.

This  constant  is  part  of  a  set  of  constants  that  describe  the  OS  characteristics.   These
constants should be used instead of hardcoding OS characteristics.


StackError  :  Boolean  =  False


Indicate whether there was a stack error.


StdErrorHandle  =  2


Value of the OS handle for the standard error-output file.



                                                                1249

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



StdInputHandle  =  0


Value of the OS handle for the standard input file.


StdOutputHandle  =  1


Value of the OS handle for the standard output file.


S_FALSE  =  1


Interface call result:  Not OK


S_OK  =  0


Interface call result:  OK


ThreadingAlreadyUsed  :  Boolean  =  False


Internal constant for the threading system.  Don't use.


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 (573  ) 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


Variant type:  variant Array


varboolean  =  11


Variant type:  Boolean type


varbyref  =  $4000


Variant type:  By reference


varbyte  =  17



                                                                1250

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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


Variant type:  Integer (64-Bit)


varinteger  =  3


Variant type:  Integer (32-bit)


varlongword  =  19


Variant type:  Word (32 bit)


varnull  =  1



                                                                1251

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Variant type:  Null (1353   ) 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


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 (1278   ).



                                                                1252

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



varunknown  =  13


Variant type:  Unknown


varustrarg  =  $49


varustrarg denotes a unicode string argument in DispInvoke call.  It will be 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 (1278   ).


varvariant  =  12


Variant type:  Variant (arrays only)


varword  =  18


Variant type:  Word (16 bit)


varword64  =  varqword


Variant type:  Word (64-bit)


vmtAfterConstruction  =  vmtMethodStart  +  ((pointer)  *  5)


VMT Layout:  ?


vmtAutoTable  =  vmtParent  +  ((pointer)  *  7)


VMT layout:  ?


vmtBeforeDestruction  =  vmtMethodStart  +  ((pointer)  *  6)


VMT Layout:  ?


vmtClassName  =  vmtParent  +  (pointer)


VMT Layout:  location of class name.


vmtDefaultHandler  =  vmtMethodStart  +  ((pointer)  *  4)


VMT Layout:  ?


vmtDefaultHandlerStr  =  vmtMethodStart  +  ((pointer)  *  7)


VMT Layout:  ?


vmtDestroy  =  vmtMethodStart



                                                                1253

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



VMT Layout:  Location of destructor pointer.


vmtDispatch  =  vmtMethodStart  +  ((pointer)  *  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 (1 )


vmtDispatchStr  =  vmtMethodStart  +  ((pointer)  *  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 (1 )


vmtDynamicTable  =  vmtParent  +  ((pointer)  *  2)


VMT Layout:  location of dynamic methods table.


vmtEquals  =  vmtMethodStart  +  ((pointer)  *  10)


vmtEquals contains the offset from the VMT start,  of the location of the TObject.Equals
(1 ) method pointer.


vmtFieldTable  =  vmtParent  +  ((pointer)  *  4)


VMT Layout:  Location of fields table.


vmtFreeInstance  =  vmtMethodStart  +  ((pointer)  *  2)


VMT Layout:  location of FreeInstance method.


vmtGetHashCode  =  vmtMethodStart  +  ((pointer)  *  11)


vmtGetHashCode  contains  the  offset  from  the  VMT  start,  of  the  location  of  the  TOb-
ject.GetHashCode (1 ) method pointer.


vmtInitTable  =  vmtParent  +  ((pointer)  *  6)


VMT Layout:  ?


vmtInstanceSize  =  0


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)



                                                                1254

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



VMT Layout:  Method table start.


vmtMsgStrPtr  =  vmtParent  +  ((pointer)  *  9)


VMT layout:  message strings table.


vmtNewInstance  =  vmtMethodStart  +  (pointer)


VMT Layout:  location of NewInstance method.


vmtParent  =  (ptruint)  *  2


VMT Layout:  location of pointer to parent VMT.


vmtSafeCallException  =  vmtMethodStart  +  ((pointer)  *  3)


VMT Layout:  ?


vmtToString  =  vmtMethodStart  +  ((pointer)  *  12)


vmtToString contains the offset from the VMT start, of the location of the TObject.ToString
(1 ) 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


vtClass  =  8


TVarRec type:  Class type


vtCurrency  =  12


TVarRec type:  Currency


vtExtended  =  3


TVarRec type:  Extended



                                                                1255

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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


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



                                                                1256

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



37.9.2         Types

AnsiChar  =  Char


Alias for 1-byte sized char.


Cardinal  =  LongWord


An unsigned 32-bits integer.


DWord  =  LongWord


An unsigned 32-bits integer


EnumResLangProc  =  function(ModuleHandle:  TFPResourceHMODULE;
                                             ResourceType:  PChar;ResourceName:  PChar;
                                             IDLanguage:  Word;lParam:  PtrInt)  :  LongBool
                                              of  object


EnumResNameProcs  used  in  the  EnumResourceLanguages  (1313   )  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  of  object


EnumResNameProcs used in the EnumResourceNames (1314   ) 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  of  object


EnumResTypeProc is used in the EnumResourceTypes (1314   ) 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.


HGLOBAL  =  PtrUInt


This is an opaque type.


HMODULE  =  PtrUInt


This is an opaque type.


HRESULT  =  LongInt



                                                                1257

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



32-Bit signed integer.


IInterface  =  IUnknown


IInterface is the basic interface from which all COM style interfaces descend.


Integer  =  SmallInt


The  system  unit  defines  Integer  as  a  signed  16-bit  integer.  But  when  DELPHI  or  OBJFPC
mode are active, then the objpas unit redefines Integer as a 32-bit integer.


IntegerArray  =  Array[0..$effffff]  of  Integer


Generic array of integer.


jmp_buf  =  packed  record
   ebx  :  LongInt;
   esi  :  LongInt;
   edi  :  LongInt;
   bp  :  Pointer;
   sp  :  Pointer;
   pc  :  Pointer;
end



Record type to store processor information.


MAKEINTRESOURCE  =  PChar


Alias for the PChar (1259   ) 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 (1259   ) type.


PAnsiString  =  ^AnsiString


Pointer to an ansistring type.


PBoolean  =  ^Boolean



                                                                1258

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



Pointer to a Boolean type.


PByte  =  ^Byte


Pointer to byte (1 ) type


pcalldesc  =  ^tcalldesc


Pointer to TCallDesc (1267   ) record.


PCardinal  =  ^Cardinal


Pointer to Cardinal (1257   ) type


PChar  =  ^Char


Or the same as a pointer to an array of char.  See the reference manual for more information
about this type.


PClass  =  ^TClass


Pointer to TClass (1267   )


PComp  =  ^Comp


PComp is a pointer to a complex type.


PCurrency  =  ^Currency


Pointer to currency type.


PDate  =  ^TDateTime


Pointer to a TDateTime (1267   ) type.


PDateTime  =  ^TDateTime


Pointer to TDatetime


PDispatch  =  ^IDispatch


Pointer to IDispatch (1432   ) interface type


pdispdesc  =  ^tdispdesc


Pointer to tdispdesc (1267   ) record


PDouble  =  ^Double


Pointer to double-sized float value.



                                                                1259

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



PDWord  =  ^DWord


Pointer to DWord (1257   ) type


pdynarrayindex  =  ^tdynarrayindex


Pointer to tdynarrayindex (1268   ) type.


pdynarraytypeinfo  =  ^tdynarraytypeinfo


Pointer to TDynArrayTypeInfo (1268   ) type.


PError  =  ^TError


Pointer to an Error (1316   ) type.


PEventState  =  pointer


Pointer to EventState, which is an opaque type.


PExceptObject  =  ^TExceptObject


Pointer to Exception handler procedural type TExceptProc (1269   )


PExtended  =  ^Extended


Pointer to extended-sized float value.


PGuid  =  ^TGuid


Pointer to TGUID (1269   ) type.


PInt64  =  ^Int64


Pointer to Int64 type


PInteger  =  ^Integer


Pointer to integer (1258   ) type


PIntegerArray  =  ^IntegerArray


Pointer to IntegerArray (1258   ) type


PInterface  =  PUnknown


Pointer to IInterface (1258   ) interface


pinterfaceentry  =  ^tinterfaceentry


Pointer to tinterfaceentry (1270   ) record.



                                                                1260

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



pinterfacetable  =  ^tinterfacetable


Pointer to tinterfacetable (1271   ) record.


PJmp_buf  =  ^jmp_buf


Pointer to jmp_buf (1258   ) record


PLongBool  =  ^LongBool


Pointer to a LongBool type.


PLongint  =  ^LongInt


Pointer to Longint (1 ) type


PLongWord  =  ^LongWord


Pointer to LongWord type


PMemoryManager  =  ^TMemoryManager


Pointer to TMemoryManager (1271   ) record


PMsgStrTable  =  ^TMsgStrTable


Pointer to array of TMsgStrTable (1271   ) records.


PointerArray  =  Array[0..512*1024*1024-2]  of  Pointer


Generic pointer array.


POleVariant  =  ^OleVariant


Pointer to OleVariant type.


PPAnsiChar  =  PPChar


Alias for PPChar (1261   ) type.


PPByte  =  ^PByte


PPByte is a pointer to a PByte (1259   ) type.


PPChar  =  ^PChar


Pointer to an array of pointers to null-terminated strings.


PPCharArray  =  ^TPCharArray


Pointer to TPCharArray (1271   ) type.



                                                                1261

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



PPDispatch  =  ^PDispatch


Pointer to PDispatch (1259   ) pointer type


PPDouble  =  ^PDouble


PPDouble is a pointer to a PDouble (1259   ) type.


PPLongint  =  ^PLongint


PPLongint is a pointer to a PLongint (1261   ) type.


PPointer  =  ^Pointer


Pointer to a pointer type.


PPointerArray  =  ^PointerArray


Pointer to PointerArray (1261   ) type


PPPChar  =  ^PPChar


PPPChar is a pointer to a PPChar (1261   )


PPPointer  =  ^PPointer


Pointer to a PPointer (1262   ) type.


PPPWideChar  =  ^PPWideChar


PPPWideChar is a pointer to a PPWideChar (1262   ) type.


PPtrInt  =  ^PtrInt


Pointer to PtrInt (1263   ) 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



                                                                1262

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



PRTLCriticalSection  =  ^TRTLCriticalSection


Pointer to #rtl.system.TRTLCriticalSection (1272   ) type.


PRTLEvent  =  pointer


Pointer to RTLEvent, which is an opaque type.


PShortInt  =  ^ShortInt


Pointer to shortint (1 ) type


PShortString  =  ^ShortString


Pointer to a shortstring type.


PSingle  =  ^Single


Pointer to single-sized float value.


PSizeInt  =  ^SizeInt


Pointer to a SizeInt (1265   ) type


PSmallInt  =  ^SmallInt


Pointer to smallint (1 ) type


pstringmessagetable  =  ^TStringMessageTable


Pointer to TStringMessageTable (1275   ) record.


PText  =  ^Text


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 (1264   ) instead.



                                                                1263

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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 (1281   ) character.


PUCS4Char  =  ^UCS4Char


Pointer to UCS4Char (1281   )


PUCS4CharArray  =  ^TUCS4CharArray


Pointer to array of UCS4Char (1281   ) characters.


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 (1282   )


pvararray  =  ^tvararray


Pointer to TVarArray (1278   ) type.


pvararraybound  =  ^tvararraybound


Pointer to tvararraybound (1278   ) type.


pvararrayboundarray  =  ^tvararrayboundarray


Pointer to tvararrayboundarray (1278   ) type.


pvararraycoorarray  =  ^tvararraycoorarray


Pointer to tvararraycoorarray (1278   ) type.



                                                                1264

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



pvardata  =  ^tvardata


Pointer to TVarData (1278   ) record.


PVariant  =  ^Variant


Pointer to Variant type.


pvariantmanager  =  ^tvariantmanager


Pointer to TVariantManager (1279   ) record.


PVarRec  =  ^TVarRec


Pointer to TVarRec (1280   ) type.


PVmt  =  ^TVmt


Pointer to TVMT (1281   ) record


PWideChar  =  ^WideChar


Pointer to WChar (1282   ).


PWideString  =  ^WideString


Pointer to widestring type


PWord  =  ^Word


Pointer to word (1 ) type


PWordBool  =  ^WordBool


Pointer to a WordBool type.


Real  =  Double


Alias for real type


real48  =  Array[0..5]  of  Byte


TP compatible real type (6 bytes) definition


SizeInt  =  LongInt


Signed integer type which fits for sizes


SizeUInt  =  DWord


Unsigned Integer type which fits for sizes



                                                                1265

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TAbstractErrorProc  =  procedure


Abstract error handler procedural type.


TAllocateThreadVarsHandler  =  procedure


Threadvar allocation callback type for TThreadManager (1276   ).


TAnsiChar  =  Char


Alias for 1-byte sized char.


TAssertErrorProc  =  procedure(const  msg:  ShortString;
                                               const  fname:  ShortString;lineno:  LongInt;
                                               erroraddr:  pointer)


Assert error handler procedural type.


TBackTraceStrFunc  =  function(Addr:  Pointer)  :  ShortString


Type for formatting of backtrace dump.


TBasicEventCreateHandler  =  function(EventAttributes:  Pointer;
                                                           AManualReset:  Boolean;
                                                           InitialState:  Boolean;
                                                           const  Name:  ansistring)
                                                             :  PEventState


callback type for creating eventstate in TThreadManager (1276   ).


TBasicEventHandler  =  procedure(state:  PEventState)


Generic callback type for handling eventstate in TThreadManager (1276   ).


TBasicEventWaitForHandler  =  function(timeout:  Cardinal;
                                                             state:  PEventState)  :  LongInt


Wait for basic event callback type for TThreadManager (1276   ).


TBeginThreadHandler  =  function(sa:  Pointer;stacksize:  PtrUInt;
                                                   ThreadFunction:  TThreadFunc;p:  pointer;
                                                   creationFlags:  DWord;
                                                   var  ThreadId:  TThreadID)  :  TThreadID


Callback for thread start in TThreadManager (1276   ).


TBoundArray  =  Array  of  SizeInt


Dynamic array of integer.



                                                                1266

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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 (1439   ).


TCriticalSectionHandler  =  procedure(var  cs)


Generic callback type for critical section handling in TThreadManager (1276   ).


TCriticalSectionHandlerTryEnter  =  function(var  cs)  :  LongInt


TCriticalSectionHandlerTryEnter is the function prototype for the TryEnterCriticalsec-
tion  (1421   )  function,  in  the  TThreadManager  (1276   )  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 (1267   )
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.


tdynarrayindex  =  SizeInt



                                                                1267

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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 (1312   ) call.


TEndThreadHandler  =  procedure(ExitCode:  DWord)


Callback for thread end in TThreadManager (1276   ).


TEntryInformation  =  record
   InitFinalTable  :  Pointer;
   ThreadvarTablesTable  :  Pointer;
   asm_exit  :  procedure  of  object;
   PascalMain  :  procedure  of  object;
   valgrind_used  :  Boolean;
end



TEntryInformation  is  used  to  initialize  a  Free  Pascal  program  or  library.  Under  normal
circumstances,  there  should  be  no  need  to  use  this  structure  directly:   it  is  used  by  the
system unit and special linking units.


TError  =  LongInt


Error type, used in variants.


TErrorProc  =  procedure(ErrNo:  LongInt;Address:  Pointer;Frame:  Pointer)


Standard error handler procedural type.


TExceptObject  =  record
   FObject  :  TObject;
   Addr  :  pointer;
   Next  :  PExceptObject;
   refcount  :  LongInt;
   Framecount  :  LongInt;
   Frames  :  PPointer;
end



TExceptObject is the exception description record which is found on the exception stack.



                                                                1268

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TExceptProc  =  procedure(Obj:  TObject;Addr:  Pointer;FrameCount:  LongInt;
                                       Frame:  PPointer)


Exception handler procedural type


TextFile  =  Text


Alias for Text file type.


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  (1270   )  record  defined  by  Delphi,  which  contains  information  not  meaningful
for  the  FPC  heap  manager.  The  heap  status  can  be  retrieved  by  the  GetFPCHeapStatus
(1328   ) 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.


TGetCurrentThreadIdHandler  =  function  :  TThreadID


Callback type for retrieving thread ID in TThreadManager (1276   ).


TGuid  =  packed  record
end



Standard GUID representation type.


THandle  =  LongInt



                                                                1269

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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 (1328   ) call.


TInitThreadVarHandler  =  procedure(var  offset:  DWord;size:  DWord)


Threadvar initialization callback type for TThreadManager (1276   ).


TInterfacedClass  =  Class  of  TInterfacedObject


TInterfacedClass is a descendent of


tinterfaceentry  =  record
   IID  :  PGuid;
   VTable  :  Pointer;
   IOffset  :  PtrUInt;
   IIDStr  :  PShortString;
end



tinterfaceentry is used to store the list of Interfaces of a class.  This list is stored as an
array of  tinterfaceentry records.


tinterfaceentrytype  =  (etStandard,etVirtualMethodResult,
                                     etStaticMethodResult,etFieldValue,
                                     etVirtualMethodClass,etStaticMethodClass,
                                     etFieldValueClass)



                     Table 37.7:  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



                                                                1270

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



This is an internal type for the compiler to encode calls to dispatch interfaces.


tinterfacetable  =  record
   EntryCount  :  PtrUInt;
   Entries  :  Array[0..0]  of  tinterfaceentry;
end



Record to store list of interfaces of a class.


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  :  Pointer;
   Data  :  Pointer;
end



TMethod  describes  a  general  method  pointer,  and  is  used  in  Run-Time  Type  Information
handling.


TMsgStrTable  =  record
   name  :  PShortString;
   method  :  pointer;
end



Record used in string message handler table.


TPCharArray  =  packed  Array[0..(MaxLongintdivSizeOf(PChar))-1]  of  PChar


Array of PChar


TProcedure  =  procedure


Simple procedural type.



                                                                1271

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TReleaseThreadVarsHandler  =  procedure


Threadvar release callback type for TThreadManager (1276   ).


TRelocateThreadVarHandler  =  function(offset:  DWord)  :  pointer


Threadvar relocalization callback type for TThreadManager (1276   ).


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 (1276   ).


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.



                                                                1272

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



TRTLEventHandler  =  procedure(AEvent:  PRTLEvent)


Generic TRTLEvent handling type for TThreadManager (1276   ).


TRTLEventHandlerTimeout  =  procedure(AEvent:  PRTLEvent;timeout:  LongInt)


TRTLEvent timeout handling type for TThreadManager (1276   ).


TRTLEventSyncHandler  =  procedure(m:  trtlmethod;p:  TProcedure)


Callback type for event sycnhronization in TThreadManager (1276   ).


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)



                                                                1273

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                        Table 37.8:  Enumeration values for type TRuntimeError


                       __Value____________________________Explanation__________________________________
                         reAccessViolation                Access Violation
                         reAssertionFailed                Assertion failed error
                         reCodesetConversion              Code set conversion error
                         reControlBreak                   User pressed CTRL-C
                         reDivByZero                      Division by zero error
                         reExternalException              An external exception occurred
                         reIntfCastError                  Interface typecast error
                         reIntOverflow                    Integer overflow error
                         reInvalidCast                    Invalid (class) typecast error
                         reInvalidOp                      Invalid operation error
                         reInvalidPtr                     Invalid pointer error
                         reNone                           No error
                         reOutOfMemory                    Out of memory error
                         reOverflow                       Overflow error
                         rePrivInstruction                Privileged instruction error
                         reQuit                           Quit signal error
                         reRangeError                     Range check error
                         reSafeCallError                  Safecall (IDispInterface) error
                         reStackOverflow                  Stack overflow error
                         reUnderflow                      Underflow error
                         reVarArrayBounds                 Variant array bounds error
                         reVarArrayCreate                 Variant array creation error
                         reVarDispatch                    Variant Dispatch error.
                         reVarInvalidOp                   Invalid variant operation error
                         reVarNotArray                    Variant is not an array error.
                         reVarTypeCast                    Invalid typecase from variant
                         reZeroDivide                     Division by zero error



TRuntimeError is used in the Error (1316   ) procedure to indicate what kind of error should
be reported.


TSafeCallErrorProc  =  procedure(error:  HRESULT;addr:  pointer)


Prototype  of  a  safecall  error  handler  routine.   Error  is  the  error  number  (passed  by  the
Windows operating system) and Addr is the address where the error occurred.


TSemaphoreDestroyHandler  =  procedure(const  sem:  Pointer)


TSemaphoreDestroyHandler is the function prototype to destroy an existing semaphore, as
returned by (ThreadManager.SemaphoreInit).  It is used by the thread manager (ThreadManager.SemaphoreDestroy)


TSemaphorePostHandler  =  procedure(const  sem:  Pointer)


TSemaphorePostHandler  is  the  function  prototype  to  post  an  event  to  the  semaphore.  It
should handle a pointer as returned by the ThreadManager.SemaphoreInit procedure.  it's
used by the thread manager ThreadManager.SemaphorePost.


TSemaphoreWaitHandler  =  procedure(const  sem:  Pointer)



                                                                1274

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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.


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 (1271   ) records.


TTextLineBreakStyle  =  (tlbsLF,tlbsCRLF,tlbsCR)



                    Table 37.9:  Enumeration values for type TTextLineBreakStyle


                 __Value____________Explanation_______________________________________________________________
                   tlbsCR            Carriage-return (#13, Mac-OS style)
                   tlbsCRLF          Carriage-return, line-feed (#13#30, Windows style)
                   tlbsLF            Line-feed only (#10, unix style)



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 (1276   ).


TThreadHandler  =  function(threadHandle:  TThreadID)  :  DWord


Generic thread handler callback for TThreadManager (1276   ).


TThreadID  =  PtrUInt


This is an opaque type, it can differ from operating system to operating system.



                                                                1275

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'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;
   InitThreadVar  :  TInitThreadVarHandler;
   RelocateThreadVar  :  TRelocateThreadVarHandler;
   AllocateThreadVars  :  TAllocateThreadVarsHandler;
   ReleaseThreadVars  :  TReleaseThreadVarsHandler;
   BasicEventCreate  :  TBasicEventCreateHandler;
   BasicEventDestroy  :  TBasicEventHandler;
   BasicEventResetEvent  :  TBasicEventHandler;
   BasicEventSetEvent  :  TBasicEventHandler;
   BasiceventWaitFOr  :  TBasicEventWaitForHandler;
   RTLEventCreate  :  TRTLCreateEventHandler;
   RTLEventDestroy  :  TRTLEventHandler;
   RTLEventSetEvent  :  TRTLEventHandler;
   RTLEventResetEvent  :  TRTLEventHandler;
   RTLEventWaitFor  :  TRTLEventHandler;
   RTLEventSync  :  TRTLEventSyncHandler;
   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  (1406   )  procedure,  and  the  current  thread  manager  can  be  retrieved  with
the GetThreadManager (1330   ) 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;



                                                                1276

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                                                             Prio:  LongInt)  :  Boolean


Callback type for thread priority setting in TThreadManager (1276   ).


TThreadSwitchHandler  =  procedure


Callback type for thread switch in TThreadManager (1276   ).


TTime  =  TDateTime


TTime is defined for Delphi compatibility.  This type is deprecated, use TDateTime (1267   )
instead.


TUCS4CharArray  =  Array[0..$effffff]  of  UCS4Char


Array of UCS4Char (1281   ) characters.


TUnicodeStringManager  =  record
   Wide2AnsiMoveProc  :  procedure(source:  PWideChar;var  dest:  ansistring;len:  SizeInt);
   Ansi2WideMoveProc  :  procedure(source:  PChar;var  dest:  widestring;len:  SizeInt);
   UpperWideStringProc  :  function(const  S:  WideString)  :  WideString;
   LowerWideStringProc  :  function(const  S:  WideString)  :  WideString;
   CompareWideStringProc  :  function(const  s1:  WideString;const  s2:  WideString)  :  PtrInt;
   CompareTextWideStringProc  :  function(const  s1:  WideString;const  s2:  WideString)  :  PtrInt;
   CharLengthPCharProc  :  function(const  Str:  PChar)  :  PtrInt;
   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:  ansistring;len:  SizeInt);
   Ansi2UnicodeMoveProc  :  procedure(source:  PChar;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;
end



TUnicodeStringManager is currently the same as the TUnicodeStringManager (1277   ) 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



                                                                1277

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



   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 (1278   ) records equal to the number of dimensions in the
array (dimcoun).


tvararraybound  =  record
   elementcount  :  LongInt;
   lowbound  :  LongInt;
end



tvararraybound is used to describe one dimension in a variant array.


tvararrayboundarray  =  Array[0..0]  of  tvararraybound


array of tvararraybound (1278   ) records.


tvararraycoorarray  =  Array[0..0]  of  LongInt


Array of variant array coordinates


tvardata  =  packed  record
   vtype  :  tvartype;
end



TVarData  is  a  record  representation  of  a  variant.   It  contains  the  internal  structure  of  a
variant and is handled by the various variant handling routines.


tvariantmanager  =  record
   vartoint  :  function(const  v:  variant)  :  LongInt;
   vartoint64  :  function(const  v:  variant)  :  Int64;
   vartoword64  :  function(const  v:  variant)  :  QWord;
   vartobool  :  function(const  v:  variant)  :  Boolean;
   vartoreal  :  function(const  v:  variant)  :  extended;
   vartotdatetime  :  function(const  v:  variant)  :  TDateTime;
   vartocurr  :  function(const  v:  variant)  :  currency;
   vartopstr  :  procedure(var  s;const  v:  variant);
   vartolstr  :  procedure(var  s:  ansistring;const  v:  variant);
   vartowstr  :  procedure(var  s:  widestring;const  v:  variant);
   vartointf  :  procedure(var  intf:  IInterface;const  v:  variant);
   vartodisp  :  procedure(var  disp:  IDispatch;const  v:  variant);
   vartodynarray  :  procedure(var  dynarr:  pointer;const  v:  variant;typeinfo:  pointer);
   varfrombool  :  procedure(var  dest:  variant;const  source:  Boolean);



                                                                1278

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



   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;const  source:  tvardata;calldesc:  pcalldesc;
                   params:  pointer)  of  object;
   vararrayredim  :  procedure(var  a:  variant;highbound:  SizeInt);
   vararrayget  :  function(const  a:  variant;indexcount:  SizeInt;indices:  PLongint)
                   :  variant  of  object;
   vararrayput  :  procedure(var  a:  variant;const  value:  variant;indexcount:  SizeInt;
                   indices:  PLongint)  of  object;
   writevariant  :  function(var  t:  text;const  v:  variant;width:  LongInt)  :  Pointer;
   write0Variant  :  function(var  t:  text;const  v:  Variant)  :  Pointer;
end



TVariantManager  describes  the  variant  manager  as  expected  by  the  SetVariantManager
(1407   ) call.


tvarop  =  (opadd,opsubtract,opmultiply,opdivide,opintdivide,opmodulus,
                opshiftleft,opshiftright,opand,opor,opxor,opcompare,opnegate,
                opnot,opcmpeq,opcmpne,opcmplt,opcmple,opcmpgt,opcmpge,oppower)



                                                                1279

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



                             Table 37.10:  Enumeration values for type tvarop


                 __Value_______________Explanation___________________________________________________________
                   opadd               Variant operation:  Addition.
                   opand               Variant operation:  Binary AND operation
                   opcmpeq             Variant operation:  Compare equal.
                   opcmpge             Variant operation:  Compare larger than or equal
                   opcmpgt             Variant operation:  Compare larger than
                   opcmple             Variant operation:  Compare less than or equal to
                   opcmplt             Variant operation:  Compare less than.
                   opcmpne             Variant operation:  Compare not equal
                   opcompare           Variant operation:  Compare
                   opdivide            Variant operation:  division
                   opintdivide         Variant operation:  integer divide
                   opmodulus           Variant operation:  Modulus
                   opmultiply          Variant operation:  multiplication
                   opnegate            Variant operation:  negation.
                   opnot               Variant operation:  Binary NOT operation.
                   opor                Variant operation:  Binary OR operation
                   oppower             Variant operation:  Power
                   opshiftleft         Variant operation:  Shift left
                   opshiftright        Variant operation:  Shift right
                   opsubtract          Variant operation:  Substraction
                   opxor               Variant operation:  binary XOR operation.



tvarop describes a variant operation.  It is mainly used for the variant manager to implement
the various conversions and mathematical operations on a variant.


TVarRec  =  record
end



TVarRec is a record generated by the compiler for each element in a array  of  const call.
The procedure that receives the constant array receives an array of  TVarRec elements, with
lower bound zero and high bound equal to the number of elements in the array minus one
(as returned by High(Args))


tvartype  =  Word


Type with size of variant type.


TVmt  =  record
   vInstanceSize  :  SizeInt;
   vInstanceSize2  :  SizeInt;
   vParent  :  PVmt;
   vClassName  :  PShortString;
   vDynamicTable  :  Pointer;
   vMethodTable  :  Pointer;
   vFieldTable  :  Pointer;
   vTypeInfo  :  Pointer;
   vInitTable  :  Pointer;



                                                                1280

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



   vAutoTable  :  Pointer;
   vIntfTable  :  pinterfacetable;
   vMsgStrPtr  :  pstringmessagetable;
   vDestroy  :  Pointer;
   vNewInstance  :  Pointer;
   vFreeInstance  :  Pointer;
   vSafeCallException  :  Pointer;
   vDefaultHandler  :  Pointer;
   vAfterConstruction  :  Pointer;
   vBeforeDestruction  :  Pointer;
   vDefaultHandlerStr  :  Pointer;
   vDispatch  :  Pointer;
   vDispatchStr  :  Pointer;
   vEquals  :  Pointer;
   vGetHashCode  :  Pointer;
   vToString  :  Pointer;
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 (1276   ).


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 (1281   ) characters.


UInt64  =  QWord


Unsigned 64-bit integer


UnicodeChar  =  WideChar


UnicodeChar is a single character from a UnicodeString.  It equals WideChar in all respects.


UTF8String  =  ansistring



                                                                1281

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



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 (1426   ) function.


ValUInt  =  Cardinal


Integer with the same size as the return code of the Val (1426   ) function.


WChar  =  WideChar


Wide char (16-bit sized char)



37.9.3         Variables

argc  :  LongInt


argc contains the number of command-line arguments passed to the program by the OS. It
is not available on all systems.


argv  :  PPChar


argv contains a pointer to a nil-terminated array of null-terminated strings, containing the
command-line arguments passed to the program by the OS. It is not available on all systems.


DispCallByIDProc  :  pointer


VarDispProc is called by the compiler if it needs to perform an interface call from a variant
which contains a dispatch interface.  For instance, the following call:


Var
    V  :  OleVariant;
begin
    (V  as  IWord).OpenDocument('c:"temp"mydoc.doc');
end;


where IWord is a dispatch interface is encoded by the compiler and passed to DispCallByIDProc.

This pointer must be set by a routine that calls the OS COM handling routines.


envp  :  PPChar


envp contains a pointer to a nil-terminated array of null-terminated strings, containing the
environment variables passed to the program by the OS. It is not available on all systems.


ErrOutput  :  Text



                                                                1282

__________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________________________*
 *___



ErrOutput is provided for Delphi compatibility.


ExitCode  :  LongInt


Exit code for the program, will be communicated to the OS on exit.


fpc_threadvar_relocate_proc  :  pointer



InOutRes  :  Word


Result of last I/O operation.  Read-Only.


Input  :  Text


Standard input text file.


IsConsole  :  Boolean


True for console applications, False for GUI applications.


IsLibrary  :  Boolean  =  false


True if the current module is a library.  Otherwise module is an excutable


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.


Output  :  Text


Standard output text file.


RandSeed  :  Cardinal


Seed for Random (1385   ) function.



                                                                1283

__________________________________________________________CHAPTER_37.___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  :  Byte


Current soft float exception flags


softfloat_exception_mask  :  Byte


Current soft float exception mask


softfloat_rounding_mode  :  Byte


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.


StackTop  :  Pointer


StackTop contains the top of the stack for the current process.  It is used to check the heap
on some operating systems, and is set by the system unit initialization code.  Do not use or
modify this value.


StdErr  :  Text


Standard diagnostic output text file.


StdOut  :  Text


Alias for Output (1283   ).


ThreadID  :  TThreadID


Current Thread ID.


widestringmanager  :  TUnicodeStringManager


Contains the current widestring manager.  Do not use directly.



                                                                1284

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10            Procedures  and  functions



                37.10.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 (1396   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.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
                (1234   ) constant is set, it will be called instead.

       Errors:   This routine causes a run-time error 211.

    See also:    AbstractErrorProc (1234   )



                37.10.3          AcquireExceptionObject

    Synopsis:    Obtain a reference to the current exception object

Declaration:     function  AcquireExceptionObject  :  Pointer

    Visibility:   default



                                                                                1285

                __________________________________________________________CHAPTER_37.___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 (1390   ) 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 (1390   )



                37.10.4          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 (1236   )



                37.10.5          Addr

    Synopsis:    Return address of a variable

Declaration:     function  Addr(X:  TAnytype)  :  Pointer

    Visibility:   default

Description:     Addr returns a pointer to its argument, which can be any type, or a function or procedure
                name.  The returned pointer isn't typed.  The same result can be obtained by the @ operator,
                which can return a typed pointer (see the programmer's guide).

       Errors:   None

    See also:    SizeOf (1408   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1286

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.6          Align

    Synopsis:    Return aligned version of an address

Declaration:     function  Align(Addr:  PtrUInt;Alignment:  PtrUInt)  :  PtrUInt
                function  Align(Addr:  Pointer;Alignment:  PtrUInt)  :  Pointer

    Visibility:   default

Description:     Align returns Address, aligned to Alignment bytes.

       Errors:   None.



                37.10.7          AllocMem

    Synopsis:    Allocate and clear memory.

Declaration:     function  AllocMem(Size:  PtrUInt)  :  pointer

    Visibility:   default

Description:     AllocMem calls getmem GetMem (1328   ), and clears the allocated memory, i.e.  the allocated
                memory is filled with Size zero bytes.

    See also:    GetMem (1328   )



                37.10.8          AnsiToUtf8

    Synopsis:    Convert ansi string to UTF-8 string

Declaration:     function  AnsiToUtf8(const  s:  ansistring)  :  UTF8String

    Visibility:   default

Description:     AnsiToUtf8 converts the ansistring S to a 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 (1426   )



                37.10.9          Append

    Synopsis:    Open a file in append mode

Declaration:     procedure  Append(var  t:  Text)

    Visibility:   default

Description:     Append opens an existing file in append mode.  Any data written to F will be appended to
                the file.  Only text files can be opened in append mode.  After a call to Append,  the file F
                becomes write-only.  File sharing is not taken into account when calling Append.

       Errors:   If the file doesn't exist when appending, a run-time error will be generated.  This behaviour
                has changed on Windows and Linux platforms, where in versions prior to 1.0.6, the file would
                be created in append mode.



                                                                                1287

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    See also:    Rewrite (1392   ), Close (1298   ), Reset (1391   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.10           arctan

    Synopsis:    Calculate inverse tangent

Declaration:     function  arctan(d:  ValReal)  :  ValReal

    Visibility:   default

Description:     Arctan returns the Arctangent of  X, which can be any Real type.  The resulting angle is in
                radial units.

       Errors:   None

    See also:    Sin (1408   ), Cos (1306   )


                Listing:  ./refex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   Program       t o  d e m o n s t r a t et h e  ArcTan      f u n c t i o n.  }


                Var    R   :   R e a l;


                 b e g i n
                    R := ArcTan     ( 0 ) ;          {  R : = 0  }
                    R := ArcTan     ( 1 ) /p i;      {  R : = 0 . 2 5 }
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.11           ArrayStringToPPchar

    Synopsis:    Concert an array of string to an array of null-terminated strings

Declaration:     function  ArrayStringToPPchar(const  S:  Array  of  AnsiString;
                                                              reserveentries:  LongInt)  :  PPChar

    Visibility:   default



                                                                                1288

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1412   )



                37.10.12           Assert

    Synopsis:    Check validity of a given condition.

Declaration:     procedure  Assert(Expr:  Boolean)
                procedure  Assert(Expr:  Boolean;const  Msg:  string)

    Visibility:   default

Description:     With assertions on,  Assert tests if  expr is false,  and if so,  aborts the application with a
                Runtime error 227 and an optional error message in msg.  If  expr is true,  program execu-
                tion  continues  normally.   If  assertions  are  not  enabled  at  compile  time,  this  routine  does
                nothing,  and  no  code  is  generated  for  the  Assert  call.  Enabling  and  disabling  assertions
                at compile time is done via the \$C or \$ASSERTIONS compiler switches.  These are global
                switches.   The  default  behavior  of  the  assert  call  can  be  changed  by  setting  a  new  han-
                dler  in  the  AssertErrorProc  variable.   Sysutils  overrides  the  default  handler  to  raise  a
                EAssertionFailed exception.

       Errors:   None.

    See also:    Halt (1332   ), Runerror (1398   )



                37.10.13           Assign

    Synopsis:    Assign a name to a file

Declaration:     procedure  Assign(out  f:  File;const  Name:  string)
                procedure  Assign(out  f:  File;p:  PChar)
                procedure  Assign(out  f:  File;c:  Char)
                procedure  Assign(out  f:  TypedFile;const  Name:  string)
                procedure  Assign(out  f:  TypedFile;p:  PChar)
                procedure  Assign(out  f:  TypedFile;c:  Char)
                procedure  Assign(out  t:  Text;const  s:  string)
                procedure  Assign(out  t:  Text;p:  PChar)
                procedure  Assign(out  t:  Text;c:  Char)

    Visibility:   default

Description:     Assign assigns a name to F, which can be any file type.  This call doesn't open the file, it
                just assigns a name to a file variable, and marks the file as closed.

       Errors:   None.

    See also:    Reset (1391   ), Rewrite (1392   ), Append (1287   )


                Listing:  ./refex/ex5.pp



                                                                                1289

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.14           Assigned

    Synopsis:    Check if a pointer is valid

Declaration:     function  Assigned(P:  Pointer)  :  Boolean

    Visibility:   default

Description:     Assigned returns True if P is non-nil and retuns False of P is nil.  The main use of Assigned
                is that Procedural variables, method variables and class-type variables also can be passed to
                Assigned.

       Errors:   None

    See also:    New (1352   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1290

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.15           BasicEventCreate

    Synopsis:    Obsolete.  Don't use

Declaration:     function  BasicEventCreate(EventAttributes:  Pointer;
                                                         AManualReset:  Boolean;InitialState:  Boolean;
                                                         const  Name:  ansistring)  :  PEventState

    Visibility:   default

Description:     BasicEventCreate is obsolete, use RTLEventCreate (1396   ) instead.

    See also:    RTLEventCreate (1396   )



                37.10.16           basiceventdestroy

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  basiceventdestroy(state:  PEventState)

    Visibility:   default

Description:     basiceventdestroy is obsolete.  Use RTLEventDestroy (1397   ) instead.

    See also:    RTLEventDestroy (1397   )



                37.10.17           basiceventResetEvent

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  basiceventResetEvent(state:  PEventState)

    Visibility:   default

Description:     basiceventResetEvent is obsolete.  Use RTLEventResetEvent (1397   ) instead.

    See also:    RTLEventResetEvent (1397   )



                37.10.18           basiceventSetEvent

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  basiceventSetEvent(state:  PEventState)

    Visibility:   default

Description:     basiceventSetEvent is obsolete.  Use RTLEventSetEvent (1397   ) instead.

    See also:    RTLEventSetEvent (1397   )



                37.10.19           basiceventWaitFor

    Synopsis:    Obsolete.  Don't use

Declaration:     function  basiceventWaitFor(Timeout:  Cardinal;state:  PEventState)
                                                             :  LongInt

    Visibility:   default

Description:     basiceventwaitfor is obsolete.  Use RTLEventWaitFor (1398   ) instead.

    See also:    RTLEventWaitFor (1398   )



                                                                                1291

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.20           BeginThread

    Synopsis:    Start a new thread.

Declaration:     function  BeginThread(sa:  Pointer;stacksize:  SizeUInt;
                                                 ThreadFunction:  TThreadFunc;p:  pointer;
                                                 creationFlags:  DWord;var  ThreadId:  TThreadID)
                                                   :  TThreadID
                function  BeginThread(ThreadFunction:  TThreadFunc)  :  TThreadID
                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 (1312   )



                37.10.21           BEtoN

    Synopsis:    Convert Big Endian-ordered integer to Native-ordered integer

Declaration:     function  BEtoN(const  AValue:  SmallInt)  :  SmallInt
                function  BEtoN(const  AValue:  Word)  :  Word
                function  BEtoN(const  AValue:  LongInt)  :  LongInt
                function  BEtoN(const  AValue:  DWord)  :  DWord
                function  BEtoN(const  AValue:  Int64)  :  Int64
                function  BEtoN(const  AValue:  QWord)  :  QWord

    Visibility:   default

Description:     BEToN will rearrange the bytes in a Big-Endian number to the native order for the current
                processor.   That  is,  for  a  big-endian  processor,  it  will  do  nothing,  and  for  a  little-endian
                processor, it will invert the order of the bytes.

    See also:    LEtoN (1347   ), NtoBE (1353   ), NtoLE (1353   )



                37.10.22           binStr

    Synopsis:    Convert integer to string with binary representation.

Declaration:     function  binStr(Val:  LongInt;cnt:  Byte)  :  shortstring
                function  binStr(Val:  Int64;cnt:  Byte)  :  shortstring
                function  binStr(Val:  QWord;cnt:  Byte)  :  shortstring



                                                                                1292

                __________________________________________________________CHAPTER_37.___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 (1411   ), Val (1426   ), HexStr (1333   ), OctStr (1354   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.23           BlockRead

    Synopsis:    Read data from an untyped file into memory

Declaration:     procedure  BlockRead(var  f:  File;var  Buf;count:  Int64;var  Result:  Int64)
                procedure  BlockRead(var  f:  File;var  Buf;count:  LongInt;
                                                var  Result:  LongInt)
                procedure  BlockRead(var  f:  File;var  Buf;count:  Cardinal;
                                                var  Result:  Cardinal)
                procedure  BlockRead(var  f:  File;var  Buf;count:  Word;var  Result:  Word)
                procedure  BlockRead(var  f:  File;var  Buf;count:  Word;var  Result:  Integer)
                procedure  BlockRead(var  f:  File;var  Buf;count:  Int64)

    Visibility:   default

Description:     Blockread  reads  count  or  less  records  from  file  F.  A  record  is  a  block  of  bytes  with  size
                specified by the Rewrite (1392   ) or Reset (1391   ) 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 (1294   ), Close (1298   ), Reset (1391   ), Assign (1289   )


                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. }



                                                                                1293

                __________________________________________________________CHAPTER_37.___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___.____________________________________________________________________________________________________________*
 *___________



                37.10.24           BlockWrite

    Synopsis:    Write data from memory to an untyped file

Declaration:     procedure  BlockWrite(var  f:  File;const  Buf;Count:  Int64;
                                                 var  Result:  Int64)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  LongInt;
                                                 var  Result:  LongInt)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  Cardinal;
                                                 var  Result:  Cardinal)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  Word;var  Result:  Word)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  Word;
                                                 var  Result:  Integer)
                procedure  BlockWrite(var  f:  File;const  Buf;Count:  LongInt)

    Visibility:   default

Description:     BlockWrite writes count records from buffer to the file F.A record is a block of bytes with
                size specified by the Rewrite (1392   ) or Reset (1391   ) 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 (1293   ), Close (1298   ), Rewrite (1392   ), Assign (1289   )



                37.10.25           Break

    Synopsis:    Exit current loop construct.

Declaration:     procedure  Break



                                                                                1294

                __________________________________________________________CHAPTER_37.___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 (1305   ), Exit (1318   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.26           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 (1296   ), BsfWord (1296   ), BsfDWord (1296   ), BsfQWord (1296   )



                                                                                1295

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.27           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 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 (1295   ), BsfWord (1296   ), BsrDWord (1297   ), BsfQWord (1296   )



                37.10.28           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 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 (1295   ), BsfWord (1296   ), BsfDWord (1296   ), BsrQWord (1297   )



                37.10.29           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  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 (1295   ), BsrWord (1297   ), BsfDWord (1296   ), BsfQWord (1296   )



                37.10.30           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 (1295   ), BsrWord (1297   ), BsrDWord (1297   ), BsrQWord (1297   )



                                                                                1296

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.31           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 (1296   ), BsrWord (1297   ), BsfDWord (1296   ), BsrQWord (1297   )



                37.10.32           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 (1295   ), BsfWord (1296   ), BsfDWord (1296   ), BsrQWord (1297   )



                37.10.33           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 (1296   ), BsfWord (1296   ), BsrDWord (1297   ), BsrQWord (1297   )



                37.10.34           chdir

    Synopsis:    Change current working directory.

Declaration:     procedure  chdir(const  s:  string);    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 (1351   ), Rmdir (1393   )


                Listing:  ./refex/ex7.pp



                                                                                1297

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.35           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 (1380   ), Str (1411   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.36           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 (1391   ) or Rewrite (1392   ) 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.



                                                                                1298

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    See also:    Assign (1289   ), Reset (1391   ), Rewrite (1392   ), Flush (1325   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.37           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  (1292   ).   It  must
                be called after the thread has ended (either by exiting the thread function or after calling
                EndThread (1312   )).

       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 (1292   ), EndThread (1312   )



                37.10.38           CompareByte

    Synopsis:    Compare 2 memory buffers byte per byte

Declaration:     function  CompareByte(const  buf1;const  buf2;len:  SizeInt)  :  SizeInt

    Visibility:   default

Description:     CompareByte compares two memory regions buf1,buf2 on a byte-per-byte basis for a total
                of  len bytes.

                The function returns one of the following values:


                less than 0      if buf1 and buf2 contain different bytes in the first len bytes, and the first such
                       byte is smaller in buf1 than the byte at the same position in buf2.

                0 if the first len bytes in buf1 and buf2 are equal.

                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.



                                                                                1299

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    See also:    CompareChar (1300   ), CompareChar0 (1302   ), CompareWord (1303   ), CompareDWord (1302   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.39           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.



                                                                                1300

            __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'____________________*
 *_______________



            0if the first len characters in buf1 and buf2 are equal.

            1if  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 (1299   ), CompareChar0 (1302   ), CompareWord (1303   ), CompareDWord (1302   )


            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
                   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   ;



                                                                            1301

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                37.10.40           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 (1299   ), CompareChar (1300   ), CompareDWord (1302   ), CompareWord (1303   )



                37.10.41           CompareDWord

    Synopsis:    Compare 2 memory buffers DWord per DWord

Declaration:     function  CompareDWord(const  buf1;const  buf2;len:  SizeInt)  :  SizeInt

    Visibility:   default

Description:     CompareDWord compares two memory regions buf1,buf2 on a DWord-per-DWord basis for
                a total of  len DWords.  (A DWord is 4 bytes).

                The function returns one of the following values:


                -1 if  buf1  and  buf2  contain  different  DWords  in  the  first  len  DWords,  and  the  first  such
                       DWord is smaller in buf1 than the DWord at the same position in buf2.

                0 if the first len DWords in buf1 and buf2 are equal.

                1 if  buf1  and  buf2  contain  different  DWords  in  the  first  len  DWords,  and  the  first  such
                       DWord is larger in buf1 than the DWord at the same position in buf2.


       Errors:   None.

    See also:    CompareChar (1300   ), CompareByte (1299   ), CompareWord (1303   )


                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



                                                                                1302

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                37.10.42           CompareWord

    Synopsis:    Compare 2 memory buffers word per word

Declaration:     function  CompareWord(const  buf1;const  buf2;len:  SizeInt)  :  SizeInt

    Visibility:   default

Description:     CompareWord  compares  two  memory  regions  buf1,buf2  on  a  Word-per-Word  basis  for  a
                total of  len Words.  (A Word is 2 bytes).

                The function returns one of the following values:


                -1 if  buf1 and buf2 contain different Words in the first len Words, and the first such Word
                       is smaller in buf1 than the Word at the same position in buf2.

                0 if the first len Words in buf1 and buf2 are equal.

                1 if  buf1 and buf2 contain different Words in the first len Words, and the first such Word
                       is larger in buf1 than the Word at the same position in buf2.


       Errors:   None.

    See also:    CompareChar (1300   ), CompareByte (1299   ), CompareDWord (1302   )


                Listing:  ./refex/ex102.pp



                                                                                1303

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.43           Concat

    Synopsis:    Append one string to another.

Declaration:     function  Concat(const  S1:  string;const  S2:  string;const  S3:  string;
                                         const  Sn:  string)  :  string

    Visibility:   default

Description:     Concat concatenates the strings S1,S2 etc.  to one long string.  The resulting string is trun-
                cated at a length of 255 bytes.  The same operation can be performed with the + operation.

       Errors:   None.

    See also:    Copy (1306   ), Delete (1309   ), Insert (1341   ), Pos (1383   ), Length (1346   )


                Listing:  ./refex/ex10.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0;



                                                                                1304

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                {   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___.____________________________________________________________________________________________________________*
 *___________



                37.10.44           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 (1294   ), Exit (1318   )


                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
                        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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1305

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.45           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 (1309   ), Insert (1341   ), Pos (1383   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.46           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 (1288   ), Sin (1408   )


                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



                                                                                1306

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    R := Cos  ( P i ) ;       {  R := -1    }
                    R := Cos  ( P i / 2 ) ;   {  R : = 0    }
                    R := Cos   ( 0 ) ;        {  R : = 1    }
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.47           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 (1311   ), Seg (1401   ), Ofs (1355   ), Ptr (1384   )


                Listing:  ./refex/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  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___.____________________________________________________________________________________________________________*
 *___________



                37.10.48           Dec

    Synopsis:    Decrease value of variable

Declaration:     procedure  Dec(var  X:  TOrdinal)
                procedure  Dec(var  X:  TOrdinal;Decrement:  TOrdinal)

    Visibility:   default

Description:     Dec decreases the value of  X with Decrement.  If  Decrement isn't specified, then 1 is taken
                as a default.

       Errors:   A range check can occur, or an underflow error, if an attempt it made to decrease X below
                its minimum value.

    See also:    Inc (1335   )


                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



                                                                                1307

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                37.10.49           DefaultAnsi2UnicodeMove

    Synopsis:    Standard widestring manager callback

Declaration:     procedure  DefaultAnsi2UnicodeMove(source:  PChar;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.



                37.10.50           DefaultAnsi2WideMove

    Synopsis:    Standard implementation of Ansi to Widestring conversion routine

Declaration:     procedure  DefaultAnsi2WideMove(source:  PChar;var  dest:  widestring;
                                                                  len:  SizeInt)

    Visibility:   default

Description:     DefaultAnsi2WideMove  simply  copies  each  character  of  the  null-terminated  ansi-string
                Source to the corresponding WideChar in Dest.  At most Len characters will be copied.

       Errors:   None.

    See also:    DefaultWide2AnsiMove (1309   )



                37.10.51           DefaultUnicode2AnsiMove

    Synopsis:    Standard widestring manager callback

Declaration:     procedure  DefaultUnicode2AnsiMove(source:  PUnicodeChar;
                                                                       var  dest:  ansistring;len:  SizeInt)

    Visibility:   default



                                                                                1308

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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.

       Errors:   None.

    See also:    WidestringManager (1284   )



                37.10.52           DefaultWide2AnsiMove

    Synopsis:    Standard implementation of Widestring to Ansi conversion routine

Declaration:     procedure  DefaultWide2AnsiMove(source:  PWideChar;var  dest:  ansistring;
                                                                  len:  SizeInt)

    Visibility:   default

Description:     DefaultWide2AnsiMove simply copies each character from Source having an ordinal value
                of  less  than  255  to  the  corresponding  character  in  Dest.   Characters  having  an  ordinal
                valuelarger  than  255  will  be  replaced  by  question  marks.  At  most  Len  characters  will  be
                copied.

       Errors:   None.

    See also:    DefaultAnsi2WideMove (1308   )



                37.10.53           Delete

    Synopsis:    Delete part of a string.

Declaration:     procedure  Delete(var  s:  shortstring;index:  SizeInt;count:  SizeInt)
                procedure  Delete(var  S:  AnsiString;Index:  SizeInt;Size:  SizeInt)
                procedure  Delete(var  S:  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 (1306   ), Pos (1383   ), Insert (1341   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1309

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.54           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  (1352   ).   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 (1352   ), Getmem (1328   ), Freemem (1326   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1310

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.55           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 (1313   ) or LeaveCritical-
                section (1346   ), unless it is again initialized with InitCriticalSection (1340   )

    See also:    InitCriticalsection (1340   ), EnterCriticalsection (1313   ), LeaveCriticalsection (1346   )



                37.10.56           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 (1292   )



                37.10.57           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 (1307   ), Seg (1401   ), Ofs (1355   ), Ptr (1384   )


                Listing:  ./refex/ex17.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 7;


                {   Program       t o  d e m o n s t r a t et h e  DSeg     f u n c t i o n. }


                Var
                   W    :  Word   ;


                 b e g i n
                   W  := DSeg    ;  {W : = 0 ,  T h i s  f u n c t i o n i s  p r o v i d e df o r  c o m p a t i b i l i t,y
                                                FPC    i s  a  3 2   b i t  c o m i l e r.}
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1311

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.58           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 (1312   )



                37.10.59           Dump__Stack

    Synopsis:    Dump stack to the given text file.

Declaration:     procedure  Dump_Stack(var  f:  text;bp:  pointer)

    Visibility:   default

Description:     Dump_Stack prints a stack dump to the file f, with base frame pointer bp

       Errors:   The file f must be opened for writing or an error will occur.

    See also:    get_caller_addr (1331   ), get_caller_frame (1331   ), get_frame (1332   )



                37.10.60           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 (1268   )

                It  should  never  be  necessary  to  call  this  function  directly,  the  standard  SetLength  (1403   )
                function should be used instead.

       Errors:   If an invalid pointer is specified, an error may occur.

    See also:    SetLength (1403   ), tdynarraytypeinfo (1268   )



                37.10.61           EndThread

    Synopsis:    End the current thread.

Declaration:     procedure  EndThread(ExitCode:  DWord)
                procedure  EndThread

    Visibility:   default



                                                                                1312

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     EndThread ends the current thread.  If ExitCode is supplied, it is returned as the exit code
                for the thread to a function waiting for the thread to terminate (WaitForThreadTerminate
                (1428   )).  If it is omitted, zero is used.

                This function does not return.

    See also:    WaitForThreadTerminate (1428   ), BeginThread (1292   )



                37.10.62           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 (1346   )), 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 (1340   ) prior to a call
                to EnterCriticalsection.

                A call to EnterCriticalsection must always be matched by a call to LeaveCriticalSection
                (1346   ).  To avoid problems, it is best to include the code to be execute in a try...finally
                block, as follows:


                EnterCriticalSection(Section);
                    Try
                       //  Code  to  be  protected  goes  here.
                    Finally
                       LeaveCriticalSection(Section);
                    end;


                For performance reasons it is best to limit the code between the entering and leaving of a
                critical section as short as possible.

    See also:    InitCriticalsection (1340   ), DoneCriticalsection (1311   ), LeaveCriticalsection (1346   )



                37.10.63           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.



                                                                                1313

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   None.

    See also:    EnumResourceTypes (1314   ), EnumResourceNames (1314   ), EnumResourceLanguages (1313   )



                37.10.64           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 (1314   ), EnumResourceLanguages (1313   )



                37.10.65           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 (1314   ), EnumResourceLanguages (1313   )



                37.10.66           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.



                                                                                1314

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       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 (1315   ), Assign (1289   ), Reset (1391   ), Rewrite (1392   )


                Listing:  ./refex/ex18.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 8;


                {   Program       t o  d e m o n s t r a t et h e  E o f  f u n c t i o n. }


                Var    T1  ,T2    :   t e x t;
                       C   :  Char    ;


                 b e g i n
                    {   S e t  f i l e t o  r e a d  f r o m.  Empty      means     f r o m  s t a n d a r d i n p u t.}
                    a s s i g n ( t1  ,p a r a m s t r( 1 ) ) ;
                    r e s e t ( t 1 ) ;
                    {   S e t  f i l e t o   w r i t e t o .  Empty     means      t o  s t a n d a r d o u t p u t. }
                    a s s i g n ( t2  ,p a r a m s t r( 2 ) ) ;
                    r e w r i t e ( t 2) ;
                    While     not    e o f (t 1 )  do
                        b e g i n
                        r e a d ( t1  ,C ) ;
                        w r i t e ( t2 , C ) ;
                       end   ;
                    C l o s e ( t 1 ) ;
                    C l o s e ( t 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.67           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 (1314   ), Assign (1289   ), Reset (1391   ), Rewrite (1392   )


                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.



                                                                                1315

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                        I t  w i l l  o n l y s t o p  when     you    p r e s s e n t e r.}
                    While     not    E o l n  do
                        W r i t e l n( e o l n) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.68           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 (1289   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.69           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 (1398   ), Halt (1332   )



                                                                                1316

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.70           Exclude

    Synopsis:    Exlude element from a set if it is present.

Declaration:     procedure  Exclude(var  S:  TSetType;E:  TSetElement)

    Visibility:   default

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 (1336   )


                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  ;



                                                                                1317

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                 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   ) ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                37.10.71           Exit

    Synopsis:    Exit current subroutine.

Declaration:     procedure  Exit(const  X:  TAnyType)
                procedure  Exit

    Visibility:   default

Description:     Exit  exits  the  current  subroutine,  and  returns  control  to  the  calling  routine.   If  invoked
                in  the  main  program  routine,  exit  stops  the  program.  The  optional  argument  X  allows  to
                specify  a  return  value,  in  the  case  Exit  is  invoked  in  a  function.  The  function  result  will
                then be equal to X.

       Errors:   None.

    See also:    Halt (1332   )


                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 }



                                                                                1318

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                 b e g i n
                    i f  Which    >0   then
                        e x i t ( True   )
                    e l s e
                        e x i t ( F a l s e) ;
                end   ;


                 b e g i n
                    {   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___.____________________________________________________________________________________________________________*
 *___________



                37.10.72           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 (1347   ), Power (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.73           FilePos

    Synopsis:    Get position in file

Declaration:     function  FilePos(var  f:  File)  :  Int64

    Visibility:   default

Description:     Filepos returns the current record position of the file-pointer in file F. It cannot be invoked
                with a file of type Text.  A compiler error will be generated if this is attempted.

       Errors:   Depending on the state of the {$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 (1320   )



                                                                                1319

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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
                       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___.____________________________________________________________________________________________________________*
 *___________



                37.10.74           FileSize

    Synopsis:    Size of file

Declaration:     function  FileSize(var  f:  File)  :  Int64

    Visibility:   default

Description:     Filesize returns the total number of records in file F. It cannot be invoked with a file of
                type Text.  (under linux and unix, this also means that it cannot be invoked on pipes).  If  F
                is empty, 0 is returned.

       Errors:   Depending on the state of the {$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 (1319   )


                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;



                                                                                1320

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                37.10.75           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  (1323   ),  and  if  it  is*
 *  a
                multiple  of  4  bytes  it  is  better  to  use  FillDWord  (1322   ),  these  routines  are  optimized  for
                their respective sizes.

       Errors:   No checking on the size of  X is done.

    See also:    Fillchar (1321   ), FillDWord (1322   ), Fillword (1323   ), Move (1351   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.76           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)



                                                                                1321

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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 (1323   ), Move (1351   ), FillByte (1321   ), FillDWord (1322   )


                Listing:  ./refex/ex25.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 5;


                {   Program       t o  d e m o n s t r a t et h e  F i l l C h a r f u n c t i o n. }


                Var    S   :   S t r i n g[ 1 0 ] ;
                        I  :  B y t e ;
                 b e g i n
                    For    i : = 1 0 downto       0  do
                        b e g i n
                       {   F i l l S   w i t h  i   s p a c e s}
                        F i l l C h a r( S ,S i z e O f(S ) , '   ') ;
                       {   S e t  L e n g t h }
                        S e t L e n g t(hS , I) ;
                        W r i t e l n( s , '*  ') ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.77           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 (1321   ), Fillchar (1321   ), Fillword (1323   ), Move (1351   )


                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 ) ;



                                                                                1322

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                37.10.78           FillQWord

    Synopsis:    Fill memory range with QWord (64-bit) values

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 (1321   ), FillWord (1323   )



                37.10.79           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 (1321   ), Move (1351   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.80           FindResource

    Synopsis:    Locate a resource and return a handle to it.



                                                                                1323

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1348   ).

       Errors:   None.  In case the resource was not found, 0 is returned.

    See also:    FreeResource  (1327   ),  LoadResource  (1348   ),  SizeofResource  (1409   ),  LockResource  (1349   ),
                UnlockResource (1424   ), FreeResource (1327   )



                37.10.81           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

                     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.



                37.10.82           float__raise

    Synopsis:    Raise floating point exception

Declaration:     procedure  float_raise(i:  ShortInt)

    Visibility:   default

Description:     float_raise raises the floating point exceptions specified by softfloat_exception_flags (1284   ).

    See also:    softfloat_exception_flags (1284   ), softfloat_exception_mask (1284   )



                                                                                1324

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.83           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 (1298   )


                Listing:  ./refex/ex26.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 6;


                {   Program       t o  d e m o n s t r a t et h e  F l u s h  f u n c t i o n. }


                Var    F   :  T e x t ;


                 b e g i n
                    {   A s s i g nF   t o   s t a n d a r do u t p u t }
                    A s s i g n ( F , ' ') ;
                    R e w r i t e (F  ) ;
                    W r i t e l n (F  , 'T h i s  l i n e  i s  w r i t t e n f i r s t,  b u t  a p p e a r s l a t e r ! ' ) ;
                    {  At    t h i s  p o i n t t h e  t e x t  i s  i n  t h e  i n t e r n a l p a s c a l b u f f e r,
                       and    n o t   y e t  w r i t t e nt o   s t a n d a r do u t p u t }
                    W r i t e l n ( ' T h i s l i n e  a p p e a r s f i r s t,  b u t  i s  w r i t t e n l a t e r  ! ') ;
                    {  A   w r i t e l n t o  ' o u t p u t'  a l w a y s c a u s e s a   f l u s h -   s o  t h i s  t e x t  i s
                        w r i t t e nt o   s c r e e n }
                    F l u s h ( f ) ;
                    {  At    t h i s  p o i n t,  t h e  t e x t  w r i t t e nt o  F   i s  w r i t t e n t o   s c r e e n. }
                    Write     ( F , ' F i n i s h i n g' ) ;
                    C l o s e ( f ) ;    {   C l o s i n ga   f i l e  a l w a y s c a u s e s a   f l u s h f i r s t }
                    W r i t e l n ( ' o f f. ') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.84           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 (1312   )



                                                                                1325

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.85           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.



                37.10.86           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 (1396   ), Int (1342   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.87           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.

       Errors:   An error will occur when P doesn't point to the heap.

    See also:    Getmem (1328   ), New (1352   ), Dispose (1310   )


                Listing:  ./refex/ex28.pp



                                                                                1326

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.88           Freememory

    Synopsis:    Alias for FreeMem (1326   )

Declaration:     procedure  Freememory(p:  pointer;Size:  PtrUInt)
                function  Freememory(p:  pointer)  :  PtrUInt

    Visibility:   default

Description:     FreeMemory is an alias for FreeMem (1326   ).

    See also:    FreeMem (1326   )



                37.10.89           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 (1348   ).  It returns True if the operation was succesful,
                False otherwise.

       Errors:   On error, False is returned.

    See also:    FindResource  (1323   ),  LoadResource  (1348   ),  SizeofResource  (1409   ),  LockResource  (1349   ),
                UnlockResource (1424   ), FreeResource (1327   )



                37.10.90           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 (1346   ) or ThreadSetPriority (1419   )

       Errors:   None.

    See also:    KillThread (1346   ), ThreadSetPriority (1419   )



                                                                                1327

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.91           getdir

    Synopsis:    Return the current directory

Declaration:     procedure  getdir(drivenr:  Byte;var  dir:  shortstring)
                procedure  getdir(drivenr:  Byte;var  dir:  ansistring)

    Visibility:   default

Description:     Getdir returns in dir the current directory on the drive drivenr, where {drivenr} is 1 for
                the first floppy drive, 3 for the first hard disk etc.  A value of 0 returns the directory on the
                current disk.  On linux and unix systems, drivenr is ignored, as there is only one directory
                tree.

       Errors:   An error is returned under dos, if the drive requested isn't ready.

    See also:    Chdir (1297   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.92           GetFPCHeapStatus

    Synopsis:    Return FPC heap manager status information

Declaration:     function  GetFPCHeapStatus  :  TFPCHeapStatus

    Visibility:   default

Description:     Return FPC heap manager status information



                37.10.93           GetHeapStatus

    Synopsis:    Return the memory manager heap status.

Declaration:     function  GetHeapStatus  :  THeapStatus

    Visibility:   default



                37.10.94           GetMem

    Synopsis:    Allocate new memory on the heap

Declaration:     procedure  Getmem(out  p:  pointer;Size:  PtrUInt)
                function  GetMem(size:  PtrUInt)  :  pointer

    Visibility:   default



                                                                                1328

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1284   ):  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.

                For an example, see Freemem (1326   ).

       Errors:   None.

    See also:    Freemem (1326   ), Dispose (1310   ), New (1352   ), returnnilifgrowheapfails (1284   )



                37.10.95           GetMemory

    Synopsis:    Alias for GetMem (1328   )

Declaration:     procedure  Getmemory(out  p:  pointer;Size:  PtrUInt)
                function  GetMemory(size:  PtrUInt)  :  pointer

    Visibility:   default

Description:     Getmemory is an alias for GetMem (1328   ).

    See also:    GetMem (1328   )



                37.10.96           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 (1403   ), IsMemoryManagerSet (1345   )



                37.10.97           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 (1330   )



                                                                                1329

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.98           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 (1272   ), SetResourceManager (1404   )



                37.10.99           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 (1329   )



                37.10.100            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 (1406   ), TThreadManager (1276   )



                37.10.101            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.



                                                                                1330

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    See also:    SetUnicodeStringManager (1406   ), TUnicodeStringManager (1277   )



                37.10.102            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 (1407   )



                37.10.103            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 (1407   ), TWideStringManager (1281   )



                37.10.104            get__caller__addr

    Synopsis:    Return the address of the caller.

Declaration:     function  get_caller_addr(framebp:  pointer)  :  pointer

    Visibility:   default

Description:     get_caller_frame  returns  a  pointer  to  address  (  the  return  address)  of  the  caller  of  the
                routine which has as frame framebp.

    See also:    get_frame (1332   ), get_caller_frame (1331   ), Dump_Stack (1312   )



                37.10.105            get__caller__frame

    Synopsis:    Return the frame pointer of the caller

Declaration:     function  get_caller_frame(framebp:  pointer)  :  pointer

    Visibility:   default

Description:     get_caller_frame returns a pointer to the frame of the caller of the routine which has as
                frame framebp.

    See also:    get_caller_addr (1331   ), get_frame (1332   ), Dump_Stack (1312   )



                                                                                1331

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.106            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 (1381   ) and ParamStr (1382   ) should be used.

    See also:    ParamCount (1381   ), ParamStr (1382   )



                37.10.107            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 (1331   ), get_caller_frame (1331   )



                37.10.108            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 (1318   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1332

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.109            hexStr

    Synopsis:    Convert integer value to string with hexadecimal representation.

Declaration:     function  hexStr(Val:  LongInt;cnt:  Byte)  :  shortstring
                function  hexStr(Val:  Int64;cnt:  Byte)  :  shortstring
                function  hexStr(Val:  QWord;cnt:  Byte)  :  shortstring
                function  hexStr(Val:  Pointer)  :  shortstring

    Visibility:   default

Description:     HexStr  returns  a  string  with  the  hexadecimal  representation  of  Value.   The  string  has
                exactly cnt charaters.  (i.e.  only the cnt rightmost nibbles are taken into account) To have
                a complete representation of a Longint-type value, 8 nibbles are needed, i.e.  cnt=8.

       Errors:   None.

    See also:    Str (1411   ), Val (1426   ), BinStr (1292   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.110            hi

    Synopsis:    Return high byte/word of value.

Declaration:     function  hi(b:  Byte)  :  Byte
                function  hi(i:  Integer)  :  Byte
                function  hi(w:  Word)  :  Byte
                function  hi(l:  LongInt)  :  Word
                function  hi(l:  DWord)  :  Word
                function  hi(i:  Int64)  :  DWord
                function  hi(q:  QWord)  :  DWord

    Visibility:   default

Description:     Hi returns the high byte or word from X, depending on the size of X. If the size of X is 4,
                then the high word is returned.  If the size is 2 then the high byte is returned.  Hi cannot be
                invoked on types of size 1, such as byte or char.

       Errors:   None

    See also:    Lo (1348   )


                Listing:  ./refex/ex31.pp



                                                                                1333

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 1;


                {   Program       t o  d e m o n s t r a t et h e  Hi   f u n c t i o n.  }


                 v a r
                    L   :  L o n g i n t;
                   W    :  Word   ;


                 b e g i n
                    L : = 1  S h l  1 6 ;         {  =   $10000      }
                   W  : = 1  S h l  8 ;           {  =   $100    }
                    W r i t e l n ( Hi ( L ) ) ;  {  P r i n t s 1   }
                    W r i t e l n ( Hi (W  ) ) ;  {  P r i n t s 1   }
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.111            High

    Synopsis:    Return highest index of open array or enumerated

Declaration:     function  High(Arg:  TypeOrVariable)  :  TOrdinal

    Visibility:   default

Description:     The return value of  High depends on it's argument:


                     1.If the argument is an ordinal type, High returns the highest value in the range of the
                       given ordinal type.

                     2.If the argument is an array type or an array type variable then High returns the highest
                       possible value of it's index.

                     3.If the argument is an open array identifier in a function or procedure, then High returns
                       the highest index of the array, as if the array has a zero-based index.

                     4.If the argument is a set type then it returns the highest value of the underlying ordinal
                       type.


                The return type is always the same type as the type of the argument (This can lead to some
                nasty surprises !).

       Errors:   None.

    See also:    Low (1350   ), Ord (1380   ), Pred (1384   ), Succ (1414   )


                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;



                                                                                1334

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                 b e g i n
                    Temp    : =   Row   [ 0 ] ;
                    For    I  : =  1   t o  High   ( Row   )  do
                         Temp     : =  Temp    +   Row   [ i] ;
                    A v e r a g e : =  Temp     /  ( High   ( Row  ) + 1 ) ;
                end   ;


                Var    A   :  TEnum    ;
                       B   :  TRange     ;
                       C   :  T A r r a y;
                        I  :   l o n g i n t;


                 b e g i n
                    W r i t e l n ( 'TEnum        g o e s f r o m  :   ' ,Ord  ( Low  ( TEnum    ) ) ,'  t o   ' ,  Ord  ( h i g h(*
 *TEnum    ) ) , '. ' ) ;
                    W r i t e l n ( 'A            g o e s f r o m  :   ' ,Ord  ( Low  ( A ) ) ,'  t o   ' ,  Ord  ( h i g h(A ) ) ,*
 * '. ' ) ;
                    W r i t e l n ( 'TRange       g o e s f r o m  :   ' ,Ord  ( Low  ( TRange     ) ) ,'  t o   ' , Ord   ( h i g *
 *h(TRange     ) ) ,' . ') ;
                    W r i t e l n ( 'B            g o e s f r o m  :   ' ,Ord  ( Low  ( B ) ) ,'  t o   ' ,  Ord  ( h i g h(B ) ) ,*
 * '. ' ) ;
                    W r i t e l n ( 'T A r r a y  i n d e x g o e s  f r o m  :  ' ,Ord   (Low   (T A r r a y) ) ,'   t o  ' ,  Ord*
 *  ( h i g h( T A r r a y) ) ,'@
                    W r i t e l n ( 'C   i n d e x          g o e s  f r o m  :  ' ,Low   (C ) , '  t o   ' ,  h i g h(C ) , ' .' )*
 * ;
                    For    I := Low  ( C )  t o   High   (C )  do
                       C [ i ] : =I ;
                    W r i t e l n ( 'A v e r a g e : ' , A v e r a g e(c ) ) ;
                    Write     (  'Type     o f  r e t u r n v a l u e  i s  a l w a y s same     a s  t y p e  o f  a r g u m e n t*
 *:' ) ;
                    W r i t e l n(h i g h( h i g h(word    ) ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.112            HINSTANCE

    Synopsis:    Windows compatibility type for use in resources

Declaration:     function  HINSTANCE  :  TFPResourceHMODULE

    Visibility:   default

Description:     This is an opaque type.



                37.10.113            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 (1307   )


                Listing:  ./refex/ex32.pp



                                                                                1335

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 2;


                {   Program       t o  d e m o n s t r a t et h e  I n c  f u n c t i o n. }


                Const
                    C   :  C a r d i n a l  =  1 ;
                    L   :  L o n g i n t    =  1 ;
                    I   :  I n t e g e r    =  1 ;
                   W    :  Word             =  1 ;
                    B   :  B y t e          =  1 ;
                    S I  :   S h o r t I n t=  1 ;
                    CH   :   Char           =   'A  ';


                 b e g i n
                    I n c  (C  ) ;         {  C : = 2       }
                    I n c  ( L , 5 ) ;     {  L : = 6       }
                    I n c  ( I , - 3 ) ;   {  I := -2       }
                    I n c  (W  , 3 ) ;     { W  : = 4       }
                    I n c  (B  , 1 0 0 ) ; {  B : = 1 0 1   }
                    I n c  ( S I, - 3 ) ;  {  S i := -2     }
                    I n c  (CH   , 1 ) ;   {  ch  : = 'B '  }
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.114            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 (1317   )

       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 (1317   )



                37.10.115            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.



                                                                                1336

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   Buf and Len are not checked to see if they are valid values.

    See also:    IndexChar (1337   ), IndexDWord (1338   ), IndexWord (1339   ), CompareByte (1299   )


                Listing:  ./refex/ex105.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 5;


                {   Program       t o  d e m o n s t r a t et h e  I n d e x B y t e f u n c t i o n. }


                Const
                    A r r a y S i z e=  2 5 6 ;
                    MaxValue       =  2 5 6 ;


                Var
                    B u f f e r :   A r r a y[ 1 . .A r r a y S i z]e  o f  B y t e;
                    I ,J   :   l o n g i n t;
                    K   :  B y t e;


                 b e g i n
                    Randomize       ;
                    For    I : = 1 To    A r r a y S i z edo
                        B u f f e r[I] : =Random     ( MaxValue      ) ;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                       K := Random     ( MaxValue      ) ;
                       J :=  I n d e x B y t(eB u f f e r,A r r a y S i z e,K ) ;
                        i f  J=-1    then
                           W r i t e l n(' V a l u e ' ,K  ,'  was     n o t  f o u n d i n  b u f f e r. ')
                        e l s e
                           W r i t e l n(' Found     ' ,K  ,'   a t  p o s i t i o n ' ,J , '  i n  b u f f e r' ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.116            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 (1336   ), IndexDWord (1338   ), IndexWord (1339   ), CompareChar (1300   )


                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



                                                                                1337

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    A r r a y S i z e=  1 0 0 0 ;
                    MaxValue       =  2 6 ;


                Var
                    B u f f e r :   A r r a y[ 1 . .A r r a y S i z]e  o f  Char   ;
                    I ,J   :   l o n g i n t;
                    K   :  Char   ;


                 b e g i n
                    Randomize       ;
                    For    I : = 1 To    A r r a y S i z edo
                        B u f f e r[I] : = c h r(Ord   ( 'A ' )+ Random     (MaxValue       ) ) ;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                       K :=  c h r( Ord  ( 'A  ')+ Random     ( MaxValue      ) ) ;
                       J :=  I n d e x C h a(rB u f f e r,A r r a y S i z e,K ) ;
                        i f  J=-1    then
                           W r i t e l n(' V a l u e ' ,K  ,'  was     n o t  f o u n d i n  b u f f e r. ')
                        e l s e
                           W r i t e l n(' Found     ' ,K  ,'   a t  p o s i t i o n ' ,J , '  i n  b u f f e r' ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.117            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 (1336   ), IndexChar (1337   ), IndexWord (1339   ), IndexDWord (1338   ), CompareChar0
                (1302   )



                37.10.118            IndexDWord

    Synopsis:    Search for a DWord value in a memory range.

Declaration:     function  IndexDWord(const  buf;len:  SizeInt;b:  DWord)  :  SizeInt

    Visibility:   default

Description:     IndexChar searches the memory at buf for maximally len positions for the DWord DW and
                returns it's position if it found one.  If  DW is not found then -1 is returned.  The position is
                zero-based.

       Errors:   Buf and Len are not checked to see if they are valid values.

    See also:    IndexByte (1336   ), IndexChar (1337   ), IndexWord (1339   ), CompareDWord (1302   )


                Listing:  ./refex/ex106.pp



                                                                                1338

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 0 6;


                {   Program       t o  d e m o n s t r a t et h e  IndexDWord         f u n c t i o n.  }


                Const
                    A r r a y S i z e=  1 0 0 0 ;
                    MaxValue       =  1 0 0 0 ;


                Var
                    B u f f e r :   A r r a y[ 1 . .A r r a y S i z]e  o f DWord     ;
                    I ,J   :   l o n g i n t;
                    K   :  DWord    ;


                 b e g i n
                    Randomize       ;
                    For    I : = 1 To    A r r a y S i z edo
                        B u f f e r[I] : =Random     ( MaxValue      ) ;
                    For    I : = 1  t o  1 0  do
                        b e g i n
                       K := Random     ( MaxValue      ) ;
                       J :=  IndexDWord       ( B u f f e r,A r r a y S i z e,K ) ;
                        i f  J=-1    then
                           W r i t e l n(' V a l u e ' ,K  ,'  was     n o t  f o u n d i n  b u f f e r. ')
                        e l s e
                           W r i t e l n(' Found     ' ,K  ,'   a t  p o s i t i o n ' ,J , '  i n  b u f f e r' ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.119            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 (1338   )



                37.10.120            Indexword

    Synopsis:    Search for a WORD value in a memory range.

Declaration:     function  Indexword(const  buf;len:  SizeInt;b:  Word)  :  SizeInt

    Visibility:   default

Description:     IndexChar  searches  the  memory  at  buf  for  maximally  len  positions  for  the  Word  W  and
                returns it's position if it found one.  If  W is not found then -1 is returned.



                                                                                1339

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   Buf and Len are not checked to see if they are valid values.

    See also:    IndexByte (1336   ), IndexDWord (1338   ), IndexChar (1337   ), CompareWord (1303   )


                Listing:__./refex/ex107.pp_________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 1 0 7;


                {   Program       t o  d e m o n s t r a t et h e  I n d e x W o r d f u n c t i o n. }


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.121            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 (1313   ) or LeaveCriticalsection (1346   ) the critical section should be
                initialized with InitCriticalSection.

                When a critical section is no longer used, it should be disposed of with DoneCriticalsection
                (1311   )

    See also:    DoneCriticalsection (1311   ), EnterCriticalsection (1313   ), LeaveCriticalsection (1346   )



                37.10.122            InitThread

    Synopsis:    Initialize a thread

Declaration:     procedure  InitThread(stklen:  SizeUInt)

    Visibility:   default

Description:     Do not use, this is used internally by the thread manager.



                                                                                1340

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.123            InitThreadVars

    Synopsis:    Initialize threadvars

Declaration:     procedure  InitThreadVars(RelocProc:  Pointer)

    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 (1276   ), TThreadManager.InitThreadVar (1 )



                37.10.124            Insert

    Synopsis:    Insert one string in another.

Declaration:     procedure  Insert(const  source:  shortstring;var  s:  shortstring;
                                           index:  SizeInt)
                procedure  Insert(source:  Char;var  s:  shortstring;index:  SizeInt)
                procedure  Insert(const  Source:  AnsiString;var  S:  AnsiString;
                                           Index:  SizeInt)
                procedure  Insert(const  Source:  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 (1309   ), Copy (1306   ), Pos (1383   )


                Listing:  ./refex/ex33.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 3;


                {   Program       t o  d e m o n s t r a t et h e  I n s e r t f u n c t i o n.  }


                Var    S   :   S t r i n g;


                 b e g i n
                    S :=  'F r e e  P a s c a l i s  d i f f i c u l t t o  u s e  ! ';
                    I n s e r t ( 'NOT     ' ,S , pos  ( ' d i f f i c u l't,S  ) ) ;
                    w r i t e l n ( s ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1341

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.125            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 (1326   ), Round (1396   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.126            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

    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 (1342   ), InterLockedIncrement (1344   ), InterLockedExchange (1343   ),
                InterLockedExchangeAdd (1343   )



                37.10.127            InterLockedDecrement

    Synopsis:    Thread-safe decrement



                                                                                1342

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1344   ), InterLockedExchange (1343   ), InterLockedExchangeAdd (1343   ),
                InterlockedCompareExchange (1342   )



                37.10.128            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 (1342   ), InterLockedIncrement (1344   ), InterLockedExchangeAdd (1343   ),
                InterlockedCompareExchange (1342   )



                37.10.129            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 (1342   ), InterLockedIncrement (1344   ), InterLockedExchange (1343   ),
                InterlockedCompareExchange (1342   )



                                                                                1343

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.130            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 (1342   ), InterLockedExchange (1343   ), InterLockedExchangeAdd (1343   ),
                InterlockedCompareExchange (1342   )



                37.10.131            IOResult

    Synopsis:    Return result of last file IO operation

Declaration:     function  IOResult  :  Word

    Visibility:   default

Description:     IOresult contains the result of any input/output call, when the {\$i-} compiler directive is
                active, disabling IO checking.  When the flag is read, it is reset to zero.  If  IOresult is zero,
                the operation completed successfully.  If non-zero,  an error occurred.  The following errors
                can occur:

                dos errors :


                2 File not found.

                3 Path not found.

                4 Too many open files.

                5 Access denied.

                6 Invalid file handle.

                12  Invalid file-access mode.

                15  Invalid disk number.

                16  Cannot remove current directory.

                17  Cannot rename across volumes.


                I/O errors :


                100   Error when reading from disk.

                101   Error when writing to disk.

                102   File not assigned.

                103   File not open.

                104   File not opened for input.

                105   File not opened for output.

                106   Invalid number.


                Fatal errors :



                                                                                1344

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.132            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 (1403   ), GetMemoryManager (1329   )



                                                                                1345

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.133            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.



                37.10.134            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 (1428   ), EndThread (1312   ), SuspendThread (1414   )



                37.10.135            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 (1313   ).

                The critical section must have been initialized with InitCriticalSection (1340   ) prior to a call
                to EnterCriticalsection and LeaveCriticalSection.

    See also:    InitCriticalsection (1340   ), DoneCriticalsection (1311   ), EnterCriticalsection (1313   )



                37.10.136            Length

    Synopsis:    Returns length of a string.

Declaration:     function  Length(S:  AStringType)  :  Integer
                function  Length(A:  DynArrayType)  :  Integer

    Visibility:   default

Description:     Length returns the length of the string  S, which is limited to 255 for shortstrings.  If the
                strings S is empty, 0 is returned.

                Note:  The length of the string S is stored in S[0] for shortstrings only.  The Length function
                should always be used on ansistrings and widestrings.



                                                                                1346

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                For dynamical 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 (1383   )


                Listing:  ./refex/ex36.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 6;


                {   Program       t o  d e m o n s t r a t et h e  L e n g t h f u n c t i o n.  }


                Var    S   :   S t r i n g;
                        I  :   I n t e g e r;


                 b e g i n
                    S :=  '' ;
                    f o r  i : = 1  t o  1 0  do
                        b e g i n
                       S :=  S+  '* ' ;
                        W r i t e l n( Length     (S ) : 2 ,'   :  ' , s ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.137            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 (1292   ), NtoBE (1353   ), NtoLE (1353   )



                37.10.138            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.



                                                                                1347

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   An run-time error will occur when X is negative.

    See also:    Exp (1319   ), Power (1 )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.139            lo

    Synopsis:    Return low byte/word of value.

Declaration:     function  lo(B:  Byte)  :  Byte
                function  lo(i:  Integer)  :  Byte
                function  lo(w:  Word)  :  Byte
                function  lo(l:  LongInt)  :  Word
                function  lo(l:  DWord)  :  Word
                function  lo(i:  Int64)  :  DWord
                function  lo(q:  QWord)  :  DWord

    Visibility:   default

Description:     Lo returns the low byte of its argument if this is of type Integer or Word.  It returns the
                low word of its argument if this is of type Longint or Cardinal.

       Errors:   None.

    See also:    Ord (1380   ), Chr (1298   ), Hi (1333   )


                Listing:  ./refex/ex38.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 8;


                {   Program       t o  d e m o n s t r a t et h e  Lo   f u n c t i o n.  }


                Var    L   :   L o n g i n t;
                       W   :  Word    ;


                 b e g i n
                    L : = ( 1 S h l  1 6 )  +  ( 1   S h l  4 ) ;    {  $10010      }
                    W r i t e l n ( Lo ( L ) ) ;                     {  P r i n t s 1 6   }
                   W  : = ( 1 S h l  8 )  +  ( 1   S h l  4 ) ;      {  $110        }
                    W r i t e l n ( Lo (W  ) ) ;                     {  P r i n t s 1 6   }
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.140            LoadResource

    Synopsis:    Load a resource for use



                                                                                1348

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1327   ) function.

       Errors:   On error, 0 is returned.

    See also:    FindResource  (1323   ),  FreeResource  (1327   ),  SizeofResource  (1409   ),  LockResource  (1349   ),
                UnlockResource (1424   ), FreeResource (1327   )



                37.10.141            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 (1424   ) function.

       Errors:   if the function fails, Nil is returned.

    See also:    FindResource  (1323   ),  FreeResource  (1327   ),  SizeofResource  (1409   ),  LoadResource  (1348   ),
                UnlockResource (1424   ), FreeResource (1327   )



                37.10.142            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 (1402   ) 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 (1402   )

       Errors:   None.

    See also:    SetJmp (1402   )



                                                                                1349

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.143            Low

    Synopsis:    Return lowest index of open array or enumerated

Declaration:     function  Low(Arg:  TypeOrVariable)  :  TOrdinal

    Visibility:   default

Description:     The return value of  Low depends on it's argument:


                     1.If  the  argument  is  an  ordinal  type,  Low  returns  the  lowest  value  in  the  range  of  the
                       given ordinal type.

                     2.If the argument is an array type or an array type variable then Low returns the lowest
                       possible value of it's index.

                     3.If the argument is an open array identifier in a function or procedure, then Low returns
                       the lowest element of the array, which is always zero.

                     4.If the argument is a set type then it returns the lowest value of the underlying ordinal
                       type.


                The return type is always the same type as the type of the argument.

                for an example, see High (1334   ).

       Errors:   None.

    See also:    High (1334   ), Ord (1380   ), Pred (1384   ), Succ (1414   )



                37.10.144            lowerCase

    Synopsis:    Return lowercase version of a string.

Declaration:     function  lowerCase(const  s:  shortstring)  :  shortstring;    Overload
                function  lowerCase(c:  Char)  :  Char;    Overload
                function  lowercase(const  s:  ansistring)  :  ansistring

    Visibility:   default

Description:     Lowercase returns the lowercase version of its argument C. If its argument is a string, then
                the complete string is converted to lowercase.  The type of the returned value is the same as
                the type of the argument.

       Errors:   None.

    See also:    Upcase (1424   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1350

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.145            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.



                37.10.146            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 (1328   ), FreeMem (1326   )



                37.10.147            mkdir

    Synopsis:    Create a new directory.

Declaration:     procedure  mkdir(const  s:  string);    Overload

    Visibility:   default

Description:     Mkdir creates a new directory S.

                For an example, see Rmdir (1393   ).

       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 (1297   ), Rmdir (1393   )



                37.10.148            Move

    Synopsis:    Move data from one location in memory to another

Declaration:     procedure  Move(const  source;var  dest;count:  SizeInt)

    Visibility:   default

Description:     Move moves Count bytes from Source to Dest.

       Errors:   If either Dest or Source is outside the accessible memory for the process, then a run-time
                error will be generated.

    See also:    Fillword (1323   ), Fillchar (1321   )


                Listing:  ./refex/ex42.pp



                                                                                1351

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.149            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 (1351   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.150            New

    Synopsis:    Dynamically allocate memory for variable

Declaration:     procedure  New(var  P:  Pointer)
                procedure  New(var  P:  Pointer;Cons:  TProcedure)



                                                                                1352

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    Visibility:  default

Description:     New allocates a new instance of the type pointed to by P, and puts the address in P. If P is
                an object, then it is possible to specify the name of the constructor with which the instance
                will be created.

                For an example, see Dispose (1310   ).

       Errors:   If not enough memory is available, Nil will be returned.

    See also:    Dispose (1310   ), Freemem (1326   ), Getmem (1328   )



                37.10.151            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 (1292   ), LEtoN (1347   ), NtoLE (1353   )



                37.10.152            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 (1292   ), LEtoN (1347   ), NtoBE (1353   )



                37.10.153            Null

    Synopsis:    Null variant

Declaration:     function  Null  :  Variant

    Visibility:   default



                                                                                1353

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.154            OctStr

    Synopsis:    Convert integer to a string with octal representation.

Declaration:     function  OctStr(Val:  LongInt;cnt:  Byte)  :  shortstring
                function  OctStr(Val:  Int64;cnt:  Byte)  :  shortstring
                function  OctStr(Val:  QWord;cnt:  Byte)  :  shortstring

    Visibility:   default

Description:     OctStr returns a string with the octal representation of Value.  The string has exactly cnt
                charaters.

       Errors:   None.

    See also:    Str (1411   ), Val (1426   ), BinStr (1292   ), HexStr (1333   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.155            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 (1285   ), Ord (1380   )


                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



                                                                                1354

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                        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___.____________________________________________________________________________________________________________*
 *___________



                37.10.156            Ofs

    Synopsis:    Return offset of a variable.

Declaration:     function  Ofs(var  X)  :  LongInt

    Visibility:   default

Description:     Ofs  returns  the  offset  of  the  address  of  a  variable.   This  function  is  only  supported  for
                compatibility.  In Free Pascal, it returns always the complete address of the variable, since
                Free Pascal is a 32/64 bit compiler.

       Errors:   None.

    See also:    DSeg (1311   ), CSeg (1307   ), Seg (1401   ), Ptr (1384   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.157            operator  *(variant,  variant):  variant

    Synopsis:    Implement multiplication (*) operation on variants.

Declaration:     operator  operator  *(variant,  variant):  variant(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 (1357   )



                                                                                1355

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.158            operator  **(variant,  variant):  variant

    Synopsis:    Implement power (**) operation on variants.

Declaration:     operator  operator  **(variant,  variant):  variant(const  op1:  variant;
                                                                                              const  op2:  variant)
                                                                                               :  variant

    Visibility:   default

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 (1355   )



                37.10.159            operator  +(variant,  variant):  variant

    Synopsis:    Implement addition (+) operation on variants.

Declaration:     operator  operator  +(variant,  variant):  variant(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 (1357   )



                37.10.160            operator  -(variant):  variant

    Synopsis:    Implement - (unary minus, negation) operation on variants.

Declaration:     operator  operator  -(variant):  variant(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 (1357   )



                                                                                1356

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.161            operator  -(variant,  variant):  variant

    Synopsis:    Implement subtraction (-) operation on variants.

Declaration:     operator  operator  -(variant,  variant):  variant(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 (1357   )



                37.10.162            operator  /(variant,  variant):  variant

    Synopsis:    Implement division (/) operation on variants.

Declaration:     operator  operator  /(variant,  variant):  variant(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 (1355   )



                37.10.163            operator  :=(ansistring):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(ansistring):  olevariant(const  source:  ansistring)
                                                                                          :  olevariant

    Visibility:   default

Description:



                37.10.164            operator  :=(ansistring):  variant

    Synopsis:

Declaration:     operator  operator  :=(ansistring):  variant(const  source:  ansistring)
                                                                                     :  variant

    Visibility:   default

Description:



                                                                                1357

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.165            operator  :=(Boolean):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(Boolean):  olevariant(const  source:  Boolean)
                                                                                     :  olevariant

    Visibility:   default

Description:



                37.10.166            operator  :=(Boolean):  variant

    Synopsis:

Declaration:     operator  operator  :=(Boolean):  variant(const  source:  Boolean)  :  variant

    Visibility:   default

Description:



                37.10.167            operator  :=(Byte):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(Byte):  olevariant(const  source:  Byte)  :  olevariant

    Visibility:   default

Description:



                37.10.168            operator  :=(Byte):  variant

    Synopsis:

Declaration:     operator  operator  :=(Byte):  variant(const  source:  Byte)  :  variant

    Visibility:   default

Description:



                37.10.169            operator  :=(Char):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(Char):  olevariant(const  source:  Char)  :  olevariant

    Visibility:   default

Description:



                37.10.170            operator  :=(Char):  variant

    Synopsis:

Declaration:     operator  operator  :=(Char):  variant(const  source:  Char)  :  variant

    Visibility:   default

Description:



                                                                                1358

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.171            operator  :=(comp):  olevariant

Declaration:     operator  operator  :=(comp):  olevariant(const  source:  comp)  :  olevariant

    Visibility:   default



                37.10.172            operator  :=(comp):  variant

Declaration:     operator  operator  :=(comp):  variant(const  source:  comp)  :  variant

    Visibility:   default



                37.10.173            operator  :=(currency):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(currency):  olevariant(const  source:  currency)
                                                                                       :  olevariant

    Visibility:   default

Description:



                37.10.174            operator  :=(currency):  variant

    Synopsis:

Declaration:     operator  operator  :=(currency):  variant(const  source:  currency)
                                                                                  :  variant

    Visibility:   default

Description:



                37.10.175            operator  :=(Double):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(Double):  olevariant(const  source:  Double)
                                                                                    :  olevariant

    Visibility:   default

Description:



                37.10.176            operator  :=(Double):  variant

    Synopsis:

Declaration:     operator  operator  :=(Double):  variant(const  source:  Double)  :  variant

    Visibility:   default

Description:



                                                                                1359

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.177            operator  :=(DWord):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(DWord):  olevariant(const  source:  DWord)
                                                                                  :  olevariant

    Visibility:   default

Description:



                37.10.178            operator  :=(DWord):  variant

    Synopsis:

Declaration:     operator  operator  :=(DWord):  variant(const  source:  DWord)  :  variant

    Visibility:   default

Description:



                37.10.179            operator  :=(extended):  olevariant

Declaration:     operator  operator  :=(extended):  olevariant(const  source:  extended)
                                                                                       :  olevariant

    Visibility:   default



                37.10.180            operator  :=(extended):  variant

Declaration:     operator  operator  :=(extended):  variant(const  source:  extended)
                                                                                  :  variant

    Visibility:   default



                37.10.181            operator  :=(Int64):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(Int64):  olevariant(const  source:  Int64)
                                                                                  :  olevariant

    Visibility:   default

Description:



                37.10.182            operator  :=(Int64):  variant

    Synopsis:

Declaration:     operator  operator  :=(Int64):  variant(const  source:  Int64)  :  variant

    Visibility:   default

Description:



                                                                                1360

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.183            operator  :=(longbool):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(longbool):  olevariant(const  source:  longbool)
                                                                                       :  olevariant

    Visibility:   default

Description:



                37.10.184            operator  :=(longbool):  variant

    Synopsis:

Declaration:     operator  operator  :=(longbool):  variant(const  source:  longbool)
                                                                                  :  variant

    Visibility:   default

Description:



                37.10.185            operator  :=(LongInt):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(LongInt):  olevariant(const  source:  LongInt)
                                                                                     :  olevariant

    Visibility:   default

Description:



                37.10.186            operator  :=(LongInt):  variant

    Synopsis:

Declaration:     operator  operator  :=(LongInt):  variant(const  source:  LongInt)  :  variant

    Visibility:   default

Description:



                37.10.187            operator  :=(olevariant):  ansistring

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  ansistring(const  source:  olevariant)
                                                                                          :  ansistring

    Visibility:   default

Description:



                                                                                1361

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.188            operator  :=(olevariant):  Boolean

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  Boolean(const  source:  olevariant)
                                                                                     :  Boolean

    Visibility:   default

Description:



                37.10.189            operator  :=(olevariant):  Byte

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  Byte(const  source:  olevariant)  :  Byte

    Visibility:   default

Description:



                37.10.190            operator  :=(olevariant):  Char

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  Char(const  source:  olevariant)  :  Char

    Visibility:   default

Description:



                37.10.191            operator  :=(olevariant):  comp

Declaration:     operator  operator  :=(olevariant):  comp(const  source:  olevariant)  :  comp

    Visibility:   default



                37.10.192            operator  :=(olevariant):  currency

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  currency(const  source:  olevariant)
                                                                                       :  currency

    Visibility:   default

Description:



                37.10.193            operator  :=(olevariant):  Double

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  Double(const  source:  olevariant)
                                                                                    :  Double

    Visibility:   default

Description:



                                                                                1362

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.194            operator  :=(olevariant):  DWord

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  DWord(const  source:  olevariant)
                                                                                  :  DWord

    Visibility:   default

Description:



                37.10.195            operator  :=(olevariant):  extended

Declaration:     operator  operator  :=(olevariant):  extended(const  source:  olevariant)
                                                                                       :  extended

    Visibility:   default



                37.10.196            operator  :=(olevariant):  Int64

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  Int64(const  source:  olevariant)
                                                                                  :  Int64

    Visibility:   default

Description:



                37.10.197            operator  :=(olevariant):  longbool

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  longbool(const  source:  olevariant)
                                                                                       :  longbool

    Visibility:   default

Description:



                37.10.198            operator  :=(olevariant):  LongInt

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  LongInt(const  source:  olevariant)
                                                                                     :  LongInt

    Visibility:   default

Description:



                                                                                1363

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.199            operator  :=(olevariant):  QWord

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  QWord(const  source:  olevariant)
                                                                                  :  QWord

    Visibility:   default

Description:



                37.10.200            operator  :=(olevariant):  Real

Declaration:     operator  operator  :=(olevariant):  Real(const  source:  olevariant)  :  Real

    Visibility:   default



                37.10.201            operator  :=(olevariant):  ShortInt

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  ShortInt(const  source:  olevariant)
                                                                                       :  ShortInt

    Visibility:   default

Description:



                37.10.202            operator  :=(olevariant):  shortstring

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  shortstring(const  source:  olevariant)
                                                                                            :  shortstring

    Visibility:   default

Description:



                37.10.203            operator  :=(olevariant):  single

Declaration:     operator  operator  :=(olevariant):  single(const  source:  olevariant)
                                                                                    :  single

    Visibility:   default



                37.10.204            operator  :=(olevariant):  SmallInt

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  SmallInt(const  source:  olevariant)
                                                                                       :  SmallInt

    Visibility:   default

Description:



                                                                                1364

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.205            operator  :=(olevariant):  TDateTime

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  TDateTime(const  source:  olevariant)
                                                                                         :  TDateTime

    Visibility:   default

Description:



                37.10.206            operator  :=(olevariant):  TError

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  TError(const  source:  olevariant)
                                                                                    :  TError

    Visibility:   default

Description:



                37.10.207            operator  :=(olevariant):  UnicodeString

Declaration:     operator  operator  :=(olevariant):  UnicodeString
                                                                                              (const  source:  olevariant)
                                                                                               :  UnicodeString

    Visibility:   default



                37.10.208            operator  :=(olevariant):  variant

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  variant(const  source:  olevariant)
                                                                                     :  variant

    Visibility:   default

Description:



                37.10.209            operator  :=(olevariant):  WideChar

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  WideChar(const  source:  olevariant)
                                                                                       :  WideChar

    Visibility:   default

Description:



                                                                                1365

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.210            operator  :=(olevariant):  widestring

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  widestring(const  source:  olevariant)
                                                                                          :  widestring

    Visibility:   default

Description:



                37.10.211            operator  :=(olevariant):  Word

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  Word(const  source:  olevariant)  :  Word

    Visibility:   default

Description:



                37.10.212            operator  :=(olevariant):  wordbool

    Synopsis:

Declaration:     operator  operator  :=(olevariant):  wordbool(const  source:  olevariant)
                                                                                       :  wordbool

    Visibility:   default

Description:



                37.10.213            operator  :=(QWord):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(QWord):  olevariant(const  source:  QWord)
                                                                                  :  olevariant

    Visibility:   default

Description:



                37.10.214            operator  :=(QWord):  variant

    Synopsis:

Declaration:     operator  operator  :=(QWord):  variant(const  source:  QWord)  :  variant

    Visibility:   default

Description:



                37.10.215            operator  :=(Real):  olevariant

Declaration:     operator  operator  :=(Real):  olevariant(const  source:  Real)  :  olevariant

    Visibility:   default



                                                                                1366

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.216            operator  :=(Real):  variant

Declaration:     operator  operator  :=(Real):  variant(const  source:  Real)  :  variant

    Visibility:   default



                37.10.217            operator  :=(real48):  Double

    Synopsis:

Declaration:     operator  operator  :=(real48):  Double(b:  real48)  :  Double

    Visibility:   default

Description:



                37.10.218            operator  :=(real48):  extended

Declaration:     operator  operator  :=(real48):  extended(b:  real48)  :  extended

    Visibility:   default



                37.10.219            operator  :=(ShortInt):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(ShortInt):  olevariant(const  source:  ShortInt)
                                                                                       :  olevariant

    Visibility:   default

Description:



                37.10.220            operator  :=(ShortInt):  variant

    Synopsis:

Declaration:     operator  operator  :=(ShortInt):  variant(const  source:  ShortInt)
                                                                                  :  variant

    Visibility:   default

Description:



                37.10.221            operator  :=(shortstring):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(shortstring):  olevariant(const  source:  shortstring)
                                                                                            :  olevariant

    Visibility:   default

Description:



                                                                                1367

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.222            operator  :=(shortstring):  variant

    Synopsis:

Declaration:     operator  operator  :=(shortstring):  variant(const  source:  shortstring)
                                                                                       :  variant

    Visibility:   default

Description:



                37.10.223            operator  :=(single):  olevariant

Declaration:     operator  operator  :=(single):  olevariant(const  source:  single)
                                                                                    :  olevariant

    Visibility:   default



                37.10.224            operator  :=(single):  variant

Declaration:     operator  operator  :=(single):  variant(const  source:  single)  :  variant

    Visibility:   default



                37.10.225            operator  :=(SmallInt):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(SmallInt):  olevariant(const  source:  SmallInt)
                                                                                       :  olevariant

    Visibility:   default

Description:



                37.10.226            operator  :=(SmallInt):  variant

    Synopsis:

Declaration:     operator  operator  :=(SmallInt):  variant(const  source:  SmallInt)
                                                                                  :  variant

    Visibility:   default

Description:



                37.10.227            operator  :=(TDateTime):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(TDateTime):  olevariant(const  source:  TDateTime)
                                                                                         :  olevariant

    Visibility:   default

Description:



                                                                                1368

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.228            operator  :=(TDateTime):  variant

    Synopsis:

Declaration:     operator  operator  :=(TDateTime):  variant(const  source:  TDateTime)
                                                                                    :  variant

    Visibility:   default

Description:



                37.10.229            operator  :=(TError):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(TError):  olevariant(const  source:  TError)
                                                                                    :  olevariant

    Visibility:   default

Description:



                37.10.230            operator  :=(TError):  variant

    Synopsis:

Declaration:     operator  operator  :=(TError):  variant(const  source:  TError)  :  variant

    Visibility:   default

Description:



                37.10.231            operator  :=(UCS4String):  variant

Declaration:     operator  operator  :=(UCS4String):  variant(const  source:  UCS4String)
                                                                                     :  variant

    Visibility:   default



                37.10.232            operator  :=(UnicodeString):  olevariant

Declaration:     operator  operator  :=(UnicodeString):  olevariant
                                                                                              (const  source:  UnicodeString)
                                                                                               :  olevariant

    Visibility:   default



                37.10.233            operator  :=(UnicodeString):  variant

Declaration:     operator  operator  :=(UnicodeString):  variant
                                                                                         (const  source:  UnicodeString)
                                                                                          :  variant

    Visibility:   default



                                                                                1369

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.234            operator  :=(UTF8String):  variant

Declaration:     operator  operator  :=(UTF8String):  variant(const  source:  UTF8String)
                                                                                     :  variant

    Visibility:   default



                37.10.235            operator  :=(variant):  ansistring

    Synopsis:

Declaration:     operator  operator  :=(variant):  ansistring(const  source:  variant)
                                                                                     :  ansistring

    Visibility:   default

Description:



                37.10.236            operator  :=(variant):  Boolean

    Synopsis:

Declaration:     operator  operator  :=(variant):  Boolean(const  source:  variant)  :  Boolean

    Visibility:   default

Description:



                37.10.237            operator  :=(variant):  Byte

    Synopsis:

Declaration:     operator  operator  :=(variant):  Byte(const  source:  variant)  :  Byte

    Visibility:   default

Description:



                37.10.238            operator  :=(variant):  Char

    Synopsis:

Declaration:     operator  operator  :=(variant):  Char(const  source:  variant)  :  Char

    Visibility:   default

Description:



                37.10.239            operator  :=(variant):  comp

Declaration:     operator  operator  :=(variant):  comp(const  source:  variant)  :  comp

    Visibility:   default



                                                                                1370

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.240            operator  :=(variant):  currency

    Synopsis:

Declaration:     operator  operator  :=(variant):  currency(const  source:  variant)
                                                                                  :  currency

    Visibility:   default

Description:



                37.10.241            operator  :=(variant):  Double

    Synopsis:

Declaration:     operator  operator  :=(variant):  Double(const  source:  variant)  :  Double

    Visibility:   default

Description:



                37.10.242            operator  :=(variant):  DWord

    Synopsis:

Declaration:     operator  operator  :=(variant):  DWord(const  source:  variant)  :  DWord

    Visibility:   default

Description:



                37.10.243            operator  :=(variant):  extended

Declaration:     operator  operator  :=(variant):  extended(const  source:  variant)
                                                                                  :  extended

    Visibility:   default



                37.10.244            operator  :=(variant):  Int64

    Synopsis:

Declaration:     operator  operator  :=(variant):  Int64(const  source:  variant)  :  Int64

    Visibility:   default

Description:



                37.10.245            operator  :=(variant):  longbool

    Synopsis:

Declaration:     operator  operator  :=(variant):  longbool(const  source:  variant)
                                                                                  :  longbool

    Visibility:   default

Description:



                                                                                1371

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.246            operator  :=(variant):  LongInt

    Synopsis:

Declaration:     operator  operator  :=(variant):  LongInt(const  source:  variant)  :  LongInt

    Visibility:   default

Description:



                37.10.247            operator  :=(variant):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(variant):  olevariant(const  source:  variant)
                                                                                     :  olevariant

    Visibility:   default

Description:



                37.10.248            operator  :=(variant):  QWord

    Synopsis:

Declaration:     operator  operator  :=(variant):  QWord(const  source:  variant)  :  QWord

    Visibility:   default

Description:



                37.10.249            operator  :=(variant):  Real

Declaration:     operator  operator  :=(variant):  Real(const  source:  variant)  :  Real

    Visibility:   default



                37.10.250            operator  :=(variant):  ShortInt

    Synopsis:

Declaration:     operator  operator  :=(variant):  ShortInt(const  source:  variant)
                                                                                  :  ShortInt

    Visibility:   default

Description:



                37.10.251            operator  :=(variant):  shortstring

    Synopsis:

Declaration:     operator  operator  :=(variant):  shortstring(const  source:  variant)
                                                                                       :  shortstring

    Visibility:   default

Description:



                                                                                1372

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.252            operator  :=(variant):  single

Declaration:     operator  operator  :=(variant):  single(const  source:  variant)  :  single

    Visibility:   default



                37.10.253            operator  :=(variant):  SmallInt

    Synopsis:

Declaration:     operator  operator  :=(variant):  SmallInt(const  source:  variant)
                                                                                  :  SmallInt

    Visibility:   default

Description:



                37.10.254            operator  :=(variant):  TDateTime

    Synopsis:

Declaration:     operator  operator  :=(variant):  TDateTime(const  source:  variant)
                                                                                    :  TDateTime

    Visibility:   default

Description:



                37.10.255            operator  :=(variant):  TError

    Synopsis:

Declaration:     operator  operator  :=(variant):  TError(const  source:  variant)  :  TError

    Visibility:   default

Description:



                37.10.256            operator  :=(variant):  unicodestring

Declaration:     operator  operator  :=(variant):  unicodestring(const  source:  variant)
                                                                                          :  unicodestring

    Visibility:   default



                37.10.257            operator  :=(variant):  UTF8String

Declaration:     operator  operator  :=(variant):  UTF8String(const  source:  variant)
                                                                                     :  UTF8String

    Visibility:   default



                                                                                1373

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.258            operator  :=(variant):  WideChar

    Synopsis:

Declaration:     operator  operator  :=(variant):  WideChar(const  source:  variant)
                                                                                  :  WideChar

    Visibility:   default

Description:



                37.10.259            operator  :=(variant):  widestring

    Synopsis:

Declaration:     operator  operator  :=(variant):  widestring(const  source:  variant)
                                                                                     :  widestring

    Visibility:   default

Description:



                37.10.260            operator  :=(variant):  Word

    Synopsis:

Declaration:     operator  operator  :=(variant):  Word(const  source:  variant)  :  Word

    Visibility:   default

Description:



                37.10.261            operator  :=(variant):  wordbool

    Synopsis:

Declaration:     operator  operator  :=(variant):  wordbool(const  source:  variant)
                                                                                  :  wordbool

    Visibility:   default

Description:



                37.10.262            operator  :=(WideChar):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(WideChar):  olevariant(const  source:  WideChar)
                                                                                       :  olevariant

    Visibility:   default

Description:



                                                                                1374

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.263            operator  :=(WideChar):  variant

    Synopsis:

Declaration:     operator  operator  :=(WideChar):  variant(const  source:  WideChar)
                                                                                  :  variant

    Visibility:   default

Description:



                37.10.264            operator  :=(widestring):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(widestring):  olevariant(const  source:  widestring)
                                                                                          :  olevariant

    Visibility:   default

Description:



                37.10.265            operator  :=(widestring):  variant

    Synopsis:

Declaration:     operator  operator  :=(widestring):  variant(const  source:  widestring)
                                                                                     :  variant

    Visibility:   default

Description:



                37.10.266            operator  :=(Word):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(Word):  olevariant(const  source:  Word)  :  olevariant

    Visibility:   default

Description:



                37.10.267            operator  :=(Word):  variant

    Synopsis:

Declaration:     operator  operator  :=(Word):  variant(const  source:  Word)  :  variant

    Visibility:   default

Description:



                                                                                1375

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.268            operator  :=(wordbool):  olevariant

    Synopsis:

Declaration:     operator  operator  :=(wordbool):  olevariant(const  source:  wordbool)
                                                                                       :  olevariant

    Visibility:   default

Description:



                37.10.269            operator  :=(wordbool):  variant

    Synopsis:

Declaration:     operator  operator  :=(wordbool):  variant(const  source:  wordbool)
                                                                                  :  variant

    Visibility:   default

Description:



                37.10.270            operator  <(variant,  variant):  Boolean

    Synopsis:    Implement < (less than) operation on variants.

Declaration:     operator  operator  <(variant,  variant):  Boolean(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 (1377   )



                37.10.271            operator  <=(variant,  variant):  Boolean

    Synopsis:    Implement <= (less than than or equal) operation on variants.

Declaration:     operator  operator  <=(variant,  variant):  Boolean(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 (1376   )



                                                                                1376

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.272            operator  =(variant,  variant):  Boolean

    Synopsis:    Implement = (equality) operation on variants.

Declaration:     operator  operator  =(variant,  variant):  Boolean(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 (1376   )



                37.10.273            operator  >(variant,  variant):  Boolean

    Synopsis:    Implement > (greater than) operation on variants.

Declaration:     operator  operator  >(variant,  variant):  Boolean(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 (1376   )



                37.10.274            operator  >=(variant,  variant):  Boolean

    Synopsis:    Implement >= (greater than or equal) operation on variants.

Declaration:     operator  operator  >=(variant,  variant):  Boolean(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 (1376   )



                                                                                1377

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.275            operator  and(variant,  variant):  variant

    Synopsis:    Implement logical/binary and operation on variants

Declaration:     operator  operator  and(variant,  variant):  variant(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 (1379   ), operator xor(variant, variant):  variant (1380   ),
                operator not(variant):  variant (1379   )



                37.10.276            operator  div(variant,  variant):  variant

    Synopsis:    Implement div (integer division) operation on variants.

Declaration:     operator  operator  div(variant,  variant):  variant(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 (1378   )



                37.10.277            operator  mod(variant,  variant):  variant

    Synopsis:    Implement mod (modulo) operation on variants.

Declaration:     operator  operator  mod(variant,  variant):  variant(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 (1378   )



                                                                                1378

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.278            operator  not(variant):  variant

    Synopsis:    Implement logical/binary not operation on variants

Declaration:     operator  operator  not(variant):  variant(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 (1378   ), operator or(variant, variant):  variant (1379   ),
                operator xor(variant, variant):  variant (1380   )



                37.10.279            operator  or(variant,  variant):  variant

    Synopsis:    Implement logical/binary or operation on variants

Declaration:     operator  operator  or(variant,  variant):  variant(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 (1378   ), operator xor(variant, variant): variant (1380   ),
                operator not(variant):  variant (1379   )



                37.10.280            operator  shl(variant,  variant):  variant

    Synopsis:    Implement binary shl operation on variants.

Declaration:     operator  operator  shl(variant,  variant):  variant(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 (1380   )



                                                                                1379

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.281            operator  shr(variant,  variant):  variant

    Synopsis:    Implement binary shr operation on variants.

Declaration:     operator  operator  shr(variant,  variant):  variant(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 (1379   )



                37.10.282            operator  xor(variant,  variant):  variant

    Synopsis:    Implement logical/binary xor operation on variants

Declaration:     operator  operator  xor(variant,  variant):  variant(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 (1379   ), operator and(variant, variant):  variant (1378   ),
                operator not(variant):  variant (1379   )



                37.10.283            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 (1298   ), Succ (1414   ), Pred (1384   ), High (1334   ), Low (1350   )


                Listing:  ./refex/ex45.pp



                                                                                1380

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 5;


                {   Program       t o  d e m o n s t r a t et h e  Ord  , Pred   , S u c c  f u n c t i o n.s  }


                Type
                    TEnum     =  (  Zero   ,  One   ,  Two  ,   Three    ,  F o u r) ;


                Var
                    X   :  L o n g i n t;
                    Y   :  TEnum    ;


                 b e g i n
                    X : = 1 2 5 ;
                    W r i t e l n ( Ord  (X  ) ) ;   {   P r i n t s 1 2 5  }
                    X := Pred   ( X ) ;
                    W r i t e l n ( Ord  (X  ) ) ;   {   p r i n t s 1 2 4  }
                    Y : =  One  ;
                    W r i t e l n ( Ord  ( y ) ) ;   {   P r i n t s 1  }
                    Y := Succ   ( Y ) ;
                    W r i t e l n ( Ord  (Y  ) ) ;   {   P r i n t s2 }
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.284            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 (1424   )



                37.10.285            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 (1382   )


                Listing:  ./refex/ex46.pp



                                                                                1381

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.286            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 (1381   ).

       Errors:   None.

    See also:    Paramcount (1381   )



                37.10.287            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 (1306   ), Sin (1408   )



                                                                                1382

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.288            Pos

    Synopsis:    Search for substring in a string.

Declaration:     function  Pos(const  substr:  shortstring;const  s:  shortstring)  :  SizeInt
                function  Pos(C:  Char;const  s:  shortstring)  :  SizeInt
                function  Pos(const  Substr:  ShortString;const  Source:  AnsiString)
                                      :  SizeInt
                function  pos(const  substr:  shortstring;c:  Char)  :  SizeInt
                function  Pos(const  Substr:  AnsiString;const  Source:  AnsiString)
                                      :  SizeInt
                function  Pos(c:  Char;const  s:  AnsiString)  :  SizeInt
                function  Pos(const  Substr:  UnicodeString;const  Source:  UnicodeString)
                                      :  SizeInt
                function  Pos(c:  Char;const  s:  UnicodeString)  :  SizeInt
                function  Pos(c:  UnicodeChar;const  s:  UnicodeString)  :  SizeInt
                function  Pos(c:  AnsiString;const  s:  UnicodeString)  :  SizeInt
                function  Pos(c:  UnicodeString;const  s:  AnsiString)  :  SizeInt
                function  Pos(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:  AnsiString)  :  SizeInt
                function  Pos(c:  AnsiString;const  s:  WideString)  :  SizeInt
                function  Pos(c:  WideString;const  s:  AnsiString)  :  SizeInt
                function  Pos(c:  ShortString;const  s:  WideString)  :  SizeInt
                function  Pos(c:  Char;const  v:  Variant)  :  SizeInt
                function  Pos(s:  ShortString;const  v:  Variant)  :  SizeInt
                function  Pos(a:  AnsiString;const  v:  Variant)  :  SizeInt
                function  Pos(w:  WideString;const  v:  Variant)  :  SizeInt
                function  Pos(w:  UnicodeString;const  v:  Variant)  :  SizeInt
                function  Pos(v:  Variant;const  c:  Char)  :  SizeInt
                function  Pos(v:  Variant;const  s:  ShortString)  :  SizeInt
                function  Pos(v:  Variant;const  a:  AnsiString)  :  SizeInt
                function  Pos(v:  Variant;const  w:  WideString)  :  SizeInt
                function  Pos(v:  Variant;const  w:  UnicodeString)  :  SizeInt
                function  Pos(v1:  Variant;const  v2:  Variant)  :  SizeInt

    Visibility:   default

Description:     Pos returns the index of Substr in S, if S contains Substr.  In case Substr isn't found, 0 is
                returned.  The search is case-sensitive.



                                                                                1383

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   None

    See also:    Length (1346   ), Copy (1306   ), Delete (1309   ), Insert (1341   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.289            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 (1380   )

       Errors:   Run-time error 201 is generated when the result is out of range.

    See also:    Ord (1380   ), Pred (1384   ), High (1334   ), Low (1350   )



                37.10.290            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.



                37.10.291            ptr

    Synopsis:    Combine segment and offset to pointer

Declaration:     function  ptr(sel:  LongInt;off:  LongInt)  :  farpointer



                                                                                1384

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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 (1286   )


                Listing:  ./refex/ex59.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 9;


                {   Program       t o  d e m o n s t r a t et h e  P t r  ( c o m p a b i l i t)y  f u n c t i o n.
                }


                 t y p e p S t r i n g =  ^  S t r i n g;


                Var    P   :   p S t r i n g;
                       S   :   S t r i n g;


                 b e g i n
                    S :=  'H e l l o,  World      ! ';
                    P := p S t r i n g(P t r( Seg  ( S ) ,L o n g i n t(Ofs   (S ) ) ) ) ;
                    {P   now    p o i n t s t o  S   ! }
                    W r i t e l n (P  ^ ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.292            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.



                37.10.293            Random

    Synopsis:    Generate random number

Declaration:     function  Random(l:  LongInt)  :  LongInt
                function  Random(l:  Int64)  :  Int64
                function  Random  :  extended

    Visibility:   default

Description:     Random returns a random number larger or equal to 0 and strictly less than L. If the argument
                L is omitted, a Real number between 0 and 1 is returned.  (0 included, 1 excluded)

       Errors:   None.



                                                                                1385

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    See also:    Randomize (1386   )


                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;


                 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___.____________________________________________________________________________________________________________*
 *___________



                37.10.294            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 (1385   ).

       Errors:   None.

    See also:    Random (1385   )



                37.10.295            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



                                                                                1386

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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 (1388   ), Blockread (1293   ), Write (1430   ), Blockwrite (1294   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.296            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 (1387   ), ReadWriteBarrier (1389   ), WriteBarrier (1430   )



                37.10.297            ReadDependencyBarrier

    Synopsis:    Memory Read Dependency Barrier

Declaration:     procedure  ReadDependencyBarrier



                                                                                1387

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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 (1387   ), ReadWriteBarrier (1389   ), WriteBarrier (1430   )



                37.10.298            ReadLn

    Synopsis:    Read from a text file into variable and goto next line

Declaration:     procedure  ReadLn(var  F:  Text;Args:  Arguments)
                procedure  ReadLn(Args:  Arguments)

    Visibility:   default

Description:     Read reads one or more values from a file F, and stores the result in V1, V2, etc.  After that it
                goes to the next line in the file.  The end of the line is marked by the LineEnding character
                sequence  (which  is  platform  dependent).  The  end-of-line  marker  is  not  considered  part  of
                the line and is ignored.

                If no file F is specified, then standard input is read.  The variables V1,  V2 etc.  must be of
                type Char, Integer, Real, String or PChar.

                For an example, see Read (1386   ).

       Errors:   If no data is available,  empty values are returned (0 for ordinal values,  empty strings for
                string values)

    See also:    Read (1386   ), Blockread (1293   ), Write (1430   ), Blockwrite (1294   )



                37.10.299            ReadStr

    Synopsis:    Read variables from a string

Declaration:     procedure  ReadStr(const  S:  string;Args:  Arguments)

    Visibility:   default

Description:     ReadStr behaves like Read (1386   ), 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;



                                                                                1388

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                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
                (1386   ).

    See also:    Read (1386   ), WriteStr (1431   ), Write (1430   )



                37.10.300            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 (1387   ), ReadDependencyBarrier (1387   ), WriteBarrier (1430   )



                37.10.301            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 ) ;



                                                                                1389

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                       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___.____________________________________________________________________________________________________________*
 *___________



                37.10.302            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 (1328   ), FreeMem (1326   )



                37.10.303            ReAllocMemory

    Synopsis:    Alias for ReAllocMem (1390   )

Declaration:     function  ReAllocMemory(p:  pointer;Size:  PtrUInt)  :  pointer

    Visibility:   default

Description:     ReAllocMemory is an alias for ReAllocMem (1390   ).

    See also:    ReAllocMem (1390   )



                37.10.304            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 (1285   ) 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 (1285   )



                                                                                1390

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.305            Rename

    Synopsis:    Rename file on disk

Declaration:     procedure  Rename(var  f:  File;const  s:  string)
                procedure  Rename(var  f:  File;p:  PChar)
                procedure  Rename(var  f:  File;c:  Char)
                procedure  Rename(var  t:  Text;const  s:  string)
                procedure  Rename(var  t:  Text;p:  PChar)
                procedure  Rename(var  t:  Text;c:  Char)

    Visibility:   default

Description:     Rename changes the name of the assigned file F to S. F must be assigned, but not opened.

       Errors:   Depending on the state of the {$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 (1316   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.306            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 (1392   ), Assign (1289   ), Close (1298   ), Append (1287   )


                Listing:  ./refex/ex51.pp



                                                                                1391

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 1;


                {   Program       t o  d e m o n s t r a t et h e  R e s e t  f u n c t i o n. }


                 F u n c t i o nF i l e E x i s t s( Name     :  S t r i n g)  :   b o o l e a n;


                Var    F   :   F i l e;


                 b e g i n
                    { $ i- }
                    A s s i g n ( F ,Name    ) ;
                    R e s e t ( F ) ;
                    { $ I+ }
                    F i l e E x i s t:s= ( I o R e s u l t=0)  and    ( Name   <>  ' ') ;
                    C l o s e ( f ) ;
                end   ;


                 b e g i n
                    I f  F i l e E x i s t s( Paramstr      ( 1 ) )  then
                        W r i t e l n(  'F i l e  f o u n d')
                    e l s e
                        W r i t e l n(  'F i l e NOT     f o u n d') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.307            ResumeThread

    Synopsis:    Resume a suspended thread.

Declaration:     function  ResumeThread(threadHandle:  TThreadID)  :  DWord

    Visibility:   default

Description:     ResumeThread  causes  a  suspended  thread  (using  SuspendThread  (1414   ))  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 (1414   ), KillThread (1346   )



                37.10.308            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



                                                                                1392

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                fmoutput.  If it should be opened in fminout mode, an extra call to Reset (1391   ) 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 (1391   ), Assign (1289   ), Close (1298   ), Flush (1325   ), Append (1287   )


                Listing:  ./refex/ex52.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 2;


                {   Program       t o  d e m o n s t r a t et h e  R e w r i t e f u n c t i o n. }


                Var    F   :   F i l e;
                        I  :   l o n g i n t;


                 b e g i n
                    A s s i g n ( F , 'T e s t. tmp  ' ) ;
                    {   C r e a t e t h e  f i l e.  R e c o r d s i z e i s 4   }
                    R e w r i t e (F  ,S i z e o f( I) ) ;
                    For    I : = 1  t o  1 0  do
                       B l o c k W r i t e (F , I , 1 ) ;
                    c l o s e ( f ) ;
                    {  F   c o n t a i n snow     a  b i n a r y  r e p r e s e n t a t i o no f
                        1 0  l o n g i n t sg o i n g  f r o m 1   t o  1 0  }
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.309            rmdir

    Synopsis:    Remove directory when empty.

Declaration:     procedure  rmdir(const  s:  string);    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 (1297   ), Mkdir (1351   )


                Listing:  ./refex/ex53.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 3;


                {   Program       t o  d e m o n s t r a t et h e  MkDir     and    RmDir      f u n c t i o n s. }


                Const      D   :  S t r i n g[ 8 ]  =  'TEST    .DIR   ';


                Var    S   :   S t r i n g;


                 b e g i n
                    W r i t e l n ( 'Making       d i r e c t o r y' ,D  ) ;
                    Mkdir     ( D ) ;
                    W r i t e l n ( 'C h a n g i n g d i r e c t o r y t o  ' ,D ) ;
                    ChDir     ( D ) ;



                                                                                1393

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                37.10.310            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 (1395   ), RolWord (1395   ), RolDWord (1394   ), RolQWord (1394   )



                37.10.311            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 (1394   ), RolWord (1395   ), RorDWord (1395   ), RolQWord (1394   )



                37.10.312            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

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 (1394   ), RolWord (1395   ), RolDWord (1394   ), RorQWord (1395   )



                                                                                1394

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.313            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 (1394   ), RorWord (1396   ), RolDWord (1394   ), RolQWord (1394   )



                37.10.314            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 (1394   ), RorWord (1396   ), RorDWord (1395   ), RorQWord (1395   )



                37.10.315            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 (1395   ), RolDWord (1394   ), RorWord (1396   ), RorQWord (1395   )



                37.10.316            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 (1395   ), RorWord (1396   ), RorDWord (1395   ), RolQWord (1394   )



                                                                                1395

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.317            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 (1395   ), RolWord (1395   ), RorDWord (1395   ), RorQWord (1395   )



                37.10.318            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 (1326   ), Int (1342   ), Trunc (1420   )


                Listing:  ./refex/ex54.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 5 4;


                {   Program       t o  d e m o n s t r a t et h e  Round      f u n c t i o n. }


                 b e g i n
                    W r i t e l n (Round     ( 1 2 3 4 . 5 6 ) ) ; {   P r i n t s1 2 3 5         }
                    W r i t e l n (Round     ( - 1 2 3 4 . 5 6 ) ) ;{  P r i n t s-1235           }
                    W r i t e l n (Round     ( 1 2 . 3 4 5 6 ) ) ; {   P r i n t s 1 2            }
                    W r i t e l n (Round     ( - 1 2 . 3 4 5 6 ) ) ;{  P r i n t s-12             }
                    W r i t e l n (Round     ( 2 . 5 ) ) ;         {   P r i n t s 2  ( down   )  }
                    W r i t e l n (Round     ( 3 . 5 ) ) ;         {   P r i n t s 4  ( up  )     }


                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.319            RTLEventCreate

    Synopsis:    Create a new RTL event

Declaration:     function  RTLEventCreate  :  PRTLEvent

    Visibility:   default



                                                                                1396

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1397   )

                RTLEvent is used mainly for the synchronize method.

    See also:    RTLEventDestroy (1397   ), RTLEventSetEvent (1397   ), RTLEventReSetEvent (1397   ), RTLEvent-
                WaitFor (1398   )



                37.10.320            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 (1396   ), RTLEventResetEvent (1397   ), RTLEventSetEvent (1397   )



                37.10.321            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 (1396   ), RTLEventDestroy (1397   ), RTLEventSetEvent (1397   ), RTLEvent-
                WaitFor (1398   )



                37.10.322            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 (1396   ), RTLEventResetEvent (1397   ), RTLEventDestroy (1397   ), RTLEvent-
                WaitFor (1398   )



                37.10.323            RTLeventsync

    Synopsis:    Obsolete.  Don't use

Declaration:     procedure  RTLeventsync(m:  trtlmethod;p:  TProcedure)

    Visibility:   default

Description:     RTLeventsync is obsolete, don't use it.



                                                                                1397

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.324            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 (1397   ) 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 (1396   ), RTLEventDestroy (1397   ), RTLEventSetEvent (1397   ), RTLEvent-
                WaitFor (1398   )



                37.10.325            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 (1318   ), Halt (1332   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.326            SarInt64

    Synopsis:    64-bit Shift Arithmetic Right

Declaration:     function  SarInt64(const  AValue:  Int64;const  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 (1399   ), SarSmallInt (1399   ), SarLongInt (1399   )



                                                                                1398

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.327            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 (1399   ), SarSmallInt (1399   ), SarInt64 (1398   )



                37.10.328            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 (1399   ), SarLongint (1399   ), SarInt64 (1398   )



                37.10.329            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 (1399   ), SarLongint (1399   ), SarInt64 (1398   )



                37.10.330            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 (1391   ) or Rewrite (1392   ), 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.



                                                                                1399

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    See also:    Eof (1314   ), SeekEof (1400   ), SeekEoln (1401   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.331            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.

                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 (1314   ), SeekEoln (1401   ), Seek (1399   )


                Listing:  ./refex/ex57.pp



                                                                                1400

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.332            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 (1314   ), SeekEof (1400   ), Seek (1399   )


                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. }
                    While     not    SeekEoln        do
                       Begin
                       Read     ( c ) ;
                       Write      ( c ) ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.333            Seg

    Synopsis:    Return segment



                                                                                1401

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1311   ), CSeg (1307   ), Ofs (1355   ), Ptr (1384   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.334            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 (1349   ) with env as an argument was made somewhere in the program.

       Errors:   None.

    See also:    LongJmp (1349   )


                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;



                                                                                1402

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                37.10.335            SetLength

    Synopsis:    Set length of a string.

Declaration:     procedure  SetLength(var  S:  AStringType;Len:  Integer)
                procedure  SetLength(var  A:  DynArrayType;Len:  Integer)

    Visibility:   default

Description:     SetLength sets the length of the string S to Len.  S can be an ansistring, a short string or
                a widestring.  For ShortStrings, Len can maximally be 255.  For AnsiStrings it can have
                any value.  For AnsiString strings, SetLength {\em must} be used to set the length of the
                string.

                In the case of a dynamical array A, setlength sets the number of elements.  The elements are
                numbered from index 0, so the count runs from 0 to Len-1.  If Zero is specified, the array is
                cleared.

       Errors:   None.

    See also:    Length (1346   )


                Listing:  ./refex/ex85.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 5;


                {   Program       t o  d e m o n s t r a t et h e  S e t L e n g t h f u n c t i o n. }


                Var    S   :   S t r i n g;


                 b e g i n
                    F i l l C h a r(S [ 1 ] , 1 0 0 , # 3 2 ) ;
                    S e t l e n g t h(S, 1 0 0 ) ;
                    W r i t e l n ( '"  ',S  , '" ' ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.336            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.



                                                                                1403

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   None.

    See also:    GetMemoryManager (1329   ), IsMemoryManagerSet (1345   )



                37.10.337            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 (1272   ), GetResourceManager (1330   )



                37.10.338            SetString

    Synopsis:    Set length of a string and copy buffer.

Declaration:     procedure  SetString(out  S:  AnsiString;Buf:  PChar;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 (1403   )



                37.10.339            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



                                                                                1404

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                reducing the number of system calls,  and thus reducing the load on the system resources.
                The maximum size of the newly assigned buffer is 65355 bytes.

 Remark:

                      oNever assign a new buffer to an opened file.  A new buffer can be assigned immediately
                      after a call to Rewrite (1392   ), Reset (1391   ) 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 (1289   ), Reset (1391   ), Rewrite (1392   ), Append (1287   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.340            SetTextLineEnding

    Synopsis:    Set the end-of-line character for the given text file.

Declaration:     procedure  SetTextLineEnding(var  f:  Text;Ending:  string)

    Visibility:   default



                                                                                1405

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     SetTextLineEnding sets the end-of-line character for the text file F to Ending.  By default,
                this is the string indicated by DefaultTextLineBreakStyle (1235   ).

       Errors:   None.

    See also:    DefaultTextLineBreakStyle (1235   ), TTextLineBreakStyle (1275   )



                37.10.341            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 (1330   ), TThreadManager (1276   )



                37.10.342            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 (1277   )



                                                                                1406

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.343            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 (1331   )



                37.10.344            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 (1281   )



                37.10.345            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 (1497   )



                                                                                1407

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.346            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 (1306   ), Pi (1382   ), Exp (1319   ), Ln (1347   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.347            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 (1286   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1408

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.348            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 (1348   )

       Errors:   In case of an error, 0 is returned.

    See also:    FindResource (1323   ), FreeResource (1327   ), LoadResource (1348   ), LockResource (1349   ), Un-
                lockResource (1424   ), FreeResource (1327   )



                37.10.349            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 (1412   )



                37.10.350            Sptr

    Synopsis:    Return current stack pointer

Declaration:     function  Sptr  :  Pointer

    Visibility:   default

Description:     Sptr returns the current stack pointer.

       Errors:   None.

    See also:    SSeg (1411   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1409

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.351            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 (1410   ), Ln (1347   ), Exp (1319   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.352            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 (1410   ), Ln (1347   ), Exp (1319   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1410

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.353            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 (1409   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.354            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 (1426   )


                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;



                                                                                1411

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                 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___.____________________________________________________________________________________________________________*
 *___________



                37.10.355            StringOfChar

    Synopsis:    Return a string consisting of 1 character repeated N times.

Declaration:     function  StringOfChar(c:  Char;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 (1403   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.356            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



                                                                                1412

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



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 (1288   )



                37.10.357            StringToUnicodeChar

    Synopsis:    Convert an ansistring to a null-terminated array of unicode characters.

Declaration:     function  StringToUnicodeChar(const  Src:  AnsiString;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 (1422   ), UnicodeCharLenToString (1422   )



                37.10.358            StringToWideChar

    Synopsis:    Convert a string to an array of widechars.

Declaration:     function  StringToWideChar(const  Src:  AnsiString;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 (1429   ), WideCharToStrVar (1429   ), WideCharLenToStrVar (1429   ), WideCharLen-
                ToString (1428   )



                37.10.359            strlen

    Synopsis:    Length of a null-terminated string.

Declaration:     function  strlen(p:  PChar)  :  SizeInt

    Visibility:   default



                                                                                1413

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:     Returns the length of the null-terminated string P.

       Errors:   None.



                37.10.360            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.



                37.10.361            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 (1380   ).

       Errors:   Run-time error 201 is generated when the result is out of range.

    See also:    Ord (1380   ), Pred (1384   ), High (1334   ), Low (1350   )



                37.10.362            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 (1392   ), KillThread (1346   )



                                                                                1414

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.363            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 (1348   ), Hi (1333   )


                Listing:__./refex/ex69.pp__________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 6 9;


                {   Program       t o  d e m o n s t r a t et h e  Swap     f u n c t i o n. }
                Var    W   :  Word    ;
                       L   :   L o n g i n t;


                 b e g i n
                   W  := $1234    ;
                   W  := Swap   (W  ) ;
                    i f  W<>  $3412      then
                        w r i t e l n(  'E r r o r when     s w a p p i n g word     ! ') ;
                    L := $ 1 2 3 4 5 6 7 8;
                    L := Swap   ( L ) ;
                    i f  L<>  $ 5 6 7 8 1 2 3 4 then
                        w r i t e l n(  'E r r o r when     s w a p p i n g L o n g i n t ! ') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.364            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 (1333   ), lo (1348   ), swap (1415   ), BEToN (1292   ), NToBE (1353   ), NToLE (1353   ), LEToN
                (1347   )



                                                                                1415

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.365            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 (1287   )

    See also:    AllocMem (1287   )



                37.10.366            SysAssert

    Synopsis:    Standard Assert failure implementation

Declaration:     procedure  SysAssert(const  Msg:  ShortString;const  FName:  ShortString;
                                                LineNo:  LongInt;ErrorAddr:  Pointer)

    Visibility:   default

Description:     SysAssert  is  the  standard  implementation  of  the  assertion  failed  code.  It  is  the  default
                value of the AssertErrorProc constant.  It will print the assert message Msg together with
                the filename FName and linenumber LineNo to standard error output (StdErr) and will halt
                the program with exit code 227.  The error address ErrorAddr is ignored.

    See also:    AssertErrorProc (1235   )



                37.10.367            SysBackTraceStr

    Synopsis:    Format an address suitable for inclusion in a backtrace

Declaration:     function  SysBackTraceStr(Addr:  Pointer)  :  ShortString

    Visibility:   default

Description:     SysBackTraceStr will create a string representation of the address Addr, suitable for inclu-
                sion in a stack backtrace.

       Errors:   None.



                37.10.368            SysFlushStdIO

    Synopsis:

Declaration:     procedure  SysFlushStdIO

    Visibility:   default

Description:



                37.10.369            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 (1326   )

    See also:    FreeMem (1326   )



                                                                                1416

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.370            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 (1326   )

    See also:    MemSize (1351   )



                37.10.371            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 (1328   ) function.

       Errors:   None.  The result of this function is bogus information if the current heapmanager is not
                the standard FPC heapmanager.

    See also:    GetFPCHeapStatus (1328   )



                37.10.372            SysGetHeapStatus

    Synopsis:    System implementation of GetHeapStatus (1328   )

Declaration:     function  SysGetHeapStatus  :  THeapStatus

    Visibility:   default

Description:     SysGetHeapStatus is the system implementation of the GetHeapStatus (1328   ) call.

    See also:    GetHeapStatus (1328   )



                37.10.373            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 (1328   )

    See also:    GetMem (1328   ), GetMemory (1329   )



                37.10.374            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.



                                                                                1417

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.375            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 (1292   )



                37.10.376            SysInitStdIO

    Synopsis:    Initialize standard input and output.

Declaration:     procedure  SysInitStdIO

    Visibility:   default

Description:     SysInitStdIO initializes the standard input and output files:  Output (1283   ), Input (1283   )
                and StdErr (1284   ).  This routine is called by the initialization code of the system unit, there
                should be no need to call it directly.



                37.10.377            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 (1351   )

    See also:    MemSize (1351   )



                37.10.378            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 (1390   ).

    See also:    ReAllocMem (1390   )



                37.10.379            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.



                                                                                1418

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.380            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 (1267   )



                37.10.381            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 (1390   ), SysReAllocMem (1418   )

    See also:    SysReAllocMem (1418   ), ReAllocMem (1390   )



                37.10.382            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 (1419   )



                37.10.383            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 (1419   )



                                                                                1419

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.384            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 (1414   ), ResumeThread (1392   ), KillThread (1346   )



                37.10.385            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 (1326   ), Int (1342   ), Round (1396   )


                Listing:  ./refex/ex70.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 0;


                {   Program       t o  d e m o n s t r a t et h e  Trunc      f u n c t i o n. }


                 b e g i n
                    W r i t e l n ( Trunc    ( 1 2 3 . 4 5 6 ) ) ; {   P r i n t s 1 2 3   }
                    W r i t e l n ( Trunc    ( - 1 2 3 . 4 5 6 ) ) ;{  P r i n t s-123     }
                    W r i t e l n ( Trunc    ( 1 2 . 3 4 5 6 ) ) ; {   P r i n t s 1 2     }
                    W r i t e l n ( Trunc    ( - 1 2 . 3 4 5 6 ) ) ;{  P r i n t s-12      }
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.386            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 (1287   ), Filepos (1319   ), Seek (1399   )


                Listing:  ./refex/ex71.pp



                                                                                1420

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.387            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.



                37.10.388            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 (1423   )



                37.10.389            UCS4StringToWideString

    Synopsis:

Declaration:     function  UCS4StringToWideString(const  s:  UCS4String)  :  WideString

    Visibility:   default



                                                                                1421

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



Description:



                37.10.390            Unassigned

    Synopsis:    Unassigned variant.

Declaration:     function  Unassigned  :  Variant

    Visibility:   default



                37.10.391            UnicodeCharLenToString

    Synopsis:    Convert a memory buffer with unicode characters to an ansistring

Declaration:     function  UnicodeCharLenToString(S:  PUnicodeChar;Len:  SizeInt)
                                                                     :  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.

                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 (1413   ), UnicodeCharToString (1422   )



                37.10.392            UnicodeCharLenToStrVar

    Synopsis:    Convert a memory buffer with unicode characters to an ansistring

Declaration:     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 (1422   ).

       Errors:   No checking is done to see if the pointer S or length len are valid.

    See also:    StringToUnicodeChar (1413   ), UnicodeCharToString (1422   ), UnicodeCharLenToString (1422   ),
                UnicodeCharToStrVar (1423   )



                37.10.393            UnicodeCharToString

    Synopsis:    Convert unicode character to string

Declaration:     function  UnicodeCharToString(S:  PUnicodeChar)  :  AnsiString

    Visibility:   default

Description:     UnicodeCharToString converts a null-word-terminated array of unicode characters in S to
                an AnsiString value.  It simply calls UnicodeCharLenToString (1422   ) with the length of the
                string S.

                This function requires the use of a widestring manager.



                                                                                1422

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   No checking is done to see if the pointer S is valid.

    See also:    StringToUnicodeChar (1413   ), UnicodeCharLenToString (1422   ), WidestringManager (1284   )



                37.10.394            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 (1422   ).

       Errors:   No checking is done to see if the pointer S is valid.

    See also:    StringToUnicodeChar (1413   ), UnicodeCharToString (1422   ), UnicodeCharLenToString (1422   ),
                UnicodeCharToString (1422   )



                37.10.395            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 (1421   )



                37.10.396            UnicodeToUtf8

    Synopsis:

Declaration:     function  UnicodeToUtf8(Dest:  PChar;Source:  PUnicodeChar;
                                                     MaxBytes:  SizeInt)  :  SizeInt
                function  UnicodeToUtf8(Dest:  PChar;MaxDestBytes:  SizeUInt;
                                                     Source:  PUnicodeChar;SourceChars:  SizeUInt)
                                                      :  SizeUInt
                function  UnicodeToUtf8(Dest:  PChar;Source:  PWideChar;MaxBytes:  SizeInt)
                                                      :  SizeInt
                function  UnicodeToUtf8(Dest:  PChar;MaxDestBytes:  SizeUInt;
                                                     Source:  PWideChar;SourceChars:  SizeUInt)
                                                      :  SizeUInt

    Visibility:   default

Description:



                                                                                1423

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.397            UniqueString

    Synopsis:    Make sure reference count of string is 1

Declaration:     procedure  UniqueString(var  S:  AnsiString)
                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.



                37.10.398            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  (1323   ),  FreeResource  (1327   ),  SizeofResource  (1409   ),  LoadResource  (1348   ),
                lockResource (1349   ), FreeResource (1327   )



                37.10.399            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 (1381   )



                37.10.400            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



                                                                                1424

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



    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.

       Errors:   None.

    See also:    Lowercase (1350   )


                Listing:__./refex/ex72.pp__________________________________________________________________________________________*
 *___________

                program       E x a m p l e 7 2;


                {   Program       t o  d e m o n s t r a t et h e  u p c a s e f u n c t i o n.  }


                 v a r c : c h a r;


                 b e g i n
                    f o r  c :=  'a '  t o   'z '  do
                        w r i t e(u p c a s e(c ) ) ;
                    W r i t e l n;
                    {   T h i s d o e s n' t  work     i n  TP  ,  b u t  i t  d o e s  i n  F r e e  P a s c a l }
                    W r i t e l n(u p c a s e( 'a b c d e f g h i j k l m n o p q r s t u v w x'y)z) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                37.10.401            UTF8Decode

    Synopsis:    Convert an UTF-8 encoded unicode string to a widestring

Declaration:     function  UTF8Decode(const  s:  UTF8String)  :  UnicodeString

    Visibility:   default

Description:     UTF8Decode converts the UTF-8 encoded unicode string S to a widestring and returns the
                resulting string.  It calls the low-level Utf8ToUnicode (1426   ) function to do the actual work.

                For this function to work, a widestring manager must be installed.

    See also:    UTF8Encode  (1425   ),  Utf8ToAnsi  (1426   ),  SetWideStringManager  (1407   ),  Utf8ToUnicode
                (1426   )



                37.10.402            UTF8Encode

    Synopsis:    Convert a widestring to an UTF-8 encoded unicode string

Declaration:     function  UTF8Encode(const  s:  Ansistring)  :  UTF8String
                function  UTF8Encode(const  s:  UnicodeString)  :  UTF8String
                function  UTF8Encode(const  s:  WideString)  :  UTF8String

    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 (1423   ) function
                to do the actual work.

                For this function to work, a widestring manager must be installed.

    See also:    UTF8Decode  (1425   ),  Utf8ToAnsi  (1426   ),  UnicodeToUtf8  (1423   ),  SetWideStringManager
                (1407   )



                                                                                1425

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.403            Utf8ToAnsi

    Synopsis:    Convert a UTF-8 encoded unicode string to an ansistring

Declaration:     function  Utf8ToAnsi(const  s:  UTF8String)  :  ansistring

    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 (1425   ), UTF8Decode (1425   ), SetWideStringManager (1407   )



                37.10.404            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
                function  Utf8ToUnicode(Dest:  PWideChar;Source:  PChar;MaxChars:  SizeInt)
                                                      :  SizeInt
                function  Utf8ToUnicode(Dest:  PWideChar;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.

       Errors:   On error, -1 is returned.

    See also:    UTF8Encode (1425   ), UTF8Decode (1425   ), Utf8ToAnsi (1426   ), SetWideStringManager (1407   )



                37.10.405            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.

                The conversion to enumerated exists only as of version 2.3.1 (or later) of the compiler.



                                                                                1426

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       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 (1411   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.406            VarArrayGet

    Synopsis:

Declaration:     function  VarArrayGet(const  A:  Variant;const  Indices:  Array  of  LongInt)
                                                   :  Variant

    Visibility:   default

Description:



                37.10.407            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 (1427   )



                                                                                1427

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.408            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.



                37.10.409            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.



                37.10.410            WaitForThreadTerminate

    Synopsis:    Wait for a thread to terminate.

Declaration:     function  WaitForThreadTerminate(threadHandle:  TThreadID;
                                                                   TimeoutMs:  LongInt)  :  DWord

    Visibility:   default

Description:     WaitForThreadTerminate  waits  for  a  thread  to  finish  its  execution.  The  thread  is  iden-
                tified  by  it's  handle  or  ID  threadHandle.   If  the  thread  does  not  exit  within  TimeoutMs
                milliseconds, the function will return with an error value.

                The function returns the exit code of the thread.

    See also:    EndThread (1312   ), KillThread (1346   )



                37.10.411            WideCharLenToString

    Synopsis:    Convert a length-limited array of widechar to an ansistring

Declaration:     function  WideCharLenToString(S:  PWideChar;Len:  SizeInt)  :  AnsiString

    Visibility:   default

Description:     WideCharLenToString converts at most Len widecharacters from the null-terminated widechar
                array S to an ansistring, and returns the ansistring.

       Errors:   No validity checking is performed on S. Passing an invalid pointer may lead to access viola-
                tions.

    See also:    StringToWideChar (1413   ), WideCharToString (1429   ), WideCharToStrVar (1429   ), WideCharLen-
                ToStrVar (1429   )



                                                                                1428

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.412            WideCharLenToStrVar

    Synopsis:    Convert a length-limited array of widechar to an ansistring

Declaration:     procedure  WideCharLenToStrVar(Src:  PWideChar;Len:  SizeInt;
                                                                out  Dest:  AnsiString)

    Visibility:   default

Description:     WideCharLenToString converts at most Len widecharacters from the null-terminated widechar
                array Src to an ansistring, and returns the ansistring in Dest.

       Errors:   No  validity  checking  is  performed  on  Src.  Passing  an  invalid  pointer  may  lead  to  access
                violations.

    See also:    StringToWideChar (1413   ), WideCharToString (1429   ), WideCharToStrVar (1429   ), WideCharLen-
                ToString (1428   )



                37.10.413            WideCharToString

    Synopsis:    Convert a null-terminated array of widechar to an ansistring

Declaration:     function  WideCharToString(S:  PWideChar)  :  AnsiString

    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 (1413   ), WideCharToStrVar (1429   ), WideCharLenToStrVar (1429   ), WideCharLen-
                ToString (1428   )



                37.10.414            WideCharToStrVar

    Synopsis:    Convert a null-terminated array of widechar to an ansistring

Declaration:     procedure  WideCharToStrVar(S:  PWideChar;out  Dest:  AnsiString)

    Visibility:   default

Description:     WideCharToString  converts  the  null-terminated  widechar  array  S  to  an  ansistring,  and
                returns the ansistring in Dest.

       Errors:   No validity checking is performed on S. Passing an invalid pointer, or an improperly termi-
                nated array may lead to access violations.

    See also:    StringToWideChar (1413   ), WideCharToString (1429   ), WideCharToStrVar (1429   ), WideCharLen-
                ToString (1428   )



                37.10.415            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.



                                                                                1429

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.10.416            Write

    Synopsis:    Write variable to a text file

Declaration:     procedure  Write(Args:  Arguments)
                procedure  Write(var  F:  Text;Args:  Arguments)

    Visibility:   default

Description:     Write writes the contents of the variables V1,  V2 etc.  to the file F. F can be a typed file,
                or a Text file.  If  F is a typed file, then the variables V1, V2 etc.  must be of the same type
                as  the  type  in  the  declaration  of  F.  Untyped  files  are  not  allowed.   If  the  parameter  F  is
                omitted, standard output is assumed.  If  F is of type Text, then the necessary conversions
                are done such that the output of the variables is in human-readable format.  This conversion
                is done for all numerical types.  Strings are printed exactly as they are in memory, as well
                as  PChar  types.   The  format  of  the  numerical  conversions  can  be  influenced  through  the
                following  modifiers:  OutputVariable  :    NumChars  [:    Decimals  ]   This  will  print  the
                value  of  OutputVariable  with  a  minimum  of  NumChars  characters,  from  which  Decimals
                are reserved for the decimals.  If the number cannot be represented with NumChars characters,
                NumChars will be increased, until the representation fits.  If the representation requires less
                than NumChars characters then the output is filled up with spaces, to the left of the generated
                string, thus resulting in a right-aligned representation.  If no formatting is specified, then the
                number is written using its natural length, with nothing in front of it if it's positive, and a
                minus sign if it's negative.  Real numbers are, by default, written in scientific notation.

       Errors:   If an error occurs, a run-time error is generated.  This behavior can be controlled with the
                {$I} switch.

    See also:    WriteLn (1430   ), Read (1386   ), Readln (1388   ), Blockwrite (1294   )



                37.10.417            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 (1387   ), ReadDependencyBarrier (1387   ), ReadWriteBarrier (1389   )



                37.10.418            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 (1430   ) for text files, and emits a Carriage Return - LineFeed
                character pair after that.  If the parameter F is omitted, standard output is assumed.  If no
                variables are specified, a Carriage Return - LineFeed character pair is emitted, resulting in
                a new line in the file F.

 Remark:          Under  linux  and  unix,  the  Carriage  Return  character  is  omitted,  as  customary  in  Unix
                environments.



                                                                                1430

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   If an error occurs, a run-time error is generated.  This behavior can be controlled with the
                {$I} switch.

    See also:    Write (1430   ), Read (1386   ), Readln (1388   ), Blockwrite (1294   )


                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___.____________________________________________________________________________________________________________*
 *___________



                37.10.419            WriteStr

    Synopsis:    Write variables to a string

Declaration:     procedure  WriteStr(out  S:  string;Args:  Arguments)

    Visibility:   default

Description:     WriteStr behaves like Write (1430   ), 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 (1430   ).

    See also:    Write (1430   ), ReadStr (1388   ), Read (1386   )



                                                                                1431

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.11            IDispatch



                37.11.1          Description

                IDispatch is the pascal definition of the Windows Dispatch interface definition.


    See also:    IUnknown (1435   )



                37.11.2          Method  overview

                __Page______Property______________________Description______________________________________________________________*
 *___________
                  1432      GetIDsOfNames                 Return IDs of named procedures
                  1432      GetTypeInfo                   Return type information about properties
                  1432      GetTypeInfoCount              Return number of properties.
                __1432______Invoke________________________Invoke_a_dispatch_method_________________________________________________*
 *___________



                37.11.3          IDispatch.GetTypeInfoCount

    Synopsis:    Return number of properties.

Declaration:     function  GetTypeInfoCount(out  count:  LongInt)  :  HRESULT

    Visibility:   default



                37.11.4          IDispatch.GetTypeInfo

    Synopsis:    Return type information about properties

Declaration:     function  GetTypeInfo(Index:  LongInt;LocaleID:  LongInt;out  TypeInfo)
                                                   :  HRESULT

    Visibility:   default



                37.11.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.



                37.11.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



                                                                                1432

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.12            IEnumerable



                37.12.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 (1433   ).


    See also:    IEnumerator (1433   )



                37.12.2          Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                __1433______GetEnumerator_____________Return_an_enumerator_interface_for_this_class________________________________*
 *___________



                37.12.3          IEnumerable.GetEnumerator

    Synopsis:    Return an enumerator interface for this class

Declaration:     function  GetEnumerator  :  IEnumerator

    Visibility:   default

Description:     GetEnumerator  returns  a  new  IEnumerator  (1433   )  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 (1433   )



                37.13            IEnumerator



                37.13.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.



                                                                                1433

                __________________________________________________________CHAPTER_37.___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 (1433   )



                37.13.2          Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  1434      GetCurrent          Returns the current element in the iteration cycle
                  1434      MoveNext            Move to the next value
                __1435______Reset_______________Reset_the_pointer__________________________________________________________________*
 *___________



                37.13.3          Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __1435______Current_________r____________Return_the_current_item___________________________________________________*
 *___________



                37.13.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  immediatly  after  IEnumerator.MoveNext  (1 )
                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 (1 ), IEnumerator.Reset (1 )



                37.13.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 (1 )
                will be called to retrieve the item.

    See also:    IEnumerator.Reset (1 ), IEnumerator.GetCurrent (1 )



                                                                                1434

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.13.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 (1 ), IEnumerator.MoveNext (1 )



                37.13.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 (1 ) as a property.  It is read-
                only.

    See also:    IEnumerator.GetCurrent (1 ), IEnumerator.MoveNext (1 )



                37.14            IInvokable



                37.14.1          Description

                IInvokable is a descendent of IInterface (1258   ), compiled in the {$M+} state, so Run-Time
                Type Information (RTTI) is generated for it.


    See also:    IDispatch (1432   ), IInterface (1258   )



                37.15            IUnknown



                37.15.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 (1258   ), IDispatch (1432   ), IInvokable (1435   )



                37.15.2          Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  1436      \_AddRef                 Increase reference count of the interface
                  1436      \_Release                Decrease reference count of the interface
                __1436______QueryInterface___________Return_pointer_to_VMT_table_of_interface______________________________________*
 *___________



                                                                                1435

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.15.3          IUnknown.QueryInterface

    Synopsis:    Return pointer to VMT table of interface

Declaration:     function  QueryInterface(const  iid:  TGuid;out  obj)  :  LongInt

    Visibility:   default



                37.15.4          IUnknown.__AddRef

    Synopsis:    Increase reference count of the interface

Declaration:     function  _AddRef  :  LongInt

    Visibility:   default

    See also:    IUnknown._Release (1 )



                37.15.5          IUnknown.__Release

    Synopsis:    Decrease reference count of the interface

Declaration:     function  _Release  :  LongInt

    Visibility:   default

    See also:    IUnknown._AddRef (1 )



                37.16            TAggregatedOb ject



                37.16.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 (1 ) 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 (1 ), Controller (1 )



                37.16.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __1437______Create__________Create_a_new_instance_of__TAggregatedObject____________________________________________*
 *___________



                37.16.3          Property  overview

                __Page______Property__________Access_______Description_____________________________________________________________*
 *___________
                __1437______Controller________r____________Controlling_instance____________________________________________________*
 *___________



                                                                                1436

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.16.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 (1 ) 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 (1 )



                37.16.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 (1 )



                37.17            TContainedOb ject



                37.17.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 (1258   )



                37.17.2          Interfaces  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                __1258______IInterface_______Basic_interface_for_all_COM_based_interfaces__________________________________________*
 *___________



                37.18            TInterfacedOb ject



                37.18.1          Description

                TInterfacedObject  is  a  descendent  of  TObject  (1439   )  which  implements  the  IUnknown
                (1435   ) interface.  It can be used as a base class for all classes which need reference counting.


    See also:    IUnknown (1435   ), TObject (1439   )



                                                                                1437

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.18.2          Interfaces  overview

                __Page______Property__________Description__________________________________________________________________________*
 *___________
                __1435______IUnknown__________Basic_interface_for_all_COM-based_interfaces_________________________________________*
 *___________



                37.18.3          Method  overview

                __Page______Property_____________________Description_______________________________________________________________*
 *___________
                  1438      AfterConstruction            Handle reference count properly.
                  1438      BeforeDestruction            Check reference count.
                __1438______NewInstance__________________Create_a_new_instance_____________________________________________________*
 *___________



                37.18.4          Property  overview

                __Page______Property_________Access_______Description______________________________________________________________*
 *___________
                __1439______RefCount_________r____________Return_the_current_reference_count_______________________________________*
 *___________



                37.18.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 (1 )



                37.18.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 (1 )



                37.18.7          TInterfacedObject.NewInstance

    Synopsis:    Create a new instance

Declaration:     class  function  NewInstance;    Override

    Visibility:   public

Description:     NewInstance initializes a new instance of TInterfacedObject (1437   )

       Errors:   None.



                                                                                1438

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.18.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 (1435   ).  When it reaches zero, the class instance
                is destroyed.

    See also:    IUnknown (1435   )



                37.19            TOb ject



                37.19.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 (1267   )



                                                                                1439

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.19.2          Method  overview

                __Page______Property_____________________________Description_______________________________________________________*
 *___________
                  1445      AfterConstruction                    Method called after the constructor was called.
                  1446      BeforeDestruction                    Method called before the destructor is called.
                  1443      ClassInfo                            Return a pointer to the type information for this class.
                  1443      ClassName                            Return the current class name.
                  1443      ClassNameIs                          Check whether the class name equals the given name.
                  1444      ClassParent                          Return the parent class.
                  1443      ClassType                            Return a "class of" pointer for the current class
                  1442      CleanupInstance                      Finalize the class instance.
                  1440      Create                               TObject Constructor
                  1442      DefaultHandler                       Default handler for integer message handlers.
                  1446      DefaultHandlerStr                    Default handler for string messages.
                  1441      Destroy                              TObject destructor.
                  1446      Dispatch                             Dispatch an integer message
                  1446      DispatchStr                          Dispatch a string message.
                  1449      Equals                               Check if two objects are equal.
                  1445      FieldAddress                         Return the address of a field.
                  1442      Free                                 Check for Nil and call destructor.
                  1441      FreeInstance                         Clean up instance and free the memory reserved for the
                                                                 instance.
                  1449      GetHashCode                          Return a hash code for the object
                  1447      GetInterface                         Return a reference to an interface
                  1447      GetInterfaceByStr                    Return an interface based on its GUID
                  1448      GetInterfaceEntry                    Return the interface table entry by GUID
                  1448      GetInterfaceEntryByStr               Return the interface table entry by string
                  1448      GetInterfaceTable                    Return a pointer to the table of implemented interfaces
                                                                 for a class
                  1447      GetInterfaceWeak                     Get a reference to an interface, not increasing the ref-
                                                                 erence count
                  1444      InheritsFrom                         Check whether class is an ancestor.
                  1442      InitInstance                         Initialize a new class instance.
                  1444      InstanceSize                         Return the size of an instance.
                  1445      MethodAddress                        Return the address of a method
                  1445      MethodName                           Return the name of a method.
                  1441      newinstance                          Allocate memory on the heap for a new instance
                  1441      SafeCallException                    Handle exception object
                  1444      StringMessageTable                   Return a pointer to the string message table.
                  1449      ToString                             Return a string representation for the object
                __1448______UnitName_____________________________Unit_name_________________________________________________________*
 *___________



                37.19.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 (1 )



                                                                                1440

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.19.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  (1 )
                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
                (1546   ) function.

    See also:    Create (1 ), Free (1 )



                37.19.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 (1 ).  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 (1 ), InitInstance (1 ), InstanceSize (1 ), FreeInstance (1 )



                37.19.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 (1 ), InitInstance (1 ), NewInstance (1 )



                37.19.7          TObject.SafeCallException

    Synopsis:    Handle exception object

Declaration:     function  SafeCallException(exceptobject:  TObject;exceptaddr:  pointer)
                                                             :  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.



                                                                                1441

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.19.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 (1 ) method.

    See also:    Dispatch (1 ), DefaultHandlerStr (1 )



                37.19.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 (1 ) 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 (1546   ) should be called.

       Errors:   None.

    See also:    Destroy (1 ), FreeAndNil (1546   )



                37.19.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 (1 ), Create (1 )



                37.19.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 (1 ), Free (1 ), InitInstance (1 )



                                                                                1442

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.19.12           TObject.ClassType

    Synopsis:    Return a "class of" pointer for the current class

Declaration:     class  function  ClassType

    Visibility:   public

Description:     ClassType returns a TClass (1267   ) class type reference for the current class.

    See also:    TClass (1267   ), ClassInfo (1 ), ClassName (1 )



                37.19.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.



                37.19.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 (1 ) class method.

       Errors:   None.

    See also:    ClassInfo (1 ), ClassType (1 ), ClassNameIs (1 )



                37.19.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 (1 ), ClassType (1 ), ClassName (1 )



                                                                                1443

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.19.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 (1 ), ClassType (1 ), ClassNameIs (1 )



                37.19.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 (1 ), ClassName (1 ), ClassInfo (1 ), ClassType (1 )



                37.19.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 (1 ), ClassInfo (1 ), ClassType (1 ), TClass (1267   )



                37.19.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 (1 ) method.

       Errors:   If there are no string message handlers, nil is returned.

    See also:    DispatchStr (1 ), Dispatch (1 )



                                                                                1444

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.19.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 (1 ), FieldAddress (1 )



                37.19.21           TObject.MethodName

    Synopsis:    Return the name of a method.

Declaration:     class  function  MethodName(address:  pointer)

    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 (1 ), FieldAddress (1 )



                37.19.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 (1 ), MethodName (1 )



                37.19.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 (1 ), Create (1 )



                                                                                1445

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.19.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 (1 ), Destroy (1 ), Free (1 )



                37.19.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 (1 ), Dispatch (1 ), DefaultHandler (1 )



                37.19.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 (1 )
                method, which can be overridden by descendent classes to add custom handling of messages.

    See also:    DispatchStr (1 ), DefaultHandler (1 )



                37.19.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 (1 ) is called.



                                                                                1446

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



       Errors:   None.

    See also:    DefaultHandlerStr (1 ), Dispatch (1 ), DefaultHandler (1 )



                37.19.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:   default

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 (1 )



                37.19.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 (1 ), TObject.GetInterfaceEntryByStr (1 )



                37.19.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 (1 ), but unlike the latter, it
                will not increase the reference count of the interface.

    See also:    TObject.GetInterface (1 )



                                                                                1447

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.19.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 (1 ), TObject.GetInterfaceEntryByStr (1 )



                37.19.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 (1 ), TObject.GetInterfaceEntry (1 )



                37.19.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 (1 ), TObject.GetInterfaceEntry (1 )



                37.19.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.



                                                                                1448

                __________________________________________________________CHAPTER_37.___REFERENCE_FOR_UNIT_'SYSTEM'________________*
 *___________________



                37.19.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 (1 ), TObject.ToString (1 )



                37.19.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 (1 ), TObject.Equals (1 )



                37.19.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 (1 ), TObject.Equals (1 )



                                                                                1449




Chapter   38



Reference   for   unit   'sysutils'



38.1          Used  units



                                    Table 38.1:  Used units by unit 'sysutils'


                                                  __Name____________Page_____
                                                    errors                1
                                                    sysconst              1
                                                    System           1230
                                                    Unix             1677
                                                    Unixtype         1715



38.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.



38.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.



                                                            1450

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



38.4          Miscellaneous  conversion  routines


Functions for various conversions.



                                                       Table 38.2:

              __Name_____________________________Description____________________________________________________
                BCDToInt (1492   )               Convert BCD number to integer
                CompareMem (1495   )             Compare two memory regions
                FloatToStrF (1532   )            Convert float to formatted string
                FloatToStr (1531   )             Convert float to string
                FloatToText (1534   )            Convert float to string
                FormatFloat (1544   )            Format a floating point value
                GetDirs (1548   )                Split string in list of directories
                IntToHex (1555   )               return hexadecimal representation of integer
                IntToStr (1555   )               return decumal representation of integer
                StrToIntDef (1587   )            Convert string to integer with default value
                StrToInt (1586   )               Convert string to integer
                StrToFloat (1585   )             Convert string to float
                TextToFloat (1591   )            Convert null-terminated string to float



38.5          Date/time  routines


Functions for date and time handling.



                                                                1451

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                                                       Table 38.3:

    _Name____________________________________________Description____________________________________________________________
      DateTimeToFileDate (1501   )                    Convert DateTime type to file date
      DateTimeToStr (1501   )                         Construct string representation of DateTime
      DateTimeToString (1502   )                      Construct string representation of DateTime
      DateTimeToSystemTime (1503   )                  Convert DateTime to system time
      DateTimeToTimeStamp (1503   )                   Convert DateTime to timestamp
      DateToStr (1504   )                             Construct string representation of date
      Date (1500   )                                  Get current date
      DayOfWeek (1504   )                             Get day of week
      DecodeDate (1505   )                            Decode DateTime to year month and day
      DecodeTime (1506   )                            Decode DateTime to hours, minutes and seconds
      EncodeDate (1509   )                            Encode year, day and month to DateTime
      EncodeTime (1510   )                            Encode hours, minutes and seconds to DateTime
      FormatDateTime (1544   )                        Return string representation of DateTime
      IncMonth (1554   )                              Add 1 to month
      IsLeapYear (1556   )                            Determine if year is leap year
      MSecsToTimeStamp (1560   )                      Convert nr of milliseconds to timestamp
      Now (1561   )                                   Get current date and time
      StrToDateTime (1583   )                         Convert string to DateTime
      StrToDate (1582   )                             Convert string to date
      StrToTime (1588   )                             Convert string to time
      SystemTimeToDateTime (1591   )                  Convert system time to datetime
      TimeStampToDateTime (1593   )                   Convert time stamp to DateTime
      TimeStampToMSecs (1594   )                      Convert Timestamp to number of millicseconds
      TimeToStr (1594   )                             return string representation of Time
      Time (1592   )                                  Get current tyme



38.6          FileName  handling  routines


Functions for file manipulation.



                                                                1452

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                                                       Table 38.4:

       __Name____________________________________________Description____________________________________________________
         AnsiCompareFileName (1478   )                   Compare 2 filenames
         AnsiLowerCaseFileName (1482   )                 Create lowercase filename
         AnsiUpperCaseFileName (1490   )                 Create uppercase filename
         AddDisk (1476   )                               Add disk to list of disk drives
         ChangeFileExt (1494   )                         Change extension of file name
         CreateDir (1498   )                             Create a directory
         DeleteFile (1506   )                            Delete a file
         DiskFree (1507   )                              Free space on disk
         DiskSize (1508   )                              Total size of disk
         ExpandFileName (1514   )                        Create full file name
         ExpandUNCFileName (1515   )                     Create full UNC file name
         ExtractFileDir (1515   )                        Extract drive and directory part of filename
         ExtractFileDrive (1516   )                      Extract drive part of filename
         ExtractFileExt (1516   )                        Extract extension part of filename
         ExtractFileName (1516   )                       Extract name part of filename
         ExtractFilePath (1517   )                       Extrct path part of filename
         ExtractRelativePath (1517   )                   Construct relative path between two files
         FileAge (1518   )                               Return file age
         FileDateToDateTime (1520   )                    Convert file date to system date
         FileExists (1520   )                            Determine whether a file exists on disk
         FileGetAttr (1521   )                           Get attributes of file
         FileGetDate (1522   )                           Get date of last file modification
         FileSearch (1524   )                            Search for file in path
         FileSetAttr (1526   )                           Get file attributes
         FileSetDate (1526   )                           Get file dates
         FindFirst (1528   )                             Start finding a file
         FindNext (1529   )                              Find next file
         GetCurrentDir (1547   )                         Return current working directory
         RemoveDir (1562   )                             Remove a directory from disk
         RenameFile (1562   )                            Rename a file on disk
         SameFileName (1564   )                          Check whether 2 filenames are the same
         SetCurrentDir (1565   )                         Set current working directory
         SetDirSeparators (1565   )                      Set directory separator characters
         FindClose (1527   )                             Stop searching a file
         DoDirSeparators (1509   )                       Replace directory separator characters



38.7          File  input/output  routines


Functions for reading/writing to file.



                                                                1453

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                                                       Table 38.5:

                        __Name___________________________Description__________________________________
                          FileCreate (1519   )           Create a file and return handle
                          FileOpen (1523   )             Open file end return handle
                          FileRead (1524   )             Read from file
                          FileSeek (1525   )             Set file position
                          FileTruncate (1527   )         Truncate file length
                          FileWrite (1527   )            Write to file
                          FileClose (1518   )            Close file handle



38.8          PChar  related  functions


Most PChar functions are the same as their counterparts in the STRINGS unit.  The following
functions are the same :


    1.  StrCat (1568   ) :  Concatenates two PChar strings.

    2.  StrComp (1569   ) :  Compares two PChar strings.

    3.  StrCopy (1569   ) :  Copies a PChar string.

    4.  StrECopy (1570   ) :  Copies a PChar string and returns a pointer to the terminating null
        byte.

    5.  StrEnd (1571   ) :  Returns a pointer to the terminating null byte.

    6.  StrIComp (1572   ) :  Case insensitive compare of 2 PChar strings.

    7.  StrLCat (1573   ) :  Appends at most L characters from one PChar to another PChar.

    8.  StrLComp (1574   ) :  Case sensitive compare of at most L characters of 2 PChar strings.

    9.  StrLCopy (1575   ) :  Copies at most L characters from one PChar to another.

   10.  StrLen (1575   ) :  Returns the length (exclusive terminating null byte) of a PChar string.

   11.  StrLIComp  (1576   )  :   Case  insensitive  compare  of  at  most  L  characters  of  2  PChar
        strings.

   12.  StrLower (1577   ) :  Converts a PChar to all lowercase letters.

   13.  StrMove (1577   ) :  Moves one PChar to another.

   14.  StrNew (1578   ) :  Makes a copy of a PChar on the heap, and returns a pointer to this
        copy.

   15.  StrPos (1580   ) :  Returns the position of one PChar string in another?

   16.  StrRScan (1580   ) :  returns a pointer to the last occurrence of on PChar string in another
        one.

   17.  StrScan (1580   ) :  returns a pointer to the first occurrence of on PChar string in another
        one.

   18.  StrUpper (1590   ) :  Converts a PChar to all uppercase letters.


The  subsequent  functions  are  different  from  their  counterparts  in  STRINGS,  although  the
same examples can be used.



                                                                1454

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



38.9          Date  and  time  formatting  characters


Various date and time formatting routines accept a format string.  to format the date and
or time.  The following characters can be used to control the date and time formatting:


c  shortdateformat + ' ' + longtimeformat

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

z  milliseconds



                                                                1455

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



38.10            Formatting  strings


Functions for formatting strings.



                                                       Table 38.6:

           __Name__________________________________Description_____________________________________________________
             AdjustLineBreaks (1477   )            Convert line breaks to line breaks for system
             FormatBuf (1543   )                   Format a buffer
             Format (1536   )                      Format arguments in string
             FmtStr (1535   )                      Format buffer
             QuotedStr (1561   )                   Quote a string
             StrFmt (1571   )                      Format arguments in a string
             StrLFmt (1576   )                     Format maximum L characters in a string
             TrimLeft (1595   )                    Remove whitespace at the left of a string
             TrimRight (1596   )                   Remove whitespace at the right of a string
             Trim (1594   )                        Remove whitespace at both ends of a string



38.11            String  functions


Functions for handling strings.



                                                                1456

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                                                       Table 38.7:

      __Name________________________________________Description__________________________________________________________
        AnsiCompareStr (1478   )                     Compare two strings
        AnsiCompareText (1479   )                    Compare two strings, case insensitive
        AnsiExtractQuotedStr (1480   )               Removes quotes from string
        AnsiLastChar (1481   )                       Get last character of string
        AnsiLowerCase (1482   )                      Convert string to all-lowercase
        AnsiQuotedStr (1483   )                      Qoutes a string
        AnsiStrComp (1484   )                        Compare strings case-sensitive
        AnsiStrIComp (1484   )                       Compare strings case-insensitive
        AnsiStrLComp (1486   )                       Compare L characters of strings case sensitive
        AnsiStrLIComp (1487   )                      Compare L characters of strings case insensitive
        AnsiStrLastChar (1485   )                    Get last character of string
        AnsiStrLower (1488   )                       Convert string to all-lowercase
        AnsiStrUpper (1489   )                       Convert string to all-uppercase
        AnsiUpperCase (1490   )                      Convert string to all-uppercase
        AppendStr (1491   )                          Append 2 strings
        AssignStr (1492   )                          Assign value of strings on heap
        CompareStr (1496   )                         Compare two strings case sensitive
        CompareText (1497   )                        Compare two strings case insensitive
        DisposeStr (1508   )                         Remove string from heap
        IsValidIdent (1557   )                       Is string a valid pascal identifier
        LastDelimiter (1558   )                      Last occurance of character in a string
        LeftStr (1558   )                            Get first N characters of a string
        LoadStr (1559   )                            Load string from resources
        LowerCase (1559   )                          Convert string to all-lowercase
        NewStr (1560   )                             Allocate new string on heap
        RightStr (1563   )                           Get last N characters of a string
        StrAlloc (1567   )                           Allocate memory for string
        StrBufSize (1567   )                         Reserve memory for a string
        StrDispose (1570   )                         Remove string from heap
        StrPas (1579   )                             Convert PChar to pascal string
        StrPCopy (1579   )                           Copy pascal string
        StrPLCopy (1579   )                          Copy N bytes of pascal string
        UpperCase (1601   )                          Convert string to all-uppercase



38.12            Constants,  types  and  variables



38.12.1          Constants

ConfigExtension  :  string  =  '.cfg'


ConfigExtension is the default extension used by the GetAppConfigFile (1547   ) 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



                                                                1457

_______________________________________________________CHAPTER_38.___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 (1528   ) call to find all matching files.


faArchive  =  $00000020


Attribute of a file, meaning the file has the archive bit set.  Used in TSearchRec (1470   ) and
FindFirst (1528   )


faDirectory  =  $00000010


Attribute of a file, meaning the file is a directory.  Used in TSearchRec (1470   ) and FindFirst
(1528   )


faHidden  =  $00000002


Attribute of a file, meaning the file is read-only.  Used in TSearchRec (1470   ) and FindFirst
(1528   )


faReadOnly  =  $00000001


Attribute of a file, meaning the file is read-only.  Used in TSearchRec (1470   ) and FindFirst
(1528   )


faSymLink  =  $00000040


faSymLink  means  the  file  (as  returned  e.g.   by  FindFirst  (1528   )/FindNext  (1529   )),  is  a
symlink.  It's ignored under Windows.


faSysFile  =  $00000004


Attribute of a file, meaning the file is a system file.  Used in TSearchRec (1470   ) and FindFirst
(1528   )


faVolumeId  =  $00000008


Attribute of a file, meaning the entry contains the volume ID. Used in TSearchRec (1470   )
and FindFirst (1528   )


feInvalidHandle  :  THandle  =  (-1)



                                                                1458

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



feInvalidHandle is the return value of FileOpen (1523   ) in case of an error.


filerecnamelength  =  255


filerecnamelength describes the length of the FileRec (1464   ) filename field.


fmOpenRead  =  $0000


fmOpenRead is used in the FileOpen (1523   ) call to open a file in read-only mode.


fmOpenReadWrite  =  $0002


fmOpenReadWrite is used in the FileOpen (1523   ) call to open a file in read-write mode.


fmOpenWrite  =  $0001


fmOpenWrite is used in the FileOpen (1523   ) call to open a file in write-only mode.


fmShareCompat  =  $0000


fmOpenShareCompat is used in the FileOpen (1523   ) call OR-ed together with one of fmOpen-
ReadWrite (1459   ), fmOpenRead (1459   ) or fmOpenWrite (1459   ),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 (1523   ) call OR-ed together with one of fmOpen-
ReadWrite  (1459   ),  fmOpenRead  (1459   )  or  fmOpenWrite  (1459   ),  to  open  a  file  so  other
processes can read/write the file as well.


fmShareDenyRead  =  $0030


fmOpenShareRead is used in the FileOpen (1523   ) call OR-ed together with one of fmOpen-
ReadWrite  (1459   ),  fmOpenRead  (1459   )  or  fmOpenWrite  (1459   ),  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 (1523   ) call OR-ed together with one of fmOpen-
ReadWrite  (1459   ),  fmOpenRead  (1459   )  or  fmOpenWrite  (1459   ),  to  open  a  file  so  other
processes cannot write to it, they can only read.


fmShareExclusive  =  $0010


fmOpenShareExclusive  is  used  in  the  FileOpen  (1523   )  call  OR-ed  together  with  one  of
fmOpenReadWrite (1459   ),  fmOpenRead (1459   ) or fmOpenWrite (1459   ),  to open a file ex-
clusively.


fsFromBeginning  =  0



                                                                1459

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



fsFromBeginning is used to indicate in the FileSeek (1525   ) call that a seek operation should
be started at the start of the file.


fsFromCurrent  =  1


fsFromBeginning is used to indicate in the FileSeek (1525   ) 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 (1525   ) 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



                                                                1460

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



MinDateTime  :  TDateTime  =  -693593.0


Minimum TDateTime value.


MinsPerDay  =  HoursPerDay  *  MinsPerHour


Number of minutes per day.


MinsPerHour  =  60


Number of minutes per hour.


MonthDays  :  Array[Boolean]  of  TDayTable  =  ((31,  28,  31,  30,  31,  30,  31,  31,  30,  31,  30,  31),  (31,  29,  31,  30, *
 * 31,  30,  31,@


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



                                                                1461

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



Package is an executable


pfIgnoreDupUnits  =  $00000008


Ignore duplicate units in package


pfLibraryModule  =  $80000000


Package is a library


pfModuleTypeMask  =  $C0000000


Mask for module type flags


pfNeverBuild  =  $00000001


Never-build flag was specified when compiling package


pfPackageModule  =  $40000000


Package is a real package (not exe)


pfProducerMask  =  $0C000000


Mask for producer flags


pfProducerUndefined  =  $04000000


Not used in Free Pascal.


pfRunOnly  =  $00000004


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



                                                                1462

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



Illegal instruction signal number (Unix only)


RTL_SIGINT  =  0


INTERRUPT signal number (Unix only)


RTL_SIGLAST  =  RTL_SIGQUIT


Last signal number (Unix only)


RTL_SIGQUIT  =  5


QUIT signal number (Unix only)


RTL_SIGSEGV  =  2


Segmentation fault signal number (Unix only)


SecsPerDay  =  MinsPerDay  *  SecsPerMin


Number of seconds per day


SecsPerMin  =  60


Number of seconds per minute


SwitchChars  =  ['-']


The  characters  in  this  set  will  be  used  by  the  FindCmdLineSwitch  (1528   )  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 (1546   ) call on some systems.


TextRecBufSize  =  256


Buffer size of text file record.


TextRecNameLength  =  256


Length of text file record filename field


ufImplicitUnit  =  $10


Unit was implicitly imported into package (did not appear in package contains list)


ufMainUnit  =  $01



                                                                1463

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



Unit is the main unit of the package


ufOrgWeakUnit  =  $08


Unit is the original weak packaged unit


ufPackageUnit  =  $02


Unit is a packaged unit (appeared in package contains list)


ufWeakPackageUnit  =  ufPackageUnit  or  ufWeakUnit


Weak (original or not) packaged unit


ufWeakUnit  =  $04


Unit is a weak packaged unit


UnixDateDelta  =  (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)



38.12.2          Types

EHeapException  =  EHeapMemoryError


EHeapMemoryError is raised when an error occurs in the heap management routines.


ExceptClass  =  Class  of  Exception


ExceptClass is a Exception (1612   ) class reference.


FileRec  =  packed  record
    Handle  :  THandle;
    Mode  :  LongInt;
    RecSize  :  SizeInt;
    _private  :  Array[1..3*SizeOf(SizeInt)+5*SizeOf(pointer)]  of  Byte;
    UserData  :  Array[1..32]  of  Byte;
    name  :  Array[0..filerecnamelength]  of  Char;
end



FileRec describes a untyped file.  This record is made available so it can be used to implement
drivers for other than the normal file system file records.


Int128Rec  =  packed  record
end



                                                                1464

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



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
end



Int64Rec can be used to extract the parts of a Int64:  the high and low cardinal, or a zero-
based array of 4 words, or a zero based array of 8 bytes.  Note that the meaning of the High
and Low parts are different on various CPUs.


LongRec  =  packed  record
end



LongRec can be used to extract the parts of an long Integer:  the high and low word, or the 4
separate bytes as a zero-based array of bytes.  Note that the meaning of High and Low parts
are different on various CPUs.


OWordRec  =  packed  record
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 (1466   ).  Use to access memory regions as a byte array.


PDayTable  =  ^TDayTable


Pointer to TDayTable type.


PString  =  ^


Pointer to a ansistring


PSysCharSet  =  ^TSysCharSet


Pointer to TSysCharSet (1471   ) type.


PWordarray  =  ^TWordArray


Generic pointer to TWordArray (1471   ).  Use to access memory regions as a word array.


TBeepHandler  =  procedure


TBeepHandler is the prototype used by the OnBeep (1474   ) handler.  This in turn is called
by  the  Beep  (1493   )  call  to  actually  implement  the  beep  functionality.   The  call  takes  no
arguments.



                                                                1465

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



TByteArray  =  Array[0..32767]  of  Byte


TByteArray is a generic array definition, mostly for use as a base type of the PByteArray
(1465   ) type.


TCreateGUIDFunc  =  function(out  GUID:  TGuid)  :  Integer


TCreateGUIDFunc is the prototype for a GUID creation handler.  On return, the GUID argu-
ment should contain a new (unique) GUID. The return value of the function should be zero
for success, nonzero for failure.


TDayTable  =  Array[1..12]  of  Word


Array of day names.


TEventType  =  (etCustom,etInfo,etWarning,etError,etDebug)



                          Table 38.8:  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



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)


TExecuteFlags is a set of flags to influence the behaviour of the ExecuteProcess (1513   ) call.


TextBuf  =  Array[0..TextRecBufSize-1]  of  Char


TextBuf is the type for the default buffer in TextRec (1467   )


TextRec  =  packed  record
   Handle  :  THandle;
   Mode  :  LongInt;
   bufsize  :  SizeInt;
   _private  :  SizeInt;
   bufpos  :  SizeInt;



                                                                1466

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



   bufend  :  SizeInt;
   bufptr  :  ^TextBuf;
   openfunc  :  pointer;
   inoutfunc  :  pointer;
   flushfunc  :  pointer;
   closefunc  :  pointer;
   UserData  :  Array[1..32]  of  Byte;
   name  :  Array[0..textrecnamelength-1]  of  Char;
   LineEnd  :  TLineEndStr;
   buffer  :  TextBuf;
end



TextRec describes a text file.  This record is made available so it can be used to implement
drivers for other than the normal file system file records.

To implement a driver, an Assign procedure must be implemented, which fills in the various
fields  of  the  record.   Most  notably,  the  callback  functions  must  be  filled  in  appropriately.
After this, the normal file operations will handle all necessary calls to the various callbacks.


TFilename  =  String


TFileName is used in the TSearchRec (1470   ) definition.


TFileRec  =  FileRec


Alias for FileRec (1464   ) for Delphi compatibility.


TFileSearchOption  =  (sfoImplicitCurrentDir,sfoStripQuotes)



                     Table 38.9:  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  (1467   )  values,  used  in  the  FileSearch
(1524   ) call when searching for files.


TFloatFormat  =  (ffGeneral,ffExponent,ffFixed,ffNumber,ffCurrency)



                                                                1467

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



                        Table 38.10:  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
(1534   ) 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 (1530   ) function.


TFloatValue  =  (fvExtended,fvCurrency,fvSingle,fvReal,fvDouble,fvComp)



                         Table 38.11:  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 (1591   ) function.


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;



                                                                1468

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



   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  (1474   )  to  return  an  alternative
application name.


TGetTempDirEvent  =  function(Global:  Boolean)  :  string


Function prototype for OnGetTempDir (1474   ) handler.


TGetTempFileEvent  =  function(const  Dir:  string;const  Prefix:  string)
                                                 :  string


Function prototype for OnGetTempFile (1474   ) handler.


TGetVendorNameEvent  =  function  :  string


TGetVendorNameEvent is the function prototype for the OnGetVendorName (1474   ) callback,
used by the VendorName (1602   ) function.


THandle  =  System.THandle


THandle refers to the definition of THandle in the system unit, and is provided for backward
compatibility only.


TIntegerSet  =  Set  of


TIntegerSet is a generic integer subrange set definition whose size fits in a single integer.


TLineEndStr  =  string


TLineEndStr is used in the TextRec (1467   ) record to indicate the end-of-line sequence for a
text file.


TMbcsByteType  =  (mbSingleByte,mbLeadByte,mbTrailByte)



                                                                1469

               _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'__________________*
 *__________________



                                     Table 38.12:  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


               TMonthNameArray is used in the month long and short name arrays.


               TProcedure  =  procedure


               TProcedure is a general definition of a procedural callback.


               TReplaceFlags=  Set  of  (rfReplaceAll,rfIgnoreCase)


               TReplaceFlags determines the behaviour of the StringReplace (1573   ) function.


               TSearchRec  =  record
                  Time  :  LongInt;
                  Size  :  Int64;
                  Attr  :  LongInt;
                  Name  :  TFilename;
                  ExcludeAttr  :  LongInt;
                  FindHandle  :  Pointer;
                  Mode  :  TMode;
                  PathOnly  :  AnsiString;
               end



               TSearchRec  is  a  search  handle  description  record.   It  is  initialized  by  a  call  to  FindFirst
               (1528   ) and can be used to do subsequent calls to FindNext (1529   ).  It contains the result of
               these function calls.  It must be used to close the search sequence with a call to FindClose
               (1527   ).

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 38.13:  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.



                                                                               1470

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



TSysCharSet  =  Set  of  Char


Generic set of characters type.


TSysLocale  =  record
   DefaultLCID  :  Integer;
   PriLangID  :  Integer;
   SubLangID  :  Integer;
end



TSysLocale describes the current locale.  If Fareast or MBCS is True, then the current locale
uses a Multi-Byte Character Set.  If  MiddleEast or RightToLeft is True then words and
sentences are read from right to left.


TTerminateProc  =  function  :  Boolean


TTerminateProc is the procedural type which should be used when adding exit procedures.


TTextRec  =  TextRec


Alias for TextRec (1467   ) for Delphi compatibility.


TTimeStamp  =  record
   Time  :  Integer;
   Date  :  Integer;
end



TTimeStamp contains a timestamp, with the date and time parts specified as separate TDateTime
values.


TWeekNameArray  =  Array[1..7]  of


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
(1465   ) 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.



                                                                1471

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



38.12.3          Variables

CurrencyDecimals  :  Byte


CurrencyDecimals is the number of decimals to be used when formatting a currency.  It is
used by the float formatting routines.  The initialization routines of the SysUtils unit initialize
this string with a value conforming to the regional preferences of the user or system regional
default.


CurrencyFormat  :  Byte


CurrencyFormat is the default format string for positive currencies.  It is used by the float
formatting routines.  The initialization routines of the SysUtils unit initialize this string with
a value conforming to the regional preferences of the user or system regional default.


CurrencyString  :  string


CurrencyString is the currency symbol for the current locale.  It is used by the float for-
matting routines.  The initialization routines of the SysUtils unit initialize this string with a
value conforming to the regional preferences of the user or system regional default.


DateSeparator  :  Char


DateSeparator is the character used by various date/time conversion routines as the char-
acter that separates the day from the month and the month from the year in a date notation.
It  is  used  by  the  date  formatting  routines.  The  initialization  routines  of  the  SysUtils  unit
initialize this string with a value conforming to the regional preferences of the user or system
regional default.


DecimalSeparator  :  Char


DecimalSeparator is used to display the decimal symbol in floating point numbers or cur-
rencies.  It is used by the float formatting routines.  The initialization routines of the SysUtils
unit initialize this string with a value conforming to the regional preferences of the user or
system regional default.


DefaultFormatSettings  :  TFormatSettings  =  (CurrencyFormat:1;NegCurrFormat:5;ThousandSeparator:''',''';DecimalSeparator:'''.''';*
 *CurrencyDecima@


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


FalseBoolStrs contains the strings that will result in a False return value by StrToBool
(1581   ).


FormatSettings  :  TFormatSettings


FormatSettings is provided for Delphi compatibility, and refers to the DefaultFormatSet-
tings (1472   ) variable.



                                                                1472

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



ListSeparator  :  Char


ListSeparator is the character used in lists of values.  It is locale dependent.


LongDateFormat  :  string


LongDateFormat contains a template to format a date in a long format.  It is used by the
date formatting routines.  The initialization routines of the SysUtils unit initialize this string
with a value conforming to the regional preferences of the user or system regional default.


LongDayNames  :  TWeekNameArray


LongDayNames  is  an  array  with  the  full  names  of  days.  It  is  used  by  the  date  formatting
routines.  The  initialization  routines  of  the  SysUtils  unit  initialize  this  string  with  a  value
conforming to the regional preferences of the user or system regional default.


LongMonthNames  :  TMonthNameArray


LongMonthNames is an array with the full names of months.  It is used by the date formatting
routines.  The  initialization  routines  of  the  SysUtils  unit  initialize  this  string  with  a  value
conforming to the regional preferences of the user or system regional default.


LongTimeFormat  :  string


LongTimeFormat  contains  a  template  to  format  a  time  in  full  notation.  It  is  used  by  the
time formatting routines.  The initialization routines of the SysUtils unit initialize this string
with a value conforming to the regional preferences of the user or system regional default.


NegCurrFormat  :  Byte


CurrencyFormat is the default format string for negative currencies.  It is used by the float
formatting routines.  The initialization routines of the SysUtils unit initialize this string with
a value conforming to the regional preferences of the user or system regional default:


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



                                                                1473

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



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)

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 (1499   ) 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 (1546   ) and GetAppConfigFile
(1547   )  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 (1550   ) 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 (1551   )
function.  Note that the values for Prefix and Dir should be observed.


OnGetVendorName  :  TGetVendorNameEvent


OnGetVendorName  must  be  set  in  order  for  VendorName  (1602   )  to  return  a  value.  It  will
then  be  used  in  GetAppConfigDir  (1546   )  and  GetAppConfigFile  (1547   )  to  determine  the
configuration  directory.   Set  it  to  a  callback  that  returns  the  actual  vendor  name  for  the
application.



                                                                1474

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



OnShowException  :  procedure(Msg:  ShortString)


OnShowException is the callback that ShowException (1566   ) uses to display a message in
a GUI application.  For GUI applications, this variable should always be set.  Note that no
memory may be available when this callback is called, so the callback should already have
all resources it needs, when the callback is set.


ShortDateFormat  :  string


ShortDateFormat contains a template to format a date in a short format.  It is used by the
date formatting routines.  The initialization routines of the SysUtils unit initialize this string
with a value conforming to the regional preferences of the user or system regional default.


ShortDayNames  :  TWeekNameArray


ShortDayNames  is  an  array  with  the  abbreviated  names  of  days.   It  is  used  by  the  date
formatting routines.  The initialization routines of the SysUtils unit initialize this string with
a value conforming to the regional preferences of the user or system regional default.


ShortMonthNames  :  TMonthNameArray


ShortMonthNames is an array with the abbreviated names of months.  It is used by the date
formatting routines.  The initialization routines of the SysUtils unit initialize this string with
a value conforming to the regional preferences of the user or system regional default.


ShortTimeFormat  :  string


ShortTimeFormat contains a template to format a time in a short notation.  It is used by the
time formatting routines.  The initialization routines of the SysUtils unit initialize this string
with a value conforming to the regional preferences of the user or system regional default.


SysLocale  :  TSysLocale


SysLocale is initialized by the initialization code of the SysUtils unit.  For an explanation of
the fields, see TSysLocale (1471   )


ThousandSeparator  :  Char


ThousandSeparator  is  used  to  separate  groups  of  thousands  in  floating  point  numbers  or
currencies.   It  is  used  by  the  float  formatting  routines.   The  initialization  routines  of  the
SysUtils unit initialize this string with a value conforming to the regional preferences of the
user or system regional default.


TimeAMString  :  string


TimeAMString is used to display the AM symbol in the time formatting routines.  It is used
by  the  time  formatting  routines.   The  initialization  routines  of  the  SysUtils  unit  initialize
this string with a value conforming to the regional preferences of the user or system regional
default.


TimePMString  :  string



                                                                1475

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                TimePMString is used to display the PM symbol in the time formatting routines.  It is used
                by  the  time  formatting  routines.   The  initialization  routines  of  the  SysUtils  unit  initialize
                this string with a value conforming to the regional preferences of the user or system regional
                default.


                TimeSeparator  :  Char


                TimeSeparator  is  used  by  the  time  formatting  routines  to  separate  the  hours  from  the
                minutes and the minutes from the seconds.  It is used by the time formatting routines.  The
                initialization routines of the SysUtils unit initialize this string with a value conforming to the
                regional preferences of the user or system regional default.


                TrueBoolStrs  :  Array  of


                TrueBoolStrs  contains  the  strings  that  will  result  in  a  True  return  value  by  StrToBool
                (1581   ).


                TwoDigitYearCenturyWindow  :  Word


                Window to determine what century 2 digit years are in.



                38.13            Procedures  and  functions



                38.13.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.



                38.13.2          Abort

    Synopsis:    Abort program execution.

Declaration:     procedure  Abort

    Visibility:   default

Description:     Abort raises an EAbort (1605   ) exception.

    See also:    EAbort (1605   )



                38.13.3          AddDisk

    Synopsis:    Add a disk to the list of known disks (Unix only)

Declaration:     function  AddDisk(const  path:  string)  :  Byte



                                                                                1476

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    Visibility:  default

Description:     On Unix-like platforms both the DiskFree (1507   ) and DiskSize (1508   ) 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 (1507   ), DiskSize (1508   )



                38.13.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 (1471   ), CallTerminateProcs (1494   )



                38.13.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.

    See also:    AnsiCompareStr (1478   ), AnsiCompareText (1479   )


                Listing:  ./sysutex/ex48.pp



                                                                                1477

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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 (1478   ) or AnsiCompareText (1479   ) depending on whether FileNameCaseSensitive
                is True or False

       Errors:   None.

    See also:    AnsiCompareStr (1478   ), AnsiCompareText (1479   ), AnsiLowerCaseFileName (1482   )



                38.13.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.


                The  comparision  takes  into  account  Ansi  characters,  i.e.  it  takes  care  of  strange  accented
                characters.  Contrary to AnsiCompareText (1479   ), the comparision is case sensitive.

 Remark:         A widestring manager must be installed in order for this function to work correctly with
                various character sets.



                                                                                1478

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    AdjustLineBreaks (1477   ), AnsiCompareText (1479   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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.


                the  comparision  takes  into  account  Ansi  characters,  i.e.  it  takes  care  of  strange  accented
                characters.  Contrary to AnsiCompareStr (1478   ), 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.



                                                                                1479

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    AdjustLineBreaks (1477   ), AnsiCompareText (1479   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.9          AnsiDequotedStr

    Synopsis:

Declaration:     function  AnsiDequotedStr(const  S:  string;AQuote:  Char)  :  string

    Visibility:   default

Description:



                38.13.10           AnsiExtractQuotedStr

    Synopsis:    Removes the first quoted string from a string.

Declaration:     function  AnsiExtractQuotedStr(var  Src:  PChar;Quote:  Char)  :  string

    Visibility:   default

Description:     AnsiExtractQuotedStr returns the first quoted string in Src, and deletes the result from
                Src.  The resulting string has with Quote characters removed from the beginning and end
                of the string (if they are present), and double Quote characters replaced by a single Quote
                characters.  As such, it revereses the action of AnsiQuotedStr (1483   ).



                                                                                1480

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    AnsiQuotedStr (1483   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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 (1485   )


                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
                    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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1481

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.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 (1490   ), AnsiStrLower (1488   ), AnsiStrUpper (1489   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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 (1482   ), AnsiCompareFileName (1478   ), AnsiUpperCaseFileName (1490   )



                                                                                1482

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.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 (1488   ), AnsiStrScan (1489   ), AnsiStrRScan (1489   )



                38.13.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 (1480   ).

                For an example, see AnsiExtractQuotedStr (1480   )

       Errors:   None.

    See also:    AnsiExtractQuotedStr (1480   )



                38.13.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 (1478   ) 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 (1478   ), SameText (1565   ), AnsiSameText (1483   )



                38.13.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 (1479   ) with S1 and S2 as parameters and returns True if
                the result of that call is zero, or False otherwise.

    See also:    AnsiCompareText (1479   ), SameText (1565   ), AnsiSameStr (1483   )



                                                                                1483

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.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 (1479   ), AnsiCompareStr (1478   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.19           AnsiStrIComp

    Synopsis:    Compare two null-terminated strings.  Case insensitive.



                                                                                1484

                _______________________________________________________CHAPTER_38.___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 (1479   ), AnsiCompareStr (1478   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.20           AnsiStrLastChar

    Synopsis:    Return a pointer to the last character of a string.

Declaration:     function  AnsiStrLastChar(Str:  PChar)  :  PChar

    Visibility:   default



                                                                                1485

                _______________________________________________________CHAPTER_38.___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 (1479   ), AnsiCompareStr (1478   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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 (1484   ),  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 (1484   ), AnsiStrIComp (1484   ), AnsiStrLIComp (1487   )



                                                                                1486

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.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 (1479   ), AnsiCompareStr (1478   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1487

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.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 (1482   ).
                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 (1489   ), AnsiLowerCase (1482   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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 (1483   ), AnsiStrScan (1489   ), AnsiStrRScan (1489   )



                                                                                1488

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.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 (1483   ), AnsiStrScan (1489   ), AnsiStrPos (1488   )



                38.13.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 (1483   ), AnsiStrScan (1489   ), AnsiStrPos (1488   )



                38.13.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 (1490   ).
                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 (1490   ), AnsiStrLower (1488   ), AnsiLowerCase (1482   )


                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) ;



                                                                                1489

                _______________________________________________________CHAPTER_38.___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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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 (1489   ), AnsiStrLower (1488   ), AnsiLowerCase (1482   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.29           AnsiUpperCaseFileName

    Synopsis:    Convert filename to uppercase.

Declaration:     function  AnsiUpperCaseFileName(const  s:  string)  :  string

    Visibility:   default



                                                                                1490

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Description:     AnsiUpperCaseFileName simply returns the result of


                AnsiUpperCase(S);


    See also:    AnsiUpperCase (1490   ), AnsiCompareFileName (1478   ), AnsiLowerCaseFileName (1482   )



                38.13.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 (1492   ), NewStr (1560   ), DisposeStr (1508   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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 (1474   ) 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 (1546   ), OnGetApplicationName (1474   ), GetAppConfigFile (1547   ), Con-
                figExtension (1457   )



                                                                                1491

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.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 (1560   ), AppendStr (1491   ), DisposeStr (1508   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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 (1586   ), IntToStr (1555   )


                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



                                                                                1492

                _______________________________________________________CHAPTER_38.___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___.____________________________________________________________________________________________________________*
 *___________



                38.13.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
                (1474   ) callback.  The Sysutils unit itself contains no implementation of this call.



                38.13.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 (1581   )



                38.13.36           ByteToCharIndex

    Synopsis:    Convert a character index in Bytes to an Index in characters

Declaration:     function  ByteToCharIndex(const  S:  string;Index:  Integer)  :  Integer

    Visibility:   default

Description:     ByteToCharIndex returns the index (in characters) of the Index-th byte in S.

       Errors:   This function does not take into account MBCS yet.

    See also:    CharToByteLen (1495   ), ByteToCharLen (1494   )



                                                                                1493

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.37           ByteToCharLen

    Synopsis:    Convert a length in bytes to a length in characters.

Declaration:     function  ByteToCharLen(const  S:  string;MaxLen:  Integer)  :  Integer

    Visibility:   default

Description:     ByteToCharLen returns the number of bytes in S, but limits the result to MaxLen

       Errors:   This function does not take into account MBCS yet.

    See also:    CharToByteLen (1495   ), ByteToCharIndex (1493   )



                38.13.38           ByteType

    Synopsis:    Return the type of byte in an ansistring for a multi-byte character set

Declaration:     function  ByteType(const  S:  string;Index:  Integer)  :  TMbcsByteType

    Visibility:   default

Description:     ByteType returns the type of byte in the ansistring S at (1-based) position Index.

       Errors:   No checking on the index is performed.

    See also:    TMbcsByteType (1470   ), StrByteType (1568   )



                38.13.39           CallTerminateProcs

    Synopsis:    Call the exit chain procedures.

Declaration:     function  CallTerminateProcs  :  Boolean

    Visibility:   default

Description:     CallTerminateProcs  is  run  on  program  exit.   It  executes  all  terminate  procedures  that
                were added to the exit chain with AddTerminateProc (1477   ), 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 (1471   ), AddTerminateProc (1477   )



                38.13.40           ChangeFileExt

    Synopsis:    Change the extension of a filename.

Declaration:     function  ChangeFileExt(const  FileName:  string;const  Extension:  string)
                                                      :  string

    Visibility:   default

Description:     ChangeFileExt changes the file extension in FileName to Extension.  The extension Extension
                includes the starting .  (dot).  The previous extension of  FileName are all characters after
                the last ., the .  character included.

                If  FileName doesn't have an extension, Extension is just appended.

       Errors:   None.

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   ), ExpandFileName (1514   )



                                                                                1494

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.41           CharToByteLen

    Synopsis:    Convert a length in characters to a length in bytes.

Declaration:     function  CharToByteLen(const  S:  string;MaxLen:  Integer)  :  Integer

    Visibility:   default

Description:     CharToByteLen returns the number of bytes in S, but limits the result to MaxLen

       Errors:   This function does not take into account MBCS yet.

    See also:    ByteToCharLen (1494   ), ByteToCharIndex (1493   )



                38.13.42           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.

                It returns the following values:


                <0 if at some position the byte at P1 is less than the byte at the same postion at P2.

                0 if all L bytes are the same.

                >0  if at some position the byte at P1 is greater than the byte at the same postion at P2.



                38.13.43           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 (1565   )



                                                                                1495

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.44           CompareStr

    Synopsis:    Compare 2 ansistrings case-sensitively, ignoring special characters.

Declaration:     function  CompareStr(const  S1:  string;const  S2:  string)  :  Integer
                                                ;    Overload

    Visibility:   default

Description:     CompareStr compares two strings, S1 and S2, and returns the following result:


                <0 if  S1<S2.

                0 if  S1=S2.

                >0  if  S1>S2.


                The comparision of the two strings is case-sensitive.  The function does not take internation-
                alization settings into account, it simply compares ASCII values.

       Errors:   None.

    See also:    AnsiCompareText (1479   ), AnsiCompareStr (1478   ), CompareText (1497   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1496

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.45           CompareText

    Synopsis:    Compare 2 ansistrings case insensitive.

Declaration:     function  CompareText(const  S1:  string;const  S2:  string)  :  Integer

    Visibility:   default

Description:     CompareText compares two strings, S1 and S2, and returns the following result:


                <0 if  S1<S2.

                0 if  S1=S2.

                >0  if  S1>S2.


                The comparision of the two strings is case-insensitive.  The function does not take interna-
                tionalization settings into account, it simply compares ASCII values.

       Errors:   None.

    See also:    AnsiCompareText (1479   ), AnsiCompareStr (1478   ), CompareStr (1496   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.46           ComposeDateTime

    Synopsis:    Add a date and time

Declaration:     function  ComposeDateTime(Date:  TDateTime;Time:  TDateTime)  :  TDateTime



                                                                                1497

                _______________________________________________________CHAPTER_38.___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 (466  )



                38.13.47           ConcatPaths

    Synopsis:    Concatenate an array of paths to form a single path

Declaration:     function  ConcatPaths(const  Paths:  Array  of  )  :  string

    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  (1553   ),  IncludeLeadingPathDelimiter  (1553   ),  ExcludeTrail-
                ingPathDelimiter (1513   ), IncludeTrailingPathDelimiter (1553   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.48           CreateDir

    Synopsis:    Create a new directory

Declaration:     function  CreateDir(const  NewDir:  string)  :  Boolean

    Visibility:   default

Description:     CreateDir creates a new directory with name NewDir.  If the directory doesn't contain an
                absolute path, then the directory is created below the current working directory.

                The function returns True if the directory was successfully created, False otherwise.

       Errors:   In case of an error, the function returns False.

    See also:    RemoveDir (1562   )



                                                                                1498

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.49           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 (1551   ), IsEqualGUID (1556   ), StringToGUID (1573   ), TryStringToGUID (1597   ),
                GUIDToString (1552   )



                38.13.50           CurrentYear

    Synopsis:    Return the current year

Declaration:     function  CurrentYear  :  Word

    Visibility:   default

Description:     CurrentYear returns the current year as a 4-digit number.

       Errors:   None.

    See also:    Date (1500   ), Time (1592   ), Now (1561   )



                                                                                1499

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.51           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 (1532   ):


                FloatToStrF(Value,ffNumber,15,2);


       Errors:   None.

    See also:    FloatToStrF (1532   ), StrToCurr (1581   )



                38.13.52           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
                (1532   ).

    See also:    FloatToStrF (1532   )



                38.13.53           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 (1592   ), Now (1561   )


                Listing:  ./sysutex/ex1.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example1       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Date     f u n c t i o n }


                 u s e s  s y s u t i l;s



                                                                                1500

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.54           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 (1518   ) function.

       Errors:   None.

    See also:    Time  (1592   ),  Date  (1500   ),  FileDateToDateTime  (1520   ),  DateTimeToSystemTime  (1503   ),
                DateTimeToTimeStamp (1503   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.55           DateTimeToStr

    Synopsis:    Converts a TDateTime value to a string using a predefined format.

Declaration:     function  DateTimeToStr(DateTime:  TDateTime)  :  string
                function  DateTimeToStr(DateTime:  TDateTime;
                                                     const  FormatSettings:  TFormatSettings)  :  string

    Visibility:   default

Description:     DateTimeToStr returns a string representation of  DateTime using the formatting specified
                in LongDateTimeFormat.  It corresponds to a call to FormatDateTime('c',DateTime) (see
                formatchars (1455   )).

       Errors:   None.

    See also:    FormatDateTime (1544   )


                Listing:  ./sysutex/ex3.pp



                                                                                1501

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.56           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)
                procedure  DateTimeToString(out  Result:  string;const  FormatStr:  string;
                                                           const  DateTime:  TDateTime;
                                                           const  FormatSettings:  TFormatSettings)

    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 (1455   ).

       Errors:   In case a wrong formatting character is found, an EConvertError is raised.

    See also:    FormatDateTime (1544   ), formatchars (1455   )


                Listing:  ./sysutex/ex4.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example4       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e D a t e T i m e T o S t r i n gf u n c t i o n}


                Uses      s y s u t i l;s



                 P r o c e d u r et o d a y ( Fmt    :   s t r i n g) ;


                Var    S   :   A n s i S t r i n;g


                 b e g i n
                    DateTimeToString              (S , Fmt  , Date   ) ;
                    W r i t e l n (S  ) ;
                end   ;


                 P r o c e d u r eNow    (Fmt     :  s t r i n g) ;


                Var    S   :   A n s i S t r i n;g


                 b e g i n
                    DateTimeToString              (S , Fmt  , Time   ) ;
                    W r i t e l n (S  ) ;
                end   ;



                                                                                1502

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.57           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 (1501   ), SystemTimeToDateTime (1591   ), DateTimeToTimeStamp (1503   )


                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;
                       end   ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.58           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.



                                                                                1503

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    DateTimeToFileDate (1501   ), SystemTimeToDateTime (1591   ), DateTimeToSystemTime (1503   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.59           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 (1594   ), DateTimeToStr (1501   ), FormatDateTime (1544   ), StrToDate (1582   )


                Listing:  ./sysutex/ex7.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example7       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e D a t e T o S t r f u n c t i o n}


                Uses      s y s u t i l;s


                Begin
                    W r i t e l n(Format      ( ' Today     i s :  % s ' , [DateToStr      ( Date    ) ] ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.60           DayOfWeek

    Synopsis:    Returns the day of the week.

Declaration:     function  DayOfWeek(DateTime:  TDateTime)  :  Integer

    Visibility:   default



                                                                                1504

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1500   ), DateToStr (1504   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.61           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 (1509   ), DecodeTime (1506   )


                Listing:  ./sysutex/ex9.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       Example9       ;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e DecodeDate          f u n c t i o n}


                Uses      s y s u t i l;s


                Var    YY  ,MM  ,DD    :  Word    ;


                Begin
                    DecodeDate       ( Date   , YY  ,MM  ,DD  ) ;
                    W r i t e l n ( Format      ( 'Today      i s %  d/%  d/%  d ' , [dd  ,mm  , y y ] ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.62           DecodeDateFully

    Synopsis:    Decode a date with additional date of the week.



                                                                                1505

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1505   ), 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 (1509   ), TryEncodeDate (1596   ), DecodeDate (1505   )



                38.13.63           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 (1510   ), DecodeDate (1505   )


                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
                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.64           DeleteFile

    Synopsis:    Delete a file from the filesystem.

Declaration:     function  DeleteFile(const  FileName:  string)  :  Boolean

    Visibility:   default

Description:     DeleteFile  deletes  file  FileName  from  disk.   The  function  returns  True  if  the  file  was
                successfully removed, False otherwise.

       Errors:   On error, False is returned.

    See also:    FileCreate (1519   ), FileExists (1520   )



                                                                                1506

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.65           DirectoryExists

    Synopsis:    Check whether a directory exists in the file system.

Declaration:     function  DirectoryExists(const  Directory:  string)  :  Boolean

    Visibility:   default

Description:     DirectoryExists checks whether Directory exists in the filesystem and is actually a di-
                rectory.  If this is the case, the function returns True, otherwise False is returned.

    See also:    FileExists (1520   )



                38.13.66           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
                (1508   ) functions must be mimicked using filenames that reside on the partitions.  For more
                information, see AddDisk (1476   ).



                                                                                1507

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   On error, -1 is returned.

    See also:    DiskSize (1508   ), AddDisk (1476   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.67           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.

                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  (1507   )  and
                DiskSize  functions  must  be  mimicked  using  filenames  that  reside  on  the  partitions.   For
                more information, see AddDisk (1476   )

                For an example, see DiskFree (1507   ).

       Errors:   On error, -1 is returned.

    See also:    DiskFree (1507   ), AddDisk (1476   )



                38.13.68           DisposeStr

    Synopsis:    Dispose an ansistring from the heap.

Declaration:     procedure  DisposeStr(S:  PString);    Overload
                procedure  DisposeStr(S:  PShortString);    Overload

    Visibility:   default



                                                                                1508

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1508   ).

       Errors:   None.

    See also:    NewStr (1560   ), AppendStr (1491   ), AssignStr (1492   )



                38.13.69           DoDirSeparators

    Synopsis:    Convert known directory separators to the current directory separator.

Declaration:     procedure  DoDirSeparators(var  FileName:  string)

    Visibility:   default

Description:     This  function  replaces  all  known  directory  separators  in  FileName  to  the  directory  sep-
                arator  character  for  the  current  system.   The  list  of  known  separators  is  specified  in  the
                AllowDirectorySeparators (1234   ) constant.

       Errors:   None.

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   )


                Listing:  ./sysutex/ex32.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 3 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e D o D i r S e p a r a t o r sf u n c t i o n}
                { $H + }


                Uses      s y s u t i l;s


                 P r o c e d u r eT e s t i t ( F   :  S t r i n g) ;


                 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___.____________________________________________________________________________________________________________*
 *___________



                38.13.70           EncodeDate

    Synopsis:    Encode a Year,Month,Day to a TDateTime value.

Declaration:     function  EncodeDate(Year:  Word;Month:  Word;Day:  Word)  :  TDateTime

    Visibility:   default



                                                                                1509

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Description:     EncodeDate encodes the Year, Month and Day variables to a date in TDateTime format.  It
                does the opposite of the DecodeDate (1505   ) 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 (1606   ) exception
                is raised.

    See also:    EncodeTime (1510   ), DecodeDate (1505   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.71           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 (1506   ) 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 (1606   ) exception
                is raised.

    See also:    EncodeDate (1509   ), DecodeTime (1506   )


                Listing:  ./sysutex/ex12.pp



                                                                                1510

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.72           ExceptAddr

    Synopsis:    Current exception address.

Declaration:     function  ExceptAddr  :  Pointer

    Visibility:   default

Description:     ExceptAddr returns the address from the currently treated exception object when an ex-
                ception is raised, and the stack is unwound.

    See also:    ExceptObject (1512   ), ExceptionErrorMessage (1512   ), ShowException (1566   )



                38.13.73           ExceptFrameCount

    Synopsis:    Number of frames included in an exception backtrace

Declaration:     function  ExceptFrameCount  :  LongInt

    Visibility:   default

Description:     ExceptFrameCount returns the number of frames that are included in an exception stack
                frame  backtrace.  The  function  returns  0  if  there  is  currently  no  exception  being  handled.
                (i.e.  it only makes sense to call this function in an finally..end or except..end block.

       Errors:   None.

    See also:    ExceptFrames  (1511   ),  ExceptAddr  (1511   ),  ExceptObject  (1512   ),  #rtl.system.ExceptProc
                (1236   )



                38.13.74           ExceptFrames

    Synopsis:

Declaration:     function  ExceptFrames  :  PPointer

    Visibility:   default

Description:

    See also:    ExceptFrameCount (1511   ), ExceptAddr (1511   ), ExceptObject (1512   ), #rtl.system.ExceptProc
                (1236   )



                                                                                1511

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.75           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 (1612   ) object or not, and adapts
                the output accordingly.

    See also:    ExceptObject (1512   ), ExceptAddr (1511   ), ShowException (1566   )



                38.13.76           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 (1511   ), ExceptionErrorMessage (1512   ), ShowException (1566   )



                38.13.77           ExcludeLeadingPathDelimiter

    Synopsis:    Strip the leading path delimiter of a path

Declaration:     function  ExcludeLeadingPathDelimiter(const  Path:  string)  :  string

    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  (1553   ),  IncludeLeadingPathDelimiter  (1553   ),  ExcludeTrail-
                ingPathDelimiter (1513   ), ConcatPaths (1498   )


                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



                                                                                1512

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.78           ExcludeTrailingBackslash

    Synopsis:    Strip trailing directory separator from a pathname, if needed.

Declaration:     function  ExcludeTrailingBackslash(const  Path:  string)  :  string

    Visibility:   default

Description:     ExcludeTrailingBackslash is provided for backwards compatibility with Delphi.  Use Ex-
                cludeTrailingPathDelimiter (1513   ) instead.

    See also:    IncludeTrailingPathDelimiter (1553   ), ExcludeTrailingPathDelimiter (1513   ), PathDelim (1461   ),
                IsPathDelimiter (1557   )



                38.13.79           ExcludeTrailingPathDelimiter

    Synopsis:    Strip trailing directory separator from a pathname, if needed.

Declaration:     function  ExcludeTrailingPathDelimiter(const  Path:  string)  :  string

    Visibility:   default

Description:     ExcludeTrailingPathDelimiter removes the trailing path delimiter character (PathDelim
                (1461   )) from Path if it is present, and returns the result.

    See also:    ExcludeTrailingBackslash (1513   ), IncludeTrailingPathDelimiter (1553   ), PathDelim (1461   ),
                IsPathDelimiter (1557   )



                38.13.80           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 (1610   )
                exception will be raised.

    See also:    TExecuteFlags (1466   ), EOSError (1610   )



                                                                                1513

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.81           ExeSearch

    Synopsis:    Search for an executable

Declaration:     function  ExeSearch(const  Name:  string;const  DirList:  string)  :  string

    Visibility:   default

Description:     ExeSearch  searches  for  an  executable  Name  in  the  list  of  directories  DirList  (a  list  of
                directories, separator by PathSeparator (1247   ).  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 (1524   )



                38.13.82           ExpandFileName

    Synopsis:    Expand a relative filename to an absolute filename.

Declaration:     function  ExpandFileName(const  FileName:  string)  :  string

    Visibility:   default

Description:     ExpandFileName  expands  the  filename  to  an  absolute  filename.   It  changes  all  directory
                separator characters to the one appropriate for the system first.

       Errors:   None.

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   ), ExtractFileDir (1515   ), ExtractFileDrive
                (1516   ), ExtractFileExt (1516   ), ExtractRelativePath (1517   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1514

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.83           ExpandUNCFileName

    Synopsis:    Expand a relative filename to an absolute UNC filename.

Declaration:     function  ExpandUNCFileName(const  FileName:  string)  :  string

    Visibility:   default

Description:     ExpandUNCFileName runs ExpandFileName (1514   ) on FileName and then attempts to re-
                place the driveletter by the name of a shared disk.

       Errors:   None.

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   ), ExtractFileDir (1515   ), ExtractFileDrive
                (1516   ), ExtractFileExt (1516   ), ExtractRelativePath (1517   )



                38.13.84           ExtractFileDir

    Synopsis:    Extract the drive and directory part of a filename.

Declaration:     function  ExtractFileDir(const  FileName:  string)  :  string

    Visibility:   default

Description:     ExtractFileDir returns only the directory part of  FileName, including a driveletter.  The
                directory name has NO ending directory separator, in difference with ExtractFilePath (1517   ).

       Errors:   None.

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   ), ExtractFileDir (1515   ), ExtractFileDrive
                (1516   ), ExtractFileExt (1516   ), ExtractRelativePath (1517   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1515

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.85           ExtractFileDrive

    Synopsis:    Extract the drive part from a filename.

Declaration:     function  ExtractFileDrive(const  FileName:  string)  :  string

    Visibility:   default

Description:     Extracts the drive letter from a filename.  Note that some operating systems do not support
                drive letters.

                For an example, see ExtractFileDir (1515   ).

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   ), ExtractFileDir (1515   ), ExtractFileDrive
                (1516   ), ExtractFileExt (1516   ), ExtractRelativePath (1517   )



                38.13.86           ExtractFileExt

    Synopsis:    Return the extension from a filename.

Declaration:     function  ExtractFileExt(const  FileName:  string)  :  string

    Visibility:   default

Description:     ExtractFileExt returns the extension (including the .(dot) character) of  FileName.

                For an example, see ExtractFileDir (1515   ).

       Errors:   None.

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   ), ExtractFileDir (1515   ), ExtractFileDrive
                (1516   ), ExtractFileExt (1516   ), ExtractRelativePath (1517   )



                38.13.87           ExtractFileName

    Synopsis:    Extract the filename part from a full path filename.

Declaration:     function  ExtractFileName(const  FileName:  string)  :  string

    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
                (1517   ) and ExtractFileName.

                For an example, see ExtractFileDir (1515   ).

       Errors:   None.

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   ), ExtractFileDir (1515   ), ExtractFileDrive
                (1516   ), ExtractFileExt (1516   ), ExtractRelativePath (1517   )



                                                                                1516

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.88           ExtractFilePath

    Synopsis:    Extract the path from a filename.

Declaration:     function  ExtractFilePath(const  FileName:  string)  :  string

    Visibility:   default

Description:     ExtractFilePath returns the path part (including driveletter) from FileName.  The path
                consists of all characters before the last directory separator character ('/' or '\'), including
                the directory separator itself.  In case there is only a drive letter, that will be returned.

                The full filename can always be reconstucted by concatenating the result of ExtractFilePath
                and ExtractFileName (1516   ).

                For an example, see ExtractFileDir (1515   ).

       Errors:   None.

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   ), ExtractFileDir (1515   ), ExtractFileDrive
                (1516   ), ExtractFileExt (1516   ), ExtractRelativePath (1517   )



                38.13.89           ExtractRelativepath

    Synopsis:    Extract a relative path from a filename, given a base directory.

Declaration:     function  ExtractRelativepath(const  BaseName:  string;
                                                              const  DestNAme:  string)  :  string

    Visibility:   default

Description:     ExtractRelativePath  constructs  a  relative  path  to  go  from  BaseName  to  DestName.   If
                DestName  is  on  another  drive  (Not  on  Unix-like  platforms)  then  the  whole  Destname  is
                returned.  Note:  This function does not exist in the Delphi unit.

       Errors:   None.

    See also:    ExtractFileName (1516   ), ExtractFilePath (1517   ), ExtractFileDir (1515   ), ExtractFileDrive
                (1516   ), ExtractFileExt (1516   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1517

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.90           ExtractShortPathName

    Synopsis:    Returns a 8.3 path name

Declaration:     function  ExtractShortPathName(const  FileName:  string)  :  string

    Visibility:   default

Description:     ExtractShortPathName  returns  a  8.3  compliant  filename  that  represents  the  same  file  as
                FileName.  On platforms other than windows, this is FileName itself.

    See also:    ExtractFilePath (1517   ), ExtractFileName (1516   )



                38.13.91           FileAge

    Synopsis:    Return the timestamp of a file.

Declaration:     function  FileAge(const  FileName:  string)  :  LongInt

    Visibility:   default

Description:     FileAge returns the last modification time of file FileName.  The FileDate format can be
                transformed to TDateTime format with the FileDateToDateTime (1520   ) function.

       Errors:   In case of errors, -1 is returned.

    See also:    FileDateToDateTime (1520   ), FileExists (1520   ), FileGetAttr (1521   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.92           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 (1519   )



                                                                                1518

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    FileCreate (1519   ), FileWrite (1527   ), FileOpen (1523   ), FileRead (1524   ), FileTruncate (1527   ),
                FileSeek (1525   )



                38.13.93           FileCreate

    Synopsis:    Create a new file and return a handle to it.

Declaration:     function  FileCreate(const  FileName:  string)  :  THandle
                function  FileCreate(const  FileName:  string;Rights:  Integer)  :  THandle
                function  FileCreate(const  FileName:  string;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  (1524   )  and  FileWrite
                (1527   ) 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 -1.

    See also:    FileClose (1518   ), FileWrite (1527   ), FileOpen (1523   ), FileRead (1524   ), FileTruncate (1527   ),
                FileSeek (1525   )


                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



                                                                                1519

                _______________________________________________________CHAPTER_38.___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___.____________________________________________________________________________________________________________*
 *___________



                38.13.94           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 (1518   ) or FindFirst
                (1528   )/FindNext (1529   ) functions to TDateTime form.

       Errors:   None.

    See also:    DateTimeToFileDate (1501   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.95           FileExists

    Synopsis:    Check whether a particular file exists in the filesystem.

Declaration:     function  FileExists(const  FileName:  string)  :  Boolean

    Visibility:   default

Description:     FileExists returns True if a file with name FileName exists on the disk, False otherwise.
                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.



                                                                                1520

                _______________________________________________________CHAPTER_38.___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 (1528   ) function.

       Errors:   None.

    See also:    FindFirst (1528   ), FileAge (1518   ), FileGetAttr (1521   ), FileSetAttr (1526   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.96           FileGetAttr

    Synopsis:    Return attributes of a file.

Declaration:     function  FileGetAttr(const  FileName:  string)  :  LongInt

    Visibility:   default

Description:     FileGetAttr  returns  the  attribute  settings  of  file  FileName.   The  attribute  is  a  OR-ed
                combination of the following constants:


                faReadOnly         The file is read-only.

                faHidden       The file is hidden.  (On unix, this means that the filename starts with a dot)

                faSysFile     The file is a system file (On unix, this means that the file is a character, block or
                       FIFO file).

                faVolumeId        Volume Label.  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 (1526   ), FileAge (1518   ), FileGetDate (1522   )


                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;



                                                                                1521

                _______________________________________________________CHAPTER_38.___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___.____________________________________________________________________________________________________________*
 *___________



                38.13.97           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 (1518   ),  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 (1518   )


                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' ) ;
                    D := F i l e G e t D a t(eF ) ;



                                                                                1522

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.98           FileIsReadOnly

    Synopsis:    Check whether a file is read-only.

Declaration:     function  FileIsReadOnly(const  FileName:  string)  :  Boolean

    Visibility:   default

Description:     FileIsReadOnly checks whether FileName exists in the filesystem and is a read-only file.
                If this is the case, the function returns True, otherwise False is returned.

    See also:    FileExists (1520   )



                38.13.99           FileOpen

    Synopsis:    Open an existing file and return a filehandle

Declaration:     function  FileOpen(const  FileName:  string;Mode:  Integer)  :  THandle

    Visibility:   default

Description:     FileOpen opens a file with name FileName with mode Mode.  Mode can be one of the following
                constants:


                fmOpenRead           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 (1524   ) 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 (1519   ) 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.

                     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.



                                                                                1523

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                     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 (1519   )

       Errors:   On Error, -1 is returned.

    See also:    fmOpenRead (1459   ),  fmOpenWrite (1459   ),  fmOpenReadWrite (1459   ),  fmShareDenyWrite
                (1459   ), fmShareExclusive (1459   ), fmShareDenyRead (1459   ), fmShareDenyNone (1459   ), fmShare-
                Compat  (1459   ),  FileClose  (1518   ),  FileWrite  (1527   ),  FileCreate  (1519   ),  FileRead  (1524   ),
                FileTruncate (1527   ), FileSeek (1525   )



                38.13.100            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 (1523   ) call.

                The function returns the number of bytes actually read, or -1 on error.

                For an example, see FileCreate (1519   )

       Errors:   On error, -1 is returned.

    See also:    FileClose (1518   ), FileWrite (1527   ), FileCreate (1519   ), FileOpen (1523   ), FileTruncate (1527   ),
                FileSeek (1525   )



                38.13.101            FileSearch

    Synopsis:    Search for a file in a path.

Declaration:     function  FileSearch(const  Name:  string;const  DirList:  string;
                                                Options:  TFileSearchOptions)  :  string
                function  FileSearch(const  Name:  string;const  DirList:  string;
                                                ImplicitCurrentDir:  Boolean)  :  string

    Visibility:   default

Description:     FileSearch looks for the file Name in DirList, where dirlist is a list of directories, separated
                by semicolons or colons.  It returns the full filename of the first match found.  The optional
                Options parameter may be specified to influence the behaviour of the search algorithm.  It
                is a set of the following options:



                                                                                1524

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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 (1514   ), FindFirst (1528   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.102            FileSeek

    Synopsis:    Set the current file position on a file handle.

Declaration:     function  FileSeek(Handle:  THandle;FOffset:  LongInt;Origin:  LongInt)
                                              :  LongInt
                function  FileSeek(Handle:  THandle;FOffset:  Int64;Origin:  LongInt)
                                              :  Int64

    Visibility:   default

Description:     FileSeek sets the file pointer on position Offset, starting from Origin.  Origin can be one
                of the following values:


                fsFromBeginning            Offset is relative to the first byte of the file.  This position is zero-based.
                       i.e.  the first byte is at offset 0.

                fsFromCurrent           Offset is relative to the current position.

                fsFromEnd        Offset is relative to the end of the file.  This means that Offset can only be
                       zero or negative in this case.


                If successfull, the function returns the new file position, relative to the beginning of the file.

 Remark:         The abovementioned constants do not exist in Delphi.

       Errors:   On error, -1 is returned.



                                                                                1525

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    FileClose  (1518   ),  FileWrite  (1527   ),  FileCreate  (1519   ),  FileOpen  (1523   ),  FileRead  (1524   ),
                FileTruncate (1527   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.103            FileSetAttr

    Synopsis:    Set the attributes of a file.

Declaration:     function  FileSetAttr(const  Filename:  string;Attr:  LongInt)  :  LongInt

    Visibility:   default

Description:     FileSetAttr sets the attributes of  FileName to Attr.  If the function was successful, 0 is
                returned, -1 otherwise.  Attr can be set to an OR-ed combination of the pre-defined faXXX
                constants.

                This function is not implemented on Unixes.

       Errors:   On error, -1 is returned (always on Unixes).

    See also:    FileGetAttr (1521   ), FileGetDate (1522   ), FileSetDate (1526   )



                38.13.104            FileSetDate

    Synopsis:    Set the date of a file.

Declaration:     function  FileSetDate(Handle:  THandle;Age:  LongInt)  :  LongInt
                function  FileSetDate(const  FileName:  string;Age:  LongInt)  :  LongInt

    Visibility:   default

Description:     FileSetDate sets the file date of the open file with handle Handle or to Age, where Age is
                a DOS date-and-time stamp value.

                Alternatively, the filename may be specified with the FileName argument.  This variant of
                the  call  is  mandatory  on  unices,  since  there  is  no  OS  support  for  setting  a  file  timestamp
                based on a handle.  (the handle may not be a real file at all).

                The function returns zero if successfull.

       Errors:   On Unix, the handle variant always returns -1, since this is impossible to implement.  On
                Windows and DOS, a negative error code is returned.



                                                                                1526

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.105            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 (1519   ).

       Errors:   On error, the function returns False.

    See also:    FileClose  (1518   ),  FileWrite  (1527   ),  FileCreate  (1519   ),  FileOpen  (1523   ),  FileRead  (1524   ),
                FileSeek (1525   )



                38.13.106            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 (1519   ).

       Errors:   In case of error, -1 is returned.

    See also:    FileClose (1518   ), FileCreate (1519   ), FileOpen (1523   ), FileRead (1524   ), FileTruncate (1527   ),
                FileSeek (1525   )



                38.13.107            FindClose

    Synopsis:    Close a find handle

Declaration:     procedure  FindClose(var  F:  TSearchRec)

    Visibility:   default

Description:     FindClose ends a series of FindFirst (1528   )/FindNext (1529   ) 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 (1528   ).

       Errors:   None.

    See also:    FindFirst (1528   ), FindNext (1529   )



                                                                                1527

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.108            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  (1463   ))  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 (1463   )



                38.13.109            FindFirst

    Synopsis:    Start a file search and return a findhandle

Declaration:     function  FindFirst(const  Path:  string;Attr:  LongInt;
                                              out  Rslt:  TSearchRec)  :  LongInt

    Visibility:   default

Description:     FindFirst looks for files that match the name (possibly with wildcards) in Path and extra
                attributes Attr.  It then fills up the Rslt record with data gathered about the file.  It returns
                0 if a file matching the specified criteria is found, a nonzero value (-1 on Unix-like platforms)
                otherwise.

                Attr is an or-ed combination of the following constants:


                faReadOnly         The file is read-only.

                faHidden       The file is hidden.  (On unix, this means that the filename starts with a dot)

                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.



                                                                                1528

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



 Remark:         A FindFirst call must always  be followed by a FindClose (1527   ) 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 (1527   ), FindNext (1529   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.110            FindNext

    Synopsis:    Find the next entry in a findhandle.

Declaration:     function  FindNext(var  Rslt:  TSearchRec)  :  LongInt

    Visibility:   default

Description:     FindNext finds a next occurrence of a search sequence initiated by FindFirst.  If another
                record matching the criteria in Rslt is found, 0 is returned, a nonzero constant is returned
                otherwise.

 Remark:         The last FindNext call must always  be followed by a FindClose call with the same Rslt
                record.  Failure to do so will result in memory loss.

                For an example, see FindFirst (1528   )

       Errors:   On error (no more file is found), a nonzero constant is returned.

    See also:    FindFirst (1528   ), FindClose (1527   )



                                                                                1529

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.111            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 (1460   ) and MaxCur-
                rency (1460   )).  If not, an EConvertError (1606   ) exception is raised.

       Errors:   If  Value is out of range, an EConvertError (1606   ) exception is raised.

    See also:    EConvertError (1606   ), TryFloatToCurr (1597   ), MinCurrency (1460   ), MaxCurrency (1460   )



                38.13.112            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 (1461   ) and Max-
                DateTime (1460   )).  If not, an EConvertError (1606   ) exception is raised.

       Errors:   If  Value is out of range, an EConvertError (1606   ) exception is raised.

    See also:    EConvertError (1606   ), MinDateTime (1461   ), MaxDateTime (1460   )



                38.13.113            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
                (1468   ) format.  It will store Precision digits in the Digits field, of which at most Decimal
                decimals.

       Errors:   None.

    See also:    TFloatRec (1468   )



                                                                                1530

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.114            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  (1532   ).   FloatToStr  is
                completely equivalent to the following call:


                FloatToStrF(Value,  ffGeneral,15,  0);


       Errors:   None.

    See also:    FloatToStrF (1532   ), FormatFloat (1544   ), StrToFloat (1585   )


                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 ) ;



                                                                                1531

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.115            FloatToStrF

    Synopsis:    Convert a float value to a string using a given format.

Declaration:     function  FloatToStrF(Value:  Double;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  string
                function  FloatToStrF(Value:  Double;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  string
                function  FloatToStrF(Value:  Single;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  string
                function  FloatToStrF(Value:  Single;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  string
                function  FloatToStrF(Value:  Comp;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  string
                function  FloatToStrF(Value:  Comp;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  string
                function  FloatToStrF(Value:  Currency;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  string
                function  FloatToStrF(Value:  Currency;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  string
                function  FloatToStrF(Value:  Int64;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer)  :  string
                function  FloatToStrF(Value:  Int64;format:  TFloatFormat;
                                                 Precision:  Integer;Digits:  Integer;
                                                 const  FormatSettings:  TFormatSettings)  :  string

    Visibility:   default

Description:     FloatToStrF converts the floating point number value to a string representation, according
                to the settings of the parameters Format, Precision and Digits.

                The meaning of the Precision and Digits parameter depends on the Format parameter.
                The format is controlled mainly by the Format parameter.  It can have one of the following
                values:


                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.



                                                                                1532

            _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            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 (1531   ), FloatToText (1534   )


            Listing:__./sysutex/ex68.pp____________________________________________________________________________________________*
 *_______

            Program       E x a m p l e 6 8;


            {   T h i s  p r o g r a m d e m o n s t r a t e st h e F l o a t T o S t r Ff u n c t i o n }


            Uses      s y s u t i l;s


            Const      Fmt    :  A r r a y  [ T F l o a t F o r m a]t o f  s t r i n g[ 1 0 ]  =
                            ( ' g e n e r a l', 'e x p o n e n t', ' f i x e d', 'number     ' , 'C u r r e n c y') ;


             P r o c e d u r eT e s t i t ( V a l u e  :    E x t e n d e d) ;


            Var     I, J   :  l o n g i n t;
                   FF    :  T F l o a t F o r m a;t


             b e g i n
                For    I : = 5  t o  1 5  do
                   For    J : = 1  t o  4   do
                       For    FF :=  f f g e n e r a lt o   f f c u r r e n c ydo
                          b e g i n
                          Write      ( V a l u e,' ( P r e c:  ' , I: 2 , ' ,  Dig  :   ' ,J , ' ,  fmt    :  ' ,Fmt   [ f f] , ' )*
 *  :   ') ;
                           W r i t e l n( F l o a t T o S t r(fV a l u e,FF  , I ,J ) ) ;
                          Write     ( - V a l u e, ' (P r e c :  ' ,I : 2 , ' , Dig   :   ', J , ' , fmt     :  ' ,Fmt   [ f f] , '*
 *)  :   ' ) ;
                           W r i t e l n( F l o a t T o S t r(f- V a l u e,FF  , I, J ) ) ;
                          end   ;
            end   ;


            Begin
                T e s t i t ( 1 . 1 ) ;
                T e s t i t ( 1 . 1E1  ) ;
                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___.________________________________________________________________________________________________________________*
 *_______



                                                                            1533

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.116            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 (1532   ).  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 (1531   ), FloatToStrF (1532   )


                Listing:  ./sysutex/ex69.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e F l o a t T o S t r Ff u n c t i o n }


                Uses      s y s u t i l;s


                Const      Fmt    :  A r r a y  [ T F l o a t F o r m a]t o f  s t r i n g[ 1 0 ]  =
                                ( ' g e n e r a l', 'e x p o n e n t', ' f i x e d', 'number     ' , 'C u r r e n c y') ;


                 P r o c e d u r eT e s t i t ( V a l u e  :    E x t e n d e d) ;


                Var     I, J   :  l o n g i n t;
                       FF    :  T F l o a t F o r m a;t
                       S   :   S h o r t S t r i n;g


                 b e g i n
                    For    I : = 5  t o  1 5  do
                       For    J : = 1  t o  4   do
                           For    FF :=  f f g e n e r a lt o   f f c u r r e n c ydo
                              b e g i n
                              Write      ( V a l u e,' ( P r e c:  ' , I: 2 , ' ,  Dig  :   ' ,J , ' ,  fmt    :  ' ,Fmt   [ f f] ,*
 * ' )  :   ') ;
                               S e t L e n g t(hS ,FloatToText          ( @S  [ 1 ] ,V a l u e,FF  ,I , J ) ) ;
                               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 ) ;



                                                                                1534

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.117            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 (1544   )

       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 (1544   )



                38.13.118            FmtStr

    Synopsis:    Format a string with given arguments.

Declaration:     procedure  FmtStr(var  Res:  string;const  Fmt:  string;
                                           const  args:  Array  of  const)
                procedure  FmtStr(var  Res:  string;const  Fmt:  string;
                                           const  args:  Array  of  const;
                                           const  FormatSettings:  TFormatSettings)

    Visibility:   default

Description:     FmtStr calls Format (1536   ) with Fmt and Args as arguments, and stores the result in Res.
                For more information on how the resulting string is composed, see Format (1536   ).

       Errors:   In case of error, a EConvertError exception is raised.

    See also:    Format (1536   ), FormatBuf (1543   )


                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



                                                                                1535

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.119            ForceDirectories

    Synopsis:    Create a chain of directories

Declaration:     function  ForceDirectories(const  Dir:  string)  :  Boolean

    Visibility:   default

Description:     ForceDirectories tries to create any missing directories in Dir till the whole path in Dir
                exists.  It returns True if Dir already existed or was created succesfully.  If it failed to create
                any of the parts, False is returned.



                38.13.120            Format

    Synopsis:    Format a string with given arguments.

Declaration:     function  Format(const  Fmt:  string;const  Args:  Array  of  const)  :  string
                function  Format(const  Fmt:  string;const  Args:  Array  of  const;
                                         const  FormatSettings:  TFormatSettings)  :  string

    Visibility:   default

Description:     Format replaces all placeholders inFmt with the arguments passed in Args and returns the
                resulting string.  A placeholder looks as follows:


                '%'  [[Index]':']  ['-']  [Width]  ['.'  Precision]  ArgType


                elements between single quotes must be typed as shown without the quotes, and elements
                between square brackets [  ] are optional.  The meaning of the different elements 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):



                                                                                1536

         _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'________________________*
 *____________



         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  (1532   ),  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
               (1532   )).  Precision indicates the number of digits following the decimal point.

               In short, the F specifier formats it's argument as follows:

               FloatToStrF(Argument,ffFixed,ffixed,9999,Precision)

         G General number format.  The next argument in the Args array should be a floating point
               value.   The  argument  is  converted  to  a  decimal  string  using  fixed  point  notation  or
               scientific notation, depending on which gives the shortest result.  Precision is used to
               determine the number of digits after the decimal point.

               In short, the G specifier formats it's argument as follows:

               FloatToStrF(Argument,ffGeneral,Precision,3)

         M  Currency  format.   the  next  argument  in  the  var{Args}  array  must  be  a  floating  point
               value.  The  argument  is  converted  to  a  decimal  string  using  currency  notation.  This
               means that fixed-point notation is used, but that the currency symbol is appended.  If
               precision is specified, then then it overrides the CurrencyDecimals global variable used
               in the FloatToStrF (1532   )

               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:



                                                                         1537

            _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



                 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 (1543   )


            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 ]
                    [ % 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 ]



                                                                            1538

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



           [%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  ;
    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



                                                                1539

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



           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 ,'=>    ' ,@
    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 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



                                                                1540

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



       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 ) ;
       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 ) ;



                                                                1541

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



       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]
       [% -*.*    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



                                                                1542

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    T e s t S m a l l N e g E x p o n e n t i;a l
                end___.____________________________________________________________________________________________________________*
 *___________



                38.13.121            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 (1536   ) and stores the result in Buf.

    See also:    Format (1536   )


                Listing:  ./sysutex/ex72.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 2;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e FormatBuf         f u n c t i o n}


                Uses      s y s u t i l;s


                Var
                    S   :  S h o r t S t r i n;g


                Const
                    Fmt    :   S h o r t S t r i n g=    'F o r  some     n i c e  e x a m p l e s o f  f o m a t t i n gs e e %  s*
 * . ';


                Begin
                    S :=  '' ;
                    S e t L e n g t h(S, FormatBuf        ( S [ 1 ] , 2 5 5 ,Fmt [ 1 ] ,Length    ( Fmt   ) , ['Format     ' ] ) ) ;
                    W r i t e l n (S  ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.122            FormatCurr

    Synopsis:    Format a currency

Declaration:     function  FormatCurr(const  Format:  string;Value:  Currency)  :  string
                function  FormatCurr(const  Format:  string;Value:  Currency;
                                                const  FormatSettings:  TFormatSettings)  :  string

    Visibility:   default

Description:     FormatCurr formats the currency  Value according to the formatting rule in Format,  and
                returns the resulting string.

                For an explanation of the formatting characters, see FormatFloat (1544   ).

    See also:    FormatFloat (1544   ), FloatToText (1534   )



                                                                                1543

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.123            FormatDateTime

    Synopsis:    Return a string representation of a TDateTime value with a given format.

Declaration:     function  FormatDateTime(const  FormatStr:  string;DateTime:  TDateTime)
                                                        :  string
                function  FormatDateTime(const  FormatStr:  string;DateTime:  TDateTime;
                                                      const  FormatSettings:  TFormatSettings)  :  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 (1455   ).

       Errors:   On error (such as an invalid character in the formatting string), and EConvertError excep-
                tion is raised.

    See also:    DateTimeToStr (1501   ), DateToStr (1504   ), TimeToStr (1594   ), StrToDateTime (1583   )


                Listing:  ./sysutex/ex14.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e FormatDateTime             f u n c t i o n}


                Uses      s y s u t i l;s


                Var    ThisMoment          :  TDateTime       ;


                Begin
                    ThisMoment       := Now   ;
                    W r i t e l n ( 'Now     :  ' ,FormatDateTime           ( 'hh  :nn  ' ,ThisMoment        ) ) ;
                    W r i t e l n ( 'Now     :  ' ,FormatDateTime           ( 'DD   MM   YYYY    ' ,ThisMoment        ) ) ;
                    W r i t e l n ( 'Now     :  ' ,FormatDateTime           ( 'c ' ,ThisMoment        ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.124            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 (1532   ) 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.



                                                                                1544

            _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            #  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 (1531   )


            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



                                                                            1545

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                       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___.____________________________________________________________________________________________________________*
 *___________



                38.13.125            FreeAndNil

    Synopsis:    Free object if needed, and set object reference to Nil

Declaration:     procedure  FreeAndNil(var  obj)

    Visibility:   default

Description:     FreeAndNil will free the object in Obj and will set the reference in Obj to Nil.  The reference
                is set to Nil first, so if an exception occurs in the destructor of the object, the reference will
                be Nil anyway.

       Errors:   Exceptions that occur during the destruction of  Obj are not caught.



                38.13.126            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 does not contain a 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 (1491   ) call,
                but can be configured by means of the OnGetApplicationName (1474   ) callback.

                If VendorName (1602   ) is not-empty, then VendorName will also be inserted before the application-
                specific directory.

       Errors:   None.

    See also:    GetAppConfigFile  (1547   ),  ApplicationName  (1491   ),  OnGetApplicationName  (1474   ),  Cre-
                ateDir (1498   ), SysConfigDir (1463   ), VendorName (1602   )



                                                                                1546

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.127            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 configu-
                ration parameters.  The Global parameter determines whether it is a global configuration file
                (value True) or a personal configuration file (value False).  The parameter SubDir, in case
                it is set to True, will insert the name of a directory before the filename.  This can be used
                in case the application needs to store other data than configuration data in an application-
                specific directory.  Default behaviour is to set this to False.  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.

                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 (1491   ) call,
                but can be configured by means of the OnGetApplicationName (1474   ) callback.

                If VendorName (1602   ) is not-empty,  then VendorName will be inserted in the path for the
                config file directory.

       Errors:   None.

    See also:    GetAppConfigDir  (1546   ),  OnGetApplicationName  (1474   ),  ApplicationName  (1491   ),  Cre-
                ateDir (1498   ), ConfigExtension (1457   ), SysConfigDir (1463   ), VendorName (1602   )



                38.13.128            GetCurrentDir

    Synopsis:    Return the current working directory of the application.

Declaration:     function  GetCurrentDir  :  string

    Visibility:   default

Description:     GetCurrentDir returns the current working directory.

       Errors:   None.

    See also:    SetCurrentDir (1565   ), DiskFree (1507   ), DiskSize (1508   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1547

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.129            GetDirs

    Synopsis:    Return a list of directory names from a path.

Declaration:     function  GetDirs(var  DirName:  string;var  Dirs:  Array  of  PChar)  :  LongInt

    Visibility:   default

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 (1517   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.130            GetEnvironmentString

    Synopsis:    Return an environment variable by index.

Declaration:     function  GetEnvironmentString(Index:  Integer)  :  string

    Visibility:   default

Description:     GetEnvironmentString returns the Index-th environment variable.  The index is 1 based,
                and is bounded from above by the result of GetEnvironmentVariableCount (1549   ).

                For an example, GetEnvironmentVariableCount (1549   ).

 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 (1549   ), GetEnvironmentVariableCount (1549   )



                                                                                1548

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.131            GetEnvironmentVariable

    Synopsis:    Return the value of an environment variable.

Declaration:     function  GetEnvironmentVariable(const  EnvVar:  string)  :  string

    Visibility:   default

Description:     GetEnvironmentVariable  returns  the  value  of  the  EnvVar  environment  variable.   If  the
                specified variable does not exist or EnvVar is empty, an empty string is returned.

    See also:    GetEnvironmentString (1548   ), GetEnvironmentVariableCount (1549   )



                38.13.132            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 (1548   ), GetEnvironmentVariable (1549   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.133            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.



                                                                                1549

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.134            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 (1562   )



                38.13.135            GetLocalTime

    Synopsis:    Get the local time.

Declaration:     procedure  GetLocalTime(var  SystemTime:  TSystemTime)

    Visibility:   default

Description:     GetLocalTime returns the system time in a TSystemTime (1 ) format.

       Errors:   None.

    See also:    Now (1561   ), Date (1500   ), Time (1592   ), TSystemTime (1 )



                38.13.136            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.



                38.13.137            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.



                                                                                1550

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                The  OnGetTempDir  (1474   )  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 (1474   ), GetTempFileName (1551   )



                38.13.138            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  (1474   )  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 (1550   ), OnGetTempFile (1474   )



                38.13.139            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 (1546   )



                38.13.140            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



                                                                                1551

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1556   )



                38.13.141            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 (1590   ), #rtl.system.TGUID (1269   ), StringToGUID (1573   ), IsEqualGuid (1556   )



                38.13.142            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.



                38.13.143            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 (1554   ), but operates on an already decoded date.

    See also:    IncMonth (1554   )



                                                                                1552

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.144            IncludeLeadingPathDelimiter

    Synopsis:    Prepend a path delimiter if there is not already one.

Declaration:     function  IncludeLeadingPathDelimiter(const  Path:  string)  :  string

    Visibility:   default

Description:     IncludeLeadingPathDelimiter will insert a path delimiter (DirectorySeparator (1235   )) in
                the first position of  Path, if there is not already a directory separator at that position.  It
                will  return  the  resulting  string.  If  the  path  is  empty,  a  DirectorySeparator  character  is
                returned.

    See also:    IncludeTrailingPathDelimiter  (1553   ),  ExcludeLeadingPathDelimiter  (1512   ),  ExcludeTrail-
                ingPathDelimiter (1513   ), ConcatPaths (1498   )


                Listing:  ./sysutex/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 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___.____________________________________________________________________________________________________________*
 *___________



                38.13.145            IncludeTrailingBackslash

    Synopsis:    Add trailing directory separator to a pathname, if needed.

Declaration:     function  IncludeTrailingBackslash(const  Path:  string)  :  string

    Visibility:   default

Description:     IncludeTrailingBackslash is provided for backwards compatibility with Delphi.  Use In-
                cludeTrailingPathDelimiter (1553   ) instead.

    See also:    IncludeTrailingPathDelimiter (1553   ), ExcludeTrailingPathDelimiter (1513   ), PathDelim (1461   ),
                IsPathDelimiter (1557   )



                38.13.146            IncludeTrailingPathDelimiter

    Synopsis:    Add trailing directory separator to a pathname, if needed.

Declaration:     function  IncludeTrailingPathDelimiter(const  Path:  string)  :  string

    Visibility:   default

Description:     IncludeTrailingPathDelimiter adds a trailing path delimiter character (PathDelim (1461   ))
                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 (1553   ), ExcludeTrailingPathDelimiter (1513   ), PathDelim (1461   ),
                IsPathDelimiter (1557   )



                                                                                1553

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.147            IncMonth

    Synopsis:    Increases the month in a TDateTime value with a given amount.

Declaration:     function  IncMonth(const  DateTime:  TDateTime;NumberOfMonths:  Integer)
                                              :  TDateTime

    Visibility:   default

Description:     IncMonth increases the month number in DateTime with NumberOfMonths.  It wraps the re-
                sult as to get a month between 1 and 12, and updates the year accordingly.  NumberOfMonths
                can be negative, and can be larger than 12 (in absolute value).

       Errors:   None.

    See also:    Date (1500   ), Time (1592   ), Now (1561   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.148            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.



                                                                                1554

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.149            IntToHex

    Synopsis:    Convert an integer value to a hexadecimal string.

Declaration:     function  IntToHex(Value:  Integer;Digits:  Integer)  :  string
                function  IntToHex(Value:  Int64;Digits:  Integer)  :  string
                function  IntToHex(Value:  QWord;Digits:  Integer)  :  string

    Visibility:   default

Description:     IntToHex converts Value to a hexadecimal string representation.  The result will contain at
                least Digits characters.  If  Digits is less than the needed number of characters, the string
                will NOT be truncated.  If Digits is larger than the needed number of characters, the result
                is padded with zeroes.

       Errors:   None.

    See also:    IntToStr (1555   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.150            IntToStr

    Synopsis:    Convert an integer value to a decimal string.

Declaration:     function  IntToStr(Value:  Integer)  :  string
                function  IntToStr(Value:  Int64)  :  string
                function  IntToStr(Value:  QWord)  :  string

    Visibility:   default

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 (1555   ), StrToInt (1586   )


                Listing:  ./sysutex/ex74.pp



                                                                                1555

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.151            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 (1558   )



                38.13.152            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 (1590   ), #rtl.system.TGUID (1269   ), StringToGUID (1573   ), GuidToString (1552   )



                38.13.153            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.



                                                                                1556

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    IncMonth (1554   ), Date (1500   )


                Listing:  ./sysutex/ex16.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 1 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e I s L e a p Y e a r f u n c t i o n}


                Uses      s y s u t i l;s


                Var    YY  ,MM  , dd   :  Word    ;


                 P r o c e d u r eT e s t Y e a r (Y   :  Word    ) ;


                 b e g i n
                    W r i t e l n (Y  , '  i s  l e a p  y e a r  :  ' ,I s L e a p Y e a r(Y) ) ;
                end   ;


                Begin
                    DeCodeDate       ( Date   , YY  ,mm  ,dd  ) ;
                    T e s t Y e a r(y y) ;
                    T e s t Y e a r( 2 0 0 0 ) ;
                    T e s t Y e a r( 1 9 0 0 ) ;
                    T e s t Y e a r( 1 6 0 0 ) ;
                    T e s t Y e a r( 1 9 9 2 ) ;
                    T e s t Y e a r( 1 9 9 5 ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.154            IsPathDelimiter

    Synopsis:    Is the character at the given position a pathdelimiter ?

Declaration:     function  IsPathDelimiter(const  Path:  string;Index:  Integer)  :  Boolean

    Visibility:   default

Description:     IsPathDelimiter returns True if the character at position Index equals PathDelim (1461   ),
                i.e.  if it is a path delimiter character for the current platform.

       Errors:   IncludeTrailingPathDelimiter (1553   )ExcludeTrailingPathDelimiter (1513   )PathDelim (1461   )



                38.13.155            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



                                                                                1557

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 5;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e  I s V a l i d I d e n tf u n c t i o n}


                Uses      s y s u t i l;s


                 P r o c e d u r eT e s t i t ( S   :  S t r i n g) ;


                 b e g i n
                    Write     (  '" ' ,S , '"   i s  ' ) ;
                    I f  not    I s V A l i d I d e n(tS )  then
                       Write    ( 'NOT     ' ) ;
                    W r i t e l n ( 'a   v a l i d  i d e n t i f i e'r) ;
                end   ;


                Begin
                    T e s t i t ( ' _MyObj     ') ;
                    T e s t i t ( ' My __Obj1     ' ) ;
                    T e s t i t ( ' My _1 _Obj    ' ) ;
                    T e s t i t ( ' 1MyObject       ') ;
                    T e s t i t ( ' My@Object       ') ;
                    T e s t i t ( 'M123    ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.156            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___.____________________________________________________________________________________________________________*
 *___________



                38.13.157            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



                                                                                1558

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1563   ), TrimLeft (1595   ), TrimRight (1596   ), Trim (1594   )


                Listing:__./sysutex/ex76.pp________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 7 6;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e L e f t S t r f u n c t i o n }


                Uses      s y s u t i l;s


                Begin
                    W r i t e l n ( L e f t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y2z0 ) ) ;
                    W r i t e l n ( L e f t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y1z5 ) ) ;
                    W r i t e l n ( L e f t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y1z) ) ;
                    W r i t e l n ( L e f t S t r(' a b c d e f g h i j k l m n o p q r s t u v w'x,y2z0 0 ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.158            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.



                38.13.159            LowerCase

    Synopsis:    Return a lowercase version of a string.

Declaration:     function  LowerCase(const  s:  string)  :  string;    Overload
                function  LowerCase(const  V:  variant)  :  string;    Overload

    Visibility:   default

Description:     LowerCase returns the lowercase equivalent of S. Ansi characters are not taken into account,
                only  ASCII  codes  below  127  are  converted.   It  is  completely  equivalent  to  the  lowercase
                function of the system unit, and is provided for compatiibility only.

       Errors:   None.

    See also:    AnsiLowerCase (1482   ), UpperCase (1601   ), AnsiUpperCase (1490   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1559

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.160            MSecsToTimeStamp

    Synopsis:    Convert a number of milliseconds to a TDateTime value.

Declaration:     function  MSecsToTimeStamp(MSecs:  Comp)  :  TTimeStamp

    Visibility:   default

Description:     MSecsTiTimeStamp converts the given number of milliseconds to a TTimeStamp date/time
                notation.

                Use TTimeStamp variables if you need to keep very precise track of time.

       Errors:   None.

    See also:    TimeStampToMSecs (1594   ), DateTimeToTimeStamp (1503   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.161            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 (1492   ).

       Errors:   If not enough memory is present, an EOutOfMemory exception will be raised.

    See also:    AssignStr (1492   ), DisposeStr (1508   )



                                                                                1560

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.162            Now

    Synopsis:    Returns the current date and time.

Declaration:     function  Now  :  TDateTime

    Visibility:   default

Description:     Now returns the current date and time.  It is equivalent to Date+Time.

       Errors:   None.

    See also:    Date (1500   ), Time (1592   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.163            OutOfMemoryError

    Synopsis:    Raise an EOutOfMemory exception

Declaration:     procedure  OutOfMemoryError

    Visibility:   default

Description:     OutOfMemoryError  raises  an  EOutOfMemory  (1610   )  exception,  with  an  exception  object
                that has been allocated on the heap at program startup.  The program should neved create
                an EOutOfMemory (1610   ) exception, but always call this routine.

    See also:    EOutOfMemory (1610   )



                38.13.164            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 (1483   ), AnsiExtractQuotedStr (1480   )


                Listing:  ./sysutex/ex78.pp



                                                                                1561

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 7 8;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Q u o t e d S t r f u n c t i o n}


                Uses      s y s u t i l;s


                Var    S   :   A n s i S t r i n;g


                Begin
                    S :=  'He   s a i d  ' ' H e l l o''  and    w a l k e d on  ' ;
                    W r i t e l n (S  ) ;
                    W r i t e l n ( '    becomes     ' ) ;
                    W r i t e l n ( Q u o t e d S t(rS ) ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.165            RaiseLastOSError

    Synopsis:    Raise an exception with the last Operating System error code.

Declaration:     procedure  RaiseLastOSError

    Visibility:   default

Description:     RaiseLastOSError raises an EOSError (1610   ) 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 (1612   ) will be raised.

    See also:    EOSError (1610   ), GetLastOSError (1550   ), Exception (1612   )



                38.13.166            RemoveDir

    Synopsis:    Remove a directory from the filesystem.

Declaration:     function  RemoveDir(const  Dir:  string)  :  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 (1498   ).

       Errors:   In case of error (e.g.  the directory isn't empty) the function returns False.  If successful,
                True is returned.



                38.13.167            RenameFile

    Synopsis:    Rename a file.

Declaration:     function  RenameFile(const  OldName:  string;const  NewName:  string)
                                                 :  Boolean

    Visibility:   default



                                                                                1562

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



Description:     RenameFile renames a file from OldName to NewName.  The function returns True if success-
                ful, False otherwise.  Remark:  you cannot rename across disks or partitions.

       Errors:   On Error, False is returned.

    See also:    DeleteFile (1506   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.168            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 (1563   )



                38.13.169            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.



                38.13.170            RightStr

    Synopsis:    Return a number of characters from a string, starting at the end.

Declaration:     function  RightStr(const  S:  string;Count:  Integer)  :  string



                                                                                1563

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    Visibility:  default

Description:     RightStr returns the Count rightmost characters of S. It is equivalent to a call to Copy(S,Length(S)+1-Count,Count*
 *).

                If  Count is larger than the actual length of  S only the real length will be used.

       Errors:   None.

    See also:    LeftStr (1558   ), Trim (1594   ), TrimLeft (1595   ), TrimRight (1596   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.171            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.



                38.13.172            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 (1478   ) with arguments S1 and
                S2 returns 0, and returns False otherwise.

       Errors:   None.

    See also:    AnsiCompareFileName (1478   )



                                                                                1564

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.173            SameText

    Synopsis:    Checks whether 2 strings are the same (case insensitive)

Declaration:     function  SameText(const  s1:  string;const  s2:  string)  :  Boolean

    Visibility:   default

Description:     SameText calls CompareText (1497   ) 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 (1497   ), AnsiSameText (1483   ), AnsiSameStr (1483   )



                38.13.174            SetCurrentDir

    Synopsis:    Set the current directory of the application.

Declaration:     function  SetCurrentDir(const  NewDir:  string)  :  Boolean

    Visibility:   default

Description:     SetCurrentDir sets the current working directory of your program to NewDir.  It returns
                True if the function was successfull, False otherwise.

       Errors:   In case of error, False is returned.

    See also:    GetCurrentDir (1547   )



                38.13.175            SetDirSeparators

    Synopsis:    Set the directory separators to the known directory separators.

Declaration:     function  SetDirSeparators(const  FileName:  string)  :  string

    Visibility:   default

Description:     SetDirSeparators returns FileName with all possible DirSeparators replaced by OSDirSeparator.

       Errors:   None.

    See also:    ExpandFileName (1514   ), ExtractFilePath (1517   ), ExtractFileDir (1515   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1565

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.176            ShowException

    Synopsis:    Show the current exception to the user.

Declaration:     procedure  ShowException(ExceptObject:  TObject;ExceptAddr:  Pointer)

    Visibility:   default

Description:     ShowException shows a message stating that a ExceptObject was raised at address ExceptAddr.
                It uses ExceptionErrorMessage (1512   ) 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
                (1475   ) is executed.

       Errors:   If, for a GUI application, OnShowException (1475   ) 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 (1512   ), ExceptAddr (1511   ), ExceptionErrorMessage (1512   )



                38.13.177            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.



                38.13.178            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:



                                                                                1566

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                d A pointer to an integer.

                fA pointer to an extended.

                sA pointer to an ansistring.

                cA pointer to a single character.


       Errors:   No error checking is performed on the type of the memory location.

    See also:    Format (1536   )



                38.13.179            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 (1188   ) function of the Strings
                unit.

                For an example, see StrBufSize (1567   ).

       Errors:   None.

    See also:    StrBufSize (1567   ), StrDispose (1570   ), StrAlloc (1188   )



                38.13.180            StrBufSize

    Synopsis:    Return the size of a null-terminated string allocated on the heap.

Declaration:     function  StrBufSize(Str:  PChar)  :  SizeUInt

    Visibility:   default

Description:     StrBufSize returns the memory allocated for Str.  This function ONLY gives the correct
                result if  Str was allocated using StrAlloc (1567   ).

       Errors:   If no more memory is available, a runtime error occurs.

    See also:    StrAlloc (1567   ), StrDispose (1570   )


                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



                                                                                1567

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                     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___.____________________________________________________________________________________________________________*
 *___________



                38.13.181            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 (1470   ), ByteType (1494   )



                38.13.182            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 (1573   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1568

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.183            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.



                38.13.184            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 (1574   ).

       Errors:   None.

    See also:    StrLComp (1574   ), StrIComp (1572   ), StrLIComp (1576   )



                38.13.185            strcopy

    Synopsis:    Copy a null-terminated string

Declaration:     function  strcopy(dest:  PChar;source:  PChar)  :  PChar

    Visibility:   default

Description:     Copy the null terminated string in Source to Dest,  and returns a pointer to Dest.  Dest
                needs enough room to contain Source, i.e.  StrLen(Source)+1 bytes.

       Errors:   No length checking is performed.

    See also:    StrPCopy (1579   ), StrLCopy (1575   ), StrECopy (1570   )


                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



                                                                                1569

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.186            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 (1567   ) from the SysUtils unit.

                For an example, see StrBufSize (1567   ).

       Errors:   If an invalid pointer is passed, or a pointer not allocated with StrAlloc, an error may occur.

    See also:    StrBufSize (1567   ), StrAlloc (1567   ), StrDispose (1570   )



                38.13.187            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 (1575   ), StrCopy (1569   )


                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



                                                                                1570

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                        W r i t e l n(  'PP =   ' ,PP  ) ;
                    S t r D i s p o s(ePP  ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                38.13.188            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 (1575   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.189            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  (1536   )  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 (1536   ).

    See also:    StrLFmt (1576   ), FmtStr (1535   ), Format (1536   ), FormatBuf (1543   )


                Listing:  ./sysutex/ex80.pp



                                                                                1571

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.190            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 (1574   ), StrComp (1569   ), StrLIComp (1576   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1572

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.191            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 (1470   ).  Standard
                behaviour is to replace only the first occurrence of OldPattern, and to search case sensitively.

       Errors:   None.

    See also:    TReplaceFlags (1470   )



                38.13.192            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  (1606   )  exception  is
                raised.

    See also:    Supports (1590   ), #rtl.system.TGUID (1269   ), GUIDToString (1552   ), IsEqualGuid (1556   )



                38.13.193            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 (1568   )


                Listing:  ./stringex/ex12.pp



                                                                                1573

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.194            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 (1569   ), StrIComp (1572   ), StrLIComp (1576   )


                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 ) ;



                                                                                1574

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.195            strlcopy

    Synopsis:    Copy a null-terminated string, limited in length.

Declaration:     function  strlcopy(dest:  PChar;source:  PChar;maxlen:  SizeInt)  :  PChar

    Visibility:   default

Description:     Copies MaxLen characters from Source to Dest, and makes Dest a null terminated string.

       Errors:   No length checking is performed.

    See also:    StrCopy (1569   ), StrECopy (1570   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.196            strlen

    Synopsis:    Length of a null-terminated string.

Declaration:     function  strlen(p:  PChar)  :  SizeInt

    Visibility:   default

Description:     Returns the length of the null-terminated string P.

       Errors:   None.

    See also:    StrNew (1578   )


                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.  }



                                                                                1575

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.197            StrLFmt

    Synopsis:    Format a string with given arguments, but with limited length.

Declaration:     function  StrLFmt(Buffer:  PChar;Maxlen:  Cardinal;Fmt:  PChar;
                                           const  args:  Array  of  const)  :  PChar
                function  StrLFmt(Buffer:  PChar;Maxlen:  Cardinal;Fmt:  PChar;
                                           const  args:  Array  of  const;
                                           const  FormatSettings:  TFormatSettings)  :  PChar

    Visibility:   default

Description:     StrLFmt will format fmt with Args, as the Format (1536   ) 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 (1536   ).

    See also:    StrFmt (1571   ), FmtStr (1535   ), Format (1536   ), FormatBuf (1543   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.198            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.



                                                                                1576

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                      oA positive Longint when S1>S2.


                For an example, see StrIComp (1572   )

       Errors:   None.

    See also:    StrLComp (1574   ), StrComp (1569   ), StrIComp (1572   )



                38.13.199            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 (1590   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.200            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 (1575   ), StrCopy (1569   )


                Listing:  ./stringex/ex10.pp



                                                                                1577

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.201            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 (1569   ), StrDispose (1570   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.202            StrNextChar

    Synopsis:    Returns a pointer to the location of the next empty character in a null-terminated string



                                                                                1578

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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.



                38.13.203            StrPas

    Synopsis:    Convert a null-terminated string to an ansistring.

Declaration:     function  StrPas(Str:  PChar)  :  string

    Visibility:   default

Description:     Converts a null terminated string in Str to an Ansitring, and returns this string.  This string
                is NOT truncated at 255 characters as is the

       Errors:   None.

    See also:    StrPCopy (1579   ), StrPLCopy (1579   )



                38.13.204            StrPCopy

    Synopsis:    Copy an ansistring to a null-terminated string.

Declaration:     function  StrPCopy(Dest:  PChar;Source:  string)  :  PChar

    Visibility:   default

Description:     StrPCopy Converts the Ansistring in Source to a Null-terminated string, and copies it to
                Dest.  Dest needs enough room to contain the string Source, i.e.  Length(Source)+1 bytes.

       Errors:   No checking is performed to see whether Dest points to enough memory to contain Source.

    See also:    StrPLCopy (1579   ), StrPas (1579   )



                38.13.205            StrPLCopy

    Synopsis:    Copy a limited number of characters from an ansistring to a null-terminated string.

Declaration:     function  StrPLCopy(Dest:  PChar;Source:  string;MaxLen:  SizeUInt)  :  PChar

    Visibility:   default

Description:     StrPLCopy Converts maximally  MaxLen characters of the Ansistring in Source to a Null-
                terminated string, and copies it to Dest.  Dest needs enough room to contain the characters.

       Errors:   No  checking  is  performed  to  see  whether  Dest  points  to  enough  memory  to  contain  L
                characters of  Source.

    See also:    StrPCopy (1579   )



                                                                                1579

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.206            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 (1580   ), StrRScan (1580   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.207            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 (1580   ).

       Errors:   None.

    See also:    StrScan (1580   ), StrPos (1580   )



                38.13.208            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 (1580   ), StrPos (1580   )



                                                                                1580

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.209            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 (1606   ) exception is raised.

       Errors:   On error, an EConvertError (1606   ) exception is raised.

    See also:    BoolToStr (1493   )



                38.13.210            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 (1581   ), TryStrToBool (1598   )



                38.13.211            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



                                                                                1581

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1606   ) exception is raised.

       Errors:   On error, an EConvertError (1606   ) exception is raised.

    See also:    CurrToStr (1500   ), StrToCurrDef (1582   )



                38.13.212            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 (1500   ), StrToCurr (1581   )



                38.13.213            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:  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 (1588   ), DateToStr (1504   ), TimeToStr (1594   )


                Listing:  ./sysutex/ex19.pp



                                                                                1582

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.214            StrToDateDef

    Synopsis:    Convert string to date, returning a default value

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 (1582   ), TryStrToDate (1598   ), StrToTimeDef (1589   )



                38.13.215            StrToDateTime

    Synopsis:    Convert a date/time string to a TDateTime value.

Declaration:     function  StrToDateTime(const  S:  string)  :  TDateTime
                function  StrToDateTime(const  s:  ShortString;
                                                     const  FormatSettings:  TFormatSettings)  :  TDateTime
                function  StrToDateTime(const  s:  AnsiString;
                                                     const  FormatSettings:  TFormatSettings)  :  TDateTime

    Visibility:   default



                                                                                1583

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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  (1582   )  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 (1582   ), StrToTime (1588   ), DateTimeToStr (1501   )


                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   ;


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.216            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  (1589   ),  StrToDateDef  (1583   ),  TryStrToDateTime  (1599   ),  StrToDateTime
                (1583   )



                                                                                1584

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.217            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 (1591   ), FloatToStr (1531   ), FormatFloat (1544   ), StrToInt (1586   )


                Listing:  ./sysutex/ex90.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 0;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e S t r T o F l o a t f u n c t i o n}
                { $mode      o b j f p c}
                { $h  +  }


                Uses     S y s U t i l s;


                Const
                    N r V a l u e s=  5 ;
                    T e s t S t r :  A r r a y[ 1 . .N r V a l u e s]  o f  s t r i n g=
                                    ( '1 , 1 ' ,' -0 ,2  ' ,' 1 , 2E-4   ', '0  ', '1 E4  ' ) ;


                 P r o c e d u r eT e s t i t;


                Var
                    I   :  I n t e g e r;
                    E   :  E x t e n d e d;


                 b e g i n
                    W r i t e l n(' U s i n g D e c i m a l S e p a r a t o r:  ', D e c i m a l S e p a r a t o)r;
                    For    I : = 1  t o  N r V a l u e sdo
                        b e g i n
                        W r i t e l n('C o n v e r t i n g :  ' ,T e s t S t r[ i] ) ;
                       Try
                           E := S t r T o F l o a t(T e s t S t r[i] ) ;
                           W r i t e l n(' C o n v e r t e dv a l u e  :  ' ,E  ) ;
                        e x c e p t
                           On   E   :  E x c e p t i o ndo
                               W r i t e l n('E x c e p t i o nwhen     c o n v e r t i n g :  ' ,E . M e s s a g e) ;
                       end   ;
                       end   ;
                end   ;



                                                                                1585

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.218            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.



                38.13.219            StrToInt

    Synopsis:    Convert a string to an integer value.

Declaration:     function  StrToInt(const  s:  string)  :  Integer

    Visibility:   default

Description:     StrToInt will convert the string Sto an integer.  If the string contains invalid characters or
                has an invalid format, then an EConvertError is raised.

                To be successfully converted, a string can contain a combination of  numerical characters,
                possibly preceded by a minus sign (-).  Spaces are not allowed.

       Errors:   In case of error, an EConvertError is raised.

    See also:    IntToStr (1555   ), StrToIntDef (1587   )


                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



                                                                                1586

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                       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___.____________________________________________________________________________________________________________*
 *___________



                38.13.220            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 (1606   ) exception is raised.

    See also:    TryStrToInt64  (1600   ),  StrToInt64Def  (1587   ),  StrToInt  (1586   ),  TryStrToInt  (1600   ),  Str-
                ToIntDef (1587   )



                38.13.221            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 (1587   ), TryStrToInt64 (1600   ), StrToInt (1586   ), TryStrToInt (1600   ), StrToIntDef
                (1587   )



                38.13.222            StrToIntDef

    Synopsis:    Convert a string to an integer value, with a default value.

Declaration:     function  StrToIntDef(const  S:  string;Default:  Integer)  :  Integer

    Visibility:   default

Description:     StrToIntDef will convert a string to an integer.  If the string contains invalid characters or
                has an invalid format, then Default is returned.

                To be successfully converted, a string can contain a combination of  numerical characters,
                possibly preceded by a minus sign (-).  Spaces are not allowed.

       Errors:   None.

    See also:    IntToStr (1555   ), StrToInt (1586   )



                                                                                1587

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.223            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 (1606   ) exception is
                raised.

    See also:    TryStrToQWord (1600   ), StrToQWordDef (1588   ), StrToInt64 (1587   ), StrToInt (1586   )



                38.13.224            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 (1588   ), TryStrToQWord (1600   ), StrToInt64Def (1587   ), StrToIntDef (1587   )



                38.13.225            StrToTime

    Synopsis:    Convert a time string to a TDateTime value.



                                                                                1588

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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 (1582   ), StrToDateTime (1583   ), TimeToStr (1594   )


                Listing:  ./sysutex/ex21.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 2 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e StrToTime         f u n c t i o n}


                Uses      s y s u t i l;s


                 P r o c e d u r eT e s t S t r (S   :   S t r i n g) ;


                 b e g i n
                    W r i t e l n (S  , '  :   ', TimeToStr      ( StrToTime       (S  ) ) ) ;
                end   ;


                Begin
                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.226            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.



                                                                                1589

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    StrToTime (1588   ), TryStrToTime (1601   ), StrToDateDef (1583   )



                38.13.227            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 (1577   )

       Errors:   None.

    See also:    StrLower (1577   )



                38.13.228            Supports

    Synopsis:    Check whether a class or given interface supports an interface

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 (1573   )



                                                                                1590

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.229            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 (1610   )



                38.13.230            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 (1503   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.231            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



                                                                                1591

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    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 (1585   ), FloatToStr (1531   ), FormatFloat (1544   )


                Listing:  ./sysutex/ex91.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 9 1;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e T e x t T o F l o a tf u n c t i o n }
                { $mode      o b j f p c}
                { $h  +  }


                Uses     S y s U t i l s;


                Const
                    N r V a l u e s=  5 ;
                    T e s t S t r :  A r r a y[ 1 . .N r V a l u e s]  o f  p c h a r=
                                    ( '1 , 1 ' ,' -0 ,2  ' ,' 1 , 2E-4   ', '0  ', '1 E4  ' ) ;


                 P r o c e d u r eT e s t i t;


                Var
                    I   :  I n t e g e r;
                    E   :  E x t e n d e d;


                 b e g i n
                    W r i t e l n(' U s i n g D e c i m a l S e p a r a t o r:  ', D e c i m a l S e p a r a t o)r;
                    For    I : = 1  t o  N r V a l u e sdo
                        b e g i n
                        W r i t e l n('C o n v e r t i n g :  ' ,T e s t S t r[ i] ) ;
                        I f  TextToFloat        ( T e s t S t r[i ] ,E )  then
                           W r i t e l n(' C o n v e r t e dv a l u e  :  ' ,E )
                        e l s e
                           W r i t e l n(' U n a b l e t o  c o n v e r t v a l u e. ') ;
                       end   ;
                end   ;


                Begin
                    D e c i m a l S e p a r a t o:r=', ' ;
                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.232            Time

    Synopsis:    Returns the current time.

Declaration:     function  Time  :  TDateTime



                                                                                1592

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    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 (1561   ), Date (1500   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.233            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 (1503   ).

       Errors:   None.

    See also:    DateTimeToTimeStamp (1503   ), TimeStampToMSecs (1594   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1593

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.234            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 (1560   ).

       Errors:   None.

    See also:    MSecsToTimeStamp (1560   ), TimeStampToDateTime (1593   )



                38.13.235            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___.____________________________________________________________________________________________________________*
 *___________



                38.13.236            Trim

    Synopsis:    Trim whitespace from the ends of a string.

Declaration:     function  Trim(const  S:  string)  :  string
                function  Trim(const  S:  widestring)  :  widestring

    Visibility:   default

Description:     Trim strips blank characters (spaces) at the beginning and end of S and returns the resulting
                string.  Only #32 characters are stripped.

                If the string contains only spaces, an empty string is returned.



                                                                                1594

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   None.

    See also:    TrimLeft (1595   ), TrimRight (1596   )


                Listing:  ./sysutex/ex84.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 8 4;


                {   T h i s  p r o g r a m d e m o n s t r a t e st h e Trim     f u n c t i o n }


                Uses      s y s u t i l;s
                { $H + }


                 P r o c e d u r eT e s t i t ( S   :  S t r i n g) ;


                 b e g i n
                    W r i t e l n ( '"  ', Trim   (S ) , '" ' ) ;
                end   ;


                Begin
                    T e s t i t ( '    ha   ha    what    g e t s  l o s t  ?   ') ;
                    T e s t i t(#10#13       'haha     ' ) ;
                    T e s t i t ( '                         ' ) ;
                End___.____________________________________________________________________________________________________________*
 *___________



                38.13.237            TrimLeft

    Synopsis:    Trim whitespace from the beginning of a string.

Declaration:     function  TrimLeft(const  S:  string)  :  string
                function  TrimLeft(const  S:  widestring)  :  widestring

    Visibility:   default

Description:     TrimLeft strips blank characters (spaces) at the beginning of  S and returns the resulting
                string.  Only #32 characters are stripped.  If the string contains only spaces, an empty string
                is returned.

       Errors:   None.

    See also:    Trim (1594   ), TrimRight (1596   )


                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



                                                                                1595

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                    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___.____________________________________________________________________________________________________________*
 *___________



                38.13.238            TrimRight

    Synopsis:    Trim whitespace from the end of a string.

Declaration:     function  TrimRight(const  S:  string)  :  string
                function  TrimRight(const  S:  widestring)  :  widestring

    Visibility:   default

Description:     Trim strips blank characters (spaces) at the end of S and returns the resulting string.  Only
                #32 characters are stripped.  If the string contains only spaces, an empty string is returned.

       Errors:   None.

    See also:    Trim (1594   ), TrimLeft (1595   )


                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.239            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 (1509   ), DecodeDateFully (1505   ), DecodeDate (1505   ), TryEncodeTime (1597   )



                                                                                1596

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.240            TryEncodeTime

    Synopsis:    Try to encode a time, and indicate success.

Declaration:     function  TryEncodeTime(Hour:  Word;Min:  Word;Sec:  Word;MSec:  Word;
                                                     out  Time:  TDateTime)  :  Boolean

    Visibility:   default

Description:     TryEncodeTime will check the validity of the Hour, Min, Sec and MSec arguments, and will
                encode them in a TDateTime value which is returned in 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 (1510   ), DecodeTime (1506   ), TryEncodeDate (1596   )



                38.13.241            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 (1460   )
                and MaxCurrency (1460   )).  If not, False is returned.

       Errors:   If  Value is out of range, False is returned.

    See also:    FloatToCurr (1530   ), MinCurrency (1460   ), MaxCurrency (1460   )



                38.13.242            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 (1573   )



                                                                                1597

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.243            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 (1472   ) (for False values) and True-
                BoolStrs (1476   ) (for True values) variables.

    See also:    StrToBool (1581   ), StrToBoolDef (1581   )



                38.13.244            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
                (1581   ), which raises an exception when the conversion fails.

                The function takes into account locale information.

    See also:    StrToCurr (1581   ), TextToFloat (1591   )



                38.13.245            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



                                                                                1598

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



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  (1582   ),  StrToTime  (1588   ),  TryStrToTime  (1601   ),  TryStrToDateTime  (1599   ),
                DateToStr (1504   ), TimeToStr (1594   )



                38.13.246            TryStrToDateTime

    Synopsis:    Try to convert a string with date/time indication to a TDateTime value

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  (1598   ),  TryStrToTime  (1601   ),  StrToDateTime  (1583   ),  StrToTime  (1588   ),
                DateToStr (1504   ), TimeToStr (1594   )



                38.13.247            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.



                                                                                1599

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



       Errors:   On error, False is returned.

    See also:    StrToFloat (1585   )



                38.13.248            TryStrToInt

    Synopsis:    Try to convert a string to an integer, and report on success.

Declaration:     function  TryStrToInt(const  s:  string;out  i:  Integer)  :  Boolean

    Visibility:   default

Description:     TryStrToInt tries to convert the string S to an integer, and returns True if this was succesful.
                In that case the converted integer is returned in I. If the conversion failed, (an invalid string,
                or the value is out of range) then False is returned.

       Errors:   None.  On error, False is returned.

    See also:    StrToInt (1586   ), TryStrToInt64 (1600   ), StrToIntDef (1587   ), StrToInt64 (1587   ), StrToInt64Def
                (1587   )



                38.13.249            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 (1587   ), StrToInt64Def (1587   ), StrToInt (1586   ), TryStrToInt (1600   ), StrToIntDef
                (1587   )



                38.13.250            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 (1588   ), StrToQWordDef (1588   ), TryStrToInt64 (1600   ), TryStrToInt (1600   )



                                                                                1600

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.251            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.

    See also:    TryStrToDate  (1598   ),  TryStrToDateTime  (1599   ),  StrToDate  (1582   ),  StrToTime  (1588   ),
                DateToStr (1504   ), TimeToStr (1594   )



                38.13.252            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.



                38.13.253            UpperCase

    Synopsis:    Return an uppercase version of a string.

Declaration:     function  UpperCase(const  s:  string)  :  string

    Visibility:   default

Description:     UpperCase returns the uppercase equivalent of S. Ansi characters are not taken into account,
                only ASCII codes below 127 are converted.  It is completely equivalent to the UpCase function
                of the system unit, and is provided for compatiibility only.

       Errors:   None.

    See also:    AnsiLowerCase (1482   ), LowerCase (1559   ), AnsiUpperCase (1490   )


                Listing:  ./sysutex/ex87.pp



                                                                                1601

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                ___________________________________________________________________________________________________________________*
 *___________
                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___.____________________________________________________________________________________________________________*
 *___________



                38.13.254            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  (1474   )  event  must  be  set,  and  an  appropriate  return  value
                must be returned.  The Vendor name is used in GetAppConfigDir (1546   ) and GetAppCon-
                figFile (1547   ) to determine the configuration directory.

       Errors:   If OnGetVendorName (1474   ) is not set, an empty string is returned.

    See also:    OnGetVendorName (1474   ), GetAppConfigDir (1546   ), GetAppConfigFile (1547   )



                38.13.255            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 (1603   ), the comparision is case sensitive.

       Errors:   None.

    See also:    WideCompareText (1603   ), WideSameStr (1604   ), WideSameText (1604   )



                                                                                1602

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.256            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 (1602   ), the comparision is case insensitive.

       Errors:   None.

    See also:    WideCompareStr (1602   ), WideSameStr (1604   ), WideSameText (1604   )



                38.13.257            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 (1603   ), WideFormatBuf (1604   ), Format (1536   )



                38.13.258            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 (1536   ) 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 (1536   ) string.

    See also:    Format (1536   )



                                                                                1603

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.13.259            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 (1603   ) 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 (1603   ), WideFormat (1603   ), Format (1536   ), FormatBuf (1543   )



                38.13.260            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 (1605   )



                38.13.261            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 (1602   ) returns 0 (zero), i.e.  when S1 and S2
                are the same string (taking into account case).

    See also:    WideSameText (1604   ),  WideCompareStr (1602   ),  WideCompareText (1603   ),  AnsiSameStr
                (1483   )



                38.13.262            WideSameText

    Synopsis:    Check whether two widestrings are the same (ignoring case)

Declaration:     function  WideSameText(const  s1:  WideString;const  s2:  WideString)
                                                     :  Boolean



                                                                                1604

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    Visibility:  default

Description:     WideSameText returns True if WideCompareText (1603   ) returns 0 (zero), i.e.  when S1 and
                S2 are the same string (taking into account case).

    See also:    WideSameStr (1604   ),  WideCompareStr (1602   ),  WideCompareText (1603   ),  AnsiSameText
                (1483   )



                38.13.263            WideUpperCase

    Synopsis:    Change a widestring to all-lowercase.

Declaration:     function  WideUpperCase(const  s:  WideString)  :  WideString

    Visibility:   default

Description:     WideUpperCase  converts  the  string  S  to  uppercase  characters  and  returns  the  resulting
                string.   It  takes  into  account  the  operating  system  language  settings  when  doing  this,  so
                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 (1604   )



                38.13.264            WrapText

    Synopsis:    Word-wrap a text.

Declaration:     function  WrapText(const  Line:  string;const  BreakStr:  string;
                                            const  BreakChars:  TSysCharSet;MaxCol:  Integer)  :  string
                function  WrapText(const  Line:  string;MaxCol:  Integer)  :  string

    Visibility:   default

Description:     WrapText does a wordwrap at column MaxCol of the string in Line.  It breaks the string
                only  at  characters  which  are  in  BreakChars  (default  whitespace  and  hyphen)  and  inserts
                then the string BreakStr (default the lineending character for the current OS).

    See also:    StringReplace (1573   )



                38.14            EAbort



                38.14.1          Description

                Abort  is  raised  by  the  Abort  (1476   )  procedure.   It  is  not  displayed  in  GUI  applications,
                and serves only to immediatly abort the current procedure, and return control to the main
                program loop.


    See also:    Abort (1476   )



                                                                                1605

_______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________________________*
 *___



38.15            EAbstractError



38.15.1          Description

EAbstractError is raised when an abstract error occurs, i.e.  when an unimplemented ab-
stract method is called.



38.16            EAccessViolation



38.16.1          Description

EAccessViolation  is  raised  when  the  OS  reports  an  Access  Violation,  i.e.   when  invalid
memory is accessed.



38.17            EAssertionFailed



38.17.1          Description

EAssertionFailed is raised when an application that is compiled with assertions, encounters
an invalid assertion.



38.18            EBusError



38.18.1          Description

EBusError is raised in case of a bus error.



38.19            EControlC



38.19.1          Description

EControlC is raised when the user has pressed CTRL-C in a console application.



38.20            EConvertError



38.20.1          Description

EConvertError is raised by the various conversion routines in the SysUtils unit.  The message
will contain more specific error information.



38.21            EDivByZero



38.21.1          Description

EDivByZero is used when the operating system or CPU signals a division by zero error.



                                                                1606

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.22            EExternal



                38.22.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 (1608   ), EExternal (1607   ), EMathError (1609   ), EExternalException (1607   ), EAc-
                cessViolation (1606   ), EPrivilege (1610   ), EStackOverflow (1611   ), EControlC (1606   )



                38.23            EExternalException



                38.23.1          Description

                EExternalException is raised when an external routine raises an exception.


    See also:    EExternal (1607   )



                38.24            EFormatError



                38.24.1          Description

                EformatError is raised in case of an error in one of the various Format (1536   ) functions.


    See also:    Format (1536   )



                38.25            EHeapMemoryError



                38.25.1          Description

                EHeapMemoryError is raised when an error occurs in heap (dynamically allocated) memory.


    See also:    EHeapException (1464   ), EoutOfMemory (1610   ), EInvalidPointer (1609   )



                38.25.2          Method  overview

                __Page______Property______________Description______________________________________________________________________*
 *___________
                __1607______FreeInstance__________Free_the_exception_instance______________________________________________________*
 *___________



                38.25.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.



                                                                                1607

            _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            38.26            EInOutError



            38.26.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 (1 ).


See also:    EInOutError.ErrorCode (1 )



            38.27            EInterror



            38.27.1          Description

            EInterror  is  used  when  the  operating  system  or  CPU  signals  an  integer  operation  error,
            e.g., an overflow.



            38.28            EIntfCastError



            38.28.1          Description

            EIntfCastError is raised when an invalid interface cast is encountered.


See also:    EInvalidCast (1608   )



            38.29            EIntOverflow



            38.29.1          Description

            EIntOverflow is used when the operating system or CPU signals a integer overflow error.


See also:    EIntError (1608   ), EDivByZero (1606   ), ERangeError (1611   )



            38.30            EInvalidCast



            38.30.1          Description

            EInvalidCast is raised when an invalid typecast error (using the as operator) is encountered.


See also:    EIntfCastError (1608   )



            38.31            EInvalidContainer



            38.31.1          Description

            EInvalidContainer is not yet used by Free Pascal, and is provided for Delphi compatibility
            only.



                                                                            1608

            _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            38.32            EInvalidInsert



            38.32.1          Description

            EInvalidInsert  is  not  yet  used  by  Free  Pascal,  and  is  provided  for  Delphi  compatibility
            only.



            38.33            EInvalidOp



            38.33.1          Description

            EInvalidOp is raised when an invalid operation is encountered.



            38.34            EInvalidPointer



            38.34.1          Description

            EInvalidPointer is raised when an invalid heap pointer is used.

See also:    EHeapException (1464   ), EHeapMemoryError (1607   ), EOutOfMemory (1610   )



            38.35            EMathError



            38.35.1          Description

            EMathError  is  used  when  the  operating  system  or  CPU  signals  a  floating  point  overflow
            error.

See also:    EIntError (1608   ), EIntOverflow (1608   ), EDivByZero (1606   ), ERangeError (1611   )



            38.36            ENoThreadSupport



            38.36.1          Description

            ENoThreadSupport is raised when some thread routines are invoked, and thread support was
            not enabled when the program was compiled.



            38.37            ENotImplemented



            38.37.1          Description

            ENotImplemented can be used to raise an exception when a particular call had been defined,
            but was not implemented.



            38.38            ENoWideStringSupport



            38.38.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.



                                                                            1609

            _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_____________________*
 *_______________



            38.39            EOSError



            38.39.1          Description

            EOSError  is  raised  when  some  Operating  System  call  fails.   The  ErrorCode  (1 )  property
            contains the operating system error code.


See also:    EOSError.ErrorCode (1 )



            38.40            EOutOfMemory



            38.40.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 (1464   ), EHeapMemoryError (1607   ), EInvalidPointer (1609   )



            38.41            EOverflow



            38.41.1          Description

            EOverflow occurs when a float operation overflows.  (i.e.  result is too big to represent).


See also:    EIntError (1608   ), EIntOverflow (1608   ), EDivByZero (1606   ), ERangeError (1611   ), EUnder-
            Flow (1611   )



            38.42            EPackageError



            38.42.1          Description

            EPackageError is not yet used by Free Pascal, and is provided for Delphi compatibility only.



            38.43            EPrivilege



            38.43.1          Description

            EPrivilege is raised when the OS reports that an invalid instruction was executed.



            38.44            EPropReadOnly



            38.44.1          Description

            EPropReadOnly is raised when an attempt is made to write to a read-only property.



            38.45            EPropWriteOnly



            38.45.1          Description

            EPropWriteOnly is raised when an attempt is made to read from a write-only property.



                                                                            1610

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    EPropReadOnly (1610   )



                38.46            ERangeError



                38.46.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 (1608   ), EDivByZero (1606   ), EIntOverflow (1608   )



                38.47            ESafecallException



                38.47.1          Description

                ESafecallException is not yet used by Free Pascal, and is provided for Delphi compatibility
                only.



                38.48            EStackOverflow



                38.48.1          Description

                EStackOverflow occurs when the stack has grown too big (e.g.  by infinite recursion).



                38.49            EUnderflow



                38.49.1          Description

                EOverflow occurs when a float operation underflows (i.e.  result is too small to represent).


    See also:    EIntError (1608   ), EIntOverflow (1608   ), EDivByZero (1606   ), ERangeError (1611   ), EOver-
                Flow (1610   )



                38.50            EVariantError



                38.50.1          Description

                EVariantError is raised by the internal variant routines.



                38.50.2          Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                __1611______CreateCode__________Create_an_instance_of_EVariantError_with_a_particular_error_code.__________________*
 *___________



                38.50.3          EVariantError.CreateCode

    Synopsis:    Create an instance of  EVariantError with a particular error code.

Declaration:     constructor  CreateCode(Code:  LongInt)



                                                                                1611

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    Visibility:  default

Description:     CreateCode calls the inherited constructor, and sets the ErrCode (1 ) property to Code.

    See also:    ErrCode (1 )



                38.51            Exception



                38.51.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 (1512   ), ExceptAddr (1511   ), ExceptionErrorMessage (1512   ), ShowException
                (1566   ), Abort (1476   )



                38.51.2          Method  overview

                __Page______Property______________________Description______________________________________________________________*
 *___________
                  1612      Create                        Constructs a new exception object with a given message.
                  1613      CreateFmt                     Constructs a new exception object and formats a new mes-
                                                          sage.
                  1614      CreateFmtHelp                 Constructs a new exception object and sets the help context
                                                          and formats the message
                  1613      CreateHelp                    Constructs a new exception object and sets the help context.
                  1613      CreateRes                     Constructs  a  new  exception  object  and  gets  the  message
                                                          from a resource.
                  1613      CreateResFmt                  Constructs a new exception object and formats the message
                                                          from a reasource.
                  1614      CreateResFmtHelp              Constructs a new exception object and sets the help context
                                                          and formats the message from a resource
                  1614      CreateResHelp                 Constructs a new exception object and sets the help context
                __________________________________________and_gets_the_message_from_a_resource_____________________________________*
 *___________



                38.51.3          Property  overview

                __Page______Property______________Access______Description__________________________________________________________*
 *___________
                  1614      HelpContext           rw          Help context associated with the exception.
                __1615______Message_______________rw__________Message_associated_with_the_exception._______________________________*
 *___________



                38.51.4          Exception.Create

    Synopsis:    Constructs a new exception object with a given message.

Declaration:     constructor  Create(const  msg:  string)

    Visibility:   public

       Errors:   Construction may fail if there is not enough memory on the heap.



                                                                                1612

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



    See also:    Exception.CreateFmt (1 ), Exception.Message (1 )



                38.51.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 (1 ), Exception.Message (1 ), Format (1536   )



                38.51.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 (1 ), Exception.CreateFmt (1 ), Exception.CreateResFmt (1 ), Exception.Message
                (1 )



                38.51.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 (1 ), but fetches the message from the resource
                string ResString.

       Errors:   Construction may fail if there is not enough memory on the heap.

    See also:    Exception.Create (1 ), Exception.CreateFmt (1 ), Exception.CreateRes (1 ), Exception.Message
                (1 )



                38.51.8          Exception.CreateHelp

    Synopsis:    Constructs a new exception object and sets the help context.

Declaration:     constructor  CreateHelp(const  Msg:  string;AHelpContext:  Integer)

    Visibility:   public

Description:     CreateHelp does the same as the Create (1 ) constructor, but additionally stores AHelpContext
                in the HelpContext (1 ) property.

    See also:    Exception.Create (1 )



                                                                                1613

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.51.9          Exception.CreateFmtHelp

    Synopsis:    Constructs a new exception object and sets the help context and formats the message

Declaration:     constructor  CreateFmtHelp(const  Msg:  string;const  Args:  Array  of  const;
                                                         AHelpContext:  Integer)

    Visibility:   public

Description:     CreateFmtHelp  does  the  same  as  the  CreateFmt  (1 )  constructor,  but  additionally  stores
                AHelpContext in the HelpContext (1 ) property.

    See also:    Exception.CreateFmt (1 )



                38.51.10           Exception.CreateResHelp

    Synopsis:    Constructs a new exception object and sets the help context and gets the message from a
                resource

Declaration:     constructor  CreateResHelp(ResString:  PString;AHelpContext:  Integer)

    Visibility:   public

Description:     CreateResHelp  does  the  same  as  the  CreateRes  (1 )  constructor,  but  additionally  stores
                AHelpContext in the HelpContext (1 ) property.

    See also:    Exception.CreateRes (1 )



                38.51.11           Exception.CreateResFmtHelp

    Synopsis:    Constructs a new exception object and sets the help context and formats the message from
                a resource

Declaration:     constructor  CreateResFmtHelp(ResString:  PString;
                                                              const  Args:  Array  of  const;
                                                              AHelpContext:  Integer)

    Visibility:   public

Description:     CreateResFmtHelp  does  the  same  as  the  CreateResFmt  (1 )  constructor,  but  additionally
                stores AHelpContext in the HelpContext (1 ) property.

    See also:    Exception.CreateResFmt (1 )



                38.51.12           Exception.HelpContext

    Synopsis:    Help context associated with the exception.

Declaration:     Property  HelpContext  :  LongInt

    Visibility:   public

      Access:    Read,Write

Description:     HelpContext is the help context associated with the exception, and can be used to provide
                context-sensitive help when the exception error message is displayed.  It should be set in the
                exception constructor.

    See also:    Exception.CreateHelp (1 ), Exception.Message (1 )



                                                                                1614

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.51.13           Exception.Message

    Synopsis:    Message associated with the exception.

Declaration:     Property  Message  :  string

    Visibility:   public

      Access:    Read,Write

Description:     Message provides additional information about the exception.  It is shown to the user in e.g.
                the ShowException (1566   ) routine, and should be set in the constructor when the exception
                is raised.

    See also:    Exception.Create (1 ), Exception.HelpContext (1 )



                38.52            EZeroDivide



                38.52.1          Description

                EZeroDivide occurs when a float division by zero occurs.


    See also:    EIntError (1608   ), EIntOverflow (1608   ), EDivByZero (1606   ), ERangeError (1611   )



                38.53            IReadWriteSync



                38.53.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.



                38.53.2          Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  1615      BeginRead           Start a read operation.
                  1616      BeginWrite          Start a write operation.
                  1616      EndRead             End a read operation
                __1616______EndWrite____________End_a_write_operation._____________________________________________________________*
 *___________



                38.53.3          IReadWriteSync.BeginRead

    Synopsis:    Start a read operation.

Declaration:     procedure  BeginRead

    Visibility:   default

Description:     BeginRead indicates that a read operation is about to be started.  If a write operation is
                in  progress,  then  the  call  will  block  untill  the  write  operation  finished.  Depending  on  the
                implementation the call may also block if another read operation is in progress.

                After BeginRead, any write operation started with BeginWrite (1 ) will block until EndRead
                (1 ) is called.

    See also:    IReadWriteSync.EndRead (1 ), IReadWriteSync.BeginWrite (1 ), IReadWriteSync.EndWrite
                (1 )



                                                                                1615

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.53.4          IReadWriteSync.EndRead

    Synopsis:    End a read operation

Declaration:     procedure  EndRead

    Visibility:   default

Description:     EndRead signals the end of a read operation.  If there was any blocked write operation, that
                will be unblocked by a call to EndRead.

    See also:    IReadWriteSync.BeginRead (1 ), IReadWriteSync.BeginWrite (1 ), IReadWriteSync.EndWrite
                (1 )



                38.53.5          IReadWriteSync.BeginWrite

    Synopsis:    Start a write operation.

Declaration:     function  BeginWrite  :  Boolean

    Visibility:   default

Description:     BeginWrite  signals  the  begin  of  a  write  operation.  This  call  will  block  if  any  other  read
                or write operation is currently in progress.  It will resumt only after all other read or write
                operations have finished.

    See also:    IReadWriteSync.EndRead (1 ), IReadWriteSync.EndWrite (1 ), IReadWriteSync.BeginRead
                (1 )



                38.53.6          IReadWriteSync.EndWrite

    Synopsis:    End a write operation.

Declaration:     procedure  EndWrite

    Visibility:   default

Description:     EndWrite signals the end of a write operation.  After the call to EndWrite any other read
                or write operations can start.

    See also:    IReadWriteSync.EndRead (1 ), IReadWriteSync.EndWrite (1 ), IReadWriteSync.BeginRead
                (1 )



                38.54            TMultiReadExclusiveWriteSynchronizer



                38.54.1          Description

                TMultiReadExclusiveWriteSynchronizer is a default implementation of the IReadWriteSync
                (1615   ) 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 (1615   )



                38.54.2          Interfaces  overview

                __Page______Property___________________Description_________________________________________________________________*
 *___________
                __1615______IReadWriteSync_____________Read/Write_synchronizer_____________________________________________________*
 *___________



                                                                                1616

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.54.3          Method  overview

                __Page______Property___________Description_________________________________________________________________________*
 *___________
                  1618      Beginread          Request read access to the resource
                  1617      Beginwrite         Request write access to the resource.
                  1617      Create             Create a new instance of the TMultiReadExclusiveWriteSynchronizer
                                               class
                  1617      Destroy            Destroys the TMultiReadExclusiveWriteSynchronizer instance
                  1618      Endread            Release read access to the resource
                __1618______Endwrite___________Release_write_access_to_the_resource________________________________________________*
 *___________



                38.54.4          TMultiReadExclusiveWriteSynchronizer.Create

    Synopsis:    Create a new instance of the TMultiReadExclusiveWriteSynchronizer class

Declaration:     constructor  Create;    Virtual

    Visibility:   public

Description:     Create creates a new instance of  TMultiReadExclusiveWriteSynchronizer.  It initializes
                a TRTLCriticalSection.

       Errors:   None.

    See also:    TRTLCriticalSection (1272   )



                38.54.5          TMultiReadExclusiveWriteSynchronizer.Destroy

    Synopsis:    Destroys the TMultiReadExclusiveWriteSynchronizer instance

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Create  destroys  the  instance  of  TMultiReadExclusiveWriteSynchronizer.   It  frees  the
                TRTLCriticalSection it initialized, and calls the inherited destructor.

       Errors:   None.

    See also:    TRTLCriticalSection (1272   )



                38.54.6          TMultiReadExclusiveWriteSynchronizer.Beginwrite

    Synopsis:    Request write access to the resource.

Declaration:     function  Beginwrite  :  Boolean

    Visibility:   public

Description:     Beginwrite is the implementation of  IReadWriteSync.BeginWrite.  It simply enters the
                critical section, and returns True.

       Errors:   None.

    See also:    IReadWriteSync.BeginWrite (1 ), EndWrite (1 )



                                                                                1617

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.54.7          TMultiReadExclusiveWriteSynchronizer.Endwrite

    Synopsis:    Release write access to the resource

Declaration:     procedure  Endwrite

    Visibility:   public

Description:     Beginwrite  is  the  implementation  of  IReadWriteSync.EndWrite.   It  simply  leaves  the
                critical section.

       Errors:   None.

    See also:    IReadWriteSync.EndWrite (1 ), BeginWrite (1 )



                38.54.8          TMultiReadExclusiveWriteSynchronizer.Beginread

    Synopsis:    Request read access to the resource

Declaration:     procedure  Beginread

    Visibility:   public

Description:     BeginRead  is  the  implementation  of  IReadWriteSync.BeginRead.  It  simply  attempts  to
                enter the critical section.

       Errors:   None.

    See also:    IReadWriteSync.BeginRead (1 ), EndRead (1 )



                38.54.9          TMultiReadExclusiveWriteSynchronizer.Endread

    Synopsis:    Release read access to the resource

Declaration:     procedure  Endread

    Visibility:   public

Description:     EndRead is the implementation of  IReadWriteSync.EndRead.  It simply leaves the critical
                section.

       Errors:   None.

    See also:    IReadWriteSync.EndRead (1 ), BeginRead (1 )



                38.55            TSimpleRWSync



                38.55.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 (1616   )



                                                                                1618

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.55.2          Interfaces  overview

                __Page______Property___________________Description_________________________________________________________________*
 *___________
                __1615______IReadWriteSync_____________Read/Write_synchronizer_____________________________________________________*
 *___________



                38.55.3          Method  overview

                __Page______Property___________Description_________________________________________________________________________*
 *___________
                  1620      Beginread          Acquire a read lock
                  1619      Beginwrite         Acquire a write lock
                  1619      Create             Create a new instance of  TSimpleRWSync
                  1619      Destroy            Removes the TSimpleRWSync instance from memory
                  1620      Endread            Release the read lock
                __1620______Endwrite___________Release_the_write_lock______________________________________________________________*
 *___________



                38.55.4          TSimpleRWSync.Create

    Synopsis:    Create a new instance of  TSimpleRWSync

Declaration:     constructor  Create;    Virtual

    Visibility:   public

Description:     Create  allocates  a  new  instance  of  TSimpleRWSync  and  initializes  the  critical  section  for
                use in the various methods.

    See also:    TSimpleRWSync.Destroy (1 )



                38.55.5          TSimpleRWSync.Destroy

    Synopsis:    Removes the TSimpleRWSync instance from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy releases the critical section and removes the TSimpleRWSync instance from memory.

    See also:    TSimpleRWSync.Create (1 )



                38.55.6          TSimpleRWSync.Beginwrite

    Synopsis:    Acquire a write lock

Declaration:     function  Beginwrite  :  Boolean

    Visibility:   public

Description:     Beginwrite waits till all other threads have released their read or write locks on the object,
                and then aquires a write lock on the object.

    See also:    TSimpleRWSync.BeginRead (1 ), TSimpleRWSync.EndWrite (1 )



                                                                                1619

                _______________________________________________________CHAPTER_38.___REFERENCE_FOR_UNIT_'SYSUTILS'_________________*
 *___________________



                38.55.7          TSimpleRWSync.Endwrite

    Synopsis:    Release the write lock

Declaration:     procedure  Endwrite

    Visibility:   public

Description:     EndWrite releases the current threads lock on the object, allowing other threads to acquire
                a read or write lock on the object.

    See also:    TSimpleRWSync.BeginWrite (1 ), TSimpleRWSync.EndRead (1 )



                38.55.8          TSimpleRWSync.Beginread

    Synopsis:    Acquire a read lock

Declaration:     procedure  Beginread

    Visibility:   public

Description:     BeginRead waits till all other threads have released their read or write locks on the object,
                and then aquires a read lock on the object.

    See also:    TSimpleRWSync.BeginWrite (1 ), TSimpleRWSync.EndRead (1 )



                38.55.9          TSimpleRWSync.Endread

    Synopsis:    Release the read lock

Declaration:     procedure  Endread

    Visibility:   public

Description:     EndRead  releases  the  current  threads  read  lock  on  the  object,  allowing  other  threads  to
                acquire a read or write lock on the object.

    See also:    TSimpleRWSync.BeginRead (1 ), TSimpleRWSync.EndWrite (1 )



                                                                                1620




Chapter   39



Reference   for   unit   'types'



39.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.



39.2          Constants,  types  and  variables



39.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.


RT_RCDATA  =  (10)



                                                            1621

____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



Resource type RCDATA


STATFLAG_DEFAULT  =  0


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)



                                                                1622

____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



Defined for Delphi compatibility, this should not be used.


STG_E_EXTANTMARSHALLINGS  =  ($80030108)


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)



                                                                1623

____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



Defined for Delphi compatibility, this should not be used.


STG_E_LOCKVIOLATION  =  ($80030021)


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)



                                                                1624

____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



Defined for Delphi compatibility, this should not be used.


STG_E_TERMINATED  =  ($80030202)


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.



                                                                1625

____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



39.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



                                                                1626

____________________________________________________________CHAPTER_39.___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 (1630   ) type.


PPOleStr  =  ^POleStr


PPOleStr is a typed pointer to a POleStr variable.


PRect  =  ^TRect


PRect is a typed pointer to the TRect (1630   ) type.


PSize  =  ^TSize


PSize is a typed pointer to the TSize (1631   ) 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 (1631   ) record.



                                                                1627

____________________________________________________________CHAPTER_39.___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 (1630   )


tagSIZE  =  TSize


tagSize is an alias for the TSize (1631   ) 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 (1 ) 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



                                                                1628

____________________________________________________________CHAPTER_39.___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 (1269   ) 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 39.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 (1630   )


TListStaticCallback  =  procedure(data:  pointer;arg:  pointer)



                                                                1629

____________________________________________________________CHAPTER_39.___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 (1629   )


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
end



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



                                                                1630

____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________________________*
 *___



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  (1630   ),  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 (1 )
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


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



                                                                1631

                ____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                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.



                39.3          Procedures  and  functions



                39.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 (1634   ), PtInRect (1634   ), IntersectRect (1633   ), UnionRect (1635   )



                39.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 (1634   ), IntersectRect (1633   ), IsRectEmpty (1633   ), OffsetRect (1634   ), InflateRect
                (1633   ), Size (1635   ), IsRectEmpty (1633   )



                                                                                1632

                ____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                39.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 (1634   ), Bounds (1632   ), PtInRect (1634   ), IntersectRect (1633   ), UnionRect (1635   ), Is-
                RectEmpty (1633   ), OffsetRect (1634   ), InflateRect (1633   ), Size (1635   )



                39.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 (1634   ), IntersectRect (1633   ), IsRectEmpty (1633   ), OffsetRect (1634   ), CenterPoint
                (1632   ), Size (1635   ), IsRectEmpty (1633   )



                39.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  (1634   ),  UnionRect  (1635   ),  IsRectEmpty  (1633   ),  OffsetRect  (1634   ),  InflateRect
                (1633   ), Size (1635   )



                39.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 (1634   ), IntersectRect (1633   ), IsRectEmpty (1633   ), OffsetRect (1634   ), InflateRect
                (1633   ), Size (1635   )



                                                                                1633

                ____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                39.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 (1634   ), IntersectRect (1633   ), IsRectEmpty (1633   ), OffsetRect (1634   ), InflateRect
                (1633   ), Size (1635   ), IsRectEmpty (1633   )



                39.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 (1634   ), PtInRect (1634   )



                39.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,0
                will be.

    See also:    IntersectRect (1633   ), UnionRect (1635   ), IsRectEmpty (1633   ), OffsetRect (1634   ), InflateRect
                (1633   ), Size (1635   )



                39.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  (1632   ),  PtInRect  (1634   ),  IntersectRect  (1633   ),  UnionRect  (1635   ),  IsRectEmpty
                (1633   ), OffsetRect (1634   ), InflateRect (1633   ), Size (1635   )



                                                                                1634

                ____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                39.3.11          Size

    Synopsis:    Return the size of the rectangle

Declaration:     function  Size(AWidth:  Integer;AHeight:  Integer)  :  TSize
                function  Size(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 (1634   ), IntersectRect (1633   ), IsRectEmpty (1633   ), OffsetRect (1634   ), InflateRect
                (1633   ), CenterPoint (1632   ), IsRectEmpty (1633   )



                39.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 (1634   ), IntersectRect (1633   ), IsRectEmpty (1633   ), OffsetRect (1634   ), InflateRect
                (1633   ), Size (1635   )



                39.4          IClassFactory



                39.4.1         Description

                IClassFactory is defined for Delphi/Kylix compatibility and should not be used.



                39.4.2         Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  1635      CreateInstance           Create a new instance of an interface.
                __1636______LockServer_______________Lock_ActiveX_server_object.___________________________________________________*
 *___________



                39.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.



                                                                                1635

                ____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                39.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.



                39.5          ISequentialStream



                39.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 (1637   )



                39.5.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  1636      Read            Read data from the stream
                __1636______Write___________Write_data_to_the_stream_______________________________________________________________*
 *___________



                39.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 (1 )



                39.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 (1 )



                                                                                1636

                ____________________________________________________________CHAPTER_39.___REFERENCE_FOR_UNIT_'TYPES'_______________*
 *___________________



                39.6          IStream



                39.6.1         Description

                An  abstract  interface  for  an  external  (non  pascal)  stream,  as  defined  in  Microsoft  COM
                interfaces



                39.6.2         Method  overview

                __Page______Property_______________Description_____________________________________________________________________*
 *___________
                  1639      Clone                  Clone the stream instance
                  1638      Commit                 Commit data to the stream
                  1637      CopyTo                 Copy data from one stream to another
                  1638      LockRegion             Lock a region of bytes in the stream
                  1638      Revert                 Revert changes
                  1637      Seek                   Set the stream position
                  1637      SetSize                Set the stream size
                  1639      Stat                   return information about the stream.
                __1638______UnlockRegion___________Unlocks_a_previously_locked_region_of_bytes_in_the_stream_______________________*
 *___________



                39.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.



                39.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.



                39.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



                                                                                1637

                ____________________________________________________________CHAPTER_39.___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.



                39.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.



                39.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.



                39.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.



                39.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



                                                                                1638

                ____________________________________________________________CHAPTER_39.___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.



                39.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.



                39.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.



                                                                                1639




Chapter   40



Reference   for   unit   'typinfo'



40.1          Used  units



                                    Table 40.1:  Used units by unit 'typinfo'


                                                   __Name__________Page_____
                                                     System        1230
                                                     sysutils      1450



40.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.



40.3          Auxiliary  functions


Other typinfo related functions.



                                                            1640

________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



                                                       Table 40.2:



__Name_______________________________________Description___________________________________________________________________________*
 *____
  GetEnumName (1650   )                      Get an enumerated type element name
  GetEnumValue (1652   )                     Get ordinal number of an enumerated type, based on the name.
  GetEnumNameCount (1651   )                 Get number of elements in an enumerated type.
  GetTypeData (1664   )                      Skip type name and return a pointer to the type data
  SetToString (1674   )                      Convert a set to its string representation
  StringToSet (1676   )                      Convert a string representation of a set to a set



40.4          Getting  or  setting  property  values


Functions to set or set a property's value.



                                                       Table 40.3:

         __Name________________________________Description____________________________________________________________
           GetEnumProp (1651   )                Return the value of an enumerated type property
           GetFloatProp (1652   )               Return the value of a float property
           GetInt64Prop (1653   )               Return the value of an Int64 property
           GetMethodProp (1654   )              Return the value of a procedural type property
           GetObjectProp (1656   )              Return the value of an object property
           GetOrdProp (1658   )                 Return the value of an ordinal type property
           GetPropValue (1662   )               Return the value of a property as a variant
           GetSetProp (1662   )                 Return the value of a set property
           GetStrProp (1663   )                 Return the value of a string property
           GetWideStrProp (1665   )             Return the value of a widestring property
           GetVariantProp (1665   )             Return the value of a variant property
           SetEnumProp (1669   )                Set the value of an enumerated type property
           SetFloatProp (1669   )               Set the value of a float property
           SetInt64Prop (1670   )               Set the value of an Int64 property
           SetMethodProp (1671   )              Set the value of a procedural type property
           SetObjectProp (1671   )              Set the value of an object property
           SetOrdProp (1672   )                 Set the value of an ordinal type property
           SetPropValue (1672   )               Set the value of a property trhough a variant
           SetSetProp (1673   )                 Set the value of a set property
           SetStrProp (1673   )                 Set the value of a string property
           SetWideStrProp (1675   )             Set the value of a widestring property
           SetVariantProp (1675   )             Set the value of a variant property



40.5          Examining  published  property  information


Functions for retrieving or examining property information



                                                                1641

________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



                                                       Table 40.4:

  _Name______________________________________Description______________________________________________________________________
    FindPropInfo (1649   )                    Getting property type information, With error checking.
    GetPropInfo (1659   )                     Getting property type information, No error checking.
    GetPropInfos (1659   )                    Find property information of a certain kind
    GetObjectPropClass (1657   )              Return the declared class of an object property
    GetPropList (1660   )                     Get a list of all published properties
    IsPublishedProp (1666   )                 Is a property published
    IsStoredProp (1666   )                    Is a property stored
    PropIsType (1667   )                      Is a property of a certain kind
    PropType (1668   )                        Return the type of a property



40.6          Constants,  types  and  variables



40.6.1         Constants

BooleanIdents  :  Array[Boolean]  of    =  ('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 (1662   ) 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 (1665   ) 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 (1672   ) 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 (1665   ) function.


ptConst  =  3


Constant used in acces method


ptField  =  0



                                                                1642

________________________________________________________CHAPTER_40.___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)


tkProperties  =  tkAny  -  tkMethods  -  [tkUnknown]


Real properties.  (not methods)


tkString  =  tkSString


Alias for the tsSString enumeration value



40.6.2         Types

PPropInfo  =  ^TPropInfo


Pointer to TPropInfo (1647   ) record


PPropList  =  ^TPropList


Pointer to TPropList (1647   )


PPTypeInfo  =  ^PTypeInfo


Pointer to PTypeInfo (1643   ) pointer


PTypeData  =  ^TTypeData


Pointer to TTypeData (1647   ) record.


PTypeInfo  =  ^TTypeInfo


Pointer to TTypeInfo (1647   ) record


PVmtFieldEntry  =  ^TVmtFieldEntry



                                                                1643

________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



Pointer to #rtl.typinfo.TVmtFieldEntry (1648   ) type.


PVmtFieldTable  =  ^TVmtFieldTable


Pointer to #rtl.typinfo.TVmtFieldTable (1649   ) type.


ShortStringBase  =  string


ShortStringBase is the base definition of a short string.


TCallConv  =  (ccReg,ccCdecl,ccPascal,ccStdCall,ccSafeCall,ccCppdecl,
                     ccFar16,ccOldFPCCall,ccInternProc,ccSysCall,ccSoftFloat,
                     ccMWPascal)



                           Table 40.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.



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 40.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



                                                                1644

________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



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 40.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 (1645   ).


TIntfFlagsBase  =  Set  of  TIntfFlag


Set of TIntfFlag (1645   ).


TMethodKind  =  (mkProcedure,mkFunction,mkConstructor,mkDestructor,
                        mkClassProcedure,mkClassFunction,mkClassConstructor,
                        mkClassDestructor,mkOperatorOverload)



                        Table 40.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



                                                                1645

________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



TOrdType  =  (otSByte,otUByte,otSWord,otUWord,otSLong,otULong)



                           Table 40.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)



                         Table 40.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


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.



                                                                1646

________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



TPropInfo  =  packed  record
   PropType  :  PTypeInfo;
   GetProc  :  Pointer;
   SetProc  :  Pointer;
   StoredProc  :  Pointer;
   Index  :  Integer;
   Default  :  LongInt;
   NameIndex  :  SmallInt;
   PropProcs  :  Byte;
   Name  :  ShortString;
end



The TPropInfo record describes one published property of a class.  The property information
of a class are stored as an array of  TPropInfo records.

The Name field is stored not with 255 characters, but with just as many characters as required
to store the name.


TPropList  =  Array[0..65535]  of  PPropInfo


Array of property information pointers


TSetPropValue  =  procedure(Instance:  TObject;const  PropName:  string;
                                          const  Value:  Variant)


The callback function must set the property with name PropName of instance Instance to
Value.


TSetVariantProp  =  procedure(Instance:  TObject;PropInfo:  PPropInfo;
                                              const  Value:  Variant)


The  callback  function  must  set  the  variant  property  with  name  PropName  of  instance  to
Value.


TTypeData  =  packed  record
end



If the typeinfo kind is tkClass, then the property information follows the UnitName string,
as an array of TPropInfo (1647   ) records.


TTypeInfo  =  record
   Kind  :  TTypeKind;
   Name  :  ShortString;
end



The TypeInfo function returns a pointer to a TTypeInfo record.

Note  that  the  Name  field  is  stored  with  as  much  bytes  as  needed  to  store  the  name,  it  is
not padded to 255 characters.  The type data immediatly follows the TTypeInfo record as a
TTypeData (1647   ) record.



                                                                1647

________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________________________*
 *___



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)



                         Table 40.11:  Enumeration values for type TTypeKind


                              __Value___________________Explanation______________________________
                                tkArray                  Array property.
                                tkAString                Ansistring property.
                                tkBool                   Boolean property.
                                tkChar                   Char property.
                                tkClass                  Class property.
                                tkDynArray               Dynamical array property.
                                tkEnumeration            Enumeration type property.
                                tkFloat                  Float property.
                                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.
                                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 (1648   ) 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.



                                                                1648

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                TVmtFieldTable  =  packed  record
                   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 (1648   ) values.



                40.7          Procedures  and  functions



                40.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
                (1659   ) 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 (1659   ), GetPropList (1660   ), GetPropInfos (1659   )


                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



                                                                                1649

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                    O   :  TMyTestObject          ;
                    PT   :   PTypeData       ;
                    PI   :   P P r o p I n f o;
                    I ,J   :   L o n g i n t;
                    PP   :   P P r o p L i s t;
                    p r I  :   P P r o p I n f;o


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    PI :=  F i n d P r o p I n f(oO ,' B o o l e a n F i e l'd) ;
                    W r i t e l n(' F i n d P r o p I n f(oI n s t a n c,eB o o l e a n F i e l)d :   ' ,PI  ^ .Name    ) ;
                    PI :=  F i n d P r o p I n f(oO .C l a s s T y p e,'B y t e F i e l d') ;
                    W r i t e l n(' F i n d P r o p I n f(oC l a s s,B y t e F i e l d)            :  ' ,PI  ^ .Name    ) ;
                    Write       ( ' F i n d P r o p I n f(oC l a s s,N o n E x i s t i n g P r o)p :  ' ) ;
                    Try
                       PI  :=  F i n d P r o p I n f(oO, 'N o n E x i s t i n g P r o'p) ;
                    e x c e p t
                       On   E  :  E x c e p t i o ndo
                           W r i t e l n(' Caught      e x c e p t i o n" ' ,E . ClassName       , '"   w i t h m e s s a g e  :  '*
 * ,E . M e s s a g e) ;
                    end  ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________



                40.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 (1658   ), GetEnumValue (1652   )


                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;



                                                                                1650

                ________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (1652   ), GetEnumName (1650   )



                40.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 (1669   ), GetOrdProp (1658   ), GetStrProp (1663   ), GetInt64Prop (1653   ), Get-
                MethodProp (1654   ), GetSetProp (1662   ), GetObjectProp (1656   ), GetEnumProp (1651   )


                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          ;



                                                                                1651

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                    PI   :   P P r o p I n f o;
                    TI   :   P T y p e I n f o;


                 b e g i n
                    O := TMyTestObject          . C r e a t e;
                    PI :=  G e t P r o p I n f(oO , 'MyEnumField         ') ;
                    TI :=  PI  ^ .PropType      ;
                    W r i t e l n('Enum      p r o p e r t y      :  ' ) ;
                    W r i t e l n(' V a l u e                                 :  ' ,GetEnumName         (TI  ,Ord   (O  .MyEnumFiel*
 *d         ) ) ) ;
                    W r i t e l n(' Get    (name    )                         :  ' ,GetEnumProp         (O , ' MyEnumField        '*
 * ) ) ;
                    W r i t e l n(' Get    ( p r o p i n f o)                 :  ' ,GetEnumProp         (O , PI  ) ) ;
                    SetEnumProp        ( O , 'MyEnumField         ', ' m e F i r s t') ;
                    W r i t e l n(' S e t  (name    ,m e F i r s t)           :  ' ,GetEnumName         (TI  ,Ord   (O  .MyEnumFiel*
 *d         ) ) ) ;
                    SetEnumProp        ( O ,PI  , 'meSecond       ') ;
                    W r i t e l n(' S e t  ( p r o p i n f o,meSecond     )  :   ' ,GetEnumName         (TI  ,Ord   (O  .MyEnumFiel*
 *d         ) ) ) ;
                    O .F r e e ;
                end___.____________________________________________________________________________________________________________*
 *___________



                40.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 (1650   ).

       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 (1650   ), SetOrdProp (1672   )



                40.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 (1669   ), GetOrdProp (1658   ), GetStrProp (1663   ), GetInt64Prop (1653   ), Get-
                MethodProp (1654   ), GetSetProp (1662   ), GetObjectProp (1656   ), GetEnumProp (1651   )



                                                                                1652

                ________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (1670   ), GetOrdProp (1658   ), GetStrProp (1663   ), GetFloatProp (1652   ), Get-
                MethodProp (1654   ), GetSetProp (1662   ), GetObjectProp (1656   ), GetEnumProp (1651   )



                                                                                1653

                ________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.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  (1670   ),  GetOrdProp  (1658   ),  GetStrProp  (1663   ),  GetFloatProp  (1652   ),
                GetInt64Prop (1653   ), GetSetProp (1662   ), GetObjectProp (1656   ), GetEnumProp (1651   )



                40.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



                                                                                1654

                ________________________________________________________CHAPTER_40.___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  (1671   ),  GetOrdProp  (1658   ),  GetStrProp  (1663   ),  GetFloatProp  (1652   ),
                GetInt64Prop (1653   ), GetSetProp (1662   ), GetObjectProp (1656   ), GetEnumProp (1651   )


                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



                                                                                1655

                ________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.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



                                                                                1656

                ________________________________________________________CHAPTER_40.___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  (1671   ),  GetOrdProp  (1658   ),  GetStrProp  (1663   ),  GetFloatProp  (1652   ),
                GetInt64Prop (1653   ), GetSetProp (1662   ), GetObjectProp (1656   ), GetEnumProp (1651   )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.7.11          GetObjectPropClass

    Synopsis:    Return class of property.



                                                                                1657

                ________________________________________________________CHAPTER_40.___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 (1656   ).

       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  (1671   ),  GetOrdProp  (1658   ),  GetStrProp  (1663   ),  GetFloatProp  (1652   ),
                GetInt64Prop (1653   )



                40.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 (1672   ), GetStrProp (1663   ), GetFloatProp (1652   ), GetInt64Prop (1653   ), Get-
                MethodProp (1654   ), GetSetProp (1662   ), GetObjectProp (1656   ), GetEnumProp (1651   )


                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



                                                                                1658

                ________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.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 a the PropName property of a
                class.  The class to examine can be specified in one of three ways:


                Instance     An instance of the class.

                AClass     A class pointer to the class.

                TypeInfo       A pointer to the type information of the class.


                In each of these three ways, if AKinds is specified, if the property has TypeKind which is not
                included in Akinds, Nil will be returned.

                For an example, see most of the other functions.

       Errors:   If the property PropName does not exist, Nil is returned.

    See also:    GetPropInfos (1659   ), GetPropList (1660   )



                40.7.14          GetPropInfos

    Synopsis:    Return a list of published properties.



                                                                                1659

                ________________________________________________________CHAPTER_40.___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 (1659   ), GetPropList (1660   )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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



                                                                                1660

                ________________________________________________________CHAPTER_40.___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 (1659   ), GetPropInfo (1659   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1661

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                40.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.



                40.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 (1654   ) function, no reference counting is done.

       Errors:   If the property PropName does not exist, an EPropertyError exception is raised.

    See also:    GetInterfaceProp (1654   ), SetRawInterfaceProp (1672   )



                40.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 (1674   ).  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  (1673   ),  GetStrProp  (1663   ),  GetFloatProp  (1652   ),  GetInt64Prop  (1653   ),  Get-
                MethodProp (1654   )



                                                                                1662

                ________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.7.19          GetStrProp

    Synopsis:    Return the value of a string property.

Declaration:     function  GetStrProp(Instance:  TObject;PropInfo:  PPropInfo)  :  Ansistring



                                                                                1663

                ________________________________________________________CHAPTER_40.___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  (1673   ),  SetWideStrProp  (1675   ),  GetOrdProp  (1658   ),  GetFloatProp  (1652   ),
                GetInt64Prop (1653   ), GetMethodProp (1654   )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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.



                                                                                1664

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                40.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 (1663   ), SetUnicodeStrProp (1675   )



                40.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 mising Variant support, the GetVariantProp function is not yet implemented.  Pro-
                vided for Delphi compatibility only.

    See also:    SetVariantProp (1675   )



                40.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  (1663   ),  SetWideStrProp  (1675   ),  GetOrdProp  (1658   ),  GetFloatProp  (1652   ),
                GetInt64Prop (1653   ), GetMethodProp (1654   )



                                                                                1665

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                40.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 (1666   ), PropIsType (1667   )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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



                                                                                1666

                ________________________________________________________CHAPTER_40.___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 (1666   ), PropIsType (1667   )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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.



                                                                                1667

                ________________________________________________________CHAPTER_40.___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 (1666   ), IsStoredProp (1666   ), PropType (1668   )


                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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (1666   ), IsStoredProp (1666   ), PropIsType (1667   )


                Listing:  ./typinfex/ex17.pp



                                                                                1668

                ________________________________________________________CHAPTER_40.___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___.____________________________________________________________________________________________________________*
 *___________



                40.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 (1652   ).

                For an example, see GetEnumProp (1651   ).

       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 (1651   ), SetStrProp (1673   ), SetFloatProp (1669   ), SetInt64Prop (1670   ), Set-
                MethodProp (1671   )



                40.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)



                                                                                1669

                ________________________________________________________CHAPTER_40.___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 (1652   ).

       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  (1652   ),  SetOrdProp  (1672   ),  SetStrProp  (1673   ),  SetInt64Prop  (1670   ),  Set-
                MethodProp (1671   )



                40.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 (1653   ).

       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 (1653   ), GetMethodProp (1654   ), SetOrdProp (1672   ), SetStrProp (1673   ), Set-
                FloatProp (1669   )



                40.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 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  (1654   ),  SetObjectProp  (1671   ),  SetOrdProp  (1672   ),  SetStrProp  (1673   ),
                SetFloatProp (1669   ), SetInt64Prop (1670   ), SetMethodProp (1671   )



                                                                                1670

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                40.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 (1654   ).

       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 (1654   ), SetOrdProp (1672   ), SetStrProp (1673   ), SetFloatProp (1669   ), SetInt64Prop
                (1670   )



                40.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  the  object  property  described  by  PropInfo  or  with
                name Propname for the object Instance.

                For an example, see GetObjectProp (1656   ).

       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 (1656   ), SetOrdProp (1672   ), SetStrProp (1673   ), SetFloatProp (1669   ), SetInt64Prop
                (1670   ), SetMethodProp (1671   )



                                                                                1671

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                40.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 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 (1658   ).

       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  (1658   ),  SetStrProp  (1673   ),  SetFloatProp  (1669   ),  SetInt64Prop  (1670   ),  Set-
                MethodProp (1671   )



                40.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.



                40.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 (1670   ) procedure, no reference counting is done.



                                                                                1672

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



       Errors:   If the property PropName does not exist, an EPropertyError exception is raised.

    See also:    SetInterfaceProp (1670   ), GetRawInterfaceProp (1662   )



                40.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 (1676   ) function.

                The value can be formed using the SetToString (1674   ) function.

                For an example, see GetSetProp (1662   ).

       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 (1662   ), SetOrdProp (1672   ), SetStrProp (1673   ), SetFloatProp (1669   ), SetInt64Prop
                (1670   ), SetMethodProp (1671   ), SetToString (1674   ), StringToSet (1676   )



                40.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 (1663   )

       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 (1663   ), SetWideStrProp (1675   ), SetOrdProp (1672   ), SetFloatProp (1669   ), SetInt64Prop
                (1670   ), SetMethodProp (1671   )



                                                                                1673

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                40.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 (1650   ), GetEnumValue (1652   ), StringToSet (1676   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1674

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                40.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 (1673   ), GetUnicodeStrProp (1665   )



                40.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.



                40.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 (1665   ), SetStrProp (1673   ), SetOrdProp (1672   ), SetFloatProp (1669   ), SetInt64Prop
                (1670   ), SetMethodProp (1671   )



                                                                                1675

                ________________________________________________________CHAPTER_40.___REFERENCE_FOR_UNIT_'TYPINFO'_________________*
 *___________________



                40.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 (1652   ) function.

                For an example, see SetToString (1674   ).

       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 (1650   ), GetEnumValue (1652   ), SetToString (1674   )



                40.8          EPropertyConvertError



                40.8.1         Description

                EPropertyConvertError is not used in the Free Pascal implementation of the typinfo unit,
                but is declared for Delphi compatibility.



                40.9          EPropertyError



                40.9.1         Description

                Exception raised in case of an error in one of the functions.



                                                                                1676




Chapter   41



Reference   for   unit   'Unix'



41.1          Used  units



                                     Table 41.1:  Used units by unit 'Unix'


                                                  _Name_____________Page______
                                                    BaseUnix           102
                                                    System           1230
                                                    unixtype         1715



41.2          Constants,  types  and  variables



41.2.1         Constants

ARG_MAX  =  UnixType  .  ARG_MAX


Maximum number of arguments to a program.


fs_ext  =  $137d


File system type (StatFS (1711   )):  (ext) Extended


fs_ext2  =  $ef53


File system type (StatFS (1711   )):  (ext2) Second extended


fs_iso  =  $9660


File system type (StatFS (1711   )):  ISO 9660


fs_minix  =  $137f


File system type (StatFS (1711   )):  Minix


fs_minix_30  =  $138f



                                                            1677

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



File system type (StatFS (1711   )):  Minix 3.0


fs_minux_V2  =  $2468


File system type (StatFS (1711   )):  Minix V2


fs_msdos  =  $4d44


File system type (StatFS (1711   )):  MSDOS (FAT)


fs_nfs  =  $6969


File system type (StatFS (1711   )):  NFS


fs_old_ext2  =  $ef51


File system type (StatFS (1711   )):  (ext2) Old second extended


fs_proc  =  $9fa0


File system type (StatFS (1711   )):  PROC fs


fs_xia  =  $012FD16D


File system type (StatFS (1711   )):  XIA


IOCtl_TCGETS  =  $5401


IOCTL call number:  get Terminal Control settings


LOCK_EX  =  2


FpFLock (1701   ) Exclusive lock


LOCK_NB  =  4


FpFLock (1701   ) Non-blocking operation


LOCK_SH  =  1


FpFLock (1701   ) Shared lock


LOCK_UN  =  8


FpFLock (1701   ) unlock


MAP_FAILED  =  baseunix  .  MAP_FAILED


Error return value for mmap:  mmap operation failed.


MAP_FIXED  =  baseunix  .  MAP_FIXED



                                                                1678

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



#rtl.baseunix.FpMMap (165  ) map type:  Interpret addr exactly


MAP_PRIVATE  =  baseunix  .  MAP_PRIVATE


#rtl.baseunix.FpMMap (165  ) map type:  Changes are private


MAP_SHARED  =  baseunix  .  MAP_SHARED


#rtl.baseunix.FpMMap (165  ) map type:  Share changes


MAP_TYPE  =  baseunix  .  MAP_TYPE


#rtl.baseunix.FpMMap (165  ) map type:  Bitmask for type of mapping


MS_ASYNC  =  1


Asynchronous operation flag for msync call


MS_INVALIDATE  =  2


Invalidate other mappings of file flag for msync call


MS_SYNC  =  4


Synchronous operation flag for msync call


NAME_MAX  =  UnixType  .  NAME_MAX


Maximum filename length.


Open_Accmode  =  3


Bitmask to determine access mode in open flags.


Open_Append  =  2  shl  9


File open mode:  Append to file


Open_Creat  =  1  shl  6


File open mode:  Create if file does not yet exist.


Open_Direct  =  4  shl  12


File open mode:  Minimize caching effects


Open_Directory  =  2  shl  15


File open mode:  File must be directory.


Open_Excl  =  2  shl  6



                                                                1679

______________________________________________________________CHAPTER_41.___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 (1680   )


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 (159  ) option:  Get process group priority.


PRIO_PROCESS  =  UnixType  .  PRIO_PROCESS



                                                                1680

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



#rtl.baseunix.fpGetPriority (159  ) option:  Get process priority.


PRIO_USER  =  UnixType  .  PRIO_USER


#rtl.baseunix.fpGetPriority (159  ) option:  Get user priority.


PROT_EXEC  =  baseunix  .  PROT_EXEC


#rtl.baseunix.FpMMap (165  ) memory access:  page can be executed


PROT_NONE  =  baseunix  .  PROT_NONE


#rtl.baseunix.FpMMap (165  ) memory access:  page can not be accessed


PROT_READ  =  baseunix  .  PROT_READ


#rtl.baseunix.FpMMap (165  ) memory access:  page can be read


PROT_WRITE  =  baseunix  .  PROT_WRITE


#rtl.baseunix.FpMMap (165  ) 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 (136  ) record) mode:  Block device


STAT_IFCHR  =  $2000


File (#rtl.baseunix.stat (136  ) record) mode:  Character device


STAT_IFDIR  =  $4000


File (#rtl.baseunix.stat (136  ) record) mode:  Directory


STAT_IFIFO  =  $1000


File (#rtl.baseunix.stat (136  ) record) mode:  FIFO


STAT_IFLNK  =  $a000



                                                                1681

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



File (#rtl.baseunix.stat (136  ) record) mode:  Link


STAT_IFMT  =  $f000


File (#rtl.baseunix.stat (136  ) record) mode:  File type bit mask


STAT_IFREG  =  $8000


File (#rtl.baseunix.stat (136  ) record) mode:  Regular file


STAT_IFSOCK  =  $c000


File (#rtl.baseunix.stat (136  ) record) mode:  Socket


STAT_IRGRP  =  STAT_IROTH  shl  3


File (#rtl.baseunix.stat (136  ) record) mode:  Group read permission


STAT_IROTH  =  $4


File (#rtl.baseunix.stat (136  ) record) mode:  Other read permission


STAT_IRUSR  =  STAT_IROTH  shl  6


File (#rtl.baseunix.stat (136  ) record) mode:  Owner read permission


STAT_IRWXG  =  STAT_IRWXO  shl  3


File (#rtl.baseunix.stat (136  ) record) mode:  Group permission bits mask


STAT_IRWXO  =  $7


File (#rtl.baseunix.stat (136  ) record) mode:  Other permission bits mask


STAT_IRWXU  =  STAT_IRWXO  shl  6


File (#rtl.baseunix.stat (136  ) record) mode:  Owner permission bits mask


STAT_ISGID  =  $0400


File (#rtl.baseunix.stat (136  ) record) mode:  GID bit set


STAT_ISUID  =  $0800


File (#rtl.baseunix.stat (136  ) record) mode:  UID bit set


STAT_ISVTX  =  $0200


File (#rtl.baseunix.stat (136  ) record) mode:  Sticky bit set


STAT_IWGRP  =  STAT_IWOTH  shl  3



                                                                1682

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



File (#rtl.baseunix.stat (136  ) record) mode:  Group write permission


STAT_IWOTH  =  $2


File (#rtl.baseunix.stat (136  ) record) mode:  Other write permission


STAT_IWUSR  =  STAT_IWOTH  shl  6


File (#rtl.baseunix.stat (136  ) record) mode:  Owner write permission


STAT_IXGRP  =  STAT_IXOTH  shl  3


File (#rtl.baseunix.stat (136  ) record) mode:  Others execute permission


STAT_IXOTH  =  $1


File (#rtl.baseunix.stat (136  ) record) mode:  Others execute permission


STAT_IXUSR  =  STAT_IXOTH  shl  6


File (#rtl.baseunix.stat (136  ) record) mode:  Others execute permission


SYS_NMLN  =  UnixType  .  SYS_NMLN


Max system name length.


Wait_Any  =  -1


#rtl.baseunix.fpWaitPID (194  ):  Wait on any process


Wait_Clone  =  $80000000


#rtl.baseunix.fpWaitPID (194  ):  Wait on clone processes only.


Wait_MyPGRP  =  0


#rtl.baseunix.fpWaitPID (194  ):  Wait processes from current process group


Wait_NoHang  =  1


#rtl.baseunix.fpWaitPID (194  ):  Do not wait


Wait_UnTraced  =  2


#rtl.baseunix.fpWaitPID (194  ):  Also report stopped but untraced processes



                                                                1683

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



41.2.2         Types

cbool  =  UnixType.cbool


Boolean type


cchar  =  UnixType.cchar


Alias for #rtl.UnixType.cchar (1717   )


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



                                                                1684

______________________________________________________________CHAPTER_41.___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 (1684   ).


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 (1684   ).


csshort  =  UnixType.csshort


Short signed integer type


cuchar  =  UnixType.cuchar


Alias for #rtl.UnixType.cuchar (1718   )


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



                                                                1685

______________________________________________________________CHAPTER_41.___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 (1719   )


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 (1684   )


pcchar  =  UnixType.pcchar



                                                                1686

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Alias for #rtl.UnixType.pcchar (1720   )


pcdouble  =  UnixType.pcdouble


Pointer to cdouble (125  ) type.


pcfloat  =  UnixType.pcfloat


Pointer to cfloat (125  ) type.


pcint  =  UnixType.pcint


Pointer to cInt (1684   ) 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 (1691   ) type.


pclong  =  UnixType.pclong


Pointer to cLong (1684   ) type.


pclonglong  =  UnixType.pclonglong


Pointer to longlong type.


pcschar  =  UnixType.pcschar


Pointer to character type cschar (1685   ).


pcshort  =  UnixType.pcshort


Pointer to cShort (1685   ) type.


pcsigned  =  UnixType.pcsigned



                                                                1687

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Pointer to signed integer type csigned (1685   ).


pcsint  =  UnixType.pcsint


Pointer to signed integer type csint (1685   )


pcsize_t  =  UnixType.psize_t


Pointer to character size type pcsize_t.


pcslong  =  UnixType.pcslong


Pointer ot the signed long cslong (1685   )


pcslonglong  =  UnixType.pcslonglong


Pointer to Signed longlong type cslonglong (1685   )


pcsshort  =  UnixType.pcsshort


Pointer to short signed integer type csshort (1685   )


pcuchar  =  UnixType.pcuchar


Alias for #rtl.UnixType.pcuchar (1721   )


pcuint  =  UnixType.pcuint


Pointer to cUInt (1685   ) 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 (1686   ) type.


pculonglong  =  UnixType.pculonglong



                                                                1688

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Unsigned longlong type


pcunsigned  =  UnixType.pcunsigned


Alias for #rtl.unixtype.pcunsigned (1722   )


pcushort  =  UnixType.pcushort


Pointer to cuShort (1686   ) type.


pDev  =  UnixType.pDev


Pointer to TDev (1691   ) type.


pGid  =  UnixType.pGid


Pointer to TGid (1691   ) type.


pid_t  =  UnixType.pid_t


Process ID type.


pIno  =  UnixType.pIno


Pointer to TIno (1691   ) type.


pMode  =  UnixType.pMode


Pointer to TMode (1692   ) type.


pnLink  =  UnixType.pnLink


Pointer to TnLink (1692   ) type.


pOff  =  UnixType.pOff


Pointer to TOff (1692   ) type.


pPid  =  UnixType.pPid


Pointer to TPid (1692   ) type.


pSize  =  UnixType.pSize


Pointer to TSize (1692   ) type.


pSize_t  =  UnixType.pSize_t


Pointer to type Size_t.


pSocklen  =  UnixType.pSocklen



                                                                1689

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Pointer to TSockLen (1692   ) type.


psSize  =  UnixType.psSize


Pointer to TsSize (1692   ) 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 (1692   ) type.


ptimespec  =  UnixType.ptimespec


Pointer to timespec (1691   ) type.


ptimeval  =  UnixType.ptimeval


Pointer to timeval (1691   ) type.


ptime_t  =  UnixType.ptime_t


Pointer to time_t (1691   ) type.


pUid  =  UnixType.pUid


Pointer to TUid (1692   ) type.


size_t  =  UnixType.size_t


Size specification type.


socklen_t  =  UnixType.socklen_t


Socket address length type.


ssize_t  =  UnixType.ssize_t



                                                                1690

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Small size type.


TClock  =  UnixType.TClock


Alias for clock_t (1684   ) type.


TDev  =  UnixType.TDev


Alias for dev_t (1686   ) type.


TFSearchOption  =  (NoCurrentDirectory,CurrentDirectoryFirst,
                             CurrentDirectoryLast)



                       Table 41.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 (1703   )


TGid  =  UnixType.TGid


Alias for gid_t (1686   ) 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 (1686   ) type.


TIOCtlRequest  =  UnixType.TIOCtlRequest


Alias for the TIOCtlRequest (1727   ) type in unixtypes


TMode  =  UnixType.TMode



                                                                1691

______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________________________*
 *___



Alias for mode_t (1686   ) type.


TnLink  =  UnixType.TnLink


Alias for nlink_t (1686   ) type.


TOff  =  UnixType.TOff


Alias for off_t (1686   ) type.


TPid  =  UnixType.TPid


Alias for pid_t (1689   ) type.


Tpipe  =  baseunix.tfildes


Array describing a pipe pair of filedescriptors.


TSize  =  UnixType.TSize


Alias for size_t (1690   ) type


TSocklen  =  UnixType.TSocklen


Alias for socklen_t (1690   ) type.


TsSize  =  UnixType.TsSize


Alias for ssize_t (1691   ) type


tstatfs  =  UnixType.TStatFs


Record describing a file system in the fpstatfs (1702   ) call.


TTime  =  UnixType.TTime


Alias for TTime (1692   ) type.


Ttimespec  =  UnixType.Ttimespec


Alias for TimeSpec (1691   ) type.


TTimeVal  =  UnixType.TTimeVal


Alias for timeval (1691   ) type.


TUid  =  UnixType.TUid


Alias for uid_t (1692   ) type.


uid_t  =  UnixType.uid_t


User ID type



                                                                1692

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                41.2.3         Variables

                tzdaylight  :  Boolean


                Indicates whether daylight savings time is active.


                tzname  :  Array[boolean]  of  PChar


                Timezone name.



                41.3          Procedures  and  functions



                41.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 (156  ) function:


                sys__emfile     Too many file descriptors for this process.

                sys__enfile    The system file table is full.


    See also:    POpen (1708   ), #rtl.baseunix.FpMkFifo (165  )


                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) ;



                                                                                1693

                ______________________________________________________________CHAPTER_41.___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___.____________________________________________________________________________________________________________*
 *___________



                41.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 (156  ) 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 (1693   ), POpen (1708   )


                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 ;



                                                                                1694

                ______________________________________________________________CHAPTER_41.___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___.____________________________________________________________________________________________________________*
 *___________



                41.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.



                                                                                1695

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



       Errors:   Extended error information is returned by the FpGetErrno (156  ) 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  (150  ),  FpExecv  (1698   ),  FpExecvp  (1699   ),  FpExecle  (1696   ),  FpExeclp  (1697   ),
                FpFork (153  )


                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___.____________________________________________________________________________________________________________*
 *___________



                41.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 (156  ) 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.



                                                                                1696

                ______________________________________________________________CHAPTER_41.___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 (150  ), FpExecv (1698   ), FpExecvp (1699   ), FpExecl (1695   ), FpExeclp (1697   ), Fp-
                Fork (153  )


                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___.____________________________________________________________________________________________________________*
 *___________



                41.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 (156  ) 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 (150  ), FpExecv (1698   ), FpExecvp (1699   ), FpExecle (1696   ), FpExecl (1695   ), Fp-
                Fork (153  )


                Listing:  ./unixex/ex76.pp



                                                                                1697

                ______________________________________________________________CHAPTER_41.___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___.____________________________________________________________________________________________________________*
 *___________



                41.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 (1697   ), 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 (1697   ), FpExecLE (1696   )



                41.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 (156  ) 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).



                                                                                1698

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



    See also:    FpExecve  (150  ),  FpExecvp  (1699   ),  FpExecle  (1696   ),  FpExecl  (1695   ),  FpExeclp  (1697   ),
                FpFork (153  )


                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___.____________________________________________________________________________________________________________*
 *___________



                41.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 (156  ) 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 (150  ), FpExecv (1698   ), FpExecle (1696   ), FpExecl (1695   ), FpExeclp (1697   ), Fp-
                Fork (153  )



                                                                                1699

                ______________________________________________________________CHAPTER_41.___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___.____________________________________________________________________________________________________________*
 *___________



                41.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 (156  ) 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 (150  ), FpExecv (1698   ), FpExecle (1696   ), FpExecl (1695   ), FpExeclp (1697   ), Fp-
                Fork (153  )



                                                                                1700

                ______________________________________________________________CHAPTER_41.___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___.____________________________________________________________________________________________________________*
 *___________



                41.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 (156  ) function:

    See also:    #rtl.baseunix.FpFcntl (151  ), FSync (1705   )



                41.3.11          fpfStatFS

    Synopsis:    Retrieve filesystem information.

Declaration:     function  fpfStatFS(Fd:  cint;Info:  pstatfs)  :  cint



                                                                                1701

                ______________________________________________________________CHAPTER_41.___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 (1702   ), #rtl.baseunix.fpfStat (153  )



                41.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.



                41.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.



                41.3.14          fpStatFS

    Synopsis:    Retrieve filesystem information.

Declaration:     function  fpStatFS(Path:  PChar;Info:  pstatfs)  :  cint

    Visibility:   default

Description:     fpStatFS returns in Info information about the filesystem on which the file or path Path
                resides.  Info is of type tstatfs.  The function returns 0 if the call was succesfull, or an error
                code if the call failed.

       Errors:   On error, a non-zero error code is returned

    See also:    fpFStatFS (1701   ), #rtl.baseunix.fpStat (186  )



                                                                                1702

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                41.3.15          fpSystem

    Synopsis:    Execute and feed command to system shell

Declaration:     function  fpSystem(const  Command:  string)  :  cint
                function  fpSystem(const  Command:  AnsiString)  :  cint

    Visibility:   default

Description:     Shell invokes the bash shell (/bin/sh),  and feeds it the command Command (using the -c
                option).  The function then waits for the command to complete, and then returns the exit
                status of the command, or 127 if it could not complete the FpFork (153  ) or FpExecve (150  )
                calls.

       Errors:   Errors are reported in (fpget)ErrNo (156  )

    See also:    POpen (1708   ), Shell (1710   ), FpFork (153  ), FpExecve (150  )


                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___.____________________________________________________________________________________________________________*
 *___________



                41.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



                                                                                1703

                ______________________________________________________________CHAPTER_41.___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 (1732   )


                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___.____________________________________________________________________________________________________________*
 *___________



                41.3.17          fStatFS

    Synopsis:    Retrieve filesystem information from a file descriptor.

Declaration:     function  fStatFS(Fd:  cint;var  Info:  tstatfs)  :  cint

    Visibility:   default

Description:     fStatFS returns in Info information about the filesystem on which the file with file descrip-
                tor fd resides.  Info is of type TStatFS (1728   ).

                The  function  returns  zero  if  the  call  was  succesful,  a  nonzero  value  is  returned  if  the  call
                failed.

       Errors:   Extended error information is returned by the FpGetErrno (156  ) function:


                sys__enotdir      A component of  Path is not a directory.

                sys__einval    Invalid character in Path.

                sys__enoent      Path does not exist.

                sys__eaccess     Search permission is denied for component inPath.

                sys__eloop     A circular symbolic link was encountered in Path.

                sys__eio   An error occurred while reading from the filesystem.


    See also:    StatFS (1711   ), #rtl.baseunix.FpLStat (163  )


                Listing:  ./unixex/ex91.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 0;


                {   Program       t o  d e m o n s t r a t et h e  F S S t a t f u n c t i o n.  }


                 u s e s B a s e U n i x,Unix   , U n i x T y p e;


                 v a r  s  :   s t r i n g;
                        f d  :  c i n t;
                        i n f o :   t s t a t f s;



                                                                                1704

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                 b e g i n
                    w r i t e l n ( ' I n f o a b o u t  c u r r e n t p a r t i t i o n:   ') ;
                    s :=  '. ' ;
                    w h i l e s <>  'q  '  do
                        b e g i n
                       Fd  := fpOpen     (S  ,O _RDOnly     ) ;
                        i f  (f d >=0)     then
                           b e g i n
                           i f   f p f s t a t f s(f d , @ i n f o)<>0    then
                              b e g i n
                               w r i t e l n('F s t a t  f a i l e d.  E r r n o :   ' ,f p g e t e r r n o) ;
                               h a l t ( 1 ) ;
                              end   ;
                           F p C l o s e(f d ) ;
                           w r i t e l n;
                           w r i t e l n ( ' R e s u l t o f  f s s t a t on    f i l e ' ' ' ,s , ' '' . ') ;
                {  $ i f d e f i n e d(L i n u x)  o r   d e f i n e d(s u n o s)}
                           //   SysV     l i k e.
                           w r i t e l n ( ' f s t y p e   :  ' , i n f o.f s t y p e) ;
                { $ e l s e}
                           //   BSD    l i k e,   i n c l Mac    OS   X .
                           w r i t e l n ( ' f s t y p e   :  ' , i n f o.f t y p e) ;
                { $ e n d i f}


                           w r i t e l n ( ' b s i z e     :  ' , i n f o.b s i z e) ;
                           w r i t e l n ( ' b f r e e     :  ' , i n f o.b f r e e) ;
                           w r i t e l n ( ' b a v a i l   :  ' , i n f o.b a v a i l) ;
                           w r i t e l n ( ' f i l e s     :  ' , i n f o.f i l e s) ;
                           w r i t e l n ( ' f f r e e     :  ' , i n f o.f f r e e) ;
                           { $ i f d e f FreeBSD     }
                           w r i t e l n ( ' f s i d       :  ' , i n f o.f s i d[ 0 ] ) ;
                           { $ e l s e}
                           w r i t e l n ( ' f s i d       :  ' , i n f o.f s i d[ 0 ] ) ;
                           w r i t e l n ( 'Namelen        :  ' , i n f o.n a m e l e n) ;
                           { $ e n d i f}
                           w r i t e (  'Type    name     o f   f i l e t o  do    f s s t a t.  (q   q u i t s)  : ' ) ;
                           r e a d l n ( s )


                           end  ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                41.3.18          fsync

    Synopsis:    Synchronize file's kernel data with disk.

Declaration:     function  fsync(fd:  cint)  :  cint

    Visibility:   default

Description:     Fsync synchronizes the kernel data for file fd (the cache) with the disk.  The call will not
                return till all file data was written to disk.

                If the call was succesfull, 0 is returned.  On failure, a nonzero value is returned.

       Errors:   Extended error information is returned by the FpGetErrno (156  ) function:

    See also:    FpFLock (1701   )



                                                                                1705

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                41.3.19          GetDomainName

    Synopsis:    Return current domain name

Declaration:     function  GetDomainName  :  string

    Visibility:   default

Description:     Get the domain name of the machine on which the process is running.  An empty string is
                returned if the domain is not set.

       Errors:   None.

    See also:    GetHostName (1706   )


                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___.____________________________________________________________________________________________________________*
 *___________



                41.3.20          GetHostName

    Synopsis:    Return host name

Declaration:     function  GetHostName  :  string

    Visibility:   default

Description:     Get  the  hostname  of  the  machine  on  which  the  process  is  running.   An  empty  string  is
                returned if hostname is not set.

       Errors:   None.

    See also:    GetDomainName (1706   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1706

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                41.3.21          GetLocalTimezone

    Synopsis:    Return local timzeone information

Declaration:     procedure  GetLocalTimezone(timer:  cint;var  leap_correct:  cint;
                                                           var  leap_hit:  cint)
                procedure  GetLocalTimezone(timer:  cint)

    Visibility:   default

Description:     GetLocalTimeZone returns the local timezone information.  It also initializes the TZSeconds
                variable, which is used to correct the epoch time to local time.

                There should never be any need to call this function directly.  It is called by the initialization
                routines of the Linux unit.

    See also:    GetTimezoneFile (1707   ), ReadTimezoneFile (1709   )



                41.3.22          GetTimezoneFile

    Synopsis:    Return name of timezone information file

Declaration:     function  GetTimezoneFile  :  string

    Visibility:   default

Description:     GetTimezoneFile returns the location of the current timezone file.  The location of file is
                determined as follows:


                     1.If  /etc/timezone exists, it is read, and the contents of this file is returned.  This should
                       work on Debian systems.

                     2.If  /usr/lib/zoneinfo/localtime  exists,  then  it  is  returned.  (this  file  is  a  symlink  to  the
                       timezone file on SuSE systems)

                     3.If  /etc/localtime exists, then it is returned.  (this file is a symlink to the timezone file
                       on RedHat systems)


       Errors:   If no file was found, an empty string is returned.

    See also:    ReadTimezoneFile (1709   )



                41.3.23          PClose

    Synopsis:    Close file opened with POpen (1708   )

Declaration:     function  PClose(var  F:  File)  :  cint
                function  PClose(var  F:  text)  :  cint

    Visibility:   default

Description:     PClose closes a file opened with POpen (1708   ).  It waits for the command to complete, and
                then returns the exit status of the command.

                For an example, see POpen (1708   )

       Errors:   Extended error information is returned by the FpGetErrno (156  ) function.

    See also:    POpen (1708   )



                                                                                1707

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                41.3.24          POpen

    Synopsis:    Pipe file to standard input/output of program

Declaration:     function  POpen(var  F:  text;const  Prog:  Ansistring;rw:  Char)  :  cint
                function  POpen(var  F:  File;const  Prog:  Ansistring;rw:  Char)  :  cint

    Visibility:   default

Description:     POpen runs the command specified in Prog, and redirects the standard in or output of the
                command to the other end of the pipe F. The parameter rw indicates the direction of the
                pipe.  If it is set to 'W', then F can be used to write data, which will then be read by the
                command from stdinput.  If it is set to 'R', then the standard output of the command can
                be read from F. F should be reset or rewritten prior to using it.  F can be of type Text or
                File.  A file opened with POpen can be closed with Close, but also with PClose (1707   ).  The
                result is the same, but PClose returns the exit status of the command Prog.

       Errors:   Extended  error  information  is  returned  by  the  FpGetErrno  (156  )  function.   Errors  are
                essentially those of the Execve, Dup and AssignPipe commands.

    See also:    AssignPipe (1693   ), PClose (1707   )


                Listing:__./unixex/ex37.pp_________________________________________________________________________________________*
 *___________

                Program       E x a m p l e 3 7;


                {   Program       t o  d e m o n s t r a t et h e  Popen      f u n c t i o n. }


                 u s e s B a s e U n i x,U n i x;


                 v a r  f  :   t e x t;
                        i  :   l o n g i n t;


                 b e g i n
                    w r i t e l n ( ' C r e a t i n ga   s h e l l s c r i p t t o   w h i c h e c h o e s i t s  a r g u m e n t s*
 *') ;
                    w r i t e l n ( 'and     i n p u t b a c k  t o  s t d o u t') ;
                    a s s i g n ( f , 't e s t 2 1 a') ;
                    r e w r i t e ( f ) ;
                    w r i t e l n ( f , '#!/  b i n/ s h ' ) ;
                    w r i t e l n ( f , 'e c h o  t h i s  i s  t h e  c h i l d s p e a k i n g. . . . ' ) ;
                    w r i t e l n ( f , 'e c h o  g o t  a r g u m e n t s\ * "$ *"\*   ' ) ;
                    w r i t e l n ( f , 'c a t ') ;
                    w r i t e l n ( f , 'e x i t 2  ') ;
                    w r i t e l n ( f ) ;
                    c l o s e ( f ) ;
                    fpchmod       ( ' t e s t 2 1 a', & 7 5 5 ) ;
                    popen     ( f , ' . /t e s t 2 1 a a r g 1  a r g 2' ,'W  ' ) ;
                    i f  f p g e t e r r n<o>0    then
                         w r i t e l n ( ' e r r o r f r o m  POpen     :   e r r n o :   ' ,  f p g e t e r r n o) ;
                    f o r  i : = 1  t o  1 0  do
                        w r i t e l n( f , 'T h i s  i s   w r i t t e nt o   t h e  p i p e,  and    s h o u l d a p p e a r on   *
 * s t d o u t.' ) ;
                    F l u s h( f) ;
                    W r i t e l n ( 'The     s c r i p t e x i t e d w i t h  s t a t u s :   ', P C l o s e ( f ) ) ;
                    w r i t e l n;
                    w r i t e l n ( ' P r e s s<  r e t u r n>  t o  r e m o v e s h e l l  s c r i p t.' ) ;
                    r e a d l n;
                    a s s i g n ( f , 't e s t 2 1 a') ;
                    e r a s e ( f )
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1708

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                41.3.25          ReadTimezoneFile

    Synopsis:    Read the timezone file and initialize time routines

Declaration:     procedure  ReadTimezoneFile(fn:  string)

    Visibility:   default

Description:     ReadTimeZoneFile reads the timezone file fn and initializes the local time routines based
                on the information found there.

                There should be no need to call this function.  The initialization routines of the linux unit
                call this routine at unit startup.

       Errors:   None.

    See also:    GetTimezoneFile (1707   ), GetLocalTimezone (1707   )



                41.3.26          SeekDir

    Synopsis:    Seek to position in directory

Declaration:     procedure  SeekDir(p:  pDir;loc:  clong)

    Visibility:   default

Description:     SeekDir sets the directory pointer to the loc-th entry in the directory structure pointed to
                by p.

                For an example, see #rtl.baseunix.fpOpenDir (170  ).

       Errors:   Extended error information is returned by the FpGetErrno (156  ) function:

    See also:    #rtl.baseunix.fpCloseDir  (146  ),  #rtl.baseunix.fpReadDir  (174  ),  #rtl.baseunix.fpOpenDir
                (170  ), TellDir (1712   )



                41.3.27          SelectText

    Synopsis:    Wait for event on text file.

Declaration:     function  SelectText(var  T:  Text;TimeOut:  ptimeval)  :  cint
                function  SelectText(var  T:  Text;TimeOut:  cint)  :  cint

    Visibility:   default

Description:     SelectText  executes  the  FpSelect  (177  )  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 (177  ).  SYS_EBADF can also mean that the file wasn't opened.

    See also:    #rtl.baseunix.FpSelect (177  )



                                                                                1709

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                41.3.28          Shell

    Synopsis:    Execute and feed command to system shell

Declaration:     function  Shell(const  Command:  string)  :  cint
                function  Shell(const  Command:  AnsiString)  :  cint

    Visibility:   default

Description:     Shell invokes the bash shell (/bin/sh),  and feeds it the command Command (using the -c
                option).  The function then waits for the command to complete, and then returns the exit
                status of the command, or 127 if it could not complete the FpFork (153  ) or FpExecve (150  )
                calls.

       Errors:   Extended error information is returned by the FpGetErrno (156  ) function:

    See also:    POpen (1708   ), FpSystem (1703   ), FpFork (153  ), FpExecve (150  )


                Listing:  ./unixex/ex56.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       e x a m p l e 5 6;


                 u s e s U n i x;


                {   Program       t o  d e m o n s t r a t et h e  S h e l l  f u n c t i o n}


                Var    S   :   L o n g i n t;


                 b e g i n
                    W r i t e l n ( 'Output       o f  l s -  l  * . pp  ') ;
                    S := S h e l l  ( 'l s  - l   * .pp  ' ) ;
                    W r i t e l n ( 'Command        e x i t e d w w i t h s t a t u s :   ' ,S ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                41.3.29          SigRaise

    Synopsis:    Raise a signal (send to current process)

Declaration:     procedure  SigRaise(sig:  Integer)

    Visibility:   default

Description:     SigRaise sends a Sig signal to the current process.

       Errors:   None.

    See also:    #rtl.baseunix.FpKill (161  ), #rtl.baseunix.FpGetPid (158  )


                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



                                                                                1710

                ______________________________________________________________CHAPTER_41.___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___.____________________________________________________________________________________________________________*
 *___________



                41.3.30          StatFS

    Synopsis:    Retrieve filesystem information from a path.

Declaration:     function  StatFS(Path:  PChar;var  Info:  tstatfs)  :  cint
                function  StatFS(Path:  ansistring;var  Info:  tstatfs)  :  cint

    Visibility:   default

Description:     StatFS  returns  in  Info  information  about  the  filesystem  on  which  the  file  Path  resides.
                Info is of type TStatFS (1728   ).

                The  function  returns  zero  if  the  call  was  succesful,  a  nonzero  value  is  returned  if  the  call
                failed.

       Errors:   Extended error information is returned by the FpGetErrno (156  ) function:


                sys__enotdir      A component of  Path is not a directory.

                sys__einval    Invalid character in Path.

                sys__enoent      Path does not exist.

                sys__eaccess     Search permission is denied for component inPath.

                sys__eloop     A circular symbolic link was encountered in Path.

                sys__eio   An error occurred while reading from the filesystem.


    See also:    #rtl.baseunix.FpStat (186  ), #rtl.baseunix.FpLStat (163  )


                Listing:  ./unixex/ex91.pp
                ___________________________________________________________________________________________________________________*
 *___________
                program       E x a m p l e 3 0;


                {   Program       t o  d e m o n s t r a t et h e  F S S t a t f u n c t i o n.  }



                                                                                1711

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                 u s e s B a s e U n i x,Unix   , U n i x T y p e;


                 v a r  s  :   s t r i n g;
                        f d  :  c i n t;
                        i n f o :   t s t a t f s;


                 b e g i n
                    w r i t e l n ( ' I n f o a b o u t  c u r r e n t p a r t i t i o n:   ') ;
                    s :=  '. ' ;
                    w h i l e s <>  'q  '  do
                        b e g i n
                       Fd  := fpOpen     (S  ,O _RDOnly     ) ;
                        i f  (f d >=0)     then
                           b e g i n
                           i f   f p f s t a t f s(f d , @ i n f o)<>0    then
                              b e g i n
                               w r i t e l n('F s t a t  f a i l e d.  E r r n o :   ' ,f p g e t e r r n o) ;
                               h a l t ( 1 ) ;
                              end   ;
                           F p C l o s e(f d ) ;
                           w r i t e l n;
                           w r i t e l n ( ' R e s u l t o f  f s s t a t on    f i l e ' ' ' ,s , ' '' . ') ;
                {  $ i f d e f i n e d(L i n u x)  o r   d e f i n e d(s u n o s)}
                           //   SysV     l i k e.
                           w r i t e l n ( ' f s t y p e   :  ' , i n f o.f s t y p e) ;
                { $ e l s e}
                           //   BSD    l i k e,   i n c l Mac    OS   X .
                           w r i t e l n ( ' f s t y p e   :  ' , i n f o.f t y p e) ;
                { $ e n d i f}


                           w r i t e l n ( ' b s i z e     :  ' , i n f o.b s i z e) ;
                           w r i t e l n ( ' b f r e e     :  ' , i n f o.b f r e e) ;
                           w r i t e l n ( ' b a v a i l   :  ' , i n f o.b a v a i l) ;
                           w r i t e l n ( ' f i l e s     :  ' , i n f o.f i l e s) ;
                           w r i t e l n ( ' f f r e e     :  ' , i n f o.f f r e e) ;
                           { $ i f d e f FreeBSD     }
                           w r i t e l n ( ' f s i d       :  ' , i n f o.f s i d[ 0 ] ) ;
                           { $ e l s e}
                           w r i t e l n ( ' f s i d       :  ' , i n f o.f s i d[ 0 ] ) ;
                           w r i t e l n ( 'Namelen        :  ' , i n f o.n a m e l e n) ;
                           { $ e n d i f}
                           w r i t e (  'Type    name     o f   f i l e t o  do    f s s t a t.  (q   q u i t s)  : ' ) ;
                           r e a d l n ( s )


                           end  ;
                       end   ;
                end___.____________________________________________________________________________________________________________*
 *___________



                41.3.31          TellDir

    Synopsis:    Return current location in a directory

Declaration:     function  TellDir(p:  pDir)  :  TOff

    Visibility:   default



                                                                                1712

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



Description:     TellDir returns the current location in the directory structure pointed to by p.  It returns
                -1 on failure.

                For an example, see #rtl.baseunix.fpOpenDir (170  ).

    See also:    #rtl.baseunix.fpCloseDir  (146  ),  #rtl.baseunix.fpReadDir  (174  ),  #rtl.baseunix.fpOpenDir
                (170  ), SeekDir (1709   )



                41.3.32          WaitProcess

    Synopsis:    Wait for process to terminate.

Declaration:     function  WaitProcess(Pid:  cint)  :  cint

    Visibility:   default

Description:     WaitProcess waits for process PID to exit.  WaitProcess is equivalent to the #rtl.baseunix.FpWaitPID
                (194  ) call:


                FpWaitPid(PID,@result,0)


                Handles of Signal interrupts (errno=EINTR), and returns the Exitcode of Process PID (>=0)
                or -Status if it was terminated

       Errors:   None.

    See also:    #rtl.baseunix.FpWaitPID (194  ), #rtl.baseunix.WTERMSIG (196  ), #rtl.baseunix.WSTOPSIG
                (196  ), #rtl.baseunix.WIFEXITED (196  ), WIFSTOPPED (1713   ), #rtl.baseunix.WIFSIGNALED
                (196  ), W_EXITCODE (1713   ), W_STOPCODE (1714   ), #rtl.baseunix.WEXITSTATUS (195  )



                41.3.33          WIFSTOPPED

    Synopsis:    Check whether the process is currently stopped.

Declaration:     function  WIFSTOPPED(Status:  Integer)  :  Boolean

    Visibility:   default

Description:     WIFSTOPPED  checks  Status  and  returns  true  if  the  process  is  currently  stopped.  This  is
                only possible if WUNTRACED was specified in the options of FpWaitPID (194  ).

    See also:    #rtl.baseunix.FpWaitPID  (194  ),  WaitProcess  (1713   ),  #rtl.baseunix.WTERMSIG  (196  ),
                #rtl.baseunix.WSTOPSIG (196  ), #rtl.baseunix.WIFEXITED (196  ), #rtl.baseunix.WIFSIGNALED
                (196  ), W_EXITCODE (1713   ), W_STOPCODE (1714   ), #rtl.baseunix.WEXITSTATUS (195  )



                41.3.34          W__EXITCODE

    Synopsis:    Construct an exit status based on an return code and signal.

Declaration:     function  W_EXITCODE(ReturnCode:  Integer;Signal:  Integer)  :  Integer

    Visibility:   default

Description:     W_EXITCODE combines ReturnCode and Signal to a status code fit for WaitPid.

    See also:    #rtl.baseunix.FpWaitPID  (194  ),  WaitProcess  (1713   ),  #rtl.baseunix.WTERMSIG  (196  ),
                #rtl.baseunix.WSTOPSIG (196  ), #rtl.baseunix.WIFEXITED (196  ), WIFSTOPPED (1713   ),
                #rtl.baseunix.WIFSIGNALED (196  ), W_EXITCODE (1713   ), W_STOPCODE (1714   ), #rtl.baseunix.WEXITSTATUS
                (195  )



                                                                                1713

                ______________________________________________________________CHAPTER_41.___REFERENCE_FOR_UNIT_'UNIX'______________*
 *___________________



                41.3.35          W__STOPCODE

    Synopsis:    Construct an exit status based on a signal.

Declaration:     function  W_STOPCODE(Signal:  Integer)  :  Integer

    Visibility:   default

Description:     W_STOPCODE constructs an exit status based on Signal, which will cause WIFSIGNALED
                (196  ) to return True

    See also:    #rtl.baseunix.FpWaitPID  (194  ),  WaitProcess  (1713   ),  #rtl.baseunix.WTERMSIG  (196  ),
                #rtl.baseunix.WSTOPSIG (196  ), #rtl.baseunix.WIFEXITED (196  ), WIFSTOPPED (1713   ),
                #rtl.baseunix.WIFSIGNALED (196  ), W_EXITCODE (1713   ), #rtl.baseunix.WEXITSTATUS
                (195  )



                                                                                1714




Chapter   42



Reference   for   unit   'unixtype'



42.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.



42.2          Constants,  types  and  variables



42.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 (159  ) option:  Get process group priority.


Prio_Process  =  0


#rtl.baseunix.fpGetPriority (159  ) option:  Get process priority.


Prio_User  =  2


#rtl.baseunix.fpGetPriority (159  ) option:  Get user priority.



                                                            1715

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



SIG_MAXSIG  =  128


Maximum signal number.


SYS_NMLN  =  65


Max system namelength


_PTHREAD_MUTEX_ADAPTIVE_NP  =  3


Mutex options:


_PTHREAD_MUTEX_DEFAULT  =  _PTHREAD_MUTEX_NORMAL


Mutex options:


_PTHREAD_MUTEX_ERRORCHECK  =  _PTHREAD_MUTEX_ERRORCHECK_NP


Mutex options:


_PTHREAD_MUTEX_ERRORCHECK_NP  =  2


Mutex options:  double lock returns an error code.


_PTHREAD_MUTEX_FAST_NP  =  _PTHREAD_MUTEX_ADAPTIVE_NP


Mutex options:  Fast mutex


_PTHREAD_MUTEX_NORMAL  =  _PTHREAD_MUTEX_TIMED_NP


Mutex options:


_PTHREAD_MUTEX_RECURSIVE  =  _PTHREAD_MUTEX_RECURSIVE_NP


Mutex options:


_PTHREAD_MUTEX_RECURSIVE_NP  =  1


Mutex options:  recursive mutex


_PTHREAD_MUTEX_TIMED_NP  =  0


Mutex options:  ?



42.2.2         Types

cbool  =  longbool


Boolean type



                                                                1716

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



cchar  =  cint8


C type:  8-bit signed integer


cdouble  =  Double


Double precision real format.


cfloat  =  single


Floating-point real format


cint  =  cint32


C type:  integer (natural size)


cint16  =  SmallInt


C type:  16 bits sized, signed integer.


cint32  =  LongInt


C type:  32 bits sized, signed integer.


cint64  =  Int64


C type:  64 bits sized, signed integer.


cint8  =  ShortInt


C type:  8 bits sized, signed integer.


clock_t  =  culong


Clock ticks type


clong  =  LongInt


C type:  long signed integer (double sized)


clongdouble  =  extended


Usually translates to an extended, but is CPU dependent.


clonglong  =  cint64


C type:  64-bit (double long) signed integer.


cschar  =  cint8


Signed character type



                                                                1717

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



cshort  =  cint16


C type:  short signed integer (half sized)


csigned  =  cint


csigned is an alias for cint (1717   ).


csint  =  cint32


Signed integer


cslong  =  LongInt


The size is CPU dependent.


cslonglong  =  cint64


cslonglong is an alias for clonglong (1717   ).


csshort  =  cint16


Short signed integer type


cuchar  =  cuint8


C type:  8-bit unsigned integer


cuint  =  cuint32


C type:  unsigned integer (natural size)


cuint16  =  Word


C type:  16 bits sized, unsigned integer.


cuint32  =  LongWord


C type:  32 bits sized, unsigned integer.


cuint64  =  QWord


C type:  64 bits sized, unsigned integer.


cuint8  =  Byte


C type:  8 bits sized, unsigned integer.


culong  =  Cardinal


C type:  long unsigned integer (double sized)



                                                                1718

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



culonglong  =  cuint64


C type:  64-bit (double long) unsigned integer.


cunsigned  =  cuint


Alias for #rtl.unixtype.cuint (1718   )


cushort  =  cuint16


C type:  short unsigned integer (half sized)


dev_t  =  cuint64


Device descriptor type.


gid_t  =  cuint32


Group ID type.


ino64_t  =  cuint64


ino64_t is an inode type capable of containing 64-bit inodes.


ino_t  =  clong


Inode type.


ipc_pid_t  =  cushort


Process ID


kDev_t  =  cushort


Kernel device type


mbstate_t  =  record
   __count  :  cint;
   __value  :  mbstate_value_t;
end



This type should never be used directly.


mbstate_value_t  =  record
end



This type should never be used directly.  It is part of the mbstate_t (1719   ) type.


mode_t  =  cuint32



                                                                1719

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



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 (1716   )


pcchar  =  ^cchar


Pointer to #rtl.UnixType.cchar (1717   )


pcdouble  =  ^cdouble


Pointer to cdouble (1717   ) type.


pcfloat  =  ^cfloat


Pointer to cfloat (1717   ) type.


pcint  =  ^cint


Pointer to cInt (1717   ) type.


pcint16  =  ^cint16


Pointer to 16-bit signed integer type


pcint32  =  ^cint32


Pointer to signed 32-bit integer type


pcint64  =  ^cint64


Pointer to signed 64-bit integer type


pcint8  =  ^cint8


Pointer to 8-bits signed integer type


pClock  =  ^clock_t



                                                                1720

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



Pointer to TClock (1726   ) type.


pclong  =  ^clong


Pointer to cLong (1717   ) type.


pclongdouble  =  ^clongdouble


Pointer to the long double type clongdouble (1717   )


pclonglong  =  ^clonglong


Pointer to longlong type.


pcschar  =  ^cschar


Pointer to character type cschar (1717   ).


pcshort  =  ^cshort


Pointer to cShort (1718   ) type.


pcsigned  =  ^csigned


Pointer to signed integer type csigned (1718   ).


pcsint  =  ^csint


Pointer to signed integer type csint (1718   )


pcslong  =  ^cslong


Pointer ot the signed long cslong (1718   )


pcslonglong  =  ^cslonglong


Pointer to Signed longlong type cslonglong (1718   )


pcsshort  =  ^csshort


Pointer to short signed integer type csshort (1718   )


pcuchar  =  ^cuchar


Pointer to #rtl.UnixType.cuchar (1718   )


pcuint  =  ^cuint


Pointer to cUInt (1718   ) type.


pcuint16  =  ^cuint16



                                                                1721

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



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 (1718   ) type.


pculonglong  =  ^culonglong


Unsigned longlong type


pcunsigned  =  ^cunsigned


Pointer to #rtl.unixtype.cunsigned (1719   )


pcushort  =  ^cushort


Pointer to cuShort (1719   ) type.


pDev  =  ^dev_t


Pointer to TDev (1726   ) type.


pGid  =  ^gid_t


Pointer to TGid (1726   ) type.


pid_t  =  cint


Process ID type.


pIno  =  ^ino_t


Pointer to TIno (1727   ) type.


pIno64  =  ^ino64_t


Pointer to ino64_t (1719   )


pkDev  =  ^kDev_t



                                                                1722

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



Pointer to TkDev (1727   ) type.


pmbstate_t  =  ^mbstate_t


Pointer to mbstate_t (1719   ) type


pMode  =  ^mode_t


Pointer to TMode (1727   ) type.


pnLink  =  ^nlink_t


Pointer to TnLink (1727   ) type.


pOff  =  ^off_t


Pointer to TOff (1727   ) type.


pOff64  =  ^off64_t


Pointer to off64_t type


pPid  =  ^pid_t


Pointer to TPid (1727   ) type.


pSize  =  ^size_t


Pointer to TSize (1727   ) type.


psize_t  =  pSize


Pointer to size_t (1726   ) type.


pSockLen  =  ^socklen_t


Pointer to TSockLen (1727   ) type.


pSSize  =  ^ssize_t


Pointer to TsSize (1727   ) type


PStatFS  =  ^TStatfs


Pointer to TStatFS (1728   ) type.


pthread_attr_t  =  record
   __detachstate  :  cint;
   __schedpolicy  :  cint;
   __schedparam  :  sched_param;
   __inheritsched  :  cint;



                                                                1723

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



   __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



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.



                                                                1724

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



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
   __rw_readers  :  cint;
   __rw_writer  :  pointer;
   __rw_read_waiting  :  pointer;
   __rw_write_waiting  :  pointer;
   __rw_kind  :  cint;
   __rw_pshared  :  cint;
end



pthread_rwlock_t describes a lock.  It should be considered an opaque record, the names of
the fields can change anytime.


pthread_t  =  culong


Thread description record


pTime  =  ^time_t


Pointer to TTime (1728   ) type.


ptimespec  =  ^timespec


Pointer to timespec (1726   ) record.


ptimeval  =  ^timeval


Pointer to timeval (1726   ) record.


ptime_t  =  ^time_t


Pointer to time_t (1727   ) type.


pUid  =  ^uid_t


Pointer to TUid (1728   ) type.


pwchar_t  =  ^wchar_t


Pointer to wchar_t (1728   ) type.


sched_param  =  record
   __sched_priority  :  cint;
end



                                                                1725

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



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  =  cuint32


Size specification type.


socklen_t  =  cuint32


Socket address length type.


ssize_t  =  cint32


Small size type.


TClock  =  clock_t


Alias for clock_t (1717   ) type.


TDev  =  dev_t


Alias for dev_t (1719   ) type.


TGid  =  gid_t


Alias for gid_t (1719   ) type.


timespec  =  packed  record
   tv_sec  :  time_t;
   tv_nsec  :  clong;
end



Record specifying time interval.


timeval  =  packed  record
   tv_sec  :  time_t;
   tv_usec  :  clong;
end



Time specification type.



                                                                1726

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



time_t  =  clong


Time span type


TIno  =  ino_t


Alias for ino_t (1719   ) type.


TIno64  =  ino64_t


Alias for ino64_t (1719   )


TIOCtlRequest  =  cint


Opaque type used in FpIOCtl (160  )


TkDev  =  kDev_t


Alias for kDev_t (1719   ) type.


TMode  =  mode_t


Alias for mode_t (1720   ) type.


TnLink  =  nlink_t


Alias for nlink_t (1720   ) type.


TOff  =  off_t


Alias for off_t (1720   ) type.


TOff64  =  off64_t


Alias for off64_t type.


TPid  =  pid_t


Alias for pid_t (1722   ) type.


TSize  =  size_t


Alias for size_t (1726   ) type


TSockLen  =  socklen_t


Alias for socklen_t (1726   ) type.


TSSize  =  ssize_t


Alias for ssize_t (1726   ) type



                                                                1727

______________________________________________________CHAPTER_42.___REFERENCE_FOR_UNIT_'UNIXTYPE'__________________________________*
 *___



TStatfs  =  packed  record
   fstype  :  cint;
   bsize  :  cint;
   blocks  :  culong;
   bfree  :  culong;
   bavail  :  culong;
   files  :  culong;
   ffree  :  culong;
   fsid  :  Array[0..1]  of  cint;
   namelen  :  cint;
   frsize  :  cint;
   spare  :  Array[0..4]  of  cint;
end



Record describing a file system in the baseunix.fpstatfs (102  ) call.


TTime  =  time_t


Alias for TTime (1728   ) type.


TTimeSpec  =  timespec


Alias for TimeSpec (1726   ) type.


TTimeVal  =  timeval


Alias for TimeVal (1726   ) record.


TUid  =  uid_t


Alias for uid_t (1728   ) 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.



                                                                1728




Chapter   43



Reference   for   unit   'unixutil'



43.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 (1677   ) or baseunix (102  ) units.

Most of the functions described here have cross-platform counterparts in the SysUtils (1450   )
unit.  It is therefore recommended to use that unit.



43.2          Constants,  types  and  variables



43.2.1         Types

ComStr  =  string


Command-line string type.


DirStr  =  string


Filename directory part string type.


ExtStr  =  string


Filename extension part string type.


NameStr  =  string


Filename name part string type.


PathStr  =  string


Filename full path string type.



43.2.2         Variables

Tzseconds  :  LongInt


Seconds west of GMT



                                                            1729

                _______________________________________________________CHAPTER_43.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



                43.3          Procedures  and  functions



                43.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 (1735   )



                43.3.2         Basename

    Synopsis:    Return basename of a file

Declaration:     function  Basename(const  path:  PathStr;const  suf:  PathStr)  :  PathStr

    Visibility:   default

Description:     Returns the filename part of  Path, stripping off  Suf if it exists.  The filename part is the
                whole  name  if  Path  contains  no  slash,  or  the  part  of  Path  after  the  last  slash.   The  last
                character of the result is not a slash, unless the directory is the root directory.

       Errors:   None.

    See also:    DirName (1731   )


                Listing:  ./unutilex/ex48.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 8;


                {   Program       t o  d e m o n s t r a t et h e  BaseName        f u n c t i o n. }


                Uses     Dos   ,Unix   , U n i x U t i l;


                Var    S   :   S t r i n g;


                 b e g i n
                    S := FExpand     ( Paramstr      ( 0 ) ) ;
                    W r i t e l n ( ' T h i s p r o g r a m i s   c a l l e d :  ' ,Basename      ( S , ' ') ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1730

                _______________________________________________________CHAPTER_43.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



                43.3.3         Dirname

    Synopsis:    Extract directory part from filename

Declaration:     function  Dirname(const  path:  PathStr)  :  PathStr

    Visibility:   default

Description:     Returns the directory part of  Path.  The directory is the part of  Path before the last slash,
                or  empty  if  there  is  no  slash.   The  last  character  of  the  result  is  not  a  slash,  unless  the
                directory is the root directory.

       Errors:   None.

    See also:    BaseName (1730   )


                Listing:  ./unutilex/ex47.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 4 7;


                {   Program       t o  d e m o n s t r a t et h e  DirName       f u n c t i o n. }


                Uses     Dos   ,Unix   , U n i x U t i l;


                Var    S   :   S t r i n g;


                 b e g i n
                    S := FExpand     ( Paramstr      ( 0 ) ) ;
                    W r i t e l n ( ' T h i s p r o g r a m i s  i n   d i r e c t o r y:   ' ,Dirname     ( S ) ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                43.3.4         EpochToLocal

    Synopsis:    Convert epoch time to local time

Declaration:     procedure  EpochToLocal(epoch:  LongInt;var  year:  Word;var  month:  Word;
                                                     var  day:  Word;var  hour:  Word;var  minute:  Word;
                                                     var  second:  Word)

    Visibility:   default

Description:     Converts the epoch time (=Number of seconds since 00:00:00 , January 1, 1970, corrected
                for your time zone ) to local date and time.

                This function takes into account the timzeone settings of your system.

       Errors:   None

    See also:    LocalToEpoch (1734   )


                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   ;



                                                                                1731

                _______________________________________________________CHAPTER_43.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



                 b e g i n
                    E p o c h T o L o c a l(FPTime     , Year   ,month    , day  , h o u r,m i n u t e, s e c o n d s) ;
                    W r i t e l n ( ' C u r r e n td a t e  :   ' ,Day  : 2 , '/ ' ,Month    : 2 , '/ ' ,Y e a r : 4 ) ;
                    W r i t e l n ( ' C u r r e n tt i m e  :   ' ,Hour   : 2 , ': ' ,m i n u t e: 2 ,' : ' ,s e c o n d s: 2 ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                43.3.5         FNMatch

    Synopsis:    Check whether filename matches wildcard specification

Declaration:     function  FNMatch(const  Pattern:  string;const  Name:  string)  :  Boolean

    Visibility:   default

Description:     FNMatch  returns  True  if  the  filename  in  Name  matches  the  wildcard  pattern  in  Pattern,
                False otherwise.

                Pattern can contain the wildcards * (match zero or more arbitrary characters) or ?  (match
                a single character).

       Errors:   None.

    See also:    #rtl.unix.FSearch (1703   )


                Listing:  ./unutilex/ex69.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 9;


                {   Program       t o  d e m o n s t r a t et h e  FNMatch       f u n c t i o n. }


                Uses      u n i x u t i;l


                    P r o c e d u r eTestMatch       ( P a t t e r n,Name     :  S t r i n g) ;


                    b e g i n
                       Write      ( '"  ',Name    , '"   ' ) ;
                        I f  FNMatch       (P a t t e r n,Name    )  then
                           Write     (  'm a t c h e s')
                        e l s e
                           Write     (  'd o e s  n o t  match    ') ;
                        W r i t e l n('  " ' ,P a t t e r n,' " . ') ;
                    end  ;


                 b e g i n
                    TestMatch       ( '* ' , 'F i l e N a m e') ;
                    TestMatch       ( '. * ' , 'F i l e N a m e') ;
                    TestMatch       ( '* a * ' ,' F i l e N a m e') ;
                    TestMatch       ( '? i l e* ' , 'F i l e N a m e') ;
                    TestMatch       ( '? ' , 'F i l e N a m e') ;
                    TestMatch       ( '. ? ' , 'F i l e N a m e') ;
                    TestMatch       ( '? a * ' ,' F i l e N a m e') ;
                    TestMatch       ( '? ? *me  ? ' ,' F i l e N a m e') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                                                                                1732

                _______________________________________________________CHAPTER_43.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



                43.3.6         FSplit

    Synopsis:    Split filename into path, name and extension

Declaration:     procedure  FSplit(const  Path:  PathStr;var  Dir:  DirStr;var  Name:  NameStr;
                                           var  Ext:  ExtStr)

    Visibility:   default

Description:     FSplit splits a full file name into 3 parts :  A Path, a Name and an extension (in ext).  The
                extension is taken to be all letters after the last dot (.).

       Errors:   None.

    See also:    #rtl.unix.FSearch (1703   )


                Listing:  ./unutilex/ex67.pp
                ___________________________________________________________________________________________________________________*
 *___________
                Program       E x a m p l e 6 7;


                 u s e s U n i x U t i l;


                {   Program       t o  d e m o n s t r a t et h e  F S p l i t f u n c t i o n.  }


                 v a r
                    Path   ,Name    ,E x t   :  s t r i n g;


                 b e g i n
                    F S p l i t(ParamStr      ( 1 ) ,Path   ,Name    , E x t) ;
                    WriteLn     ( ' S p l i t  ', ParamStr      ( 1 ) ,'  i n : ') ;
                    WriteLn     ( ' Path            :  ' ,Path    ) ;
                    WriteLn     ( 'Name             :  ' ,Name    ) ;
                    WriteLn     ( ' E x t e n s i o n: ' ,E x t ) ;
                end___.____________________________________________________________________________________________________________*
 *___________



                43.3.7         GetFS

    Synopsis:    Return file selector

Declaration:     function  GetFS(var  T:  Text)  :  LongInt
                function  GetFS(var  F:  File)  :  LongInt

    Visibility:   default

Description:     GetFS returns the file selector that the kernel provided for your file.  In principle you don'
                need this file selector.  Only for some calls it is needed,  such as the #rtl.baseunix.fpSelect
                (177  ) call or so.

       Errors:   In case the file was not opened, then -1 is returned.

    See also:    #rtl.baseunix.fpSelect (177  )


                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;



                                                                                1733

                _______________________________________________________CHAPTER_43.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



                Var     t v  :  TimeVal      ;


                 b e g i n
                    W r i t e l n ( ' P r e s s t h e < ENTER    >   t o  c o n t i n u e t h e  p r o g r a m.' ) ;
                    {  Wait     u n t i l  F i l e  d e s c r i p t o r0  ( = I n p u t)  c h a n g e s }
                    S e l e c t T e x t( I n p u t, n i l) ;
                    {  Get     r i d  o f < ENTER    >   i n  b u f f e r }
                    r e a d l n;
                    W r i t e l n ( ' P r e s s< ENTER    >   k e y  i n  l e s s  t h a n 2   s e c o n d s. . .') ;
                    t v .t v _s e c : = 2 ;
                    t v .t v _s e c : = 0 ;
                    i f  S e l e c t T e x t( I n p u t, @tv  ) >0   then
                        W r i t e l n(  'Thank     you    ! ' )
                    e l s e
                        W r i t e l n(  'Too    l a t e  ! ') ;
                end___.____________________________________________________________________________________________________________*
 *___________



                43.3.8         GregorianToJulian

    Synopsis:    Converts a gregorian date to a julian date

Declaration:     function  GregorianToJulian(Year:  LongInt;Month:  LongInt;Day:  LongInt)
                                                             :  LongInt

    Visibility:   default

Description:     GregorianToJulian takes a gregorian date and converts it to a Julian day.

       Errors:   None.

    See also:    JulianToGregorian (1734   )



                43.3.9         JulianToGregorian

    Synopsis:    Converts a julian date to a gregorian date

Declaration:     procedure  JulianToGregorian(JulianDN:  LongInt;var  Year:  Word;
                                                             var  Month:  Word;var  Day:  Word)

    Visibility:   default

Description:     JulianToGregorian takes a julian day and converts it to a gregorian date.  (Start of the
                Julian Date count is from 0 at 12 noon 1 JAN -4712 (4713 BC),)

       Errors:   None.

    See also:    GregorianToJulian (1734   )



                43.3.10          LocalToEpoch

    Synopsis:    Convert local time to epoch (unix) time

Declaration:     function  LocalToEpoch(year:  Word;month:  Word;day:  Word;hour:  Word;
                                                   minute:  Word;second:  Word)  :  LongInt

    Visibility:   default



                                                                                1734

                _______________________________________________________CHAPTER_43.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________*
 *___________________



Description:     Converts  the  Local  time  to  epoch  time  (=Number  of  seconds  since  00:00:00  ,  January  1,
                1970 ).

       Errors:   None

    See also:    EpochToLocal (1731   )


                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___.____________________________________________________________________________________________________________*
 *___________



                43.3.11          StringToPPChar

    Synopsis:    Split string in list of null-terminated strings

Declaration:     function  StringToPPChar(S:  PChar;ReserveEntries:  Integer)  :  ppchar
                function  StringToPPChar(var  S:  string;ReserveEntries:  Integer)  :  ppchar
                function  StringToPPChar(var  S:  AnsiString;ReserveEntries:  Integer)
                                                        :  ppchar

    Visibility:   default

Description:     StringToPPChar splits the string S in words, replacing any whitespace with zero characters.
                It returns a pointer to an array of pchars that point to the first letters of the words in S.
                This array is terminated by a Nil pointer.

                The function does not add a zero character to the end of the string unless it ends on whites-
                pace.

                The function reserves memory on the heap to store the array of PChar; The caller is respon-
                sible for freeing this memory.

                This function can be called to create arguments for the various Exec calls.

       Errors:   None.

    See also:    ArrayStringToPPchar (1730   ), #rtl.baseunix.FpExecve (150  )


                Listing:  ./unutilex/ex70.pp



                                                                                1735

_______________________________________________________CHAPTER_43.___REFERENCE_FOR_UNIT_'UNIXUTIL'_________________________________*
 *___



______________________________________________________________________________________________________________________________
Program       E x a m p l e 7 0;


{   Program       t o  d e m o n s t r a t et h e  S t r i n g T o P P c h a rf u n c t i o.n  }


Uses     U n i x U t i l;


Var    S   :   S t r i n g;
       P   :  PPChar     ;
        I  :   l o n g i n t;


 b e g i n
    //   r e m a r k  w h i t e s p a c ea t  end  .
    S :=  'T h i s  i s  a   s t r i n g w i t h w o r d s.   ';
    P := S t r i n g T o P P C h a(rS, 0 ) ;
    I : = 0 ;
    While     P [ i]<>   N i l  do
        b e g i n
        W r i t e l n('Word     ' ,i , '   :  ' ,P [ i ] ) ;
        I n c( I) ;
       end   ;
    FreeMem     ( P , i* S i z e O f(P c h a r) ) ;
end___._______________________________________________________________________________________________________________________



                                                                1736




Chapter   44



Reference   for   unit   'video'



44.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  (1756   ),  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 (1759   ) 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.



                                                            1737

               ____________________________________________________________CHAPTER_44.___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 (1756   ) function can be used:  This will increment an internal counter.  As
               long as the counter differs from zero, calling UpdateScreen (1759   ) will not do anything.  The
               counter can be lowered with UnlockScreenUpdate (1759   ).  When it reaches zero, the next call
               to UpdateScreen (1759   ) 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 (1758   )
               call.  The current video driver can be retrieved using the GetVideoDriver (1753   ) 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.



               44.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___._____________________________________________________________________________________________________________*
 *__________



                                                                               1738

____________________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___



44.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 (1758   ) function.  The various
functions that can be implemented are located in the TVideoDriver (1748   ) 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)



                                                                1739

____________________________________________________________CHAPTER_44.___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;



                                                                1740

____________________________________________________________CHAPTER_44.___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



                                                                1741

____________________________________________________________CHAPTER_44.___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___._______________________________________________________________________________________________________________________



44.4          Constants,  types  and  variables



44.4.1         Constants

Black  =  0


Black color attribute


Blink  =  128


Blink attribute


Blue  =  1



                                                                1742

____________________________________________________________CHAPTER_44.___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



                                                                1743

____________________________________________________________CHAPTER_44.___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 (1750   ) 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



                                                                1744

____________________________________________________________CHAPTER_44.___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



                                                                1745

____________________________________________________________CHAPTER_44.___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



44.4.2         Types

PVideoBuf  =  ^TVideoBuf


Pointer type to TVideoBuf (1747   )


PVideoCell  =  ^TVideoCell


Pointer type to TVideoCell (1748   )


PVideoMode  =  ^TVideoMode


Pointer to TVideoMode (1748   ) record.


Tencoding  =  (cp437,cp850,cp852,cp866,koi8r,iso01,iso02,iso03,iso04,
                      iso05,iso06,iso07,iso08,iso09,iso10,iso13,iso14,iso15,utf8)



                                                                1746

____________________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'VIDEO'_______________________________*
 *___



                           Table 44.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 44.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.



                                                                1747

____________________________________________________________CHAPTER_44.___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
(1758   ) 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.



44.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.



                                                                1748

                ____________________________________________________________CHAPTER_44.___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 (1759   ) 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 (1759   ) will write the actual characters to the
                screen.


                VideoBufSize  :  LongInt


                Current size of the video buffer pointed to by VideoBuf (1749   )



                44.5          Procedures  and  functions



                44.5.1         ClearScreen

    Synopsis:    Clear the video screen.

Declaration:     procedure  ClearScreen

    Visibility:   default

Description:     ClearScreen  clears  the  entire  screen,  and  calls  UpdateScreen  (1759   )  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).



                                                                                1749

                ____________________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



       Errors:   None.

    See also:    InitVideo (1756   ), UpdateScreen (1759   )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.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.



                44.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.



                                                                                1750

                ____________________________________________________________CHAPTER_44.___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 (1756   )



                44.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 (1752   ), GetVideoDriver (1753   )


                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



                                                                                1751

                ____________________________________________________________CHAPTER_44.___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___.____________________________________________________________________________________________________________*
 *___________



                44.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 (1758   ), GetCapabilities (1751   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1752

                ____________________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                44.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 (1759   ) will actually update the screen.

       Errors:   None.

    See also:    LockScreenUpdate (1756   ), UnlockScreenUpdate (1759   ), UpdateScreen (1759   )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.5.7         GetVideoDriver

    Synopsis:    Get a copy of the current video driver.

Declaration:     procedure  GetVideoDriver(var  Driver:  TVideoDriver)

    Visibility:   default



                                                                                1753

                ____________________________________________________________CHAPTER_44.___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
                (1758   ) call.

       Errors:   None.

    See also:    SetVideoDriver (1758   )



                44.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 (1758   ), GetVideoModeData (1756   )


                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___.____________________________________________________________________________________________________________*
 *___________



                44.5.9         GetVideoModeCount

    Synopsis:    Get the number of video modes supported by the driver.



                                                                                1754

                ____________________________________________________________CHAPTER_44.___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  (1756   )  function  to
                retrieve data for the supported video modes.

       Errors:   None.

    See also:    GetVideoModeData (1756   ), GetVideoMode (1754   )


                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___.____________________________________________________________________________________________________________*
 *___________



                                                                                1755

                ____________________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                44.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 (1754   ).

       Errors:   In case Index has a wrong value, False is returned.

    See also:    GetVideoModeCount (1754   ), SetVideoMode (1758   ), GetVideoMode (1754   )



                44.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 (1750   )



                44.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 (1759   ) 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 (1759   ) after the drawing, followed by a UpdateScreen (1759   ) call,
                all writing will be shown on screen at once.

                For an example, see GetLockScreenCount (1753   ).

       Errors:   None.

    See also:    UpdateScreen (1759   ), UnlockScreenUpdate (1759   ), GetLockScreenCount (1753   )



                                                                                1756

                ____________________________________________________________CHAPTER_44.___REFERENCE_FOR_UNIT_'VIDEO'_______________*
 *___________________



                44.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 (1758   )


                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



                                                                                1757

                ____________________________________________________________CHAPTER_44.___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___.____________________________________________________________________________________________________________*
 *___________



                44.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 (1757   )



                44.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 (1756   )) or after it was deactivated (i.e after a call to DoneVideo).

                For more information about installing a videodriver, see viddriver (1739   ).

                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 (1739   )



                44.5.16          SetVideoMode

    Synopsis:    Set current video mode.

Declaration:     function  SetVideoMode(const  Mode:  TVideoMode)  :  Boolean

    Visibility:   default



                                                                                1758

                ____________________________________________________________CHAPTER_44.___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
                (1756   )  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 (1754   ) and GetVideoMode-
                Data (1756   ) functions.  To retrieve the current video mode, use the GetVideoMode (1754   )
                procedure.

       Errors:   If the specified mode cannot be set, then errVioNoSuchMode may be set in ErrorCode

    See also:    GetVideoModeCount (1754   ), GetVideoModeData (1756   ), GetVideoMode (1754   )



                44.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 (1759   ) 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 (1756   ) is matched by exactly
                one call to UnlockScreenUpdate

                For an example, see GetLockScreenCount (1753   ).

       Errors:   None.

    See also:    LockScreenUpdate (1756   ), GetLockScreenCount (1753   ), UpdateScreen (1759   )



                44.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



                                                                                1759

            ____________________________________________________________CHAPTER_44.___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 (1749   )



                                                                            1760




                Chapter   45



                Reference   for   unit   'wincrt'



                45.1          Overview


                The wincrt unit provides some auxiliary routines for use with the graph (634  ) unit, namely
                keyboard support.  It has no connection with the crt (424  ) unit, nor with the Turbo-Pascal
                for  Windows  WinCrt  unit.  As  such,  it  should  not  be  used  by  end  users.  Refer  to  the  crt
                (424  ) unit instead.



                45.2          Constants,  types  and  variables



                45.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.



                45.3          Procedures  and  functions



                45.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 (1762   ), nosound (1762   )



                45.3.2         keypressed

    Synopsis:    Check if a key was pressed.



                                                                            1761

                _________________________________________________________CHAPTER_45.___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 (1762   )



                45.3.3         nosound

    Synopsis:    Stop the speaker

Declaration:     procedure  nosound

    Visibility:   default

Description:     NoSound does nothing, windows does not support this.

    See also:    sound (1762   )



                45.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 (1761   )



                45.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 (1762   )



                45.3.6         textmode

    Synopsis:    Set indicated text mode

Declaration:     procedure  textmode(mode:  Integer)

    Visibility:   default

Description:     TextMode does nothing.



                                                                                1762




                Chapter   46



                Reference   for   unit   'x86'



                46.1          Used  units



                                                      Table 46.1:  Used units by unit 'x86'


                                                                  _Name_____________Page______
                                                                    BaseUnix           102
                                                                    System           1230



                46.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.



                46.3          Procedures  and  functions



                46.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 (153  ), the permissions are reset.  When doing a FpExecVE (150  )
                       they are kept.

       Errors:   Extended error information can be retrieved with FpGetErrno (156  )



                                                                            1763

                _________________________________________________________________CHAPTER_46.___REFERENCE_FOR_UNIT_'X86'____________*
 *___________________



                46.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.



                46.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 (1763   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm  (1763   ),  ReadPortB  (1764   ),  ReadPortW  (1765   ),  ReadPortL  (1765   ),  WritePort
                (1765   ), WritePortB (1766   ), WritePortL (1766   ), WritePortW (1766   )



                46.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 (1763   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm  (1763   ),  ReadPort  (1764   ),  ReadPortW  (1765   ),  ReadPortL  (1765   ),  WritePort
                (1765   ), WritePortB (1766   ), WritePortL (1766   ), WritePortW (1766   )



                                                                                1764

                _________________________________________________________________CHAPTER_46.___REFERENCE_FOR_UNIT_'X86'____________*
 *___________________



                46.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 (1763   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm  (1763   ),  ReadPort  (1764   ),  ReadPortW  (1765   ),  ReadPortB  (1764   ),  WritePort
                (1765   ), WritePortB (1766   ), WritePortL (1766   ), WritePortW (1766   )



                46.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 (1763   ) call.

       Errors:   In case of an error (not enough permissions read this port), runtime 216 (Access Violation)
                will occur.

    See also:    FpIOPerm (1763   ), ReadPort (1764   ), ReadPortB (1764   ), ReadPortL (1765   ), WritePort (1765   ),
                WritePortB (1766   ), WritePortL (1766   ), WritePortW (1766   )



                46.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 (1763   ) call.



                                                                                1765

                _________________________________________________________________CHAPTER_46.___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 (1763   ), WritePortB (1766   ), WritePortL (1766   ), WritePortW (1766   ), ReadPortB
                (1764   ), ReadPortL (1765   ), ReadPortW (1765   )



                46.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 (1763   ) call.

       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm (1763   ),  WritePort (1765   ),  WritePortL (1766   ),  WritePortW (1766   ),  ReadPortB
                (1764   ), ReadPortL (1765   ), ReadPortW (1765   )



                46.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 (1763   ) call.

       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm (1763   ), WritePort (1765   ), WritePortB (1766   ), WritePortW (1766   ), ReadPortB
                (1764   ), ReadPortL (1765   ), ReadPortW (1765   )



                46.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



                                                                                1766

                _________________________________________________________________CHAPTER_46.___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 (1763   ) call.

       Errors:   In  case  of  an  error  (not  enough  permissions  to  write  to  this  port),  runtime  216  (Access
                Violation) will occur.

    See also:    FpIOPerm  (1763   ),  WritePort  (1765   ),  WritePortL  (1766   ),  WritePortB  (1766   ),  ReadPortB
                (1764   ), ReadPortL (1765   ), ReadPortW (1765   )



                                                                                1767
