

Free  Component  Library  (FCL):

Reference  guide.

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

                                                                          Reference guide for FCL units.

                                                                                         Document version 2.1

                                                                                                            June 2008


Micha"el Van Canneyt
______________________________________________________________________________________________________________________________



Contents



     0.1    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    28


1    Reference for unit 'base64'                                                                                          29

     1.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    29

     1.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    29

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

            1.3.1     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    29

     1.4    EBase64DecodingException                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    30

            1.4.1     Description       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    30

     1.5    TBase64DecodingStream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    30

            1.5.1     Description       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    30

            1.5.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    30

            1.5.3     Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    30

            1.5.4     TBase64DecodingStream.Create                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    30

            1.5.5     TBase64DecodingStream.Reset                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    31

            1.5.6     TBase64DecodingStream.Read                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    31

            1.5.7     TBase64DecodingStream.Seek                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    31

            1.5.8     TBase64DecodingStream.EOF                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    32

            1.5.9     TBase64DecodingStream.Mode                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    32

     1.6    TBase64EncodingStream                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    32

            1.6.1     Description       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    32

            1.6.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    32

            1.6.3     TBase64EncodingStream.Create                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    32

            1.6.4     TBase64EncodingStream.Destroy                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    33

            1.6.5     TBase64EncodingStream.Write                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    33

            1.6.6     TBase64EncodingStream.Seek                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    33


2    Reference for unit 'BlowFish'                                                                                        34

     2.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    34

     2.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    34

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

            2.3.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    34
                                                              1

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           2.3.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    34

    2.4    EBlowFishError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    35

           2.4.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    35

    2.5    TBlowFish          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    35

           2.5.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    35

           2.5.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    35

           2.5.3     TBlowFish.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    35

           2.5.4     TBlowFish.Encrypt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    35

           2.5.5     TBlowFish.Decrypt              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    36

    2.6    TBlowFishDeCryptStream                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    36

           2.6.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    36

           2.6.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    36

           2.6.3     TBlowFishDeCryptStream.Read                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   36

           2.6.4     TBlowFishDeCryptStream.Seek                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   37

    2.7    TBlowFishEncryptStream                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    37

           2.7.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    37

           2.7.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    37

           2.7.3     TBlowFishEncryptStream.Destroy                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  37

           2.7.4     TBlowFishEncryptStream.Write                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   38

           2.7.5     TBlowFishEncryptStream.Seek                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   38

           2.7.6     TBlowFishEncryptStream.Flush                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   38

    2.8    TBlowFishStream              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    38

           2.8.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    38

           2.8.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    39

           2.8.3     Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    39

           2.8.4     TBlowFishStream.Create                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    39

           2.8.5     TBlowFishStream.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    39

           2.8.6     TBlowFishStream.BlowFish                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    39


3    Reference for unit 'bufstream'                                                                                       40

    3.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    40

    3.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    40

    3.3    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    40

           3.3.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    40

    3.4    TBufStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    40

           3.4.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    40

           3.4.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    41

           3.4.3     Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    41

           3.4.4     TBufStream.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    41

           3.4.5     TBufStream.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    41
                                                                  2

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           3.4.6     TBufStream.Buffer           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    41

           3.4.7     TBufStream.Capacity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    42

           3.4.8     TBufStream.BufferPos             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    42

           3.4.9     TBufStream.BufferSize            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    42

    3.5    TReadBufStream            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    43

           3.5.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    43

           3.5.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    43

           3.5.3     TReadBufStream.Seek              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    43

           3.5.4     TReadBufStream.Read                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    43

    3.6    TWriteBufStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    43

           3.6.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    43

           3.6.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    44

           3.6.3     TWriteBufStream.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    44

           3.6.4     TWriteBufStream.Seek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    44

           3.6.5     TWriteBufStream.Write               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    44


4    Reference for unit 'CacheCls'                                                                                        45

    4.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    45

    4.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    45

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

           4.3.1     Resource strings          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    45

           4.3.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    45

    4.4    ECacheError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    46

           4.4.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    46

    4.5    TCache        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    46

           4.5.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    46

           4.5.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    47

           4.5.3     Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    47

           4.5.4     TCache.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    47

           4.5.5     TCache.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    47

           4.5.6     TCache.Add           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    47

           4.5.7     TCache.AddNew             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    48

           4.5.8     TCache.FindSlot           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    48

           4.5.9     TCache.IndexOf            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    48

           4.5.10    TCache.Remove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    49

           4.5.11    TCache.Data          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    49

           4.5.12    TCache.MRUSlot            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    49

           4.5.13    TCache.LRUSlot            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    50

           4.5.14    TCache.SlotCount            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    50

           4.5.15    TCache.Slots         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    50
                                                                  3

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           4.5.16    TCache.OnIsDataEqual                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    50

           4.5.17    TCache.OnFreeSlot           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    51


5    Reference for unit 'contnrs'                                                                                         52

    5.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    52

    5.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    52

    5.3    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    52

           5.3.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    52

           5.3.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    53

    5.4    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    55

           5.4.1     RSHash        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    55

    5.5    EDuplicate         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    55

           5.5.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    55

    5.6    EKeyNotFound            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    55

           5.6.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    55

    5.7    TClassList      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    55

           5.7.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    55

           5.7.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    55

           5.7.3     Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    55

           5.7.4     TClassList.Add         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    56

           5.7.5     TClassList.Extract          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    56

           5.7.6     TClassList.Remove           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    56

           5.7.7     TClassList.IndexOf          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    56

           5.7.8     TClassList.First          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    57

           5.7.9     TClassList.Last        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    57

           5.7.10    TClassList.Insert         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    57

           5.7.11    TClassList.Items          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    57

    5.8    TComponentList            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    58

           5.8.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    58

           5.8.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    58

           5.8.3     Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    58

           5.8.4     TComponentList.Destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    58

           5.8.5     TComponentList.Add               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    58

           5.8.6     TComponentList.Extract                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    59

           5.8.7     TComponentList.Remove                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    59

           5.8.8     TComponentList.IndexOf                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    59

           5.8.9     TComponentList.First             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    60

           5.8.10    TComponentList.Last              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    60

           5.8.11    TComponentList.Insert               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    60

           5.8.12    TComponentList.Items                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    60
                                                                  4

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    5.9    TFPCustomHashTable               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    61

           5.9.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    61

           5.9.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    61

           5.9.3     Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    61

           5.9.4     TFPCustomHashTable.Create                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   61

           5.9.5     TFPCustomHashTable.CreateWith                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  62

           5.9.6     TFPCustomHashTable.Destroy                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   62

           5.9.7     TFPCustomHashTable.ChangeTableSize                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 62

           5.9.8     TFPCustomHashTable.Clear                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    62

           5.9.9     TFPCustomHashTable.Delete                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    63

           5.9.10    TFPCustomHashTable.Find                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    63

           5.9.11    TFPCustomHashTable.IsEmpty                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   63

           5.9.12    TFPCustomHashTable.HashFunction                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 63

           5.9.13    TFPCustomHashTable.Count                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    64

           5.9.14    TFPCustomHashTable.HashTableSize                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 64

           5.9.15    TFPCustomHashTable.HashTable                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  64

           5.9.16    TFPCustomHashTable.VoidSlots                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   65

           5.9.17    TFPCustomHashTable.LoadFactor                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  65

           5.9.18    TFPCustomHashTable.AVGChainLen                         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 65

           5.9.19    TFPCustomHashTable.MaxChainLength                           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *65

           5.9.20    TFPCustomHashTable.NumberOfCollisions                          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *66

           5.9.21    TFPCustomHashTable.Density                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   66

    5.10   TFPDataHashTable               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    66

           5.10.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    66

           5.10.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    66

           5.10.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    67

           5.10.4    TFPDataHashTable.Add                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    67

           5.10.5    TFPDataHashTable.Items                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    67

    5.11   TFPHashList          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    67

           5.11.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    67

           5.11.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    68

           5.11.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    68

           5.11.4    TFPHashList.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    68

           5.11.5    TFPHashList.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    68

           5.11.6    TFPHashList.Add             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    69

           5.11.7    TFPHashList.Clear              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    69

           5.11.8    TFPHashList.NameOfIndex                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    69

           5.11.9    TFPHashList.HashOfIndex                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    69

           5.11.10   TFPHashList.Delete             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    70

           5.11.11   TFPHashList.Error              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    70



                                                                  5

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           5.11.12   TFPHashList.Expand               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    70

           5.11.13   TFPHashList.Extract              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    70

           5.11.14   TFPHashList.IndexOf              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    71

           5.11.15   TFPHashList.Find            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    71

           5.11.16   TFPHashList.FindIndexOf                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    71

           5.11.17   TFPHashList.FindWithHash                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    71

           5.11.18   TFPHashList.Rename               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    72

           5.11.19   TFPHashList.Remove               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    72

           5.11.20   TFPHashList.Pack            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    72

           5.11.21   TFPHashList.ShowStatistics                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    72

           5.11.22   TFPHashList.ForEachCall               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    73

           5.11.23   TFPHashList.Capacity             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    73

           5.11.24   TFPHashList.Count              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    73

           5.11.25   TFPHashList.Items              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    73

           5.11.26   TFPHashList.List            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    74

           5.11.27   TFPHashList.Strs            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    74

    5.12   TFPHashObject             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    74

           5.12.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    74

           5.12.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    74

           5.12.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    74

           5.12.4    TFPHashObject.CreateNotOwned                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  75

           5.12.5    TFPHashObject.Create                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    75

           5.12.6    TFPHashObject.ChangeOwner                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   75

           5.12.7    TFPHashObject.ChangeOwnerAndName                            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *75

           5.12.8    TFPHashObject.Rename                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    76

           5.12.9    TFPHashObject.Name               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    76

           5.12.10   TFPHashObject.Hash               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    76

    5.13   TFPHashObjectList              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    77

           5.13.1    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    77

           5.13.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    77

           5.13.3    TFPHashObjectList.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    77

           5.13.4    TFPHashObjectList.Destroy                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    77

           5.13.5    TFPHashObjectList.Clear               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    78

           5.13.6    TFPHashObjectList.Add                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    78

           5.13.7    TFPHashObjectList.NameOfIndex                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  78

           5.13.8    TFPHashObjectList.HashOfIndex                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  79

           5.13.9    TFPHashObjectList.Delete                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    79

           5.13.10   TFPHashObjectList.Expand                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    79

           5.13.11   TFPHashObjectList.Extract                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    79

           5.13.12   TFPHashObjectList.Remove                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    80



                                                                  6

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           5.13.13   TFPHashObjectList.IndexOf                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    80

           5.13.14   TFPHashObjectList.Find                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    80

           5.13.15   TFPHashObjectList.FindIndexOf                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   80

           5.13.16   TFPHashObjectList.FindWithHash                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  81

           5.13.17   TFPHashObjectList.Rename                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    81

           5.13.18   TFPHashObjectList.FindInstanceOf                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  81

           5.13.19   TFPHashObjectList.Pack                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    81

           5.13.20   TFPHashObjectList.ShowStatistics                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  82

           5.13.21   TFPHashObjectList.ForEachCall                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   82

           5.13.22   TFPHashObjectList.Capacity                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    82

           5.13.23   TFPHashObjectList.Count                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    82

           5.13.24   TFPHashObjectList.OwnsObjects                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  83

           5.13.25   TFPHashObjectList.Items               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    83

           5.13.26   TFPHashObjectList.List              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    83

    5.14   TFPObjectHashTable               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    83

           5.14.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    83

           5.14.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    84

           5.14.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    84

           5.14.4    TFPObjectHashTable.Create                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    84

           5.14.5    TFPObjectHashTable.CreateWith                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  84

           5.14.6    TFPObjectHashTable.Add                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    84

           5.14.7    TFPObjectHashTable.Items                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    85

           5.14.8    TFPObjectHashTable.OwnsObjects                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  85

    5.15   TFPObjectList           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    85

           5.15.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    85

           5.15.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    86

           5.15.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    86

           5.15.4    TFPObjectList.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    86

           5.15.5    TFPObjectList.Destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    86

           5.15.6    TFPObjectList.Clear            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    87

           5.15.7    TFPObjectList.Add              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    87

           5.15.8    TFPObjectList.Delete             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    87

           5.15.9    TFPObjectList.Exchange                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    88

           5.15.10   TFPObjectList.Expand                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    88

           5.15.11   TFPObjectList.Extract               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    88

           5.15.12   TFPObjectList.Remove                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    88

           5.15.13   TFPObjectList.IndexOf               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    89

           5.15.14   TFPObjectList.FindInstanceOf                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   89

           5.15.15   TFPObjectList.Insert             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    89

           5.15.16   TFPObjectList.First            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    90



                                                                  7

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           5.15.17   TFPObjectList.Last             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    90

           5.15.18   TFPObjectList.Move             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    90

           5.15.19   TFPObjectList.Assign             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    90

           5.15.20   TFPObjectList.Pack             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    91

           5.15.21   TFPObjectList.Sort             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    91

           5.15.22   TFPObjectList.ForEachCall                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    91

           5.15.23   TFPObjectList.Capacity              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    92

           5.15.24   TFPObjectList.Count              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    92

           5.15.25   TFPObjectList.OwnsObjects                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    92

           5.15.26   TFPObjectList.Items              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    92

           5.15.27   TFPObjectList.List             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    93

    5.16   TFPStringHashTable             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    93

           5.16.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    93

           5.16.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    93

           5.16.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    93

           5.16.4    TFPStringHashTable.Add                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    93

           5.16.5    TFPStringHashTable.Items                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    93

    5.17   THTCustomNode                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    94

           5.17.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    94

           5.17.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    94

           5.17.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    94

           5.17.4    THTCustomNode.CreateWith                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   94

           5.17.5    THTCustomNode.HasKey                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    94

           5.17.6    THTCustomNode.Key                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    95

    5.18   THTDataNode             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    95

           5.18.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    95

           5.18.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    95

           5.18.3    THTDataNode.Data               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    95

    5.19   THTObjectNode             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    95

           5.19.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    95

           5.19.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    95

           5.19.3    THTObjectNode.Data               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    96

    5.20   THTOwnedObjectNode                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    96

           5.20.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    96

           5.20.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    96

           5.20.3    THTOwnedObjectNode.Destroy                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   96

    5.21   THTStringNode             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    96

           5.21.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    96

           5.21.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    96

           5.21.3    THTStringNode.Data               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    97



                                                                  8

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    5.22   TObjectList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    97

           5.22.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    97

           5.22.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    97

           5.22.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    97

           5.22.4    TObjectList.create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    97

           5.22.5    TObjectList.Add           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    98

           5.22.6    TObjectList.Extract            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    98

           5.22.7    TObjectList.Remove             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    98

           5.22.8    TObjectList.IndexOf            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    99

           5.22.9    TObjectList.FindInstanceOf               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    99

           5.22.10   TObjectList.Insert          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    99

           5.22.11   TObjectList.First         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    99

           5.22.12   TObjectList.Last          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  100

           5.22.13   TObjectList.OwnsObjects               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  100

           5.22.14   TObjectList.Items           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  100

    5.23   TObjectQueue            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  101

           5.23.1    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  101

           5.23.2    TObjectQueue.Push              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  101

           5.23.3    TObjectQueue.Pop            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  101

           5.23.4    TObjectQueue.Peek              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  101

    5.24   TObjectStack         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  102

           5.24.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  102

           5.24.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  102

           5.24.3    TObjectStack.Push           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  102

           5.24.4    TObjectStack.Pop            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  102

           5.24.5    TObjectStack.Peek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  102

    5.25   TOrderedList         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  103

           5.25.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  103

           5.25.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  103

           5.25.3    TOrderedList.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  103

           5.25.4    TOrderedList.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  103

           5.25.5    TOrderedList.Count             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  103

           5.25.6    TOrderedList.AtLeast             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  104

           5.25.7    TOrderedList.Push           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  104

           5.25.8    TOrderedList.Pop            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  104

           5.25.9    TOrderedList.Peek           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  105

    5.26   TQueue        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  105

           5.26.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  105

    5.27   TStack      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  .  105

           5.27.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  105



                                                                  9

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
6    Reference for unit 'CustApp'                                                                                       106

    6.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  106

    6.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  106

    6.3    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  106

           6.3.1     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  106

    6.4    TCustomApplication             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  107

           6.4.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  107

           6.4.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  107

           6.4.3     Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  107

           6.4.4     TCustomApplication.Create                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  108

           6.4.5     TCustomApplication.Destroy                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  108

           6.4.6     TCustomApplication.HandleException                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *08

           6.4.7     TCustomApplication.Initialize                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 108

           6.4.8     TCustomApplication.Run                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  109

           6.4.9     TCustomApplication.ShowException                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *109

           6.4.10    TCustomApplication.Terminate                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 109

           6.4.11    TCustomApplication.FindOptionIndex                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *10

           6.4.12    TCustomApplication.GetOptionValue                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *10

           6.4.13    TCustomApplication.HasOption                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 111

           6.4.14    TCustomApplication.CheckOptions                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *111

           6.4.15    TCustomApplication.GetEnvironmentList                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  112

           6.4.16    TCustomApplication.ExeName                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 112

           6.4.17    TCustomApplication.HelpFile                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  112

           6.4.18    TCustomApplication.Terminated                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 113

           6.4.19    TCustomApplication.Title              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  113

           6.4.20    TCustomApplication.OnException                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *113

           6.4.21    TCustomApplication.ConsoleApplication                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  113

           6.4.22    TCustomApplication.Location                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 114

           6.4.23    TCustomApplication.Params                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  114

           6.4.24    TCustomApplication.ParamCount                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *114

           6.4.25    TCustomApplication.EnvironmentVariable                         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  115

           6.4.26    TCustomApplication.OptionChar                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 115

           6.4.27    TCustomApplication.CaseSensitiveOptions                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  115

           6.4.28    TCustomApplication.StopOnException                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *16


7    Reference for unit 'dbugintf '                                                                                     117

    7.1    Writing a debug server           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  117

    7.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  117

    7.3    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  117

           7.3.1     Resource strings          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  117
                                                                 10

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           7.3.2     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  118

           7.3.3     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  118

    7.4    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  118

           7.4.1     GetDebuggingEnabled              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  118

           7.4.2     InitDebugClient           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  119

           7.4.3     SendBoolean          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  119

           7.4.4     SendDateTime           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  119

           7.4.5     SendDebug          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  119

           7.4.6     SendDebugEx          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  120

           7.4.7     SendDebugFmt           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  120

           7.4.8     SendDebugFmtEx              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  120

           7.4.9     SendInteger        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  121

           7.4.10    SendMethodEnter             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  121

           7.4.11    SendMethodExit            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  121

           7.4.12    SendPointer        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  122

           7.4.13    SendSeparator          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  122

           7.4.14    SetDebuggingEnabled              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  122

           7.4.15    StartDebugServer          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  122


8    Reference for unit 'dbugmsg'                                                                                       124

    8.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  124

    8.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  124

    8.3    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  124

           8.3.1     Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  124

           8.3.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  125

    8.4    Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  125

           8.4.1     DebugMessageName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  125

           8.4.2     ReadDebugMessageFromStream                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 125

           8.4.3     WriteDebugMessageToStream                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  126


9    Reference for unit 'eventlog'                                                                                      127

    9.1    Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  127

    9.2    Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  127

    9.3    Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  127

           9.3.1     Resource strings          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  127

           9.3.2     Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  128

    9.4    ELogError       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  129

           9.4.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  129

    9.5    TEventLog          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  129

           9.5.1     Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  129

           9.5.2     Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  129



                                                                 11

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           9.5.3     Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  129

           9.5.4     TEventLog.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  129

           9.5.5     TEventLog.EventTypeToString                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 130

           9.5.6     TEventLog.RegisterMessageFile                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 130

           9.5.7     TEventLog.Log          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  131

           9.5.8     TEventLog.Warning              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  131

           9.5.9     TEventLog.Error           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  131

           9.5.10    TEventLog.Debug             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  132

           9.5.11    TEventLog.Info         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  132

           9.5.12    TEventLog.Identification              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  132

           9.5.13    TEventLog.LogType              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  132

           9.5.14    TEventLog.Active            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  133

           9.5.15    TEventLog.RaiseExceptionOnError                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *133

           9.5.16    TEventLog.DefaultEventType                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  133

           9.5.17    TEventLog.FileName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  133

           9.5.18    TEventLog.TimeStampFormat                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 134

           9.5.19    TEventLog.CustomLogType                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  134

           9.5.20    TEventLog.EventIDOffset               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  134

           9.5.21    TEventLog.OnGetCustomCategory                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *135

           9.5.22    TEventLog.OnGetCustomEventID                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *135

           9.5.23    TEventLog.OnGetCustomEvent                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 135


10   Reference for unit 'ezcgi'                                                                                         136

    10.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  136

    10.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  136

    10.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  136

           10.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  136

    10.4   ECGIException           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  136

           10.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  136

    10.5   TEZcgi        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  137

           10.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  137

           10.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  137

           10.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  137

           10.5.4    TEZcgi.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  137

           10.5.5    TEZcgi.Destroy         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  137

           10.5.6    TEZcgi.Run         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  138

           10.5.7    TEZcgi.WriteContent              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  138

           10.5.8    TEZcgi.PutLine            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  138

           10.5.9    TEZcgi.GetValue           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  139

           10.5.10   TEZcgi.DoPost          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  139
                                                                 12

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           10.5.11   TEZcgi.DoGet           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  139

           10.5.12   TEZcgi.Values          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  139

           10.5.13   TEZcgi.Names           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  140

           10.5.14   TEZcgi.Variables          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  141

           10.5.15   TEZcgi.VariableCount             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  141

           10.5.16   TEZcgi.Name          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  141

           10.5.17   TEZcgi.Email         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  141


11   Reference for unit 'gettext'                                                                                       142

    11.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  142

    11.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  142

    11.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  142

           11.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  142

           11.3.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  142

    11.4   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  143

           11.4.1    GetLanguageIDs            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  143

           11.4.2    TranslateResourceStrings              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  144

           11.4.3    TranslateUnitResourceStrings               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  144

    11.5   EMOFileError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  144

           11.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  144

    11.6   TMOFile         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  144

           11.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  144

           11.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  145

           11.6.3    TMOFile.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  145

           11.6.4    TMOFile.Destroy           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  145

           11.6.5    TMOFile.Translate           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  145


12   Reference for unit 'idea'                                                                                          146

    12.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  146

    12.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  146

    12.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  146

           12.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  146

           12.3.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  147

    12.4   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  147

           12.4.1    CipherIdea         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  147

           12.4.2    DeKeyIdea          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  148

           12.4.3    EnKeyIdea          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  148

    12.5   EIDEAError           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  148

           12.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  148

    12.6   TIDEADeCryptStream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  148

           12.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  148



                                                                 13

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           12.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  148

           12.6.3    TIDEADeCryptStream.Read                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  149

           12.6.4    TIDEADeCryptStream.Seek                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  149

    12.7   TIDEAEncryptStream               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  149

           12.7.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  149

           12.7.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  150

           12.7.3    TIDEAEncryptStream.Destroy                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 150

           12.7.4    TIDEAEncryptStream.Write                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  150

           12.7.5    TIDEAEncryptStream.Seek                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  150

           12.7.6    TIDEAEncryptStream.Flush                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  151

    12.8   TIDEAStream             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  151

           12.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  151

           12.8.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  151

           12.8.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  151

           12.8.4    TIDEAStream.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  151

           12.8.5    TIDEAStream.Key             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  152


13   Reference for unit 'inicol'                                                                                        153

    13.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  153

    13.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  153

    13.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  153

           13.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  153

    13.4   EIniCol       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  154

           13.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  154

    13.5   TIniCollection       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  154

           13.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  154

           13.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  154

           13.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  154

           13.5.4    TIniCollection.Load            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  154

           13.5.5    TIniCollection.Save            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  155

           13.5.6    TIniCollection.SaveToIni              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  155

           13.5.7    TIniCollection.SaveToFile             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  155

           13.5.8    TIniCollection.LoadFromIni               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  156

           13.5.9    TIniCollection.LoadFromFile                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  156

           13.5.10   TIniCollection.Prefix          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  156

           13.5.11   TIniCollection.SectionPrefix             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  157

           13.5.12   TIniCollection.FileName             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  157

           13.5.13   TIniCollection.GlobalSection               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  157

    13.6   TIniCollectionItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  157

           13.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  157
                                                                 14

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           13.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  158

           13.6.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  158

           13.6.4    TIniCollectionItem.SaveToIni               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  158

           13.6.5    TIniCollectionItem.LoadFromIni                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 158

           13.6.6    TIniCollectionItem.SaveToFile                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 158

           13.6.7    TIniCollectionItem.LoadFromFile                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 159

           13.6.8    TIniCollectionItem.SectionName                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 159

    13.7   TNamedIniCollection            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  159

           13.7.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  159

           13.7.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  159

           13.7.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  160

           13.7.4    TNamedIniCollection.IndexOfUserData                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *60

           13.7.5    TNamedIniCollection.IndexOfName                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *160

           13.7.6    TNamedIniCollection.FindByName                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *160

           13.7.7    TNamedIniCollection.FindByUserData                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *61

           13.7.8    TNamedIniCollection.NamedItems                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *161

    13.8   TNamedIniCollectionItem               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  161

           13.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  161

           13.8.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  161

           13.8.3    TNamedIniCollectionItem.UserData                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *161

           13.8.4    TNamedIniCollectionItem.Name                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 162


14   Reference for unit 'IniFiles'                                                                                      163

    14.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  163

    14.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  163

    14.3   TCustomIniFile          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  163

           14.3.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  163

           14.3.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  164

           14.3.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  164

           14.3.4    TCustomIniFile.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  164

           14.3.5    TCustomIniFile.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  165

           14.3.6    TCustomIniFile.SectionExists               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  165

           14.3.7    TCustomIniFile.ReadString                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  165

           14.3.8    TCustomIniFile.WriteString               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  166

           14.3.9    TCustomIniFile.ReadInteger                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  166

           14.3.10   TCustomIniFile.WriteInteger                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  166

           14.3.11   TCustomIniFile.ReadBool               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  166

           14.3.12   TCustomIniFile.WriteBool                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  167

           14.3.13   TCustomIniFile.ReadDate               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  167

           14.3.14   TCustomIniFile.ReadDateTime                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 168
                                                                 15

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           14.3.15   TCustomIniFile.ReadFloat                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  168

           14.3.16   TCustomIniFile.ReadTime                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  168

           14.3.17   TCustomIniFile.ReadBinaryStream                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *169

           14.3.18   TCustomIniFile.WriteDate                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  169

           14.3.19   TCustomIniFile.WriteDateTime                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 169

           14.3.20   TCustomIniFile.WriteFloat                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  170

           14.3.21   TCustomIniFile.WriteTime                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  170

           14.3.22   TCustomIniFile.WriteBinaryStream                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *170

           14.3.23   TCustomIniFile.ReadSection                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  171

           14.3.24   TCustomIniFile.ReadSections                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  171

           14.3.25   TCustomIniFile.ReadSectionValues                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *171

           14.3.26   TCustomIniFile.EraseSection                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  171

           14.3.27   TCustomIniFile.DeleteKey                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  172

           14.3.28   TCustomIniFile.UpdateFile                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  172

           14.3.29   TCustomIniFile.ValueExists               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  172

           14.3.30   TCustomIniFile.FileName               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  172

           14.3.31   TCustomIniFile.EscapeLineFeeds                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 173

           14.3.32   TCustomIniFile.CaseSensitive               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  173

           14.3.33   TCustomIniFile.StripQuotes                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  173

    14.4   THashedStringList            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  173

           14.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  173

           14.4.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  174

           14.4.3    THashedStringList.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  174

           14.4.4    THashedStringList.Destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  174

           14.4.5    THashedStringList.IndexOf                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  174

           14.4.6    THashedStringList.IndexOfName                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 174

    14.5   TIniFile      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  175

           14.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  175

           14.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  175

           14.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  175

           14.5.4    TIniFile.Create        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  175

           14.5.5    TIniFile.Destroy          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  175

           14.5.6    TIniFile.ReadString            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  176

           14.5.7    TIniFile.WriteString           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  176

           14.5.8    TIniFile.ReadSection           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  176

           14.5.9    TIniFile.ReadSectionRaw               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  177

           14.5.10   TIniFile.ReadSections            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  177

           14.5.11   TIniFile.ReadSectionValues               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  177

           14.5.12   TIniFile.EraseSection            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  177

           14.5.13   TIniFile.DeleteKey          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  178



                                                                 16

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           14.5.14   TIniFile.UpdateFile            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  178

           14.5.15   TIniFile.Stream        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  178

           14.5.16   TIniFile.CacheUpdates            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  178

    14.6   TIniFileKey        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  179

           14.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  179

           14.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  179

           14.6.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  179

           14.6.4    TIniFileKey.Create          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  179

           14.6.5    TIniFileKey.Ident           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  179

           14.6.6    TIniFileKey.Value           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  180

    14.7   TIniFileKeyList         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  180

           14.7.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  180

           14.7.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  180

           14.7.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  180

           14.7.4    TIniFileKeyList.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  180

           14.7.5    TIniFileKeyList.Clear            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  180

           14.7.6    TIniFileKeyList.Items            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  181

    14.8   TIniFileSection         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  181

           14.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  181

           14.8.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  181

           14.8.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  181

           14.8.4    TIniFileSection.Empty            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  181

           14.8.5    TIniFileSection.Create           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  181

           14.8.6    TIniFileSection.Destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  182

           14.8.7    TIniFileSection.Name             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  182

           14.8.8    TIniFileSection.KeyList             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  182

    14.9   TIniFileSectionList          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  182

           14.9.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  182

           14.9.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  183

           14.9.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  183

           14.9.4    TIniFileSectionList.Destroy              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  183

           14.9.5    TIniFileSectionList.Clear             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  183

           14.9.6    TIniFileSectionList.Items             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  183

    14.10  TMemIniFile          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  184

           14.10.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  184

           14.10.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  184

           14.10.3   TMemIniFile.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  184

           14.10.4   TMemIniFile.Clear           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  184

           14.10.5   TMemIniFile.GetStrings              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  184

           14.10.6   TMemIniFile.Rename               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  185



                                                                 17

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           14.10.7   TMemIniFile.SetStrings              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  185


15   Reference for unit 'iostream'                                                                                      186

    15.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  186

    15.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  186

    15.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  186

           15.3.1    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  186

    15.4   EIOStreamError            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  187

           15.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  187

    15.5   TIOStream          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  187

           15.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  187

           15.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  187

           15.5.3    TIOStream.Create            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  187

           15.5.4    TIOStream.Read            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  187

           15.5.5    TIOStream.Write           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  188

           15.5.6    TIOStream.SetSize           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  188

           15.5.7    TIOStream.Seek            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  188


16   Reference for unit 'Pipes'                                                                                         189

    16.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  189

    16.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  189

    16.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  189

           16.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  189

    16.4   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  189

           16.4.1    CreatePipeHandles           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  189

           16.4.2    CreatePipeStreams           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  190

    16.5   EPipeCreation           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  190

           16.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  190

    16.6   EPipeError         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  190

           16.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  190

    16.7   EPipeSeek       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  190

           16.7.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  190

    16.8   TInputPipeStream             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  190

           16.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  190

           16.8.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  191

           16.8.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  191

           16.8.4    TInputPipeStream.Write                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  191

           16.8.5    TInputPipeStream.Seek               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  191

           16.8.6    TInputPipeStream.Read               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  192

           16.8.7    TInputPipeStream.NumBytesAvailable                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *92

    16.9   TOutputPipeStream              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  192



                                                                 18

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           16.9.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  192

           16.9.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  192

           16.9.3    TOutputPipeStream.Seek                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  192

           16.9.4    TOutputPipeStream.Read                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  193


17   Reference for unit 'pooledmm'                                                                                      194

    17.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  194

    17.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  194

    17.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  194

           17.3.1    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  194

    17.4   TNonFreePooledMemManager                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  195

           17.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  195

           17.4.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  195

           17.4.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  195

           17.4.4    TNonFreePooledMemManager.Clear                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *195

           17.4.5    TNonFreePooledMemManager.Create                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *95

           17.4.6    TNonFreePooledMemManager.Destroy                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *96

           17.4.7    TNonFreePooledMemManager.NewItem                          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *96

           17.4.8    TNonFreePooledMemManager.EnumerateItems                            .  .  .  .  .  .  .  .  .  .  .  .  .  196

           17.4.9    TNonFreePooledMemManager.ItemSize                         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *96

    17.5   TPooledMemManager                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  197

           17.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  197

           17.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  197

           17.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  197

           17.5.4    TPooledMemManager.Clear                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  197

           17.5.5    TPooledMemManager.Create                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  197

           17.5.6    TPooledMemManager.Destroy                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 197

           17.5.7    TPooledMemManager.MinimumFreeCount                             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  198

           17.5.8    TPooledMemManager.MaximumFreeCountRatio                               .  .  .  .  .  .  .  .  .  .  .  .  198

           17.5.9    TPooledMemManager.Count                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  198

           17.5.10   TPooledMemManager.FreeCount                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 199

           17.5.11   TPooledMemManager.AllocatedCount                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *99

           17.5.12   TPooledMemManager.FreedCount                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *199


18   Reference for unit 'process'                                                                                       200

    18.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  200

    18.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  200

    18.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  200

           18.3.1    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  200

    18.4   EProcess      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .  202

           18.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  202



                                                                 19

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    18.5   TProcess        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  202

           18.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  202

           18.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  203

           18.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  204

           18.5.4    TProcess.Create           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  204

           18.5.5    TProcess.Destroy          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  204

           18.5.6    TProcess.Execute          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  205

           18.5.7    TProcess.CloseInput            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  205

           18.5.8    TProcess.CloseOutput             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  205

           18.5.9    TProcess.CloseStderr             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  206

           18.5.10   TProcess.Resume           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  206

           18.5.11   TProcess.Suspend            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  206

           18.5.12   TProcess.Terminate             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  207

           18.5.13   TProcess.WaitOnExit              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  207

           18.5.14   TProcess.WindowRect              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  207

           18.5.15   TProcess.Handle           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  207

           18.5.16   TProcess.ProcessHandle              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  208

           18.5.17   TProcess.ThreadHandle               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  208

           18.5.18   TProcess.ProcessID             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  208

           18.5.19   TProcess.ThreadID              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  209

           18.5.20   TProcess.Input         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  209

           18.5.21   TProcess.Output           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  209

           18.5.22   TProcess.Stderr           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  210

           18.5.23   TProcess.ExitStatus            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  210

           18.5.24   TProcess.InheritHandles             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  210

           18.5.25   TProcess.Active           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  211

           18.5.26   TProcess.ApplicationName                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  211

           18.5.27   TProcess.CommandLine                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  211

           18.5.28   TProcess.ConsoleTitle            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  212

           18.5.29   TProcess.CurrentDirectory                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  212

           18.5.30   TProcess.Desktop            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  212

           18.5.31   TProcess.Environment             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  212

           18.5.32   TProcess.Options          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  213

           18.5.33   TProcess.Priority         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  213

           18.5.34   TProcess.StartupOptions               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  214

           18.5.35   TProcess.Running            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  214

           18.5.36   TProcess.ShowWindow                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  215

           18.5.37   TProcess.WindowColumns                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  215

           18.5.38   TProcess.WindowHeight               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  216

           18.5.39   TProcess.WindowLeft              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  216



                                                                 20

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           18.5.40   TProcess.WindowRows                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  216

           18.5.41   TProcess.WindowTop               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  217

           18.5.42   TProcess.WindowWidth                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  217

           18.5.43   TProcess.FillAttribute           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  217


19   Reference for unit 'rttiutils'                                                                                     218

    19.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  218

    19.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  218

    19.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  218

           19.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  218

           19.3.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  218

           19.3.3    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  219

    19.4   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  219

           19.4.1    CreateStoredItem          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  219

           19.4.2    ParseStoredItem           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  219

           19.4.3    UpdateStoredList          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  220

    19.5   TPropInfoList        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  220

           19.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  220

           19.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  220

           19.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  221

           19.5.4    TPropInfoList.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  221

           19.5.5    TPropInfoList.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  221

           19.5.6    TPropInfoList.Contains              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  221

           19.5.7    TPropInfoList.Find             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  221

           19.5.8    TPropInfoList.Delete           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  222

           19.5.9    TPropInfoList.Intersect             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  222

           19.5.10   TPropInfoList.Count            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  222

           19.5.11   TPropInfoList.Items            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  222

    19.6   TPropsStorage           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  223

           19.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  223

           19.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  223

           19.6.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  223

           19.6.4    TPropsStorage.StoreAnyProperty                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 223

           19.6.5    TPropsStorage.LoadAnyProperty                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 223

           19.6.6    TPropsStorage.StoreProperties                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 224

           19.6.7    TPropsStorage.LoadProperties                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 224

           19.6.8    TPropsStorage.LoadObjectsProps                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *224

           19.6.9    TPropsStorage.StoreObjectsProps                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *225

           19.6.10   TPropsStorage.AObject               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  226

           19.6.11   TPropsStorage.Prefix             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  226
                                                                 21

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           19.6.12   TPropsStorage.Section            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  226

           19.6.13   TPropsStorage.OnReadString                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  226

           19.6.14   TPropsStorage.OnWriteString                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 227

           19.6.15   TPropsStorage.OnEraseSection                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 227


20   Reference for unit 'simpleipc'                                                                                     228

    20.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  228

    20.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  228

    20.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  228

           20.3.1    Resource strings          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  228

           20.3.2    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  229

           20.3.3    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  229

           20.3.4    Variables       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  229

    20.4   EIPCError          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  230

           20.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  230

    20.5   TIPCClientComm               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  230

           20.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  230

           20.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  230

           20.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  230

           20.5.4    TIPCClientComm.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  230

           20.5.5    TIPCClientComm.Connect                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  231

           20.5.6    TIPCClientComm.Disconnect                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  231

           20.5.7    TIPCClientComm.ServerRunning                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 231

           20.5.8    TIPCClientComm.SendMessage                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 232

           20.5.9    TIPCClientComm.Owner                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  232

    20.6   TIPCServerComm               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  232

           20.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  232

           20.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  232

           20.6.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  233

           20.6.4    TIPCServerComm.Create                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  233

           20.6.5    TIPCServerComm.StartServer                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 233

           20.6.6    TIPCServerComm.StopServer                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  233

           20.6.7    TIPCServerComm.PeekMessage                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 234

           20.6.8    TIPCServerComm.ReadMessage                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 234

           20.6.9    TIPCServerComm.Owner                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  234

           20.6.10   TIPCServerComm.InstanceID                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  234

    20.7   TSimpleIPC         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  235

           20.7.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  235

           20.7.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  235

           20.7.3    TSimpleIPC.Active           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  235
                                                                 22

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           20.7.4    TSimpleIPC.ServerID              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  235

    20.8   TSimpleIPCClient             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  235

           20.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  235

           20.8.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  236

           20.8.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  236

           20.8.4    TSimpleIPCClient.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  236

           20.8.5    TSimpleIPCClient.Destroy                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  236

           20.8.6    TSimpleIPCClient.Connect                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  236

           20.8.7    TSimpleIPCClient.Disconnect                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  237

           20.8.8    TSimpleIPCClient.ServerRunning                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *237

           20.8.9    TSimpleIPCClient.SendMessage                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 237

           20.8.10   TSimpleIPCClient.SendStringMessage                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  2*
 *38

           20.8.11   TSimpleIPCClient.SendStringMessageFmt                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  238

           20.8.12   TSimpleIPCClient.ServerInstance                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 238

    20.9   TSimpleIPCServer             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  239

           20.9.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  239

           20.9.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  239

           20.9.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  239

           20.9.4    TSimpleIPCServer.Create               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  239

           20.9.5    TSimpleIPCServer.Destroy                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  239

           20.9.6    TSimpleIPCServer.StartServer                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 240

           20.9.7    TSimpleIPCServer.StopServer                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  240

           20.9.8    TSimpleIPCServer.PeekMessage                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 240

           20.9.9    TSimpleIPCServer.GetMessageData                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *241

           20.9.10   TSimpleIPCServer.StringMessage                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 241

           20.9.11   TSimpleIPCServer.MsgType                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  241

           20.9.12   TSimpleIPCServer.MsgData                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  241

           20.9.13   TSimpleIPCServer.InstanceID                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  242

           20.9.14   TSimpleIPCServer.Global               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  242

           20.9.15   TSimpleIPCServer.OnMessage                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 242


21   Reference for unit 'streamcoll'                                                                                    243

    21.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  243

    21.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  243

    21.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  243

           21.3.1    ColReadBoolean            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  243

           21.3.2    ColReadCurrency           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  244

           21.3.3    ColReadDateTime             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  244

           21.3.4    ColReadFloat         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  244

           21.3.5    ColReadInteger         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  244
                                                                 23

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           21.3.6    ColReadString          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  245

           21.3.7    ColWriteBoolean           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  245

           21.3.8    ColWriteCurrency            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  245

           21.3.9    ColWriteDateTime            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  245

           21.3.10   ColWriteFloat          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  246

           21.3.11   ColWriteInteger           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  246

           21.3.12   ColWriteString         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  246

    21.4   EStreamColl          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  246

           21.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  246

    21.5   TStreamCollection            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  246

           21.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  246

           21.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  247

           21.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  247

           21.5.4    TStreamCollection.LoadFromStream                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *247

           21.5.5    TStreamCollection.SaveToStream                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 247

           21.5.6    TStreamCollection.Streaming                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  247

    21.6   TStreamCollectionItem               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  248

           21.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  248


22   Reference for unit 'streamex'                                                                                      249

    22.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  249

    22.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  249

    22.3   TBidirBinaryObjectReader                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  249

           22.3.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  249

           22.3.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  249

           22.3.3    TBidirBinaryObjectReader.Position                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *249

    22.4   TBidirBinaryObjectWriter              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  250

           22.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  250

           22.4.2    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  250

           22.4.3    TBidirBinaryObjectWriter.Position                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *250

    22.5   TDelphiReader           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  250

           22.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  250

           22.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  250

           22.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  250

           22.5.4    TDelphiReader.GetDriver               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  251

           22.5.5    TDelphiReader.ReadStr               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  251

           22.5.6    TDelphiReader.Read             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  251

           22.5.7    TDelphiReader.Position              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  251

    22.6   TDelphiWriter           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  252

           22.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  252
                                                                 24

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           22.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  252

           22.6.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  252

           22.6.4    TDelphiWriter.GetDriver               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  252

           22.6.5    TDelphiWriter.FlushBuffer                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  252

           22.6.6    TDelphiWriter.Write            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  252

           22.6.7    TDelphiWriter.WriteStr              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  253

           22.6.8    TDelphiWriter.WriteValue              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  253

           22.6.9    TDelphiWriter.Position              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  253


23   Reference for unit 'StreamIO'                                                                                      254

    23.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  254

    23.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  254

    23.3   Procedures and functions              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  254

           23.3.1    AssignStream         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  254

           23.3.2    GetStream          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  255


24   Reference for unit 'syncobjs'                                                                                      256

    24.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  256

    24.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  256

    24.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  256

           24.3.1    Constants       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  256

           24.3.2    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  256

    24.4   TCriticalSection          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  257

           24.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  257

           24.4.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  257

           24.4.3    TCriticalSection.Acquire            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  258

           24.4.4    TCriticalSection.Release            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  258

           24.4.5    TCriticalSection.Enter           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  258

           24.4.6    TCriticalSection.Leave           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  258

           24.4.7    TCriticalSection.Create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  259

           24.4.8    TCriticalSection.Destroy            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  259

    24.5   TEventObject         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  259

           24.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  259

           24.5.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  259

           24.5.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  259

           24.5.4    TEventObject.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  260

           24.5.5    TEventObject.destroy             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  260

           24.5.6    TEventObject.ResetEvent               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  260

           24.5.7    TEventObject.SetEvent               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  260

           24.5.8    TEventObject.WaitFor             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  261

           24.5.9    TEventObject.ManualReset                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  261



                                                                 25

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
    24.6   THandleObject           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  261

           24.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  261

           24.6.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  261

           24.6.3    Property overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  261

           24.6.4    THandleObject.destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  261

           24.6.5    THandleObject.Handle                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  262

           24.6.6    THandleObject.LastError               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  262

    24.7   TSimpleEvent         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  262

           24.7.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  262

           24.7.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  262

           24.7.3    TSimpleEvent.Create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  262

    24.8   TSynchroObject            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  263

           24.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  263

           24.8.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  263

           24.8.3    TSynchroObject.Acquire              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  263

           24.8.4    TSynchroObject.Release              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  263


25   Reference for unit 'zstream'                                                                                       264

    25.1   Used units      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  264

    25.2   Overview        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  264

    25.3   Constants, types and variables                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  264

           25.3.1    Types      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  264

    25.4   Ecompressionerror            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  265

           25.4.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  265

    25.5   Edecompressionerror            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  265

           25.5.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  265

    25.6   Egzfileerror       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  265

           25.6.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  265

    25.7   Ezliberror      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  265

           25.7.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  265

    25.8   Tcompressionstream             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  265

           25.8.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  265

           25.8.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  266

           25.8.3    Tcompressionstream.create                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  266

           25.8.4    Tcompressionstream.destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  266

           25.8.5    Tcompressionstream.write              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  266

           25.8.6    Tcompressionstream.flush              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  267

           25.8.7    Tcompressionstream.get_compressionrate                      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  267

    25.9   Tcustomzlibstream            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  267

           25.9.1    Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  267
                                                                 26

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           25.9.2    Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  267

           25.9.3    Tcustomzlibstream.create              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  267

           25.9.4    Tcustomzlibstream.destroy                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  268

    25.10  Tdecompressionstream             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  268

           25.10.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  268

           25.10.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  268

           25.10.3   Tdecompressionstream.create                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  268

           25.10.4   Tdecompressionstream.destroy                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 269

           25.10.5   Tdecompressionstream.read                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  269

           25.10.6   Tdecompressionstream.seek                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  269

           25.10.7   Tdecompressionstream.get_compressionrate                       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  270

    25.11  TGZFileStream           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  270

           25.11.1   Description        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  270

           25.11.2   Method overview           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  270

           25.11.3   TGZFileStream.create             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  270

           25.11.4   TGZFileStream.read             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  270

           25.11.5   TGZFileStream.write              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  271

           25.11.6   TGZFileStream.seek             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  271

           25.11.7   TGZFileStream.destroy               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  271

                                                                 27

____________________________________________________________________________________________________________________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 FCL (Free Component Library).

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 Free Component Library is a series of units that implemenent various classes and non-
visual  components  for  use  with  Free  Pascal.  They  are  building  blocks  for  non-visual  and
visual programs, such as designed in Lazarus.

The TDataset descendents have been implemented in a way that makes them compatible to
the Delphi implementation of these units.  There are other units that have counterparts in
Delphi, but most of them are unique to Free Pascal.

                                                                 28


Chapter   1


Reference   for   unit   'base64'
1.1         Used  units
                                     Table 1.1:  Used units by unit 'base64'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     sysutils         ??



1.2         Overview


base64  implements  base64  encoding  (as  used  for  instance  in  MIME  encoding)  based  on
streams.  it  implements  2  streams  which  encode  or  decode  anything  written  or  read  from
it.  The source or the destination of the encoded data is another stream.  2 classes are imple-
mented for this:  TBase64EncodingStream (32 ) for encoding, and TBase64DecodingStream
(30 ) for decoding.

The streams are designed as plug-in streams, which can be placed between other streams, to
provide base64 encoding and decoding on-the-fly...
1.3         Constants,  types  and  variables



1.3.1        Types

TBase64DecodingMode  =  (bdmStrict,bdmMIME)
                   Table 1.2:  Enumeration values for type TBase64DecodingMode


                                         __Value______________Explanation_____________
                                           bdmMIME            MIME encoding
                                           bdmStrict          Strict encoding



                                                              29

                _____________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASE64'______________*
 *___________________
                TBase64DecodingMode determines the decoding algorithm used by TBase64DecodingStream
                (30 ).  There are 2 modes:


                bdmStrict        Strict mode, which follows RFC3548 and rejects any characters outside of base64
                       alphabet.  In this mode only up to two '=' characters are accepted at the end.  It requires
                       the input to have a Size being a multiple of 4, otherwise an EBase64DecodingException
                       (30 ) exception is raised.

                bdmMime          MIME  mode,  which  follows  RFC2045  and  ignores  any  characters  outside  of
                       base64 alphabet.  In this mode any '=' is seen as the end of string, it handles apparently
                       truncated input streams gracefully.
                1.4         EBase64DecodingException



                1.4.1        Description

                EBase64DecodeException  is  raised  when  the  stream  contains  errors  against  the  encoding
                format.  Whether or not this exception is raised depends on the mode in which the stream
                is decoded.
                1.5         TBase64DecodingStream



                1.5.1        Description

                TBase64DecodingStream can be used to read data from a stream (the source stream) that
                contains Base64 encoded data.  The data is read and decoded on-the-fly.

                The decoding stream is read-only, and provides a limited forward-seek capability.
                1.5.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  30        Create          Create a new instance of the TBase64DecodingStream class
                  31        Read            Read and decrypt data from the source stream
                  31        Reset           Reset the stream
                __31________Seek____________Set_stream_position.___________________________________________________________________*
 *___________
                1.5.3        Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  32        EOF             r
                __32________Mode____________rw___________Decoding_mode_____________________________________________________________*
 *___________
                1.5.4        TBase64DecodingStream.Create

    Synopsis:    Create a new instance of the TBase64DecodingStream class

Declaration:     constructor  Create(AInputStream:  TStream)
                constructor  Create(AInputStream:  TStream;AMode:  TBase64DecodingMode)

    Visibility:   public


                                                                                 30

                _____________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASE64'______________*
 *___________________
Description:     Create creates a new instance of the TBase64DecodingStream class.  It stores the source
                stream AInputStream for reading the data from.

                The optional AMode parameter determines the mode in which the decoding will be done.  If
                omitted, bdmMIME is used.

    See also:    TBase64EncodingStream.Create (32 ), TBase64DecodingMode (29 )
                1.5.5        TBase64DecodingStream.Reset

    Synopsis:    Reset the stream

Declaration:     procedure  Reset

    Visibility:   public

Description:     Reset resets the data as if it was again on the start of the decoding stream.

       Errors:   None.

    See also:    TBase64DecodingStream.EOF (32 ), TBase64DecodingStream.Read (31 )
                1.5.6        TBase64DecodingStream.Read

    Synopsis:    Read and decrypt data from the source stream

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read reads encrypted data from the source stream and stores this data in Buffer.  At most
                Count bytes will be stored in the buffer, but more bytes will be read from the source stream:
                the encoding algorithm multiplies the number of bytes.

                The function returns the number of bytes stored in the buffer.

       Errors:   If an error occurs during the read from the source stream, an exception may occur.

    See also:    TBase64DecodingStream.Write (30 ), TBase64DecodingStream.Seek (31 ), #rtl.classes.TStream.Read
                (??  )
                1.5.7        TBase64DecodingStream.Seek

    Synopsis:    Set stream position.

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek sets the position of the stream.  In the TBase64DecodingStream class, the seek oper-
                ation is forward only, it does not support backward seeks.  The forward seek is emulated by
                reading and discarding data till the desired position is reached.

                For an explanation of the parameters, see TStream.Seek (??  )

       Errors:   In case of an unsupported operation, an EStreamError exception is raised.

    See also:    TBase64DecodingStream.Read (31 ), TBase64DecodingStream.Write (30 ), TBase64EncodingStream.Seek
                (33 ), #rtl.classes.TStream.Seek (??  )
                                                                                 31

                _____________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASE64'______________*
 *___________________
                1.5.8        TBase64DecodingStream.EOF

    Synopsis:

Declaration:     Property  EOF  :  Boolean

    Visibility:   public

      Access:    Read

Description:
                1.5.9        TBase64DecodingStream.Mode

    Synopsis:    Decoding mode

Declaration:     Property  Mode  :  TBase64DecodingMode

    Visibility:   public

      Access:    Read,Write

Description:     Mode is the mode in which the stream is read.  It can be set when creating the stream or at
                any time afterwards.

    See also:    TBase64DecodingStream (30 )
                1.6         TBase64EncodingStream



                1.6.1        Description

                TBase64EncodingStream can be used to encode data using the base64 algorithm.  At creation
                time,  a  destination  stream  is  specified.  Any  data  written  to  the  TBase64EncodingStream
                instance will be base64 encoded, and subsequently written to the destination stream.

                The TBase64EncodingStream stream is a write-only stream.  Obviously it is also not seekable.
                It is meant to be included in a chain of streams.
                1.6.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  32        Create          Create a new instance of the TBase64EncodingStream class.
                  33        Destroy         Remove a TBase64EncodingStream instannce from memory
                  33        Seek            Position the stream
                __33________Write___________Write_data_to_the_stream.______________________________________________________________*
 *___________
                1.6.3        TBase64EncodingStream.Create

    Synopsis:    Create a new instance of the TBase64EncodingStream class.

Declaration:     constructor  Create(AOutputStream:  TStream)

    Visibility:   public

Description:     Create instantiates a new  TBase64EncodingStream class.  The AOutputStream stream is
                stored and used to write the encoded data to.

    See also:    TBase64EncodingStream.Destroy (33 ), TBase64DecodingStream.Create (30 )



                                                                                 32

                _____________________________________________________________CHAPTER_1.___REFERENCE_FOR_UNIT_'BASE64'______________*
 *___________________
                1.6.4        TBase64EncodingStream.Destroy

    Synopsis:    Remove a TBase64EncodingStream instannce from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy flushes any remaining output and then removes the TBase64EncodingStream in-
                stance from memory by calling the inherited destructor.

       Errors:   An exception may be raised if the destination stream no longer exists or is closed.

    See also:    TBase64EncodingStream.Create (32 )
                1.6.5        TBase64EncodingStream.Write

    Synopsis:    Write data to the stream.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write encodes Count bytes from Buffer using the Base64 mechanism, and then writes the
                encoded data to the destination stream.  It returns the number of bytes from Buffer that
                were actually written.  Note that this is not the number of bytes written to the destination
                stream:  the base64 mechanism writes more bytes to the destination stream.

       Errors:   If there is an error writing to the destination stream, an error may occur.

    See also:    TBase64EncodingStream.Seek (33 ), TBase64EncodingStream.Read (32 ), TBase64DecodingStream.Write
                (30 ), #rtl.classes.TStream.Write (??  )
                1.6.6        TBase64EncodingStream.Seek

    Synopsis:    Position the stream

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek  always  raises  an  EStreamError  exception  unless  the  arguments  it  received  it  don't
                change the current file pointer position.  The encryption stream is not seekable.

       Errors:   An EStreamError error is raised.

    See also:    TBase64EncodingStream.Read (32 ), TBase64EncodingStream.Write (33 ), #rtl.classes.TStream.Seek
                (??  )

                                                                                 33


Chapter   2


Reference   for   unit   'BlowFish'
2.1         Used  units
                                   Table 2.1:  Used units by unit 'BlowFish'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     sysutils         ??



2.2         Overview


The BlowFish implements a class TBlowFish (35 ) to handle blowfish encryption/descryption
of memory buffers, and 2 TStream (??  ) descendents TBlowFishDeCryptStream (36 ) which
descrypts any data that is read from it on the fly, as well as TBlowFishEnCryptStream (37 )
which encrypts the data that is written to it on the fly.
2.3         Constants,  types  and  variables



2.3.1        Constants

BFRounds  =  16


Number of rounds in blowfish encryption.
2.3.2        Types

PBlowFishKey  =  ^TBlowFishKey


PBlowFishKey is a simple pointer to a TBlowFishKey (35 ) array.


TBFBlock  =  Array[0..1]  of  LongInt


                                                              34

                _______________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'BLOWFISH'__________________*
 *___________________
                TBFBlock is the basic data structure used by the encrypting/decrypting routines in TBlow-
                Fish  (35 ),  TBlowFishDeCryptStream  (36 )  and  TBlowFishEnCryptStream  (37 ).   It  is  the
                basic encryption/decryption block for all encrypting/decrypting:  all encrypting/decrypting
                happens on a TBFBlock structure.


                TBlowFishKey  =  Array[0..55]  of  Byte


                TBlowFishKey  is  a  data  structure  which  keeps  the  encryption  or  decryption  key  for  the
                TBlowFish (35 ), TBlowFishDeCryptStream (36 ) and TBlowFishEnCryptStream (37 ) classes.
                It  should  be  filled  with  the  encryption  key  and  passed  to  the  constructor  of  one  of  these
                classes.
                2.4         EBlowFishError



                2.4.1        Description

                EBlowFishError is used by the TBlowFishStream (38 ), TBlowFishEncryptStream (37 ) and
                TBlowFishDecryptStream (36 ) classes to report errors.
                2.5         TBlowFish



                2.5.1        Description

                TBlowFish  is  a  simple  class  that  can  be  used  to  encrypt/decrypt  a  single  TBFBlock  (35 )
                data block with the Encrypt (35 ) and Decrypt (36 ) calls.  It is used internally by the TBlow-
                FishEnCryptStream (37 ) and TBlowFishDeCryptStream (36 ) classes to encrypt or decrypt
                the actual data.
                2.5.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  35        Create          Create a new instance of the TBlowFish class
                  36        Decrypt         Decrypt a block
                __35________Encrypt_________Encrypt_a_block________________________________________________________________________*
 *___________
                2.5.3        TBlowFish.Create

    Synopsis:    Create a new instance of the TBlowFish class

Declaration:     constructor  Create(Key:  TBlowFishKey;KeySize:  Integer)

    Visibility:   public

Description:     Create initializes a new instance of the TBlowFish class:  it stores the key Key in the internal
                data structures so it can be used in later calls to Encrypt (35 ) and Decrypt (36 ).

    See also:    TBlowFish.Encrypt (35 ), TBlowFish.Decrypt (36 )
                2.5.4        TBlowFish.Encrypt

    Synopsis:    Encrypt a block

                                                                                 35

                _______________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'BLOWFISH'__________________*
 *___________________
Declaration:     procedure  Encrypt(var  Block:  TBFBlock)

    Visibility:  public

Description:     Encrypt encrypts the data in Block (always 8 bytes) using the key (35 ) specified when the
                TBlowFish instance was created.

    See also:    TBlowFishKey (35 ), TBlowFish.Decrypt (36 ), TBlowFish.Create (35 )
                2.5.5        TBlowFish.Decrypt

    Synopsis:    Decrypt a block

Declaration:     procedure  Decrypt(var  Block:  TBFBlock)

    Visibility:   public

Description:     ncrypt decrypts the data in Block (always 8 bytes) using the key (35 ) specified when the
                TBlowFish  instance  was  created.  The  data  must  have  been  encrypted  with  the  same  key
                and the Encrypt (35 ) call.

    See also:    TBlowFishKey (35 ), TBlowFish.Encrypt (35 ), TBlowFish.Create (35 )
                2.6         TBlowFishDeCryptStream



                2.6.1        Description

                The TBlowFishDecryptStream provides On-the-fly Blowfish decryption:  all data that is read
                from the source stream is decrypted before it is placed in the output buffer.  The source stream
                must be specified when the TBlowFishDecryptStream instance is created.  The Decryption
                key must also be created when the stream instance is created, and must be the same key as
                the one used when encrypting the data.

                This is a read-only stream:  it is seekable only in a forward direction, and data can only be
                read from it, writing is not possible.  For writing data so it is encrypted, the TBlowFishEn-
                cryptStream (37 ) stream must be used.
                2.6.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  36        Read            Read data from the stream
                __37________Seek____________Set_the_stream_position._______________________________________________________________*
 *___________
                2.6.3        TBlowFishDeCryptStream.Read

    Synopsis:    Read data from the stream

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read  reads  Count  bytes  from  the  source  stream,  decrypts  them  using  the  key  provided
                when the TBlowFishDeCryptStream instance was created, and writes the decrypted data to
                Buffer

    See also:    TBlowFishStream.Create (39 ), TBlowFishEncryptStream (37 )



                                                                                 36

                _______________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'BLOWFISH'__________________*
 *___________________
                2.6.4        TBlowFishDeCryptStream.Seek

    Synopsis:    Set the stream position.

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek emulates a forward seek by reading and discarding data.  The discarded data is lost.
                Since it is a forward seek, this means that only soFromCurrent can be specified for Origin
                with  a  positive  (or  zero)  Offset  value.  All  other  values  will  result  in  an  exception.  The
                function returns the new position in the stream.

       Errors:   If any other combination of  Offset and Origin than the allowed combination is specified,
                then an EBlowFishError (35 ) exception will be raised.

    See also:    TBlowFishDeCryptStream.Read (36 ), EBlowFishError (35 )
                2.7         TBlowFishEncryptStream



                2.7.1        Description

                The  TBlowFishEncryptStream  provides  On-the-fly  Blowfish  encryption:   all  data  that  is
                written to it is encrypted and then written to a destination stream, which must be specified
                when the TBlowFishEncryptStream instance is created.  The encryption key must also be
                created when the stream instance is created.

                This is a write-only stream:  it is not seekable, and data can only be written to it, reading is
                not possible.  For reading encrypted data, the TBlowFishDecryptStream (36 ) stream must
                be used.
                2.7.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  37        Destroy         Free the TBlowFishEncryptStream
                  38        Flush           Flush the encryption buffer
                  38        Seek            Set the position in the stream
                __38________Write___________Write_data_to_the_stream_______________________________________________________________*
 *___________
                2.7.3        TBlowFishEncryptStream.Destroy

    Synopsis:    Free the TBlowFishEncryptStream

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy flushes the encryption buffer, and writes it to the destination stream.  After that
                the Inherited destructor is called to clean up the TBlowFishEncryptStream instance.

    See also:    TBlowFishEncryptStream.Flush (38 ), TBlowFishStream.Create (39 )

                                                                                 37

                _______________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'BLOWFISH'__________________*
 *___________________
                2.7.4        TBlowFishEncryptStream.Write

    Synopsis:    Write data to the stream

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write  will  encrypt  and  write  Count  bytes  from  Buffer  to  the  destination  stream.   The
                function returns the actual number of bytes written.  The data is not encrypted in-place, but
                placed in a special buffer for encryption.

                Data is always written 4 bytes at a time, since this is the amount of bytes required by the
                Blowfish algorithm.  If no multiple of 4 was written to the destination stream, the Flush (38 )
                mechanism can be used to write the remaining bytes.

    See also:    TBlowFishEncryptStream.Read (37 )
                2.7.5        TBlowFishEncryptStream.Seek

    Synopsis:    Set the position in the stream

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Read  will  raise  an  EBlowFishError  exception:  TBlowFishEncryptStream  is  a  write-only
                stream, and cannot be positioned.

       Errors:   Calling this function always results in an EBlowFishError (35 ) exception.

    See also:    TBlowFishEncryptStream.Write (38 )
                2.7.6        TBlowFishEncryptStream.Flush

    Synopsis:    Flush the encryption buffer

Declaration:     procedure  Flush

    Visibility:   public

Description:     Flush writes the remaining data in the encryption buffer to the destination stream.

                For  efficiency,  data  is  always  written  4  bytes  at  a  time,  since  this  is  the  amount  of  bytes
                required  by  the  Blowfish  algorithm.   If  no  multiple  of  4  was  written  to  the  destination
                stream, the Flush mechanism can be used to write the remaining bytes.

                Flush  is  called  automatically  when  the  stream  is  destroyed,  so  there  is  no  need  to  call  it
                after all data was written and the stream is no longer needed.

    See also:    TBlowFishEncryptStream.Write (38 ), TBFBlock (35 )
                2.8         TBlowFishStream



                2.8.1        Description

                TBlowFishStream  is  an  abstract  class  which  is  used  as  a  parent  class  for  TBlowFishEn-
                cryptStream (37 ) and TBlowFishDecryptStream (36 ).  It simply provides a constructor and
                storage for a TBlowFish (35 ) instance and for the source or destination stream.

                Do not create an instance of TBlowFishStream directly.  Instead create one of the descendent
                classes TBlowFishEncryptStream or TBlowFishDecryptStream.



                                                                                 38

                _______________________________________________________CHAPTER_2.___REFERENCE_FOR_UNIT_'BLOWFISH'__________________*
 *___________________
                2.8.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  39        Create          Create a new instance of the TBlowFishStream class
                __39________Destroy_________Destroy_the_TBlowFishStream_instance.__________________________________________________*
 *___________
                2.8.3        Property  overview

                __Page______Property_________Access_______Description______________________________________________________________*
 *___________
                __39________BlowFish_________r____________Blowfish_instance_used_when_encrypting/descrypting_______________________*
 *___________
                2.8.4        TBlowFishStream.Create

    Synopsis:    Create a new instance of the TBlowFishStream class

Declaration:     constructor  Create(AKey:  TBlowFishKey;AKeySize:  Byte;Dest:  TStream)

    Visibility:   public

Description:     Create initializes a new instance of  TBlowFishStream, and creates an internal instance of
                TBlowFish  (35 )  using  AKey  and  AKeySize.   The  Dest  stream  is  stored  so  the  descendent
                classes can refer to it.

                Do not create an instance of TBlowFishStream directly.  Instead create one of the descendent
                classes TBlowFishEncryptStream or TBlowFishDecryptStream.

    See also:    TBlowFishEncryptStream (37 ), TBlowFishDecryptStream (36 ), TBlowFish (35 )
                2.8.5        TBlowFishStream.Destroy

    Synopsis:    Destroy the TBlowFishStream instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the internal TBlowFish (35 ) instance.

       Errors:

    See also:    TBlowFishStream.Create (39 ), TBlowFish (35 )
                2.8.6        TBlowFishStream.BlowFish

    Synopsis:    Blowfish instance used when encrypting/descrypting

Declaration:     Property  BlowFish  :  TBlowFish

    Visibility:   public

      Access:    Read

Description:     BlowFish  is  the  TBlowFish  (35 )  instance  which  is  created  when  the  TBlowFishStream
                class is initialized.  Normally it should not be used directly, it's intended for access by the
                descencent classes TBlowFishEncryptStream (37 ) and TBlowFishDecryptStream (36 ).

    See also:    TBlowFishEncryptStream (37 ), TBlowFishDecryptStream (36 ), TBlowFish (35 )

                                                                                 39


Chapter   3


Reference   for   unit   'bufstream'
3.1         Used  units
                                   Table 3.1:  Used units by unit 'bufstream'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     sysutils         ??



3.2         Overview


BufStream implements two one-way buffered streams:  the streams store all data from (or for)
the source stream in a memory buffer, and only flush the buffer when it's full (or refill it when
it's empty).  The buffer size can be specified at creation time.  2 streams are implemented:
TReadBufStream  (43 )  which  is  for  reading  only,  and  TWriteBufStream  (43 )  which  is  for
writing only.

Buffered streams can help in speeding up read or write operations, especially when a lot of
small read/write operations are done:  it avoids doing a lot of operating system calls.
3.3         Constants,  types  and  variables



3.3.1        Constants

DefaultBufferCapacity  :  Integer  =  16


If no buffer size is specified when the stream is created, then this size is used.
3.4         TBufStream



3.4.1        Description

TBufStream is the common ancestor for the TReadBufStream (43 ) and TWriteBufStream
(43 ) streams.  It completely handles the buffer memory management and position manage-



                                                              40

                ____________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'BUFSTREAM'____________________*
 *___________________
                ment.  An instance of TBufStream should never be created directly.  It also keeps the instance
                of the source stream.
                3.4.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  41        Create          Create a new TBufStream instance.
                __41________Destroy_________Destroys_the_TBufStream_instance_______________________________________________________*
 *___________
                3.4.3        Property  overview

                __Page______Property__________Access_______Description_____________________________________________________________*
 *___________
                  41        Buffer            r            The current buffer
                  42        BufferPos         r            Current buffer position.
                  42        BufferSize        r            Amount of data in the buffer
                __42________Capacity__________rw___________Current_buffer_capacity_________________________________________________*
 *___________
                3.4.4        TBufStream.Create

    Synopsis:    Create a new TBufStream instance.

Declaration:     constructor  Create(ASource:  TStream;ACapacity:  Integer)
                constructor  Create(ASource:  TStream)

    Visibility:   public

Description:     Create creates a new  TBufStream instance.  A buffer of size ACapacity is allocated,  and
                the ASource source (or destination) stream is stored.  If no capacity is specified,  then De-
                faultBufferCapacity (40 ) is used as the capacity.

                An  instance  of  TBufStream  should  never  be  instantiated  directly.  Instead,  an  instance  of
                TReadBufStream (43 ) or TWriteBufStream (43 ) should be created.

       Errors:   If not enough memory is available for the buffer, then an exception may be raised.

    See also:    TBufStream.Destroy (41 ), TReadBufStream (43 ), TWriteBufStream (43 )
                3.4.5        TBufStream.Destroy

    Synopsis:    Destroys the TBufStream instance

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy destroys the instance of TBufStream.  It flushes the buffer, deallocates it, and then
                destroys the TBufStream instance.

    See also:    TBufStream.Create (41 ), TReadBufStream (43 ), TWriteBufStream (43 )
                3.4.6        TBufStream.Buffer

    Synopsis:    The current buffer

Declaration:     Property  Buffer  :  Pointer
                                                                                 41

                ____________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'BUFSTREAM'____________________*
 *___________________
    Visibility:  public

      Access:    Read

Description:     Buffer is a pointer to the actual buffer in use.

    See also:    TBufStream.Create (41 ), TBufStream.Capacity (42 ), TBufStream.BufferSize (42 )
                3.4.7        TBufStream.Capacity

    Synopsis:    Current buffer capacity

Declaration:     Property  Capacity  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Capacity  is  the  amount  of  memory  the  buffer  occupies.   To  change  the  buffer  size,  the
                capacity can be set.  Note that the capacity cannot be set to a value that is less than the
                current buffer size, i.e.  the current amount of data in the buffer.

    See also:    TBufStream.Create (41 ), TBufStream.Buffer (41 ), TBufStream.BufferSize (42 ), TBufStream.BufferPos
                (42 )
                3.4.8        TBufStream.BufferPos

    Synopsis:    Current buffer position.

Declaration:     Property  BufferPos  :  Integer

    Visibility:   public

      Access:    Read

Description:     BufPos is the current stream position in the buffer.  Depending on whether the stream is
                used for reading or writing, data will be read from this position, or will be written at this
                position in the buffer.

    See also:    TBufStream.Create (41 ), TBufStream.Buffer (41 ), TBufStream.BufferSize (42 ), TBufStream.Capacity
                (42 )
                3.4.9        TBufStream.BufferSize

    Synopsis:    Amount of data in the buffer

Declaration:     Property  BufferSize  :  Integer

    Visibility:   public

      Access:    Read

Description:     BufferSize is the actual amount of data in the buffer.  This is always less than or equal to
                the Capacity (42 ).

    See also:    TBufStream.Create (41 ), TBufStream.Buffer (41 ), TBufStream.BufferPos (42 ), TBufStream.Capacity
                (42 )


                                                                                 42

                ____________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'BUFSTREAM'____________________*
 *___________________
                3.5         TReadBufStream



                3.5.1        Description

                TReadBufStream is a read-only buffered stream.  It implements the needed methods to read
                data from the buffer and fill the buffer with additional data when needed.

                The stream provides limited forward-seek possibilities.
                3.5.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  43        Read            Reads data from the stream
                __43________Seek____________Set_location_in_the_buffer_____________________________________________________________*
 *___________
                3.5.3        TReadBufStream.Seek

    Synopsis:    Set location in the buffer

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek sets the location in the buffer.  Currently, only a forward seek is allowed.  It is emulated
                by reading and discarding data.  For an explanation of the parameters, see TStream.Seek"
                (??  )

                The seek method needs enhancement to enable it to do a full-featured seek.  This may be
                implemented in a future release of Free Pascal.

       Errors:   In case an illegal seek operation is attempted, an exception is raised.

    See also:    TWriteBufStream.Seek (44 ), TReadBufStream.Read (43 ), TReadBufStream.Write (43 )
                3.5.4        TReadBufStream.Read

    Synopsis:    Reads data from the stream

Declaration:     function  Read(var  ABuffer;ACount:  LongInt)  :  Integer;    Override

    Visibility:   public

Description:     Read reads at most ACount bytes from the stream and places them in Buffer.  The number
                of actually read bytes is returned.

                TReadBufStream first reads whatever data is still available in the buffer, and then refills the
                buffer, after which it continues to read data from the buffer.  This is repeated untill ACount
                bytes are read, or no more data is available.

    See also:    TReadBufStream.Seek (43 ), TReadBufStream.Read (43 )
                3.6         TWriteBufStream



                3.6.1        Description

                TWriteBufStream  is  a  write-only  buffered  stream.   It  implements  the  needed  methods  to
                write data to the buffer and flush the buffer (i.e.,  write its contents to the source stream)
                when needed.



                                                                                 43

                ____________________________________________________CHAPTER_3.___REFERENCE_FOR_UNIT_'BUFSTREAM'____________________*
 *___________________
                3.6.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  44        Destroy         Remove the TWriteBufStream instance from memory
                  44        Seek            Set stream position.
                __44________Write___________Write_data_to_the_stream_______________________________________________________________*
 *___________
                3.6.3        TWriteBufStream.Destroy

    Synopsis:    Remove the TWriteBufStream instance from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy flushes the buffer and then calls the inherited Destroy (41 ).

       Errors:   If an error occurs during flushing of the buffer, an exception may be raised.

    See also:    TBufStream.Create (41 ), TBufStream.Destroy (41 )
                3.6.4        TWriteBufStream.Seek

    Synopsis:    Set stream position.

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek always raises an EStreamError exception, except when the seek operation would not
                alter the current position.

                A  later  implementation  may  perform  a  proper  seek  operation  by  flushing  the  buffer  and
                doing a seek on the source stream.

       Errors:

    See also:    TWriteBufStream.Write (44 ), TWriteBufStream.Read (43 ), TReadBufStream.Seek (43 )
                3.6.5        TWriteBufStream.Write

    Synopsis:    Write data to the stream

Declaration:     function  Write(const  ABuffer;ACount:  LongInt)  :  Integer;    Override

    Visibility:   public

Description:     Write  writes  at  most  ACount  bytes  from  ABuffer  to  the  stream.  The  data  is  written  to
                the internal buffer first.  As soon as the internal buffer is full, it is flushed to the destination
                stream, and the internal buffer is filled again.  This process continues till all data is written
                (or an error occurs).

       Errors:   An exception may occur if the destination stream has problems writing.

    See also:    TWriteBufStream.Seek (44 ), TWriteBufStream.Read (43 ), TReadBufStream.Write (43 )


                                                                                 44


Chapter   4


Reference   for   unit   'CacheCls'
4.1         Used  units
                                   Table 4.1:  Used units by unit 'CacheCls'


                                                   __Name__________Page_____
                                                     sysutils         ??



4.2         Overview


The  CacheCls  unit  implements  a  caching  class:  similar  to  a  hash  class,  it  can  be  used  to
cache data, associated with string values (keys).  The class is calles TCache
4.3         Constants,  types  and  variables



4.3.1        Resource  strings

SInvalidIndex  =  'Invalid  index  %i'


Message shown when an invalid index is passed.
4.3.2        Types

PCacheSlot  =  ^TCacheSlot


Pointer to TCacheSlot (46 ) record.


PCacheSlotArray  =  ^TCacheSlotArray


Pointer to TCacheSlotArray (46 ) array


TCacheSlot  =  record



                                                              45

_______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CACHECLS'__________________________________*
 *___
   Prev  :  PCacheSlot;
   Next  :  PCacheSlot;
   Data  :  Pointer;
   Index  :  Integer;
end
TCacheSlot is internally used by the TCache (46 ) class.  It represents 1 element in the linked
list.


TCacheSlotArray  =  Array[0..MaxIntdivSizeOf(TCacheSlot)-1]  of  TCacheSlot


TCacheSlotArray is an array of  TCacheSlot items.  Do not use TCacheSlotArray directly,
instead, use PCacheSlotArray (45 ) and allocate memory dynamically.


TOnFreeSlot  =  procedure(ACache:  TCache;SlotIndex:  Integer)  of  object


TOnFreeSlot is a callback prototype used when not enough slots are free, and a slot must
be freed.


TOnIsDataEqual  =  function(ACache:  TCache;AData1:  Pointer;
                                          AData2:  Pointer)  :  Boolean  of  object


TOnIsDataEqual is a callback prototype; It is used by the TCache.Add (47 ) call to determine
whether the item to be added is a new item or not.  The function returns True if the 2 data
pointers AData1 and AData2 should be considered equal, or False when they are not.

For most purposes, comparing the pointers will be enough, but if the pointers are ansistrings,
then the contents should be compared.
4.4         ECacheError



4.4.1        Description

Exception class used in the cachecls unit.
4.5         TCache



4.5.1        Description

TCache implements a cache class:  it is a list-like class, but which uses a counting mechanism,
and keeps a Most-Recent-Used list; this list represents the 'cache'.  The list is internally kept
as a doubly-linked list.

The Data (49 ) property offers indexed access to the array of items.  When accessing the array
through this property, the MRUSlot (49 ) property is updated.


                                                                 46

                _______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CACHECLS'__________________*
 *___________________
                4.5.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  47        Add             Add a data element to the list.
                  48        AddNew          Add a new item to the list.
                  47        Create          Create a new cache class.
                  47        Destroy         Free the TCache class from memory
                  48        FindSlot        Find data pointer in the list
                  48        IndexOf         Return index of a data pointer in the list.
                __49________Remove__________Remove_a_data_item_from_the_list.______________________________________________________*
 *___________
                4.5.3        Property  overview

                __Page______Property__________________Access______Description______________________________________________________*
 *___________
                  49        Data                      rw          Indexed access to data items
                  50        LRUSlot                   r           Last used item
                  49        MRUSlot                   rw          Most recent item slot.
                  51        OnFreeSlot                rw          Event called when a slot is freed
                  50        OnIsDataEqual             rw          Event to compare 2 items.
                  50        SlotCount                 rw          Number of slots in the list
                __50________Slots_____________________r___________Indexed_array_to_the_slots_______________________________________*
 *___________
                4.5.4        TCache.Create

    Synopsis:    Create a new cache class.

Declaration:     constructor  Create(ASlotCount:  Integer)

    Visibility:   public

Description:     Create instantiates a new instance of  TCache.  It allocates room for ASlotCount entries in
                the list.  The number of slots can be increased later.

    See also:    TCache.SlotCount (50 )
                4.5.5        TCache.Destroy

    Synopsis:    Free the TCache class from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the array for the elements, and calls the inherited Destroy.  The elements
                in the array are not freed by this action.

    See also:    TCache.Create (47 )
                4.5.6        TCache.Add

    Synopsis:    Add a data element to the list.

Declaration:     function  Add(AData:  Pointer)  :  Integer

    Visibility:   public

                                                                                 47

                _______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CACHECLS'__________________*
 *___________________
Description:     Add checks whether AData is already in the list.  If so, the item is added to the top of the
                MRU list.  If the item is not yet in the list, then the item is added to the list and placed at
                the top of the MRU list using the AddNew (48 ) call.

                The function returns the index at which the item was added.

                If the maximum number of slots is reached, and a new item is being added, the least used
                item is dropped from the list.

    See also:    TCache.AddNew  (48 ),  TCache.FindSlot  (48 ),  TCache.IndexOf  (48 ),  TCache.Data  (49 ),
                TCache.MRUSlot (49 )
                4.5.7        TCache.AddNew

    Synopsis:    Add a new item to the list.

Declaration:     function  AddNew(AData:  Pointer)  :  Integer

    Visibility:   public

Description:     AddNew  adds  a  new  item  to  the  list:  in  difference  with  the  Add  (47 )  call,  no  checking  is
                performed to see whether the item is already in the list.

                The function returns the index at which the item was added.

                If the maximum number of slots is reached, and a new item is being added, the least used
                item is dropped from the list.

    See also:    TCache.Add (47 ), TCache.FindSlot (48 ), TCache.IndexOf (48 ), TCache.Data (49 ), TCache.MRUSlot
                (49 )
                4.5.8        TCache.FindSlot

    Synopsis:    Find data pointer in the list

Declaration:     function  FindSlot(AData:  Pointer)  :  PCacheSlot

    Visibility:   public

Description:     FindSlot  checks  all  items  in  the  list,  and  returns  the  slot  which  contains  a  data  pointer
                that matches the pointer AData.

                If no item with data pointer that matches AData is found, Nil is returned.

                For this function to work correctly, the OnIsDataEqual (50 ) event must be set.

       Errors:   If  OnIsDataEqual is not set, an exception wil be raised.

    See also:    TCache.IndexOf (48 ), TCache.Add (47 ), TCache.OnIsDataEqual (50 )
                4.5.9        TCache.IndexOf

    Synopsis:    Return index of a data pointer in the list.

Declaration:     function  IndexOf(AData:  Pointer)  :  Integer

    Visibility:   public

Description:     IndexOF searches in the list for a slot with data pointer that matches AData and returns
                the index of the slot.

                If no item with data pointer that matches AData is found, -1 is returned.

                For this function to work correctly, the OnIsDataEqual (50 ) event must be set.



                                                                                 48

                _______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CACHECLS'__________________*
 *___________________
       Errors:   If  OnIsDataEqual is not set, an exception wil be raised.

    See also:    TCache.FindSlot (48 ), TCache.Add (47 ), TCache.OnIsDataEqual (50 )
                4.5.10         TCache.Remove

    Synopsis:    Remove a data item from the list.

Declaration:     procedure  Remove(AData:  Pointer)

    Visibility:   public

Description:     Remove searches the slot which matches AData and if it is found, sets the data pointer to
                Nil, thus effectively removing the pointer from the list.

       Errors:   None.

    See also:    TCache.FindSlot (48 )
                4.5.11         TCache.Data

    Synopsis:    Indexed access to data items

Declaration:     Property  Data[SlotIndex:  Integer]:  Pointer

    Visibility:   public

      Access:    Read,Write

Description:     Data offers index-based access to the data pointers in the cache.  By accessing an item in
                the list in this manner, the item is moved to the front of the MRU list, i.e.  MRUSlot (49 )
                will point to the accessed item.  The access is both read and write.

                The index is zero-based and can maximally be SlotCount-1 (50 ).  Providing an invalid index
                will result in an exception.

    See also:    TCache.MRUSlot (49 )
                4.5.12         TCache.MRUSlot

    Synopsis:    Most recent item slot.

Declaration:     Property  MRUSlot  :  PCacheSlot

    Visibility:   public

      Access:    Read,Write

Description:     MRUSlot points to the most recent used slot.  The most recent used slot is updated when
                the list is accessed through the Data (49 ) property, or when an item is added to the list with
                Add (47 ) or AddNew (48 )

    See also:    TCache.Add (47 ), TCache.AddNew (48 ), TCache.Data (49 ), TCache.LRUSlot (50 )

                                                                                 49

                _______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CACHECLS'__________________*
 *___________________
                4.5.13         TCache.LRUSlot

    Synopsis:    Last used item

Declaration:     Property  LRUSlot  :  PCacheSlot

    Visibility:   public

      Access:    Read

Description:     LRUSlot points to the least recent used slot.  It is the last item in the chain of slots.

    See also:    TCache.Add (47 ), TCache.AddNew (48 ), TCache.Data (49 ), TCache.MRUSlot (49 )
                4.5.14         TCache.SlotCount

    Synopsis:    Number of slots in the list

Declaration:     Property  SlotCount  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     SlotCount is the number of slots in the list.  Its initial value is set when the TCache instance
                is created, but this can be changed at any time.  If items are added to the list and the list is
                full, then the number of slots is not increased, but the least used item is dropped from the
                list.  In that case OnFreeSlot (51 ) is called.

    See also:    TCache.Create (47 ), TCache.Data (49 ), TCache.Slots (50 )
                4.5.15         TCache.Slots

    Synopsis:    Indexed array to the slots

Declaration:     Property  Slots[SlotIndex:  Integer]:  PCacheSlot

    Visibility:   public

      Access:    Read

Description:     Slots  provides  index-based  access  to  the  TCacheSlot  records  in  the  list.   Accessing  the
                records directly does not change their position in the MRU list.

                The index is zero-based and can maximally be SlotCount-1 (50 ).  Providing an invalid index
                will result in an exception.

    See also:    TCache.Data (49 ), TCache.SlotCount (50 )
                4.5.16         TCache.OnIsDataEqual

    Synopsis:    Event to compare 2 items.

Declaration:     Property  OnIsDataEqual  :  TOnIsDataEqual

    Visibility:   public

      Access:    Read,Write


                                                                                 50

                _______________________________________________________CHAPTER_4.___REFERENCE_FOR_UNIT_'CACHECLS'__________________*
 *___________________
Description:     OnIsDataEqual is used by FindSlot (48 ) and IndexOf (48 ) to compare items when looking
                for  a  particular  item.  These  functions  are  called  by  the  Add  (47 )  method.  Failing  to  set
                this event will result in an exception.  The function should return True if the 2 data pointers
                should be considered equal.

    See also:    TCache.FindSlot (48 ), TCache.IndexOf (48 ), TCache.Add (47 )
                4.5.17         TCache.OnFreeSlot

    Synopsis:    Event called when a slot is freed

Declaration:     Property  OnFreeSlot  :  TOnFreeSlot

    Visibility:   public

      Access:    Read,Write

Description:     OnFreeSlot is called when an item needs to be freed, i.e.  when a new item is added to a
                full list, and the least recent used item needs to be dropped from the list.

                The cache class instance and the index of the item to be removed are passed to the callback.

    See also:    TCache.Add (47 ), TCache.AddNew (48 ), TCache.SlotCount (50 )

                                                                                 51


Chapter   5


Reference   for   unit   'contnrs'
5.1         Used  units
                                    Table 5.1:  Used units by unit 'contnrs'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     sysutils         ??



5.2         Overview


The contnrs implements various general-purpose classes:


Stacks      Stack classes to push/pop pointers or objects

Object lists        lists that manage objects instead of pointers, and which automatically dispose
        of the objects.

Component lists             lists that manage components instead of pointers, and which automati-
        cally dispose the components.

Class lists      lists that manage class pointers instead of pointers.

Stacks      Stack classes to push/pop pointers or objects

Queues       Classes to manage a FIFO list of pointers or objects

Hash lists       General-purpose Hash lists.
5.3         Constants,  types  and  variables



5.3.1        Constants

MaxHashListSize  =  Maxint  div  16


MaxHashListSize is the maximum number of elements a hash list can contain.



                                                              52

_________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________________________*
 *___
MaxHashStrSize  =  Maxint


MaxHashStrSize is the maximum amount of data for the key string values.  The key strings
are kept in a continuous memory area.  This constant determines the maximum size of this
memory area.


MaxHashTableSize  =  Maxint  div  4


MaxHashTableSize is the maximum number of elements in the hash.


MaxItemsPerHash  =  3


MaxItemsPerHash  is  the  threshold  above  which  the  hash  is  expanded.   If  the  number  of
elements in a hash bucket becomes larger than this value, the hash size is increased.
5.3.2        Types

PHashItem  =  ^THashItem


PHashItem is a pointer type, pointing to the THashItem (54 ) record.


PHashItemList  =  ^THashItemList


PHashItemList is a pointer to the THashItemList (54 ).  It's used in the TFPHashList (67 )
as a pointer to the memory area containing the hash item records.


PHashTable  =  ^THashTable


PHashTable is a pointer to the THashTable (54 ).  It's used in the TFPHashList (67 ) as a
pointer to the memory area containing the hash values.


TDataIteratorMethod  =  procedure(Item:  Pointer;const  Key:  String;
                                                     var  Continue:  Boolean)  of  object


TDataIteratorMethod is a callback prototype for the TDataHashTable.Iterate (52 ) method.
It  is  called  for  each  data  pointer  in  the  hash  list,  passing  the  key  (key)  and  data  pointer
(item) for each item in the list.  If  Continue is set to false, the iteration stops.


THashFunction  =  function(const  S:  String;const  TableSize:  LongWord)
                                           :  LongWord


THashFunction is the prototype for a hash calculation function.  It should calculate a hash
of string  S, where the hash table size is TableSize.  The return value should be the hash
value.


THashItem  =  record
    HashValue  :  LongWord;
    StrIndex  :  Integer;
    NextIndex  :  Integer;
    Data  :  Pointer;
end

                                                                 53

_________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________________________*
 *___
THashItem is used internally in the hash list.  It should never be used directly.


THashItemList  =  Array[0..MaxHashListSize-1]  of  THashItem


THashItemList is an array type, primarily used to be able to define the PHashItemList (53 )
type.  It's used in the TFPHashList (67 ) class.


THashTable  =  Array[0..MaxHashTableSize-1]  of  Integer


THashTable defines an array of integers, used to hold hash values.  It's mainly used to define
the PHashTable (53 ) class.


THTCustomNodeClass  =  Class  of  THTCustomNode


THTCustomNodeClass is used by THTCustomHashTable (52 ) to decide which class should
be created for elements in the list.


THTNode  =  THTDataNode


THTNode is provided for backwards compatibility.


TIteratorMethod  =  TDataIteratorMethod


TIteratorMethod is used in an internal TFPHashTable (52 ) method.


TObjectIteratorMethod  =  procedure(Item:  TObject;const  Key:  String;
                                                        var  Continue:  Boolean)  of  object


TObjectIteratorMethod is the iterator callback prototype.  It is used to iterate over all items
in the hash table, and is called with each key value (Key) and associated object (Item).  If
Continue is set to false, the iteration stops.


TObjectListCallback  =  procedure(data:  TObject;arg:  pointer)  of  object


TObjectListCallback is used as the prototype for the TFPObjectList.ForEachCall (91 ) link
call when a method should be called.  The Data argument will contain each of the objects
in the list in turn, and the Data argument will contain the data passed to the ForEachCall
call.


TObjectListStaticCallback  =  procedure(data:  TObject;arg:  pointer)


TObjectListCallback  is  used  as  the  prototype  for  the  TFPObjectList.ForEachCall  (91 )
link call when a plain procedure should be called.  The Data argument will contain each of
the objects in the list in turn, and the Data argument will contain the data passed to the
ForEachCall call.


TStringIteratorMethod  =  procedure(Item:  String;const  Key:  String;
                                                        var  Continue:  Boolean)  of  object


TStringIteratorMethod is the callback prototype for the Iterate (61 ) method.  It is called
for each element in the hash table, with the string.  If Continue is set to false, the iteration
stops.



                                                                 54

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.4         Procedures  and  functions



                5.4.1        RSHash

    Synopsis:    Standard hash value calculating function.

Declaration:     function  RSHash(const  S:  String;const  TableSize:  LongWord)  :  LongWord

    Visibility:   default

Description:     RSHash is the standard hash calculating function used in the TFPCustomHashTable (61 )
                hash class.  It's Robert Sedgwick's  lgorithms in C" hash function.

       Errors:   None.

    See also:    TFPCustomHashTable (61 )
                5.5         EDuplicate



                5.5.1        Description

                Exception raised when a key is stored twice in a hash table.
                5.6         EKeyNotFound



                5.6.1        Description

                Exception raised when a key is not found.
                5.7         TClassList



                5.7.1        Description

                TClassList is a Tlist (??  ) descendent which stores class references instead of pointers.  It
                introduces no new behaviour other than ensuring all stored pointers are class pointers.

                The  OwnsObjects  property  as  found  in  TComponentList  and  TObjectList  is  not  imple-
                mented as there are no actual instances.
                5.7.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  56        Add             Add a new class pointer to the list.
                  56        Extract         Extract a class pointer from the list.
                  57        First           Return first non-nil class pointer
                  56        IndexOf         Search for a class pointer in the list.
                  57        Insert          Insert a new class pointer in the list.
                  57        Last            Return last non-Nil class pointer
                __56________Remove__________Remove_a_class_pointer_from_the_list.__________________________________________________*
 *___________
                5.7.3        Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __57________Items___________rw___________Index_based_access_to_class_pointers._____________________________________*
 *___________



                                                                                 55

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.7.4        TClassList.Add

    Synopsis:    Add a new class pointer to the list.

Declaration:     function  Add(AClass:  TClass)  :  Integer

    Visibility:   public

Description:     Add  adds  AClass  to  the  list,  and  returns  the  position  at  which  it  was  added.   It  simply
                overrides the TList (??  ) bevahiour, and introduces no new functionality.

       Errors:   If not enough memory is available to expand the list, an exception may be raised.

    See also:    TClassList.Extract (56 ), #rtl.classes.tlist.add (??  )
                5.7.5        TClassList.Extract

    Synopsis:    Extract a class pointer from the list.

Declaration:     function  Extract(Item:  TClass)  :  TClass

    Visibility:   public

Description:     Extract extracts a class pointer Item from the list,  if it is present in the list.  It returns
                the extracted class pointer, or Nil if the class pointer was not present in the list.  It simply
                overrides the implementation in TList so it accepts a class pointer instead of a simple pointer.
                No new behaviour is introduced.

       Errors:   None.

    See also:    TClassList.Remove (56 ), #rtl.classes.Tlist.Extract (??  )
                5.7.6        TClassList.Remove

    Synopsis:    Remove a class pointer from the list.

Declaration:     function  Remove(AClass:  TClass)  :  Integer

    Visibility:   public

Description:     Remove removes a class pointer Item from the list, if it is present in the list.  It returns the
                index of the removed class pointer, or -1 if the class pointer was not present in the list.  It
                simply overrides the implementation in TList so it accepts a class pointer instead of a simple
                pointer.  No new behaviour is introduced.

       Errors:   None.

    See also:    TClassList.Extract (56 ), #rtl.classes.Tlist.Remove (??  )
                5.7.7        TClassList.IndexOf

    Synopsis:    Search for a class pointer in the list.

Declaration:     function  IndexOf(AClass:  TClass)  :  Integer

    Visibility:   public

Description:     IndexOf searches for AClass in the list, and returns it's position if it was found, or -1 if it
                was not found in the list.

       Errors:   None.

    See also:    #rtl.classes.tlist.indexof (??  )



                                                                                 56

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.7.8        TClassList.First

    Synopsis:    Return first non-nil class pointer

Declaration:     function  First  :  TClass

    Visibility:   public

Description:     First returns a reference to the first non-Nil class pointer in the list.  If no non-Nil element
                is found, Nil is returned.

       Errors:   None.

    See also:    TClassList.Last (57 ), TClassList.Pack (55 )
                5.7.9        TClassList.Last

    Synopsis:    Return last non-Nil class pointer

Declaration:     function  Last  :  TClass

    Visibility:   public

Description:     Last returns a reference to the last non-Nil class pointer in the list.  If no non-Nil element
                is found, Nil is returned.

       Errors:   None.

    See also:    TClassList.First (57 ), TClassList.Pack (55 )
                5.7.10         TClassList.Insert

    Synopsis:    Insert a new class pointer in the list.

Declaration:     procedure  Insert(Index:  Integer;AClass:  TClass)

    Visibility:   public

Description:     Insert inserts a class pointer in the list at position Index.  It simply overrides the parent
                implementation so it only accepts class pointers.  It introduces no new behaviour.

       Errors:   None.

    See also:    #rtl.classes.TList.Insert (??  ), TClassList.Add (56 ), TClassList.Remove (56 )
                5.7.11         TClassList.Items

    Synopsis:    Index based access to class pointers.

Declaration:     Property  Items[Index:  Integer]:  TClass;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items provides index-based access to the class pointers in the list.  TClassList overrides
                the default Items implementation of  TList so it returns class pointers instead of pointers.

    See also:    #rtl.classes.TList.Items (??  ), #rtl.classes.TList.Count (??  )
                                                                                 57

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.8         TComponentList



                5.8.1        Description

                TComponentList is a TObjectList (97 ) descendent which has as the default array property
                TComponents (??  ) instead of objects.  It overrides some methods so only components can
                be added.

                In difference with TObjectList (97 ), TComponentList removes any TComponent from the list
                if the TComponent instance was freed externally.  It uses the FreeNotification mechanism
                for this.
                5.8.2        Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  58        Add             Add a component to the list.
                  58        Destroy         Destroys the instance
                  59        Extract         Remove a component from the list without destroying it.
                  60        First           First non-nil instance in the list.
                  59        IndexOf         Search for an instance in the list
                  60        Insert          Insert a new component in the list
                  60        Last            Last non-nil instance in the list.
                __59________Remove__________Remove_a_component_from_the_list,_possibly_destroying_it.______________________________*
 *___________
                5.8.3        Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __60________Items___________rw___________Index-based_access_to_the_elements_in_the_list.___________________________*
 *___________
                5.8.4        TComponentList.Destroy

    Synopsis:    Destroys the instance

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy unhooks the free notification handler and then calls the inherited destroy to clean
                up the TComponentList instance.

       Errors:   None.

    See also:    TObjectList (97 ), #rtl.classes.TComponent (??  )
                5.8.5        TComponentList.Add

    Synopsis:    Add a component to the list.

Declaration:     function  Add(AComponent:  TComponent)  :  Integer

    Visibility:   public

Description:     Add overrides the Add operation of it's ancestors, so it only accepts TComponent instances.
                It introduces no new behaviour.

                The function returns the index at which the component was added.
                                                                                 58

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
       Errors:   If not enough memory is available to expand the list, an exception may be raised.

    See also:    TObectList.Add (52 )
                5.8.6        TComponentList.Extract

    Synopsis:    Remove a component from the list without destroying it.

Declaration:     function  Extract(Item:  TComponent)  :  TComponent

    Visibility:   public

Description:     Extract removes a component (Item) from the list, without destroying it.  It overrides the
                implementation of TObjectList (97 ) so only  TComponent descendents can be extracted.  It
                introduces no new behaviour.

                Extract returns the instance that was extracted, or Nil if no instance was found.

    See also:    TComponentList.Remove (59 ), TObjectList.Extract (98 )
                5.8.7        TComponentList.Remove

    Synopsis:    Remove a component from the list, possibly destroying it.

Declaration:     function  Remove(AComponent:  TComponent)  :  Integer

    Visibility:   public

Description:     Remove  removes  item  from  the  list,  and  if  the  list  owns  it's  items,  it  also  destroys  it.  It
                returns the index of the item that was removed, or -1 if no item was removed.

                Remove simply overrides the implementation in TObjectList (97 ) so it only accepts TComponent
                descendents.  It introduces no new behaviour.

       Errors:   None.

    See also:    TComponentList.Extract (59 ), TObjectList.Remove (98 )
                5.8.8        TComponentList.IndexOf

    Synopsis:    Search for an instance in the list

Declaration:     function  IndexOf(AComponent:  TComponent)  :  Integer

    Visibility:   public

Description:     IndexOf searches for an instance in the list and returns it's position in the list.  The position
                is zero-based.  If no instance is found, -1 is returned.

                IndexOf just overrides the implementation of the parent class so it accepts only TComponent
                instances.  It introduces no new behaviour.

       Errors:   None.

    See also:    TObjectList.IndexOf (99 )



                                                                                 59

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.8.9        TComponentList.First

    Synopsis:    First non-nil instance in the list.

Declaration:     function  First  :  TComponent

    Visibility:   public

Description:     First overrides the implementation of it's ancestors to return the first non-nil instance of
                TComponent in the list.  If no non-nil instance is found, Nil is returned.

       Errors:   None.

    See also:    TComponentList.Last (60 ), TObjectList.First (99 )
                5.8.10         TComponentList.Last

    Synopsis:    Last non-nil instance in the list.

Declaration:     function  Last  :  TComponent

    Visibility:   public

Description:     Last  overrides  the  implementation  of  it's  ancestors  to  return  the  last  non-nil  instance  of
                TComponent in the list.  If no non-nil instance is found, Nil is returned.

       Errors:   None.

    See also:    TComponentList.First (60 ), TObjectList.Last (100  )
                5.8.11         TComponentList.Insert

    Synopsis:    Insert a new component in the list

Declaration:     procedure  Insert(Index:  Integer;AComponent:  TComponent)

    Visibility:   public

Description:     Insert inserts a TComponent instance (AComponent) in the list at position Index.  It simply
                overrides the parent implementation so it only accepts TComponent instances.  It introduces
                no new behaviour.

       Errors:   None.

    See also:    TObjectList.Insert (99 ), TComponentList.Add (58 ), TComponentList.Remove (59 )
                5.8.12         TComponentList.Items

    Synopsis:    Index-based access to the elements in the list.

Declaration:     Property  Items[Index:  Integer]:  TComponent;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items provides access to the components in the list using an index.  It simply overrides the
                default property of the parent classes so it returns/accepts TComponent instances only.  Note
                that the index is zero based.

    See also:    TObjectList.Items (100  )



                                                                                 60

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.9         TFPCustomHashTable



                5.9.1        Description

                TFPCustomHashTable is a general-purpose hashing class.  It can store string keys and point-
                ers associated with these strings.  The hash mechanism is configurable and can be optionally
                be specified when a new instance of the class is created; A default hash mechanism is imple-
                mented in RSHash (55 ).

                A TFPHasList should be used when fast lookup of data based on some key is required.  The
                other  container  objects  only  offer  linear  search  methods,  while  the  hash  list  offers  faster
                search mechanisms.
                5.9.2        Method  overview

                __Page______Property____________________Description________________________________________________________________*
 *___________
                  62        ChangeTableSize             Change the table size of the hash table.
                  62        Clear                       Clear the hash table.
                  61        Create                      Instantiate a new TFPCustomHashTable instance using the de-
                                                        fault hash mechanism
                  62        CreateWith                  Instantiate  a  new  TFPCustomHashTable  instance  with  given
                                                        algorithm and size
                  63        Delete                      Delete a key from the hash list.
                  62        Destroy                     Free the hash table.
                  63        Find                        Search for an item with a certain key value.
                __63________IsEmpty_____________________Check_if_the_hash_table_is_empty.__________________________________________*
 *___________
                5.9.3        Property  overview

                __Page______Property________________________Access_______Description_______________________________________________*
 *___________
                  65        AVGChainLen                     r            Average chain length
                  64        Count                           r            Number of items in the hash table.
                  66        Density                         r            Number of filled slots
                  63        HashFunction                    rw           Hash function currently in use
                  64        HashTable                       r            Hash table instance
                  64        HashTableSize                   rw           Size of the hash table
                  65        LoadFactor                      r            Fraction of count versus size
                  65        MaxChainLength                  r            Maximum chain length
                  66        NumberOfCollisions              r            Number of extra items
                __65________VoidSlots_______________________r____________Number_of_empty_slots_in_the_hash_table.__________________*
 *___________
                5.9.4        TFPCustomHashTable.Create

    Synopsis:    Instantiate a new TFPCustomHashTable instance using the default hash mechanism

Declaration:     constructor  Create

    Visibility:   public

Description:     Create  creates  a  new  instance  of  TFPCustomHashTable  with  hash  size  196613  and  hash
                algorithm RSHash (55 )

       Errors:   If no memory is available, an exception may be raised.

    See also:    TFPCustomHashTable.CreateWith (62 )
                                                                                 61

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.9.5        TFPCustomHashTable.CreateWith

    Synopsis:    Instantiate a new TFPCustomHashTable instance with given algorithm and size

Declaration:     constructor  CreateWith(AHashTableSize:  LongWord;
                                                     aHashFunc:  THashFunction)

    Visibility:   public

Description:     CreateWith creates a new instance of TFPCustomHashTable with hash size AHashTableSize
                and hash calculating algorithm aHashFunc.

       Errors:   If no memory is available, an exception may be raised.

    See also:    TFPCustomHashTable.Create (61 )
                5.9.6        TFPCustomHashTable.Destroy

    Synopsis:    Free the hash table.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy removes the hash table from memory.  If any data was associated with the keys in
                the hash table, then this data is not freed.  This must be done by the programmer.

       Errors:   None.

    See also:    TFPCustomHashTable.Destroy (62 ), TFPCustomHashTable.Create (61 ), TFPCustomHashTable.CreateWith
                (62 ), THTCustomNode.Data (94 )
                5.9.7        TFPCustomHashTable.ChangeTableSize

    Synopsis:    Change the table size of the hash table.

Declaration:     procedure  ChangeTableSize(const  ANewSize:  LongWord);    Virtual

    Visibility:   public

Description:     ChangeTableSize changes the size of the hash table:  it recomputes the hash value for all
                of the keys in the table, so this is an expensive operation.

       Errors:   If no memory is available, an exception may be raised.

    See also:    TFPCustomHashTable.HashTableSize (64 )
                5.9.8        TFPCustomHashTable.Clear

    Synopsis:    Clear the hash table.

Declaration:     procedure  Clear;    Virtual

    Visibility:   public

Description:     Clear removes all keys and their associated data from the hash table.  The data itself is not
                freed from memory, this should be done by the programmer.

       Errors:   None.

    See also:    TFPCustomHashTable.Destroy (62 )



                                                                                 62

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.9.9        TFPCustomHashTable.Delete

    Synopsis:    Delete a key from the hash list.

Declaration:     procedure  Delete(const  aKey:  String);    Virtual

    Visibility:   public

Description:     Delete  deletes  all  keys  with  value  AKey  from  the  hash  table.   It  does  not  free  the  data
                associated with key.  If  AKey is not in the list, nothing is removed.

       Errors:   None.

    See also:    TFPCustomHashTable.Find (63 ), TFPCustomHashTable.Add (61 )
                5.9.10         TFPCustomHashTable.Find

    Synopsis:    Search for an item with a certain key value.

Declaration:     function  Find(const  aKey:  String)  :  THTCustomNode

    Visibility:   public

Description:     Find searches for the THTCustomNode (94 ) instance with key value equal to Akey and if
                it finds it, it returns the instance.  If no matching value is found, Nil is returned.

                Note that the instance returned by this function cannot be freed;  If it should be removed
                from the hash table, the Delete (63 ) method should be used instead.

       Errors:   None.

    See also:    TFPCustomHashTable.Add (61 ), TFPCustomHashTable.Delete (63 )
                5.9.11         TFPCustomHashTable.IsEmpty

    Synopsis:    Check if the hash table is empty.

Declaration:     function  IsEmpty  :  Boolean

    Visibility:   public

Description:     IsEmpty  returns  True  if  the  hash  table  contains  no  elements,  or  False  if  there  are  still
                elements in the hash table.

       Errors:

    See also:    TFPCustomHashTable.Count  (64 ),  TFPCustomHashTable.HashTableSize  (64 ),  TFPCus-
                tomHashTable.AVGChainLen (65 ), TFPCustomHashTable.MaxChainLength (65 )
                5.9.12         TFPCustomHashTable.HashFunction

    Synopsis:    Hash function currently in use

Declaration:     Property  HashFunction  :  THashFunction

    Visibility:   public

      Access:    Read,Write


                                                                                 63

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
Description:     HashFunction is the hash function currently in use to calculate hash values from keys.  The
                property  can  be  set,  this  simply  calls  SetHashFunction  (61 ).   Note  that  setting  the  hash
                function does NOT the hash value of all keys to be recomputed, so changing the value while
                there are still keys in the table is not a good idea.

    See also:    TFPCustomHashTable.SetHashFunction (61 ), TFPCustomHashTable.HashTableSize (64 )
                5.9.13         TFPCustomHashTable.Count

    Synopsis:    Number of items in the hash table.

Declaration:     Property  Count  :  LongWord

    Visibility:   public

      Access:    Read

Description:     Count is the number of items in the hash table.

    See also:    TFPCustomHashTable.IsEmpty (63 ), TFPCustomHashTable.HashTableSize (64 ), TFPCus-
                tomHashTable.AVGChainLen (65 ), TFPCustomHashTable.MaxChainLength (65 )
                5.9.14         TFPCustomHashTable.HashTableSize

    Synopsis:    Size of the hash table

Declaration:     Property  HashTableSize  :  LongWord

    Visibility:   public

      Access:    Read,Write

Description:     HashTableSize is the size of the hash table.  It can be set, in which case it will be rounded
                to the nearest prime number suitable for RSHash.

    See also:    TFPCustomHashTable.IsEmpty (63 ), TFPCustomHashTable.Count (64 ), TFPCustomHashTable.AVGChainLen
                (65 ), TFPCustomHashTable.MaxChainLength (65 ), TFPCustomHashTable.VoidSlots (65 ),
                TFPCustomHashTable.Density (66 )
                5.9.15         TFPCustomHashTable.HashTable

    Synopsis:    Hash table instance

Declaration:     Property  HashTable  :  TFPObjectList

    Visibility:   public

      Access:    Read

Description:     TFPCustomHashTable is the internal list object (TFPObjectList (85 ) used for the hash table.
                Each element in this table is again a TFPObjectList (85 ) instance or Nil.


                                                                                 64

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.9.16         TFPCustomHashTable.VoidSlots

    Synopsis:    Number of empty slots in the hash table.

Declaration:     Property  VoidSlots  :  LongWord

    Visibility:   public

      Access:    Read

Description:     VoidSlots is the number of empty slots in the hash table.  Calculating this is an expensive
                operation.

    See also:    TFPCustomHashTable.IsEmpty (63 ), TFPCustomHashTable.Count (64 ), TFPCustomHashTable.AVGChainLen
                (65 ), TFPCustomHashTable.MaxChainLength (65 ), TFPCustomHashTable.LoadFactor (65 ),
                TFPCustomHashTable.Density (66 ), TFPCustomHashTable.NumberOfCollisions (66 )
                5.9.17         TFPCustomHashTable.LoadFactor

    Synopsis:    Fraction of count versus size

Declaration:     Property  LoadFactor  :  double

    Visibility:   public

      Access:    Read

Description:     LoadFactor is the ratio of elements in the table versus table size.  Ideally, this should be as
                small as possible.

    See also:    TFPCustomHashTable.IsEmpty (63 ), TFPCustomHashTable.Count (64 ), TFPCustomHashTable.AVGChainLen
                (65 ), TFPCustomHashTable.MaxChainLength (65 ), TFPCustomHashTable.VoidSlots (65 ),
                TFPCustomHashTable.Density (66 ), TFPCustomHashTable.NumberOfCollisions (66 )
                5.9.18         TFPCustomHashTable.AVGChainLen

    Synopsis:    Average chain length

Declaration:     Property  AVGChainLen  :  double

    Visibility:   public

      Access:    Read

Description:     AVGChainLen is the average chain length, i.e.  the ratio of elements in the table versus the
                number of filled slots.  Calculating this is an expensive operation.

    See also:    TFPCustomHashTable.IsEmpty (63 ), TFPCustomHashTable.Count (64 ), TFPCustomHashTable.LoadFactor
                (65 ), TFPCustomHashTable.MaxChainLength (65 ), TFPCustomHashTable.VoidSlots (65 ),
                TFPCustomHashTable.Density (66 ), TFPCustomHashTable.NumberOfCollisions (66 )
                5.9.19         TFPCustomHashTable.MaxChainLength

    Synopsis:    Maximum chain length

Declaration:     Property  MaxChainLength  :  LongWord

    Visibility:   public
                                                                                 65

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
      Access:    Read

Description:     MaxChainLength is the length of the longest chain in the hash table.  Calculating this is an
                expensive operation.

    See also:    TFPCustomHashTable.IsEmpty (63 ), TFPCustomHashTable.Count (64 ), TFPCustomHashTable.LoadFactor
                (65 ),  TFPCustomHashTable.AvgChainLength (61 ),  TFPCustomHashTable.VoidSlots (65 ),
                TFPCustomHashTable.Density (66 ), TFPCustomHashTable.NumberOfCollisions (66 )
                5.9.20         TFPCustomHashTable.NumberOfCollisions

    Synopsis:    Number of extra items

Declaration:     Property  NumberOfCollisions  :  LongWord

    Visibility:   public

      Access:    Read

Description:     NumberOfCollisions is the number of items which are not the first item in a chain.  If this
                number is too big, the hash size may be too small.

    See also:    TFPCustomHashTable.IsEmpty (63 ), TFPCustomHashTable.Count (64 ), TFPCustomHashTable.LoadFactor
                (65 ),  TFPCustomHashTable.AvgChainLength (61 ),  TFPCustomHashTable.VoidSlots (65 ),
                TFPCustomHashTable.Density (66 )
                5.9.21         TFPCustomHashTable.Density

    Synopsis:    Number of filled slots

Declaration:     Property  Density  :  LongWord

    Visibility:   public

      Access:    Read

Description:     Density is the number of filled slots in the hash table.

    See also:    TFPCustomHashTable.IsEmpty (63 ), TFPCustomHashTable.Count (64 ), TFPCustomHashTable.LoadFactor
                (65 ),  TFPCustomHashTable.AvgChainLength (61 ),  TFPCustomHashTable.VoidSlots (65 ),
                TFPCustomHashTable.Density (66 )
                5.10          TFPDataHashTable



                5.10.1         Description

                TFPDataHashTable  is  a  TFPCustomHashTable  (61 )  descendent  which  stores  simple  data
                pointers  together  with  the  keys.   In  case  the  data  associated  with  the  keys  are  objects,
                it's better to use TFPObjectHashTable (83 ), or for string data, TFPStringHashTable (93 )
                is  more  suitable.   The  data  pointers  are  exposed  with  their  keys  through  the  Items  (67 )
                property.
                5.10.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __67________Add_____________Add_a_data_pointer_to_the_list.________________________________________________________*
 *___________



                                                                                 66

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.10.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __67________Items___________rw___________Key-based_access_to_the_items_in_the_table________________________________*
 *___________
                5.10.4         TFPDataHashTable.Add

    Synopsis:    Add a data pointer to the list.

Declaration:     procedure  Add(const  aKey:  String;AItem:  pointer);    Virtual

    Visibility:   public

Description:     Add adds a data pointer (AItem) to the list with key AKey.

       Errors:   If  AKey already exists in the table, an exception is raised.

    See also:    TFPDataHashTable.Items (67 )
                5.10.5         TFPDataHashTable.Items

    Synopsis:    Key-based access to the items in the table

Declaration:     Property  Items[index:  String]:  Pointer;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items provides access to the items in the hash table using their key:  the array index Index
                is the key.  A key which is not present will result in an Nil pointer.

    See also:    TFPStringHashTable.Add (93 )
                5.11          TFPHashList



                5.11.1         Description

                TFPHashList implements a fast hash class.  The class is built for speed,  therefore the key
                values can be shortstrings only, and the data can only be pointers.

                if a base class for an own hash class is wanted, the TFPCustomHashTable (61 ) class can be
                used.  If a hash class for objects is needed instead of pointers, the TFPHashObjectList (77 )
                class can be used.

                                                                                 67

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.11.2         Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  69        Add                      Add a new key/data pair to the list
                  69        Clear                    Clear the list
                  68        Create                   Create a new instance of the hashlist
                  70        Delete                   Delete an item from the list.
                  68        Destroy                  Removes an instance of the hashlist from the heap
                  70        Error                    Raise an error
                  70        Expand                   Expand the list
                  70        Extract                  Extract a pointer from the list
                  71        Find                     Find data associated with key
                  71        FindIndexOf              Return index of named item.
                  71        FindWithHash             Find first element with given name and hash value
                  73        ForEachCall              Call a procedure for each element in the list
                  69        HashOfIndex              Return the hash valye of an item by index
                  71        IndexOf                  Return the index of the data pointer
                  69        NameOfIndex              Returns the key name of an item by index
                  72        Pack                     Remove nil pointers from the list
                  72        Remove                   Remove first instance of a pointer
                  72        Rename                   Rename a key
                __72________ShowStatistics___________Return_some_statistics_for_the_list.__________________________________________*
 *___________
                5.11.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  73        Capacity        rw           Capacity of the list.
                  73        Count           rw           Current number of elements in the list.
                  73        Items           rw           Indexed array with pointers
                  74        List            r            Low-level hash list
                __74________Strs____________r____________Low-level_memory_area_with_strings._______________________________________*
 *___________
                5.11.4         TFPHashList.Create

    Synopsis:    Create a new instance of the hashlist

Declaration:     constructor  Create

    Visibility:   public

Description:     Create creates a new instance of  TFPHashList on the heap and sets the hash capacity to
                1.

    See also:    TFPHashList.Destroy (68 )
                5.11.5         TFPHashList.Destroy

    Synopsis:    Removes an instance of the hashlist from the heap

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  cleans  up  the  memory  structures  maintained  by  the  hashlist  and  removes  the
                TFPHashList instance from the heap.

                Destroy should not be called directly, it's better to use Free or FreeAndNil instead.



                                                                                 68

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
    See also:    TFPHashList.Create (68 ), TFPHashList.Clear (69 )
                5.11.6         TFPHashList.Add

    Synopsis:    Add a new key/data pair to the list

Declaration:     function  Add(const  AName:  shortstring;Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Add adds a new data pointer (Item) with key AName to the list.  It returns the position of
                the item in the list.

       Errors:   If not enough memory is available to hold the key and data, an exception may be raised.  If
                an item with this name already exists in the list, an exception is raised.

    See also:    TFPHashList.Extract (70 ), TFPHashList.Remove (72 ), TFPHashList.Delete (70 )
                5.11.7         TFPHashList.Clear

    Synopsis:    Clear the list

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear removes all items from the list.  It does not free the data items themselves.  It frees
                all memory needed to contain the items.

       Errors:   None.

    See also:    TFPHashList.Extract (70 ), TFPHashList.Remove (72 ), TFPHashList.Delete (70 ), TFPHash-
                List.Add (69 )
                5.11.8         TFPHashList.NameOfIndex

    Synopsis:    Returns the key name of an item by index

Declaration:     function  NameOfIndex(Index:  Integer)  :  ShortString

    Visibility:   public

Description:     NameOfIndex returns the key name of the item at position Index.

       Errors:   If  Index is out of the valid range, an exception is raised.

    See also:    TFPHashList.HashOfIndex (69 ), TFPHashList.Find (71 ), TFPHashList.FindIndexOf (71 ),
                TFPHashList.FindWithHash (71 )
                5.11.9         TFPHashList.HashOfIndex

    Synopsis:    Return the hash valye of an item by index

Declaration:     function  HashOfIndex(Index:  Integer)  :  LongWord

    Visibility:   public

Description:     HashOfIndex returns the hash value of the item at position Index.



                                                                                 69

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
       Errors:   If  Index is out of the valid range, an exception is raised.

    See also:    TFPHashList.HashOfName (67 ), TFPHashList.Find (71 ), TFPHashList.FindIndexOf (71 ),
                TFPHashList.FindWithHash (71 )
                5.11.10          TFPHashList.Delete

    Synopsis:    Delete an item from the list.

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete deletes the item at position Index.  The data to which it points is not freed from
                memory.

       Errors:   TFPHashList.Extract (70 )TFPHashList.Remove (72 )TFPHashList.Add (69 )
                5.11.11          TFPHashList.Error

    Synopsis:    Raise an error

Declaration:     procedure  Error(const  Msg:  String;Data:  PtrInt)

    Visibility:   public

Description:     Error  raises  an  EListError  exception,  with  message  Msg.   The  Data  pointer  is  used  to
                format the message.
                5.11.12          TFPHashList.Expand

    Synopsis:    Expand the list

Declaration:     function  Expand  :  TFPHashList

    Visibility:   public

Description:     Expand enlarges the capacity of the list if the maximum capacity was reached.  It returns
                itself.

       Errors:   If not enough memory is available, an exception may be raised.

    See also:    TFPHashList.Clear (69 )
                5.11.13          TFPHashList.Extract

    Synopsis:    Extract a pointer from the list

Declaration:     function  Extract(item:  Pointer)  :  Pointer

    Visibility:   public

Description:     Extract removes the data item from the list, if it is in the list.  It returns the pointer if it
                was removed from the list, Nil otherwise.

                Extract does a linear search, and is not very efficient.

    See also:    TFPHashList.Delete (70 ), TFPHashList.Remove (72 ), TFPHashList.Clear (69 )
                                                                                 70

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.11.14          TFPHashList.IndexOf

    Synopsis:    Return the index of the data pointer

Declaration:     function  IndexOf(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     IndexOf returns the index of the first occurrence of pointer Item.  If the item is not in the
                list, -1 is returned.

                The performed search is linear, and not very efficient.

    See also:    TFPHashList.HashOfIndex (69 ), TFPHashList.NameOfIndex (69 ), TFPHashList.Find (71 ),
                TFPHashList.FindIndexOf (71 ), TFPHashList.FindWithHash (71 )
                5.11.15          TFPHashList.Find

    Synopsis:    Find data associated with key

Declaration:     function  Find(const  AName:  shortstring)  :  Pointer

    Visibility:   public

Description:     Find searches (using the hash) for the data item associated with item AName and returns
                the data pointer associated with it.  If the item is not found,  Nil is returned.  It uses the
                hash value of the key to perform the search.

    See also:    TFPHashList.HashOfIndex (69 ),  TFPHashList.NameOfIndex (69 ),  TFPHashList.IndexOf
                (71 ), TFPHashList.FindIndexOf (71 ), TFPHashList.FindWithHash (71 )
                5.11.16          TFPHashList.FindIndexOf

    Synopsis:    Return index of named item.

Declaration:     function  FindIndexOf(const  AName:  shortstring)  :  Integer

    Visibility:   public

Description:     FindIndexOf returns the index of the key AName, or -1 if the key does not exist in the list.
                It uses the hash value to search for the key.

    See also:    TFPHashList.HashOfIndex (69 ),  TFPHashList.NameOfIndex (69 ),  TFPHashList.IndexOf
                (71 ), TFPHashList.Find (71 ), TFPHashList.FindWithHash (71 )
                5.11.17          TFPHashList.FindWithHash

    Synopsis:    Find first element with given name and hash value

Declaration:     function  FindWithHash(const  AName:  shortstring;AHash:  LongWord)
                                                     :  Pointer

    Visibility:   public

Description:     FindWithHash searches for the item with key AName.  It uses the provided hash value AHash
                to perform the search.  If the item exists, the data pointer is returned, if not, the result is
                Nil.

    See also:    TFPHashList.HashOfIndex (69 ),  TFPHashList.NameOfIndex (69 ),  TFPHashList.IndexOf
                (71 ), TFPHashList.Find (71 ), TFPHashList.FindIndexOf (71 )



                                                                                 71

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.11.18          TFPHashList.Rename

    Synopsis:    Rename a key

Declaration:     function  Rename(const  AOldName:  shortstring;const  ANewName:  shortstring)
                                           :  Integer

    Visibility:   public

Description:     Rename renames key AOldname to ANewName.  The hash value is recomputed and the item is
                moved in the list to it's new position.

       Errors:   If an item with ANewName already exists, an exception will be raised.
                5.11.19          TFPHashList.Remove

    Synopsis:    Remove first instance of a pointer

Declaration:     function  Remove(Item:  Pointer)  :  Integer

    Visibility:   public

Description:     Remove removes the first occurence of the data pointer Item in the list, if it is present.  The
                return value is the removed data pointer, or Nil if no data pointer was removed.

    See also:    TFPHashList.Delete (70 ), TFPHashList.Clear (69 ), TFPHashList.Extract (70 )
                5.11.20          TFPHashList.Pack

    Synopsis:    Remove nil pointers from the list

Declaration:     procedure  Pack

    Visibility:   public

Description:     Pack removes all Nil items from the list, and frees all unused memory.

    See also:    TFPHashList.Clear (69 )
                5.11.21          TFPHashList.ShowStatistics

    Synopsis:    Return some statistics for the list.

Declaration:     procedure  ShowStatistics

    Visibility:   public

Description:     ShowStatistics prints some information about the hash list to standard output.  It prints
                the following values:


                HashSize       Size of the hash table

                HashMean         Mean hash value

                HashStdDev          Standard deviation of hash values

                ListSize     Size and capacity of the list

                StringSize      Size and capacity of key strings


                                                                                 72

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.11.22          TFPHashList.ForEachCall

    Synopsis:    Call a procedure for each element in the list

Declaration:     procedure  ForEachCall(proc2call:  TListCallback;arg:  pointer)
                procedure  ForEachCall(proc2call:  TListStaticCallback;arg:  pointer)

    Visibility:   public

Description:     ForEachCall loops over the items in the list and calls proc2call, passing it the item and
                arg.
                5.11.23          TFPHashList.Capacity

    Synopsis:    Capacity of the list.

Declaration:     Property  Capacity  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Capacity returns the current capacity of the list.  The capacity is expanded as more elements
                are added to the list.  If a good estimate of the number of elements that will be added to
                the list, the property can be set to a sufficiently large value to avoid reallocation of memory
                each time the list needs to grow.

    See also:    TFPHashList.Count (73 ), TFPHashList.Items (73 )
                5.11.24          TFPHashList.Count

    Synopsis:    Current number of elements in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Count is the current number of elements in the list.

    See also:    TFPHashList.Capacity (73 ), TFPHashList.Items (73 )
                5.11.25          TFPHashList.Items

    Synopsis:    Indexed array with pointers

Declaration:     Property  Items[Index:  Integer]:  Pointer;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items provides indexed access to the pointers, the index runs from 0 to Count-1 (73 ).

       Errors:   Specifying an invalid index will result in an exception.

    See also:    TFPHashList.Capacity (73 ), TFPHashList.Count (73 )

                                                                                 73

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.11.26          TFPHashList.List

    Synopsis:    Low-level hash list

Declaration:     Property  List  :  PHashItemList

    Visibility:   public

      Access:    Read

Description:     List exposes the low-level item list (54 ).  It should not be used directly.

    See also:    TFPHashList.Strs (74 ), THashItemList (54 )
                5.11.27          TFPHashList.Strs

    Synopsis:    Low-level memory area with strings.

Declaration:     Property  Strs  :  PChar

    Visibility:   public

      Access:    Read

Description:     Strs exposes the raw memory area with the strings.

    See also:    TFPHashList.List (74 )
                5.12          TFPHashOb ject



                5.12.1         Description

                TFPHashObject  is  a  TObject  descendent  which  is  aware  of  the  TFPHashObjectList  (77 )
                class.  It has a name property and an owning list:  if the name is changed, it will reposition
                itself in the list which owns it.  It offers methods to change the owning list:  the object will
                correctly remove itself from the list which currently owns it, and insert itself in the new list.
                5.12.2         Method  overview

                __Page______Property_____________________________Description_______________________________________________________*
 *___________
                  75        ChangeOwner                          Change the list owning the object.
                  75        ChangeOwnerAndName                   Simultaneously change the list owning the object and
                                                                 the name of the object.
                  75        Create                               Create a named instance, and insert in a hash list.
                  75        CreateNotOwned                       Create an instance not owned by any list.
                __76________Rename_______________________________Rename_the_object_________________________________________________*
 *___________
                5.12.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  76        Hash            r            Hash value
                __76________Name____________r____________Current_name_of_the_object________________________________________________*
 *___________


                                                                                 74

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.12.4         TFPHashObject.CreateNotOwned

    Synopsis:    Create an instance not owned by any list.

Declaration:     constructor  CreateNotOwned

    Visibility:   public

Description:     CreateNotOwned  creates  an  instance  of  TFPHashObject  which  is  not  owned  by  any  TF-
                PHashObjectList (77 ) hash list.  It also has no name when created in this way.

    See also:    TFPHashObject.Name (76 ), TFPHashObject.ChangeOwner (75 ), TFPHashObject.ChangeOwnerAndName
                (75 )
                5.12.5         TFPHashObject.Create

    Synopsis:    Create a named instance, and insert in a hash list.

Declaration:     constructor  Create(HashObjectList:  TFPHashObjectList;
                                              const  s:  shortstring)

    Visibility:   public

Description:     Create creates an instance of TFPHashObject, gives it the name S and inserts it in the hash
                list HashObjectList (77 ).

    See also:    TFPHashObject.CreateNotOwned (75 ), TFPHashObject.ChangeOwner (75 ), TFPHashOb-
                ject.Name (76 )
                5.12.6         TFPHashObject.ChangeOwner

    Synopsis:    Change the list owning the object.

Declaration:     procedure  ChangeOwner(HashObjectList:  TFPHashObjectList)

    Visibility:   public

Description:     ChangeOwner  can  be  used  to  move  the  object  between  hash  lists:  The  object  will  be  re-
                moved  correctly  from  the  hash  list  that  currently  owns  it,  and  will  be  inserted  in  the  list
                HashObjectList.

       Errors:   If an object with the same name already is present in the new hash list, an exception will
                be raised.

    See also:    TFPHashObject.ChangeOwnerAndName (75 ), TFPHashObject.Name (76 )
                5.12.7         TFPHashObject.ChangeOwnerAndName

    Synopsis:    Simultaneously change the list owning the object and the name of the object.

Declaration:     procedure  ChangeOwnerAndName(HashObjectList:  TFPHashObjectList;
                                                              const  s:  shortstring)

    Visibility:   public

Description:     ChangeOwnerAndName can be used to move the object between hash lists:  The object will
                be removed correctly from the hash list that currently owns it (using the current name), and
                will be inserted in the list HashObjectList with the new name S.

       Errors:   If the new name already is present in the new hash list, an exception will be raised.

    See also:    TFPHashObject.ChangeOwner (75 ), TFPHashObject.Name (76 )



                                                                                 75

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.12.8         TFPHashObject.Rename

    Synopsis:    Rename the object

Declaration:     procedure  Rename(const  ANewName:  shortstring)

    Visibility:   public

Description:     Rename changes the name of the object, and notifies the hash list of this change.

       Errors:   If the new name already is present in the hash list, an exception will be raised.

    See also:    TFPHashObject.ChangeOwner  (75 ),  TFPHashObject.ChangeOwnerAndName  (75 ),  TF-
                PHashObject.Name (76 )
                5.12.9         TFPHashObject.Name

    Synopsis:    Current name of the object

Declaration:     Property  Name  :  shortstring

    Visibility:   public

      Access:    Read

Description:     Name is the name of the object, it is stored in the hash list using this name as the key.

    See also:    TFPHashObject.Rename (76 ), TFPHashObject.ChangeOwnerAndName (75 )
                5.12.10          TFPHashObject.Hash

    Synopsis:    Hash value

Declaration:     Property  Hash  :  LongWord

    Visibility:   public

      Access:    Read

Description:     Hash is the hash value of the object in the hash list that owns it.

    See also:    TFPHashObject.Name (76 )
                                                                                 76

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.13          TFPHashOb jectList



                5.13.1         Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  78        Add                       Add a new key/data pair to the list
                  78        Clear                     Clear the list
                  77        Create                    Create a new instance of the hashlist
                  79        Delete                    Delete an object from the list.
                  77        Destroy                   Removes an instance of the hashlist from the heap
                  79        Expand                    Expand the list
                  79        Extract                   Extract a object instance from the list
                  80        Find                      Find data associated with key
                  80        FindIndexOf               Return index of named object.
                  81        FindInstanceOf            Search an instance of a certain class
                  81        FindWithHash              Find first element with given name and hash value
                  82        ForEachCall               Call a procedure for each object in the list
                  79        HashOfIndex               Return the hash valye of an object by index
                  80        IndexOf                   Return the index of the object instance
                  78        NameOfIndex               Returns the key name of an object by index
                  81        Pack                      Remove nil object instances from the list
                  80        Remove                    Remove first occurrence of a object instance
                  81        Rename                    Rename a key
                __82________ShowStatistics____________Return_some_statistics_for_the_list._________________________________________*
 *___________
                5.13.2         Property  overview

                __Page______Property_______________Access______Description_________________________________________________________*
 *___________
                  82        Capacity               rw          Capacity of the list.
                  82        Count                  rw          Current number of elements in the list.
                  83        Items                  rw          Indexed array with object instances
                  83        List                   r           Low-level hash list
                __83________OwnsObjects____________rw__________Does_the_list_own_the_objects_it_contains___________________________*
 *___________
                5.13.3         TFPHashObjectList.Create

    Synopsis:    Create a new instance of the hashlist

Declaration:     constructor  Create(FreeObjects:  Boolean)

    Visibility:   public

Description:     Create creates a new instance of TFPHashObjectList on the heap and sets the hash capacity
                to 1.

                If  FreeObjects  is  True  (the  default),  then  the  list  owns  the  objects:  when  an  object  is
                removed  from  the  list,  it  is  destroyed  (freed  from  memory).  Clearing  the  list  will  free  all
                objects in the list.

    See also:    TFPHashObjectList.Destroy (77 ), TFPHashObjectList.OwnsObjects (83 )
                5.13.4         TFPHashObjectList.Destroy

    Synopsis:    Removes an instance of the hashlist from the heap

                                                                                 77

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
Declaration:     destructor  Destroy;    Override

    Visibility:  public

Description:     Destroy  cleans  up  the  memory  structures  maintained  by  the  hashlist  and  removes  the
                TFPHashObjectList instance from the heap.  If the list owns its objects, they are freed from
                memory as well.

                Destroy should not be called directly, it's better to use Free or FreeAndNil instead.

    See also:    TFPHashObjectList.Create (77 ), TFPHashObjectList.Clear (78 )
                5.13.5         TFPHashObjectList.Clear

    Synopsis:    Clear the list

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear  removes  all  objects  from  the  list.   It  does  not  free  the  objects  themselves,  unless
                OwnsObjects (83 ) is True.  It always frees all memory needed to contain the objects.

       Errors:   None.

    See also:    TFPHashObjectList.Extract (79 ), TFPHashObjectList.Remove (80 ), TFPHashObjectList.Delete
                (79 ), TFPHashObjectList.Add (78 )
                5.13.6         TFPHashObjectList.Add

    Synopsis:    Add a new key/data pair to the list

Declaration:     function  Add(const  AName:  shortstring;AObject:  TObject)  :  Integer

    Visibility:   public

Description:     Add adds a new object instance (AObject) with key AName to the list.  It returns the position
                of the object in the list.

       Errors:   If not enough memory is available to hold the key and data, an exception may be raised.  If
                an object with this name already exists in the list, an exception is raised.

    See also:    TFPHashObjectList.Extract (79 ), TFPHashObjectList.Remove (80 ), TFPHashObjectList.Delete
                (79 )
                5.13.7         TFPHashObjectList.NameOfIndex

    Synopsis:    Returns the key name of an object by index

Declaration:     function  NameOfIndex(Index:  Integer)  :  ShortString

    Visibility:   public

Description:     NameOfIndex returns the key name of the object at position Index.

       Errors:   If  Index is out of the valid range, an exception is raised.

    See also:    TFPHashObjectList.HashOfIndex (79 ), TFPHashObjectList.Find (80 ), TFPHashObjectList.FindIndexOf
                (80 ), TFPHashObjectList.FindWithHash (81 )



                                                                                 78

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.13.8         TFPHashObjectList.HashOfIndex

    Synopsis:    Return the hash valye of an object by index

Declaration:     function  HashOfIndex(Index:  Integer)  :  LongWord

    Visibility:   public

Description:     HashOfIndex returns the hash value of the object at position Index.

       Errors:   If  Index is out of the valid range, an exception is raised.

    See also:    TFPHashObjectList.HashOfName (77 ), TFPHashObjectList.Find (80 ), TFPHashObjectList.FindIndexOf
                (80 ), TFPHashObjectList.FindWithHash (81 )
                5.13.9         TFPHashObjectList.Delete

    Synopsis:    Delete an object from the list.

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete deletes the object at position Index.  If OwnsObjects (83 ) is True, then the object
                itself is also freed from memory.

    See also:    TFPHashObjectList.Extract (79 ), TFPHashObjectList.Remove (80 ), TFPHashObjectList.Add
                (78 ), TFPHashObjectList.OwnsObjects (83 )
                5.13.10          TFPHashObjectList.Expand

    Synopsis:    Expand the list

Declaration:     function  Expand  :  TFPHashObjectList

    Visibility:   public

Description:     Expand enlarges the capacity of the list if the maximum capacity was reached.  It returns
                itself.

       Errors:   If not enough memory is available, an exception may be raised.

    See also:    TFPHashObjectList.Clear (78 )
                5.13.11          TFPHashObjectList.Extract

    Synopsis:    Extract a object instance from the list

Declaration:     function  Extract(Item:  TObject)  :  TObject

    Visibility:   public

Description:     Extract  removes  the  data  object  from  the  list,  if  it  is  in  the  list.   It  returns  the  object
                instance if it was removed from the list, Nil otherwise.  The object is not freed from memory,
                regardless of the value of OwnsObjects (83 ).

                Extract does a linear search, and is not very efficient.

    See also:    TFPHashObjectList.Delete (79 ), TFPHashObjectList.Remove (80 ), TFPHashObjectList.Clear
                (78 )



                                                                                 79

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.13.12          TFPHashObjectList.Remove

    Synopsis:    Remove first occurrence of a object instance

Declaration:     function  Remove(AObject:  TObject)  :  Integer

    Visibility:   public

Description:     Remove removes the first occurence of the object instance Item in the list, if it is present.
                The return value is the location of the removed object instance, or -1 if no object instance
                was removed.

                If OwnsObjects (83 ) is True, then the object itself is also freed from memory.

    See also:    TFPHashObjectList.Delete (79 ), TFPHashObjectList.Clear (78 ), TFPHashObjectList.Extract
                (79 )
                5.13.13          TFPHashObjectList.IndexOf

    Synopsis:    Return the index of the object instance

Declaration:     function  IndexOf(AObject:  TObject)  :  Integer

    Visibility:   public

Description:     IndexOf returns the index of the first occurrence of object instance AObject.  If the object
                is not in the list, -1 is returned.

                The performed search is linear, and not very efficient.

    See also:    TFPHashObjectList.HashOfIndex (79 ), TFPHashObjectList.NameOfIndex (78 ), TFPHashOb-
                jectList.Find (80 ), TFPHashObjectList.FindIndexOf (80 ), TFPHashObjectList.FindWithHash
                (81 )
                5.13.14          TFPHashObjectList.Find

    Synopsis:    Find data associated with key

Declaration:     function  Find(const  s:  shortstring)  :  TObject

    Visibility:   public

Description:     Find searches (using the hash) for the data object associated with key AName and returns
                the data object instance associated with it.  If the object is not found, Nil is returned.  It
                uses the hash value of the key to perform the search.

    See also:    TFPHashObjectList.HashOfIndex (79 ), TFPHashObjectList.NameOfIndex (78 ), TFPHashOb-
                jectList.IndexOf (80 ), TFPHashObjectList.FindIndexOf (80 ), TFPHashObjectList.FindWithHash
                (81 )
                5.13.15          TFPHashObjectList.FindIndexOf

    Synopsis:    Return index of named object.

Declaration:     function  FindIndexOf(const  s:  shortstring)  :  Integer

    Visibility:   public

Description:     FindIndexOf returns the index of the key AName, or -1 if the key does not exist in the list.
                It uses the hash value to search for the key.



                                                                                 80

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
    See also:    TFPHashObjectList.HashOfIndex (79 ), TFPHashObjectList.NameOfIndex (78 ), TFPHashOb-
                jectList.IndexOf  (80 ),  TFPHashObjectList.Find  (80 ),  TFPHashObjectList.FindWithHash
                (81 )
                5.13.16          TFPHashObjectList.FindWithHash

    Synopsis:    Find first element with given name and hash value

Declaration:     function  FindWithHash(const  AName:  shortstring;AHash:  LongWord)
                                                     :  Pointer

    Visibility:   public

Description:     FindWithHash  searches  for  the  object  with  key  AName.   It  uses  the  provided  hash  value
                AHash  to  perform  the  search.  If  the  object  exists,  the  data  object  instance  is  returned,  if
                not, the result is Nil.

    See also:    TFPHashObjectList.HashOfIndex (79 ), TFPHashObjectList.NameOfIndex (78 ), TFPHashOb-
                jectList.IndexOf (80 ), TFPHashObjectList.Find (80 ), TFPHashObjectList.FindIndexOf (80 )
                5.13.17          TFPHashObjectList.Rename

    Synopsis:    Rename a key

Declaration:     function  Rename(const  AOldName:  shortstring;const  ANewName:  shortstring)
                                           :  Integer

    Visibility:   public

Description:     Rename renames key AOldname to ANewName.  The hash value is recomputed and the object
                is moved in the list to it's new position.

       Errors:   If an object with ANewName already exists, an exception will be raised.
                5.13.18          TFPHashObjectList.FindInstanceOf

    Synopsis:    Search an instance of a certain class

Declaration:     function  FindInstanceOf(AClass:  TClass;AExact:  Boolean;
                                                      AStartAt:  Integer)  :  Integer

    Visibility:   public

Description:     FindInstanceOf searches the list for an instance of class AClass.  It starts searching at po-
                sition AStartAt.  If AExact is True, only instances of class AClass are considered.  If AExact
                is False, then descendent classes of  AClass are also taken into account when searching.  If
                no instance is found, Nil is returned.
                5.13.19          TFPHashObjectList.Pack

    Synopsis:    Remove nil object instances from the list

Declaration:     procedure  Pack

    Visibility:   public

Description:     Pack removes all Nil objects from the list, and frees all unused memory.

    See also:    TFPHashObjectList.Clear (78 )



                                                                                 81

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.13.20          TFPHashObjectList.ShowStatistics

    Synopsis:    Return some statistics for the list.

Declaration:     procedure  ShowStatistics

    Visibility:   public

Description:     ShowStatistics prints some information about the hash list to standard output.  It prints
                the following values:

                HashSize       Size of the hash table

                HashMean         Mean hash value

                HashStdDev          Standard deviation of hash values

                ListSize     Size and capacity of the list

                StringSize      Size and capacity of key strings
                5.13.21          TFPHashObjectList.ForEachCall

    Synopsis:    Call a procedure for each object in the list

Declaration:     procedure  ForEachCall(proc2call:  TObjectListCallback;arg:  pointer)
                procedure  ForEachCall(proc2call:  TObjectListStaticCallback;arg:  pointer)

    Visibility:   public

Description:     ForEachCall loops over the objects in the list and calls proc2call, passing it the object
                and arg.
                5.13.22          TFPHashObjectList.Capacity

    Synopsis:    Capacity of the list.

Declaration:     Property  Capacity  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Capacity returns the current capacity of the list.  The capacity is expanded as more elements
                are added to the list.  If a good estimate of the number of elements that will be added to
                the list, the property can be set to a sufficiently large value to avoid reallocation of memory
                each time the list needs to grow.

    See also:    TFPHashObjectList.Count (82 ), TFPHashObjectList.Items (83 )
                5.13.23          TFPHashObjectList.Count

    Synopsis:    Current number of elements in the list.

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     Count is the current number of elements in the list.

    See also:    TFPHashObjectList.Capacity (82 ), TFPHashObjectList.Items (83 )



                                                                                 82

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.13.24          TFPHashObjectList.OwnsObjects

    Synopsis:    Does the list own the objects it contains

Declaration:     Property  OwnsObjects  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     OwnsObjects determines what to do when an object is removed from the list:  if it is True
                (the default), then the list owns the objects:  when an object is removed from the list, it is
                destroyed (freed from memory).  Clearing the list will free all objects in the list.

                The value of OwnsObjects is set when the hash list is created, and cannot be changed during
                the lifetime of the hash list.

    See also:    TFPHashObjectList.Create (77 )
                5.13.25          TFPHashObjectList.Items

    Synopsis:    Indexed array with object instances

Declaration:     Property  Items[Index:  Integer]:  TObject;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items  provides  indexed  access  to  the  object  instances,  the  index  runs  from  0  to  Count-1
                (82 ).

       Errors:   Specifying an invalid index will result in an exception.

    See also:    TFPHashObjectList.Capacity (82 ), TFPHashObjectList.Count (82 )
                5.13.26          TFPHashObjectList.List

    Synopsis:    Low-level hash list

Declaration:     Property  List  :  TFPHashList

    Visibility:   public

      Access:    Read

Description:     List exposes the low-level hash list (67 ).  It should not be used directly.

    See also:    TFPHashList (67 )
                5.14          TFPOb jectHashTable



                5.14.1         Description

                TFPStringHashTable  is  a  TFPCustomHashTable  (61 )  descendent  which  stores  object  in-
                stances together with the keys.  In case the data associated with the keys are strings them-
                selves, it's better to use TFPStringHashTable (93 ), or for arbitrary pointer data, TFPData-
                HashTable (66 ) is more suitable.  The objects are exposed with their keys through the Items
                (85 ) property.



                                                                                 83

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.14.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  84        Add                 Add a new object to the hash table
                  84        Create              Create a new instance of  TFPObjectHashTable
                __84________CreateWith__________Create_a_new_hash_table_with_given_size_and_hash_function__________________________*
 *___________
                5.14.3         Property  overview

                __Page______Property_______________Access______Description_________________________________________________________*
 *___________
                  85        Items                  rw          Key-based access to the objects
                __85________OwnsObjects____________rw__________Does_the_hash_table_own_the_objects_?_______________________________*
 *___________
                5.14.4         TFPObjectHashTable.Create

    Synopsis:    Create a new instance of  TFPObjectHashTable

Declaration:     constructor  Create(AOwnsObjects:  Boolean)

    Visibility:   public

Description:     Create creates a new instance of  TFPObjectHashTable on the heap.  It sets the OwnsOb-
                jects (85 ) property to AOwnsObjects, and then calls the inherited Create.  If AOwnsObjects
                is set to True, then the hash table owns the objects:  whenever an object is removed from
                the list, it is automatically freed.

       Errors:   If not enough memory is available on the heap, an exception may be raised.

    See also:    TFPObjectHashTable.OwnsObjects (85 ), TFPObjectHashTable.CreateWith (84 ), TFPOb-
                jectHashTable.Items (85 )
                5.14.5         TFPObjectHashTable.CreateWith

    Synopsis:    Create a new hash table with given size and hash function

Declaration:     constructor  CreateWith(AHashTableSize:  LongWord;
                                                     aHashFunc:  THashFunction;AOwnsObjects:  Boolean)

    Visibility:   public

Description:     CreateWith sets the OwnsObjects (85 ) property to AOwnsObjects, and then calls the in-
                herited CreateWith.  If  AOwnsObjects is set to True, then the hash table owns the objects:
                whenever an object is removed from the list, it is automatically freed.

                This constructor should be used when a table size and hash algorithm should be specified
                that differ from the default table size and hash algorithm.

       Errors:   If not enough memory is available on the heap, an exception may be raised.

    See also:    TFPObjectHashTable.OwnsObjects  (85 ),  TFPObjectHashTable.Create  (84 ),  TFPObjec-
                tHashTable.Items (85 )
                5.14.6         TFPObjectHashTable.Add

    Synopsis:    Add a new object to the hash table

Declaration:     procedure  Add(const  aKey:  String;AItem:  TObject);    Virtual



                                                                                 84

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
    Visibility:  public

Description:     Add adds the object AItem to the hash table, and associates it with key aKey.

       Errors:   If the key aKey is already in the hash table, an exception will be raised.

    See also:    TFPObjectHashTable.Items (85 )
                5.14.7         TFPObjectHashTable.Items

    Synopsis:    Key-based access to the objects

Declaration:     Property  Items[index:  String]:  TObject;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items provides access to the objects in the hash table using their key:  the array index Index
                is the key.  A key which is not present will result in an Nil instance.

    See also:    TFPObjectHashTable.Add (84 )
                5.14.8         TFPObjectHashTable.OwnsObjects

    Synopsis:    Does the hash table own the objects ?

Declaration:     Property  OwnsObjects  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     OwnsObjects determines what happens with objects which are removed from the hash table:
                if True, then removing an object from the hash list will free the object.  If False, the object
                is not freed.  Note that way in which the object is removed is not relevant:  be it Delete,
                Remove or Clear.

    See also:    TFPObjectHashTable.Create (84 ), TFPObjectHashTable.Items (85 )
                5.15          TFPOb jectList



                5.15.1         Description

                TFPObjectList is a TFPList (??  ) based list which has as the default array property TObjects
                (??  ) instead of pointers.  By default it also manages the objects:  when an object is deleted
                or removed from the list, it is automatically freed.  This behaviour can be disabled when the
                list is created.

                In difference with TObjectList (97 ), TFPObjectList offers no notification mechanism of list
                operations, allowing it to be faster than TObjectList.  For the same reason, it is also not a
                descendent of  TFPList (although it uses one internally).
                                                                                 85

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.15.2         Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  87        Add                       Add an object to the list.
                  90        Assign                    Copy the contents of a list.
                  87        Clear                     Clear all elements in the list.
                  86        Create                    Create a new object list
                  87        Delete                    Delete an element from the list.
                  86        Destroy                   Clears the list and destroys the list instance
                  88        Exchange                  Exchange the location of two objects
                  88        Expand                    Expand the capacity of the list.
                  88        Extract                   Extract an object from the list
                  89        FindInstanceOf            Search for an instance of a certain class
                  90        First                     Return the first non-nil object in the list
                  91        ForEachCall               For each object in the list, call a method or procedure, passing
                                                      it the object.
                  89        IndexOf                   Search for an object in the list
                  89        Insert                    Insert a new object in the list
                  90        Last                      Return the last non-nil object in the list.
                  90        Move                      Move an object to another location in the list.
                  91        Pack                      Remove all Nil references from the list
                  88        Remove                    Remove an item from the list.
                __91________Sort______________________Sort_the_list_of_objects_____________________________________________________*
 *___________
                5.15.3         Property  overview

                __Page______Property_______________Access______Description_________________________________________________________*
 *___________
                  92        Capacity               rw          Capacity of the list
                  92        Count                  rw          Number of elements in the list.
                  92        Items                  rw          Indexed access to the elements of the list.
                  93        List                   r           Internal list used to keep the objects.
                __92________OwnsObjects____________rw__________Should_the_list_free_elements_when_they_are_removed.________________*
 *___________
                5.15.4         TFPObjectList.Create

    Synopsis:    Create a new object list

Declaration:     constructor  Create
                constructor  Create(FreeObjects:  Boolean)

    Visibility:   public

Description:     Create  instantiates  a  new  object  list.   The  FreeObjects  parameter  determines  whether
                objects that are removed from the list should also be freed from memory.  By default this is
                True.  This behaviour can be changed after the list was instantiated.

       Errors:   None.

    See also:    TFPObjectList.Destroy (86 ), TFPObjectList.OwnsObjects (92 ), TObjectList (97 )
                5.15.5         TFPObjectList.Destroy

    Synopsis:    Clears the list and destroys the list instance

Declaration:     destructor  Destroy;    Override
                                                                                 86

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
    Visibility:  public

Description:     Destroy clears the list, freeing all objects in the list if OwnsObjects (92 ) is True.

    See also:    TFPObjectList.OwnsObjects (92 ), TObjectList.Create (97 )
                5.15.6         TFPObjectList.Clear

    Synopsis:    Clear all elements in the list.

Declaration:     procedure  Clear

    Visibility:   public

Description:     Removes all objects from the list, freeing all objects in the list if OwnsObjects (92 ) is True.

    See also:    TObjectList.Destroy (97 )
                5.15.7         TFPObjectList.Add

    Synopsis:    Add an object to the list.

Declaration:     function  Add(AObject:  TObject)  :  Integer

    Visibility:   public

Description:     Add adds AObject to the list and returns the index of the object in the list.

                Note that when OwnsObjects (92 ) is True, an object should not be added twice to the list:
                this will result in memory corruption when the object is freed (as it will be freed twice).  The
                Add method does not check this, however.

       Errors:   None.

    See also:    TFPObjectList.OwnsObjects (92 ), TFPObjectList.Delete (87 )
                5.15.8         TFPObjectList.Delete

    Synopsis:    Delete an element from the list.

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete removes the object at index Index from the list.  When OwnsObjects (92 ) is True,
                the object is also freed.

       Errors:   An access violation may occur when OwnsObjects (92 ) is True and either the object was
                freed externally, or when the same object is in the same list twice.

    See also:    TTFPObjectList.Remove (52 ), TFPObjectList.Extract (88 ), TFPObjectList.OwnsObjects
                (92 ), TTFPObjectList.Add (52 ), TTFPObjectList.Clear (52 )


                                                                                 87

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.15.9         TFPObjectList.Exchange

    Synopsis:    Exchange the location of two objects

Declaration:     procedure  Exchange(Index1:  Integer;Index2:  Integer)

    Visibility:   public

Description:     Exchange exchanges the objects at indexes Index1 and Index2 in a direct operation (i.e.
                no delete/add is performed).

       Errors:   If either Index1 or Index2 is invalid, an exception will be raised.

    See also:    TTFPObjectList.Add (52 ), TTFPObjectList.Delete (52 )
                5.15.10          TFPObjectList.Expand

    Synopsis:    Expand the capacity of the list.

Declaration:     function  Expand  :  TFPObjectList

    Visibility:   public

Description:     Expand increases the capacity of the list.  It calls #rtl.classes.tfplist.expand (??  ) and then
                returns a reference to itself.

       Errors:   If there is not enough memory to expand the list, an exception will be raised.

    See also:    TFPObjectList.Pack (91 ), TFPObjectList.Clear (87 ), #rtl.classes.tfplist.expand (??  )
                5.15.11          TFPObjectList.Extract

    Synopsis:    Extract an object from the list

Declaration:     function  Extract(Item:  TObject)  :  TObject

    Visibility:   public

Description:     Extract  removes  Item  from  the  list,  if  it  is  present  in  the  list.  It  returns  Item  if  it  was
                found, Nil if item was not present in the list.

                Note that the object is not freed, and that only the first found object is removed from the
                list.

       Errors:   None.

    See also:    TFPObjectList.Pack  (91 ),  TFPObjectList.Clear  (87 ),  TFPObjectList.Remove  (88 ),  TF-
                PObjectList.Delete (87 )
                5.15.12          TFPObjectList.Remove

    Synopsis:    Remove an item from the list.

Declaration:     function  Remove(AObject:  TObject)  :  Integer

    Visibility:   public

Description:     Remove removes Item from the list, if it is present in the list.  It frees Item if OwnsObjects
                (92 ) is True, and returns the index of the object that was found in the list, or -1 if the object
                was not found.

                Note that only the first found object is removed from the list.



                                                                                 88

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
       Errors:   None.

    See also:    TFPObjectList.Pack (91 ), TFPObjectList.Clear (87 ), TFPObjectList.Delete (87 ), TFPOb-
                jectList.Extract (88 )
                5.15.13          TFPObjectList.IndexOf

    Synopsis:    Search for an object in the list

Declaration:     function  IndexOf(AObject:  TObject)  :  Integer

    Visibility:   public

Description:     IndexOf searches for the presence of  AObject in the list, and returns the location (index)
                in the list.  The index is 0-based, and -1 is returned if  AObject was not found in the list.

       Errors:   None.

    See also:    TFPObjectList.Items (92 ), TFPObjectList.Remove (88 ), TFPObjectList.Extract (88 )
                5.15.14          TFPObjectList.FindInstanceOf

    Synopsis:    Search for an instance of a certain class

Declaration:     function  FindInstanceOf(AClass:  TClass;AExact:  Boolean;
                                                      AStartAt:  Integer)  :  Integer

    Visibility:   public

Description:     FindInstanceOf will look through the instances in the list and will return the first instance
                which is a descendent of class AClass if AExact is False.  If AExact is true, then the instance
                should be of class AClass.

                If no instance of the requested class is found, Nil is returned.

       Errors:   None.

    See also:    TFPObjectList.IndexOf (89 )
                5.15.15          TFPObjectList.Insert

    Synopsis:    Insert a new object in the list

Declaration:     procedure  Insert(Index:  Integer;AObject:  TObject)

    Visibility:   public

Description:     Insert  inserts  AObject  at  position  Index  in  the  list.   All  elements  in  the  list  after  this
                position are shifted.  The index is zero based, i.e.  an insert at position 0 will insert an object
                at the first position of the list.

       Errors:   None.

    See also:    TFPObjectList.Add (87 ), TFPObjectList.Delete (87 )



                                                                                 89

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.15.16          TFPObjectList.First

    Synopsis:    Return the first non-nil object in the list

Declaration:     function  First  :  TObject

    Visibility:   public

Description:     First returns a reference to the first non-Nil element in the list.  If no non-Nil element is
                found, Nil is returned.

       Errors:   None.

    See also:    TFPObjectList.Last (90 ), TFPObjectList.Pack (91 )
                5.15.17          TFPObjectList.Last

    Synopsis:    Return the last non-nil object in the list.

Declaration:     function  Last  :  TObject

    Visibility:   public

Description:     Last returns a reference to the last non-Nil element in the list.  If no non-Nil element is
                found, Nil is returned.

       Errors:   None.

    See also:    TFPObjectList.First (90 ), TFPObjectList.Pack (91 )
                5.15.18          TFPObjectList.Move

    Synopsis:    Move an object to another location in the list.

Declaration:     procedure  Move(CurIndex:  Integer;NewIndex:  Integer)

    Visibility:   public

Description:     Move moves the object at current location CurIndex to location NewIndex.  Note that the
                NewIndex is determined after the object was removed from location CurIndex, and can hence
                be shifted with 1 position if  CurIndex is less than NewIndex.

                Contrary  to  exchange  (88 ),  the  move  operation  is  done  by  extracting  the  object  from  it's
                current location and inserting it at the new location.

       Errors:   If either CurIndex or NewIndex is out of range, an exception may occur.

    See also:    TFPObjectList.Exchange (88 ), TFPObjectList.Delete (87 ), TFPObjectList.Insert (89 )
                5.15.19          TFPObjectList.Assign

    Synopsis:    Copy the contents of a list.

Declaration:     procedure  Assign(Obj:  TFPObjectList)

    Visibility:   public

Description:     Assign copies the contents of  Obj if  Obj is of type TFPObjectList

       Errors:   None.



                                                                                 90

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.15.20          TFPObjectList.Pack

    Synopsis:    Remove all Nil references from the list

Declaration:     procedure  Pack

    Visibility:   public

Description:     Pack removes all Nil elements from the list.

       Errors:   None.

    See also:    TFPObjectList.First (90 ), TFPObjectList.Last (90 )
                5.15.21          TFPObjectList.Sort

    Synopsis:    Sort the list of objects

Declaration:     procedure  Sort(Compare:  TListSortCompare)

    Visibility:   public

Description:     Sort will perform a quick-sort on the list, using Compare as the compare algorithm.  This
                function should accept 2 pointers and should return the following result:


                less than 0      If the first pointer comes before the second.

                equal to 0      If the pointers have the same value.

                larger than 0        If the first pointer comes after the second.


                The function should be able to deal with Nil values.

       Errors:   None.

    See also:    #rtl.classes.TList.Sort (??  )
                5.15.22          TFPObjectList.ForEachCall

    Synopsis:    For each object in the list, call a method or procedure, passing it the object.

Declaration:     procedure  ForEachCall(proc2call:  TObjectListCallback;arg:  pointer)
                procedure  ForEachCall(proc2call:  TObjectListStaticCallback;arg:  pointer)

    Visibility:   public

Description:     ForEachCall  loops  through  all  objects  in  the  list,  and  calls  proc2call,  passing  it  the
                object  in  the  list.  Additionally,  arg  is  also  passed  to  the  procedure.  Proc2call  can  be  a
                plain procedure or can be a method of a class.

       Errors:   None.

    See also:    TObjectListStaticCallback (54 ), TObjectListCallback (54 )
                                                                                 91

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.15.23          TFPObjectList.Capacity

    Synopsis:    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  before  it  needs  to  expand
                itself, i.e., reserve more memory for pointers.  It is always equal or larger than Count (92 ).

    See also:    TFPObjectList.Count (92 )
                5.15.24          TFPObjectList.Count

    Synopsis:    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.  Note that this includes Nil elements.

    See also:    TFPObjectList.Capacity (92 )
                5.15.25          TFPObjectList.OwnsObjects

    Synopsis:    Should the list free elements when they are removed.

Declaration:     Property  OwnsObjects  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     OwnsObjects  determines  whether  the  objects  in  the  list  should  be  freed  when  they  are
                removed (not extracted) from the list,  or when the list is cleared.  If the property is True
                then they are freed.  If the property is False the elements are not freed.

                The value is usually set in the constructor, and is seldom changed during the lifetime of the
                list.  It defaults to True.

    See also:    TFPObjectList.Create (86 ), TFPObjectList.Delete (87 ), TFPObjectList.Remove (88 ), TF-
                PObjectList.Clear (87 )
                5.15.26          TFPObjectList.Items

    Synopsis:    Indexed access to the elements of the list.

Declaration:     Property  Items[Index:  Integer]:  TObject;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items is the default property of the list.  It provides indexed access to the elements in the
                list.  The index Index is zero based, i.e., runs from 0 (zero) to Count-1.

    See also:    TFPObjectList.Count (92 )



                                                                                 92

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.15.27          TFPObjectList.List

    Synopsis:    Internal list used to keep the objects.

Declaration:     Property  List  :  TFPList

    Visibility:   public

      Access:    Read

Description:     List is a reference to the TFPList (??  ) instance used to manage the elements in the list.

    See also:    #rtl.classes.tfplist (??  )
                5.16          TFPStringHashTable



                5.16.1         Description

                TFPStringHashTable is a TFPCustomHashTable (61 ) descendent which stores simple strings
                together with the keys.  In case the data associated with the keys are objects, it's better to
                use  TFPObjectHashTable  (83 ),  or  for  arbitrary  pointer  data,  TFPDataHashTable  (66 )  is
                more suitable.  The strings are exposed with their keys through the Items (93 ) property.
                5.16.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __93________Add_____________Add_a_new_string_to_the_hash_list______________________________________________________*
 *___________
                5.16.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __93________Items___________rw___________Key_based_access_to_the_strings_in_the_hash_table_________________________*
 *___________
                5.16.4         TFPStringHashTable.Add

    Synopsis:    Add a new string to the hash list

Declaration:     procedure  Add(const  aKey:  String;const  aItem:  String);    Virtual

    Visibility:   public

Description:     Add adds a new string AItem to the hash list with key AKey.

       Errors:   If a string with key Akey already exists in the hash table, an exception will be raised.

    See also:    TFPStringHashTable.Items (93 )
                5.16.5         TFPStringHashTable.Items

    Synopsis:    Key based access to the strings in the hash table

Declaration:     Property  Items[index:  String]:  String;  default

    Visibility:   public

      Access:    Read,Write
                                                                                 93

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
Description:     Items provides access to the strings in the hash table using their key:  the array index Index
                is the key.  A key which is not present will result in an empty string.

    See also:    TFPStringHashTable.Add (93 )
                5.17          THTCustomNode



                5.17.1         Description

                THTCustomNode is used by the TFPCustomHashTable (61 ) class to store the keys and asso-
                ciated values.
                5.17.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  94        CreateWith          Create a new instance of  THTCustomNode
                __94________HasKey______________Check_whether_this_node_matches_the_given_key._____________________________________*
 *___________
                5.17.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __95________Key_____________r____________Key_value_associated_with_this_hash_item._________________________________*
 *___________
                5.17.4         THTCustomNode.CreateWith

    Synopsis:    Create a new instance of  THTCustomNode

Declaration:     constructor  CreateWith(const  AString:  String)

    Visibility:   public

Description:     CreateWith creates a new instance of THTCustomNode and stores the string AString in it.  It
                should never be necessary to call this method directly, it will be called by the TFPHashTable
                (52 ) class when needed.

       Errors:   If no more memory is available, an exception may be raised.

    See also:    TFPHashTable (52 )
                5.17.5         THTCustomNode.HasKey

    Synopsis:    Check whether this node matches the given key.

Declaration:     function  HasKey(const  AKey:  String)  :  Boolean

    Visibility:   public

Description:     HasKey  checks  whether  this  node  matches  the  given  key  AKey,  by  comparing  it  with  the
                stored key.  It returns True if it does, False if not.

       Errors:   None.

    See also:    THTCustomNode.Key (95 )



                                                                                 94

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.17.6         THTCustomNode.Key

    Synopsis:    Key value associated with this hash item.

Declaration:     Property  Key  :  String

    Visibility:   public

      Access:    Read

Description:     Key is the key value associated with this hash item.  It is stored when the item is created,
                and is read-only.

    See also:    THTCustomNode.CreateWith (94 )
                5.18          THTDataNode



                5.18.1         Description

                THTDataNode is used by TDataHashTable (52 ) to store the hash items in.  It simply holds
                the data pointer.

                It should not be necessary to use THTDataNode directly, it's only for inner use by TFPDataHashTable
                5.18.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __95________Data____________rw___________Data_pointer______________________________________________________________*
 *___________
                5.18.3         THTDataNode.Data

    Synopsis:    Data pointer

Declaration:     Property  Data  :  pointer

    Visibility:   public

      Access:    Read,Write

Description:     Pointer containing the user data associated with the hash value.
                5.19          THTOb jectNode



                5.19.1         Description

                THTObjectNode is a THTCustomNode (94 ) descendent which holds the data in the TFPOb-
                jectHashTable (83 ) hash table.  It exposes a data string.

                It should not be necessary to use THTObjectNode directly, it's only for inner use by TFPObjectHashTable
                5.19.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __96________Data____________rw___________Object_instance___________________________________________________________*
 *___________


                                                                                 95

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.19.3         THTObjectNode.Data

    Synopsis:    Object instance

Declaration:     Property  Data  :  TObject

    Visibility:   public

      Access:    Read,Write

Description:     Data  is  the  object  instance  associated  with  the  key  value.   It  is  exposed  in  TFPObjec-
                tHashTable.Items (85 )

    See also:    TFPObjectHashTable (83 ), TFPObjectHashTable.Items (85 ), THTOwnedObjectNode (96 )
                5.20          THTOwnedOb jectNode



                5.20.1         Description

                THTOwnedObjectNode is used instead of THTObjectNode (95 ) in case TFPObjectHashTable
                (83 )  owns  it's  objects.   When  this  object  is  destroyed,  the  associated  data  object  is  also
                destroyed.
                5.20.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __96________Destroy_________Destroys_the_node_and_the_object.______________________________________________________*
 *___________
                5.20.3         THTOwnedObjectNode.Destroy

    Synopsis:    Destroys the node and the object.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy first frees the data object, and then only frees itself.

    See also:    THTOwnedObjectNode (96 ), TFPObjectHashTable.OwnsObjects (85 )
                5.21          THTStringNode



                5.21.1         Description

                THTStringNode  is  a  THTCustomNode  (94 )  descendent  which  holds  the  data  in  the  TFP-
                StringHashTable (93 ) hash table.  It exposes a data string.

                It should not be necessary to use THTStringNode directly, it's only for inner use by TFPStringHashTable
                5.21.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __97________Data____________rw___________String_data_______________________________________________________________*
 *___________



                                                                                 96

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.21.3         THTStringNode.Data

    Synopsis:    String data

Declaration:     Property  Data  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Data is the data of this has node.  The data is a string, associated with the key.  It is also
                exposed in TFPStringHashTable.Items (93 )

    See also:    TFPStringHashTable (93 )
                5.22          TOb jectList



                5.22.1         Description

                TObjectList is a TList (??  ) descendent which has as the default array property TObjects
                (??  ) instead of pointers.  By default it also manages the objects:  when an object is deleted
                or removed from the list, it is automatically freed.  This behaviour can be disabled when the
                list is created.

                In difference with TFPObjectList (85 ), TObjectList offers a notification mechanism of list
                change  operations:  insert,  delete.  This  slows  down  bulk  operations,  so  if  the  notifications
                are not needed, TObjectList may be more appropriate.
                5.22.2         Method  overview

                __Page______Property__________________Description__________________________________________________________________*
 *___________
                  98        Add                       Add an object to the list.
                  97        create                    Create a new object list.
                  98        Extract                   Extract an object from the list.
                  99        FindInstanceOf            Search for an instance of a certain class
                  99        First                     Return the first non-nil object in the list
                  99        IndexOf                   Search for an object in the list
                  99        Insert                    Insert an object in the list.
                  100       Last                      Return the last non-nil object in the list.
                __98________Remove____________________Remove_(and_possibly_free)_an_element_from_the_list._________________________*
 *___________
                5.22.3         Property  overview

                __Page______Property_______________Access______Description_________________________________________________________*
 *___________
                  100       Items                  rw          Indexed access to the elements of the list.
                __100_______OwnsObjects____________rw__________Should_the_list_free_elements_when_they_are_removed.________________*
 *___________
                5.22.4         TObjectList.create

    Synopsis:    Create a new object list.

Declaration:     constructor  create
                constructor  create(freeobjects:  Boolean)

    Visibility:   public
                                                                                 97

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
Description:     Create  instantiates  a  new  object  list.   The  FreeObjects  parameter  determines  whether
                objects that are removed from the list should also be freed from memory.  By default this is
                True.  This behaviour can be changed after the list was instantiated.

       Errors:   None.

    See also:    TObjectList.Destroy (97 ), TObjectList.OwnsObjects (100  ), TFPObjectList (85 )
                5.22.5         TObjectList.Add

    Synopsis:    Add an object to the list.

Declaration:     function  Add(AObject:  TObject)  :  Integer

    Visibility:   public

Description:     Add overrides the TList (??  ) implementation to accept objects (AObject) instead of pointers.

                The function returns the index of the position where the object was added.

       Errors:   If  the  list  must  be  expanded,  and  not  enough  memory  is  available,  an  exception  may  be
                raised.

    See also:    TObjectList.Insert  (99 ),  #rtl.classes.TList.Delete  (??  ),  TObjectList.Extract  (98 ),  TOb-
                jectList.Remove (98 )
                5.22.6         TObjectList.Extract

    Synopsis:    Extract an object from the list.

Declaration:     function  Extract(Item:  TObject)  :  TObject

    Visibility:   public

Description:     Extract removes the object Item from the list if it is present in the list.  Contrary to Remove
                (98 ), Extract does not free the extracted element if OwnsObjects (100  ) is True

                The function returns a reference to the item which was removed from the list, or Nil if no
                element was removed.

       Errors:   None.

    See also:    TObjectList.Remove (98 )
                5.22.7         TObjectList.Remove

    Synopsis:    Remove (and possibly free) an element from the list.

Declaration:     function  Remove(AObject:  TObject)  :  Integer

    Visibility:   public

Description:     Remove removes Item from the list, if it is present in the list.  It frees Item if OwnsObjects
                (100  )  is  True,  and  returns  the  index  of  the  object  that  was  found  in  the  list,  or  -1  if  the
                object was not found.

                Note that only the first found object is removed from the list.

       Errors:   None.

    See also:    TObjectList.Extract (98 )



                                                                                 98

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.22.8         TObjectList.IndexOf

    Synopsis:    Search for an object in the list

Declaration:     function  IndexOf(AObject:  TObject)  :  Integer

    Visibility:   public

Description:     IndexOf overrides the TList (??  ) implementation to accept an object instance instead of a
                pointer.

                The function returns the index of the first match for AObject in the list, or -1 if no match
                was found.

       Errors:   None.

    See also:    TObjectList.FindInstanceOf (99 )
                5.22.9         TObjectList.FindInstanceOf

    Synopsis:    Search for an instance of a certain class

Declaration:     function  FindInstanceOf(AClass:  TClass;AExact:  Boolean;
                                                      AStartAt:  Integer)  :  Integer

    Visibility:   public

Description:     FindInstanceOf will look through the instances in the list and will return the first instance
                which is a descendent of class AClass if AExact is False.  If AExact is true, then the instance
                should be of class AClass.

                If no instance of the requested class is found, Nil is returned.

       Errors:   None.

    See also:    TObjectList.IndexOf (99 )
                5.22.10          TObjectList.Insert

    Synopsis:    Insert an object in the list.

Declaration:     procedure  Insert(Index:  Integer;AObject:  TObject)

    Visibility:   public

Description:     Insert inserts AObject in the list at position Index.  The index is zero-based.  This method
                overrides the implementation in TList (??  ) to accept objects instead of pointers.

       Errors:   If an invalid Index is specified, an exception is raised.

    See also:    TObjectList.Add (98 ), TObjectList.Remove (98 )
                5.22.11          TObjectList.First

    Synopsis:    Return the first non-nil object in the list

Declaration:     function  First  :  TObject

    Visibility:   public

                                                                                 99

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
Description:     First returns a reference to the first non-Nil element in the list.  If no non-Nil element is
                found, Nil is returned.

       Errors:   None.

    See also:    TObjectList.Last (100  ), TObjectList.Pack (97 )
                5.22.12          TObjectList.Last

    Synopsis:    Return the last non-nil object in the list.

Declaration:     function  Last  :  TObject

    Visibility:   public

Description:     Last returns a reference to the last non-Nil element in the list.  If no non-Nil element is
                found, Nil is returned.

       Errors:   None.

    See also:    TObjectList.First (99 ), TObjectList.Pack (97 )
                5.22.13          TObjectList.OwnsObjects

    Synopsis:    Should the list free elements when they are removed.

Declaration:     Property  OwnsObjects  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     OwnsObjects  determines  whether  the  objects  in  the  list  should  be  freed  when  they  are
                removed (not extracted) from the list,  or when the list is cleared.  If the property is True
                then they are freed.  If the property is False the elements are not freed.

                The value is usually set in the constructor, and is seldom changed during the lifetime of the
                list.  It defaults to True.

    See also:    TObjectList.Create (97 ), TObjectList.Delete (97 ), TObjectList.Remove (98 ), TObjectList.Clear
                (97 )
                5.22.14          TObjectList.Items

    Synopsis:    Indexed access to the elements of the list.

Declaration:     Property  Items[Index:  Integer]:  TObject;  default

    Visibility:   public

      Access:    Read,Write

Description:     Items is the default property of the list.  It provides indexed access to the elements in the
                list.  The index Index is zero based, i.e., runs from 0 (zero) to Count-1.

    See also:    #rtl.classes.TList.Count (??  )
                                                                                 100

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.23          TOb jectQueue



                5.23.1         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  101       Peek            Look at the first object in the queue.
                  101       Pop             Pop the first element off the queue
                __101_______Push____________Push_an_object_on_the_queue____________________________________________________________*
 *___________
                5.23.2         TObjectQueue.Push

    Synopsis:    Push an object on the queue

Declaration:     function  Push(AObject:  TObject)  :  TObject

    Visibility:   public

Description:     Push pushes another object on the queue.  It overrides the Push method as implemented in
                TQueue so it accepts only objects as arguments.

       Errors:   If not enough memory is available to expand the queue, an exception may be raised.

    See also:    TObjectQueue.Pop (101  ), TObjectQueue.Peek (101  )
                5.23.3         TObjectQueue.Pop

    Synopsis:    Pop the first element off the queue

Declaration:     function  Pop  :  TObject

    Visibility:   public

Description:     Pop removes the first element in the queue, and returns a reference to the instance.  If the
                queue is empty, Nil is returned.

       Errors:   None.

    See also:    TObjectQueue.Push (101  ), TObjectQueue.Peek (101  )
                5.23.4         TObjectQueue.Peek

    Synopsis:    Look at the first object in the queue.

Declaration:     function  Peek  :  TObject

    Visibility:   public

Description:     Peek returns the first object in the queue, without removing it from the queue.  If there are
                no more objects in the queue, Nil is returned.

       Errors:   None

    See also:    TObjectQueue.Push (101  ), TObjectQueue.Pop (101  )
                                                                                 101

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.24          TOb jectStack



                5.24.1         Description

                TObjectStack is a stack implementation which manages pointers only.

                TObjectStack  introduces  no  new  behaviour,  it  simply  overrides  some  methods  to  accept
                and/or return TObject instances instead of pointers.
                5.24.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  102       Peek            Look at the top object in the stack.
                  102       Pop             Pop the top object of the stack.
                __102_______Push____________Push_an_object_on_the_stack.___________________________________________________________*
 *___________
                5.24.3         TObjectStack.Push

    Synopsis:    Push an object on the stack.

Declaration:     function  Push(AObject:  TObject)  :  TObject

    Visibility:   public

Description:     Push pushes another object on the stack.  It overrides the Push method as implemented in
                TStack so it accepts only objects as arguments.

       Errors:   If not enough memory is available to expand the stack, an exception may be raised.

    See also:    TObjectStack.Pop (102  ), TObjectStack.Peek (102  )
                5.24.4         TObjectStack.Pop

    Synopsis:    Pop the top object of the stack.

Declaration:     function  Pop  :  TObject

    Visibility:   public

Description:     Pop pops the top object of the stack, and returns the object instance.  If there are no more
                objects on the stack, Nil is returned.

       Errors:   None

    See also:    TObjectStack.Push (102  ), TObjectStack.Peek (102  )
                5.24.5         TObjectStack.Peek

    Synopsis:    Look at the top object in the stack.

Declaration:     function  Peek  :  TObject

    Visibility:   public

Description:     Peek returns the top object of the stack, without removing it from the stack.  If there are
                no more objects on the stack, Nil is returned.

       Errors:   None

    See also:    TObjectStack.Push (102  ), TObjectStack.Pop (102  )



                                                                                 102

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.25          TOrderedList



                5.25.1         Description

                TOrderedList provides the base class for TQueue (105  ) and TStack (105  ).  It provides an
                interface for pushing and popping elements on or off the list, and manages the internal list
                of pointers.

                Note that TOrderedList does not manage objects on the stack,  i.e.  objects are not freed
                when the ordered list is destroyed.
                5.25.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  104       AtLeast         Check whether the list contains a certain number of elements.
                  103       Count           Number of elements on the list.
                  103       Create          Create a new ordered list
                  103       Destroy         Free an ordered list
                  105       Peek            Return the next element to be popped from the list.
                  104       Pop             Remove an element from the list.
                __104_______Push____________Push_another_element_on_the_list.______________________________________________________*
 *___________
                5.25.3         TOrderedList.Create

    Synopsis:    Create a new ordered list

Declaration:     constructor  Create

    Visibility:   public

Description:     Create instantiates a new ordered list.  It initializes the internal pointer list.

       Errors:   None.

    See also:    TOrderedList.Destroy (103  )
                5.25.4         TOrderedList.Destroy

    Synopsis:    Free an ordered list

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the internal pointer list, and removes the TOrderedList instance from
                memory.

       Errors:   None.

    See also:    TOrderedList.Create (103  )
                5.25.5         TOrderedList.Count

    Synopsis:    Number of elements on the list.

Declaration:     function  Count  :  Integer
                                                                                 103

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
    Visibility:  public

Description:     Count is the number of pointers in the list.

       Errors:   None.

    See also:    TOrderedList.AtLeast (104  )
                5.25.6         TOrderedList.AtLeast

    Synopsis:    Check whether the list contains a certain number of elements.

Declaration:     function  AtLeast(ACount:  Integer)  :  Boolean

    Visibility:   public

Description:     AtLeast returns True if the number of elements in the list is equal to or bigger than ACount.
                It returns False otherwise.

       Errors:   None.

    See also:    TOrderedList.Count (103  )
                5.25.7         TOrderedList.Push

    Synopsis:    Push another element on the list.

Declaration:     function  Push(AItem:  Pointer)  :  Pointer

    Visibility:   public

Description:     Push adds AItem to the list, and returns AItem.

       Errors:   If not enough memory is available to expand the list, an exception may be raised.

    See also:    TOrderedList.Pop (104  ), TOrderedList.Peek (105  )
                5.25.8         TOrderedList.Pop

    Synopsis:    Remove an element from the list.

Declaration:     function  Pop  :  Pointer

    Visibility:   public

Description:     Pop removes an element from the list, and returns the element that was removed from the
                list.  If no element is on the list, Nil is returned.

       Errors:   None.

    See also:    TOrderedList.Peek (105  ), TOrderedList.Push (104  )
                                                                                 104

                _________________________________________________________CHAPTER_5.___REFERENCE_FOR_UNIT_'CONTNRS'_________________*
 *___________________
                5.25.9         TOrderedList.Peek

    Synopsis:    Return the next element to be popped from the list.

Declaration:     function  Peek  :  Pointer

    Visibility:   public

Description:     Peek returns the element that will be popped from the list at the next call to Pop (104  ),
                without actually popping it from the list.

       Errors:   None.

    See also:    TOrderedList.Pop (104  ), TOrderedList.Push (104  )
                5.26          TQueue



                5.26.1         Description

                TQueue is a descendent of TOrderedList (103  ) which implements Push (104  ) and Pop (104  )
                behaviour as a queue:  what is first pushed on the queue, is popped of first (FIFO: First in,
                first out).

                TQueue offers no new methods, it merely implements some abstract methods introduced by
                TOrderedList (103  )
                5.27          TStack



                5.27.1         Description

                TStack is a descendent of TOrderedList (103  ) which implements Push (104  ) and Pop (104  )
                behaviour as a stack:  what is last pushed on the stack,  is popped of first (LIFO: Last in,
                first out).

                TStack offers no new methods, it merely implements some abstract methods introduced by
                TOrderedList (103  )

                                                                                 105


Chapter   6


Reference   for   unit   'CustApp'
6.1         Used  units
                                   Table 6.1:  Used units by unit 'CustApp'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     sysutils         ??



6.2         Overview


The  CustApp  unit  implements  the  TCustomApplication  (107  )  class,  which  serves  as  the
common ancestor to many kinds of  TApplication classes:  a GUI application in the LCL,
a  CGI  application  in  FPCGI,  a  daemon  application  in  daemonapp.   It  introduces  some
properties  to  describe  the  environment  in  which  the  application  is  running  (environment
variables,  program  command-line  parameters)  and  introduces  some  methods  to  initialize
and run a program, as well as functionality to handle exceptions.

Typical use of a descendent class is to introduce a global variable Application and use the
following code:


Application.Initialize;
    Application.Run;


Since normally only a single instance of this class is created, and it is a TComponent descen-
dent, it can be used as an owner for many components, doing so will ensure these components
will be freed when the application terminates.
6.3         Constants,  types  and  variables



6.3.1        Types

TExceptionEvent  =  procedure(Sender:  TObject;E:  Exception)  of  object


TExceptionEvent is the prototype for the exception handling events in TCustomApplication.



                                                             106

_________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________________________*
 *___
6.4         TCustomApplication



6.4.1        Description

TCustomApplication  is  the  ancestor  class  for  classes  that  whish  to  implement  a  global
application class instance.  It introduces several application-wide functionalities.


     o  Exception  handling  in  HandleException  (108  ),  ShowException  (109  ),  OnException
        (113  ) and StopOnException (116  ).

     o  Command-line  parameter  parsing  in  FindOptionIndex  (110  ),  GetOptionValue  (110  ),
        CheckOptions (111  ) and HasOption (111  )

     o  Environment variable handling in GetEnvironmentList (112  ) and EnvironmentVariable
        (115  ).


Descendent classes need to override the DoRun protected method to implement the function-
ality of the program.
6.4.2        Method  overview

__Page______Property________________________Description_______________________________________________________________________
  111       CheckOptions                    Check whether all given options on the command-line are
                                            valid.
  108       Create                          Create a new instance of the TCustomApplication class
  108       Destroy                         Destroys the TCustomApplication instance.
  110       FindOptionIndex                 Return the index of an option.
  112       GetEnvironmentList              Return a list of environment variables.
  110       GetOptionValue                  Return the value of a command-line option.
  108       HandleException                 Handle an exception.
  111       HasOption                       Check whether an option was specified.
  108       Initialize                      Initialize the application
  109       Run                             Runs the application.
  109       ShowException                   Show an exception to the user
__109_______Terminate_______________________Terminate_the_application.________________________________________________________
6.4.3        Property  overview

__Page______Property__________________________Access______Description_________________________________________________________
  115       CaseSensitiveOptions              rw          Are options interpreted case sensitive or not
  113       ConsoleApplication                r           Is the application a console application or not
  115       EnvironmentVariable               r           Environment variable access
  112       ExeName                           r           Name of the executable.
  112       HelpFile                          rw          Location of the application help file.
  114       Location                          r           Application location
  113       OnException                       rw          Exception handling event
  115       OptionChar                        rw          Command-line switch character
  114       ParamCount                        r           Number of command-line parameters
  114       Params                            r           Command-line parameters
  116       StopOnException                   rw          Should the program loop stop on an exception
  113       Terminated                        r           Was Terminate called or not
__113_______Title_____________________________rw__________Application_title___________________________________________________


                                                                 107

                _________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________*
 *___________________
                6.4.4        TCustomApplication.Create

    Synopsis:    Create a new instance of the TCustomApplication class

Declaration:     constructor  Create(AOwner:  TComponent);    Override

    Visibility:   public

Description:     Create creates a new instance of the TCustomApplication class.  It sets some defaults for
                the various properties, and then calls the inherited Create.

    See also:    TCustomApplication.Destroy (108  )
                6.4.5        TCustomApplication.Destroy

    Synopsis:    Destroys the TCustomApplication instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy simply calls the inherited Destroy.

    See also:    TCustomApplication.Create (108  )
                6.4.6        TCustomApplication.HandleException

    Synopsis:    Handle an exception.

Declaration:     procedure  HandleException(Sender:  TObject);    Virtual

    Visibility:   public

Description:     HandleException is called (or can be called) to handle the exception Sender.  If the excep-
                tion is not of class Exception then the default handling of exceptions in the SysUtils unit is
                called.

                If the exception is of class Exception and the OnException (113  ) handler is set, the handler
                is called with the exception object and Sender argument.

                If the OnException handler is not set, then the exception is passed to the ShowException
                (109  ) routine, which can be overridden by descendent application classes to show the excep-
                tion  in  a  way  that  is  fit  for  the  particular  class  of  application.  (a  GUI  application  might
                show the exception in a message dialog.

                When the exception is handled in the above manner, and the StopOnException (116  ) prop-
                erty is set to True, the Terminated (113  ) property is set to True, which will cause the Run
                (109  ) loop to stop, and the application will exit.

    See also:    TCustomApplication.ShowException  (109  ),  TCustomApplication.StopOnException  (116  ),
                TCustomApplication.Terminated (113  ), TCustomApplication.Run (109  )
                6.4.7        TCustomApplication.Initialize

    Synopsis:    Initialize the application

Declaration:     procedure  Initialize;    Virtual

    Visibility:   public
                                                                                 108

                _________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________*
 *___________________
Description:     Initialize can be overridden by descendent applications to perform any initialization after
                the class was created.  It can be used to react to properties being set at program startup.
                End-user code should call Initialize prior to calling Run

                In TCustomApplication, Initialize sets Terminated to False.

    See also:    TCustomApplication.Run (109  ), TCustomApplication.Terminated (113  )
                6.4.8        TCustomApplication.Run

    Synopsis:    Runs the application.

Declaration:     procedure  Run

    Visibility:   public

Description:     Run is the start of the user code:  when called, it starts a loop and repeatedly calls DoRun
                until Terminated is set to True.  If an exception is raised during the execution of  DoRun, it
                is  caught  and  handled  to  TCustomApplication.HandleException  (108  ).  If  TCustomAppli-
                cation.StopOnException (116  ) is set to True (which is not  the default), Run will exit, and
                the application will then terminate.  The default is to call DoRun again, which is useful for
                applications running a message loop such as services and GUI applications.

    See also:    TCustomApplication.HandleException (108  ), TCustomApplication.StopException (107  )
                6.4.9        TCustomApplication.ShowException

    Synopsis:    Show an exception to the user

Declaration:     procedure  ShowException(E:  Exception);    Virtual

    Visibility:   public

Description:     ShowException should be overridden by descendent classes to show an exception message to
                the user.  The default behaviour is to call the ShowException (??  ) procedure in the SysUtils
                unit.

                Descendent classes should do something appropriate for their context:  GUI applications can
                show  a  message  box,  daemon  applications  can  write  the  exception  message  to  the  system
                log, web applications can send a 500 error response code.

       Errors:   None.

    See also:    #rtl.sysutils.ShowException (??  ), TCustomApplication.HandleException (108  ), TCustom-
                Application.StopException (107  )
                6.4.10         TCustomApplication.Terminate

    Synopsis:    Terminate the application.

Declaration:     procedure  Terminate;    Virtual

    Visibility:   public

Description:     Terminate  sets  the  Terminated  property  to  True.  By  itself,  this  does  not  terminate  the
                application.  Instead,  descendent  classes  should  in  their  DoRun  method,  check  the  value  of
                the Terminated (113  ) property and properly shut down the application if it is set to True.

    See also:    TCustomApplication.Terminated (113  ), TCustomApplication.Run (109  )



                                                                                 109

                _________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________*
 *___________________
                6.4.11         TCustomApplication.FindOptionIndex

    Synopsis:    Return the index of an option.

Declaration:     function  FindOptionIndex(const  S:  String;var  Longopt:  Boolean)  :  Integer

    Visibility:   public

Description:     FindOptionIndex will return the index of the option S or the long option LongOpt.  Neither
                of them should include the switch character.  If no such option was specified, -1 is returned.
                If  either  the  long  or  short  option  was  specified,  then  the  position  on  the  command-line  is
                returned.

                Depending on the value of the CaseSensitiveOptions (115  ) property, the search is performed
                case sensitive or case insensitive.

                Options are identified as command-line parameters which start with OptionChar (115  ) (by
                default the dash ('-') character).

    See also:    TCustomApplication.HasOption (111  ), TCustomApplication.GetOptionValue (110  ), TCus-
                tomApplication.CheckOptions (111  ), TCustomApplication.CaseSensitiveOptions (115  ), TCus-
                tomApplication.OptionChar (115  )
                6.4.12         TCustomApplication.GetOptionValue

    Synopsis:    Return the value of a command-line option.

Declaration:     function  GetOptionValue(const  S:  String)  :  String
                function  GetOptionValue(const  C:  Char;const  S:  String)  :  String

    Visibility:   public

Description:     GetOptionValue  returns  the  value  of  an  option.   Values  are  specified  in  the  usual  GNU
                option format, either of


                --longopt=Value


                or


                -c  Value


                is supported.

                The function returns the specified value, or the empty string if none was specified.

                Depending on the value of the CaseSensitiveOptions (115  ) property, the search is performed
                case sensitive or case insensitive.

                Options are identified as command-line parameters which start with OptionChar (115  ) (by
                default the dash ('-') character).

    See also:    TCustomApplication.FindOptionIndex (110  ), TCustomApplication.HasOption (111  ), TCus-
                tomApplication.CheckOptions (111  ), TCustomApplication.CaseSensitiveOptions (115  ), TCus-
                tomApplication.OptionChar (115  )
                                                                                 110

                _________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________*
 *___________________
                6.4.13         TCustomApplication.HasOption

    Synopsis:    Check whether an option was specified.

Declaration:     function  HasOption(const  S:  String)  :  Boolean
                function  HasOption(const  C:  Char;const  S:  String)  :  Boolean

    Visibility:   public

Description:     HasOption returns True if the specified option was given on the command line.  Either the
                short option character C or the long option S may be used.  Note that both options (requiring
                a value) and switches can be specified.

                Depending on the value of the CaseSensitiveOptions (115  ) property, the search is performed
                case sensitive or case insensitive.

                Options are identified as command-line parameters which start with OptionChar (115  ) (by
                default the dash ('-') character).

    See also:    TCustomApplication.FindOptionIndex (110  ), TCustomApplication.GetOptionValue (110  ),
                TCustomApplication.CheckOptions (111  ), TCustomApplication.CaseSensitiveOptions (115  ),
                TCustomApplication.OptionChar (115  )
                6.4.14         TCustomApplication.CheckOptions

    Synopsis:    Check whether all given options on the command-line are valid.

Declaration:     function  CheckOptions(const  ShortOptions:  String;
                                                   const  Longopts:  TStrings;Opts:  TStrings;
                                                   NonOpts:  TStrings)  :  String
                function  CheckOptions(const  ShortOptions:  String;
                                                   const  Longopts:  TStrings)  :  String
                function  CheckOptions(const  ShortOptions:  String;
                                                   const  LongOpts:  Array  of  String)  :  String
                function  CheckOptions(const  ShortOptions:  String;const  LongOpts:  String)
                                                     :  String

    Visibility:   public

Description:     CheckOptions  scans  the  command-line  and  checks  whether  the  options  given  are  valid
                options.   It  also  checks  whether  options  that  require  a  valued  are  indeed  specified  with  a
                value.

                The ShortOptions contains a string with valid short option characters.  Each character in
                the string is a valid option character.  If a character is followed by a colon (:), then a value
                must be specified.  If it is followed by 2 colon characters (::)  then the value is optional.

                LongOpts is a list of strings (which can be specified as an array, a TStrings instance or a
                string with whitespace-separated values) of valid long options.

                When the function returns, if  Opts is non-Nil, the Opts stringlist is filled with the passed
                valid options.  If NonOpts is non-nil, it is filled with any non-option strings that were passed
                on the command-line.

                The function returns an empty string if all specified options were valid options, and whether
                options requiring a value have a value.  If an error was found during the check, the return
                value is a string describing the error.

                Options are identified as command-line parameters which start with OptionChar (115  ) (by
                default the dash ('-') character).

       Errors:   if an error was found during the check, the return value is a string describing the error.



                                                                                 111

                _________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________*
 *___________________
    See also:    TCustomApplication.FindOptionIndex (110  ), TCustomApplication.GetOptionValue (110  ),
                TCustomApplication.HasOption (111  ), TCustomApplication.CaseSensitiveOptions (115  ), TCus-
                tomApplication.OptionChar (115  )
                6.4.15         TCustomApplication.GetEnvironmentList

    Synopsis:    Return a list of environment variables.

Declaration:     procedure  GetEnvironmentList(List:  TStrings;NamesOnly:  Boolean)
                procedure  GetEnvironmentList(List:  TStrings)

    Visibility:   public

Description:     GetEnvironmentList returns a list of environment variables in List.  They are in the form
                Name=Value, one per item in list.  If NamesOnly is True, then only the names are returned.

    See also:    TCustomApplication.EnvironmentVariable (115  )
                6.4.16         TCustomApplication.ExeName

    Synopsis:    Name of the executable.

Declaration:     Property  ExeName  :  String

    Visibility:   public

      Access:    Read

Description:     ExeName returns the full name of the executable binary (path+filename).  This is equivalent
                to Paramstr(0)

                Note that some operating systems do not return the full pathname of the binary.

    See also:    #rtl.system.paramstr (??  )
                6.4.17         TCustomApplication.HelpFile

    Synopsis:    Location of the application help file.

Declaration:     Property  HelpFile  :  String

    Visibility:   public

      Access:    Read,Write

Description:     HelpFile is the location of the application help file.  It is a simple string property which can
                be set by an IDE such as Lazarus,  and is mainly provided for compatibility with Delphi's
                TApplication implementation.

    See also:    TCustomApplication.Title (113  )

                                                                                 112

                _________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________*
 *___________________
                6.4.18         TCustomApplication.Terminated

    Synopsis:    Was Terminate called or not

Declaration:     Property  Terminated  :  Boolean

    Visibility:   public

      Access:    Read

Description:     Terminated indicates whether Terminate (109  ) was called or not.  Descendent classes should
                check Terminated at regular intervals in their implementation of  DoRun, and if it is set to
                True, should exit gracefully the DoRun method.

    See also:    TCustomApplication.Terminate (109  )
                6.4.19         TCustomApplication.Title

    Synopsis:    Application title

Declaration:     Property  Title  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Title  is  a  simple  string  property  which  can  be  set  to  any  string  describing  the  applica-
                tion.   It  does  nothing  by  itself,  and  is  mainly  introduced  for  compatibility  with  Delphi's
                TApplication implementation.

    See also:    TCustomApplication.HelpFile (112  )
                6.4.20         TCustomApplication.OnException

    Synopsis:    Exception handling event

Declaration:     Property  OnException  :  TExceptionEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnException can be set to provide custom handling of events, instead of the default action,
                which is simply to show the event using ShowEvent (107  ).

                If set, OnException is called by the HandleEvent (107  ) routine.  Do not use the OnException
                event directly, instead call HandleEvent

    See also:    TCustomApplication.ShowEvent (107  )
                6.4.21         TCustomApplication.ConsoleApplication

    Synopsis:    Is the application a console application or not

Declaration:     Property  ConsoleApplication  :  Boolean

    Visibility:   public

      Access:    Read
                                                                                 113

                _________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________*
 *___________________
Description:     ConsoleApplication returns True if the application is compiled as a console application
                (the default) or False if not.  The result of this property is determined at compile-time by
                the settings of the compiler:  it returns the value of the IsConsole (??  ) constant.

    See also:    #rtl.system.IsConsole (??  )
                6.4.22         TCustomApplication.Location

    Synopsis:    Application location

Declaration:     Property  Location  :  String

    Visibility:   public

      Access:    Read

Description:     Location returns the directory part of the application binary.  This property works on most
                platforms, although some platforms do not allow to retrieve this information (Mac OS under
                certain circumstances).  See the discussion of Paramstr (??  ) in the RTL documentation.

    See also:    #rtl.system.paramstr (??  ), TCustomApplication.Params (114  )
                6.4.23         TCustomApplication.Params

    Synopsis:    Command-line parameters

Declaration:     Property  Params[Index:  Integer]:  String

    Visibility:   public

      Access:    Read

Description:     Params gives access to the command-line parameters.  They contain the value of the Index-
                th  parameter,  where  Index  runs  from  0  to  ParamCount  (114  ).  It  is  equivalent  to  calling
                ParamStr (??  ).

    See also:    TCustomApplication.ParamCount (114  ), #rtl.system.paramstr (??  )
                6.4.24         TCustomApplication.ParamCount

    Synopsis:    Number of command-line parameters

Declaration:     Property  ParamCount  :  Integer

    Visibility:   public

      Access:    Read

Description:     ParamCount returns the number of command-line parameters that were passed to the pro-
                gram.  The actual parameters can be retrieved with the Params (114  ) property.

    See also:    TCustomApplication.Params  (114  ),  #rtl.system.paramstr  (??  ),  #rtl.system.paramcount
                (??  )



                                                                                 114

                _________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________*
 *___________________
                6.4.25         TCustomApplication.EnvironmentVariable

    Synopsis:    Environment variable access

Declaration:     Property  EnvironmentVariable[envName:  String]:  String

    Visibility:   public

      Access:    Read

Description:     EnvironmentVariable gives access to the environment variables of the application:  It re-
                turns the value of the environment variable EnvName, or an empty string if no such value is
                available.

                To use this property, the name of the environment variable must be known.  To get a list of
                available names (and values), GetEnvironmentList (112  ) can be used.

    See also:    TCustomApplication.GetEnvironmentList (112  ), TCustomApplication.Params (114  )
                6.4.26         TCustomApplication.OptionChar

    Synopsis:    Command-line switch character

Declaration:     Property  OptionChar  :  Char

    Visibility:   public

      Access:    Read,Write

Description:     OptionChar is the character used for command line switches.  By default, this is the dash
                ('-')  character,  but  it  can  be  set  to  any  other  non-alphanumerical  character  (although  no
                check is performed on this).

    See also:    TCustomApplication.FindOptionIndex (110  ), TCustomApplication.GetOptionValue (110  ),
                TCustomApplication.HasOption (111  ), TCustomApplication.CaseSensitiveOptions (115  ), TCus-
                tomApplication.CheckOptions (111  )
                6.4.27         TCustomApplication.CaseSensitiveOptions

    Synopsis:    Are options interpreted case sensitive or not

Declaration:     Property  CaseSensitiveOptions  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     CaseSensitiveOptions determines whether FindOptionIndex (110  ) and CheckOptions (111  )
                perform searches in a case sensitive manner or not.  By default, the search is case-sensitive.
                Setting this property to False makes the search case-insensitive.

    See also:    TCustomApplication.FindOptionIndex (110  ), TCustomApplication.GetOptionValue (110  ),
                TCustomApplication.HasOption (111  ),  TCustomApplication.OptionChar (115  ),  TCustom-
                Application.CheckOptions (111  )
                                                                                 115

                _________________________________________________________CHAPTER_6.___REFERENCE_FOR_UNIT_'CUSTAPP'_________________*
 *___________________
                6.4.28         TCustomApplication.StopOnException

    Synopsis:    Should the program loop stop on an exception

Declaration:     Property  StopOnException  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     StopOnException controls the behaviour of the Run (109  ) and HandleException (108  ) pro-
                cedures in case of an unhandled exception in the DoRun code.  If  StopOnException is True
                then Terminate (109  ) will be called after the exception was handled.

    See also:    TCustomApplication.Run  (109  ),  TCustomApplication.HandleException  (108  ),  TCustom-
                Application.Terminate (109  )

                                                                                 116


Chapter   7


Reference   for   unit   'dbugintf '
7.1         Writing  a  debug  server


Writing  a  debug  server  is  relatively  easy.  It  should  instantiate  a  TSimpleIPCServer  class
from the SimpleIPC (117  ) unit, and use the DebugServerID as ServerID identification.  This
constant, as well as the record containing the message which is sent between client and server
is defined in the msgintf  unit.

The dbugintf unit relies on the SimpleIPC (117  ) mechanism to communicate with the debug
server,  hence it works on all platforms that have a functional version of that unit.  It also
uses TProcess to start the debug server if needed, so the process (117  ) unit should also be
functional.
7.2         Overview


Use  dbugintf  to  add  debug  messages  to  your  application.   The  messages  are  not  sent  to
standard output, but are sent to a debug server process which collects messages from various
clients and displays them somehow on screen.

The  unit  is  transparant  in  its  use:  it  does  not  need  initialization,  it  will  start  the  debug
server by itself if it can find it:  the program should be called debugserver and should be in
the PATH. When the first debug message is sent, the unit will initialize itself.

The  FCL  contains  a  sample  debug  server  (dbugsvr)  which  can  be  started  in  advance,  and
which  writes  debug  message  to  the  console  (both  on  Windows  and  Linux).   The  Lazarus
project contains a visual application which displays the messages in a GUI.

The dbugintf unit relies on the SimpleIPC (117  ) mechanism to communicate with the debug
server,  hence it works on all platforms that have a functional version of that unit.  It also
uses TProcess to start the debug server if needed, so the process (117  ) unit should also be
functional.
7.3         Constants,  types  and  variables



7.3.1        Resource  strings

SEntering  =  '>  Entering  '


String used when sending method enter message.



                                                             117

                _______________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'DBUGINTF'__________________*
 *___________________
                SExiting  =  '<  Exiting  '


                String used when sending method exit message.


                SProcessID  =  'Process  %s'


                String used when sending identification message to the server.


                SSeparator  =  '>-=-=-=-=-=-=-=-=-=-=-=-=-=-=-<'


                String used when sending a separator line.
                7.3.2        Constants

                SendError  :  String  =  ''


                Whenever a call encounteres an exception, the exception message is stored in this variable.
                7.3.3        Types

                TDebugLevel  =  (dlInformation,dlWarning,dlError)
                                          Table 7.1:  Enumeration values for type TDebugLevel


                                                   _Value__________________Explanation_______________________
                                                     dlError                Error message
                                                     dlInformation          Informational message
                                                     dlWarning              Warning message
                TDebugLevel  indicates  the  severity  level  of  the  debug  message  to  be  sent.  By  default,  an
                informational message is sent.
                7.4         Procedures  and  functions



                7.4.1        GetDebuggingEnabled

    Synopsis:    Check if sending of debug messages is enabled.

Declaration:     function  GetDebuggingEnabled  :  Boolean

    Visibility:   default

Description:     GetDebuggingEnabled returns the value set by the last call to SetDebuggingEnabled.  It
                is True by default.

    See also:    SetDebuggingEnabled (122  ), SendDebug (119  )
                                                                                 118

                _______________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'DBUGINTF'__________________*
 *___________________
                7.4.2        InitDebugClient

    Synopsis:    Initialize the debug client.

Declaration:     function  InitDebugClient  :  Boolean

    Visibility:   default

Description:     InitDebugClient starts the debug server and then performs all necessary initialization of
                the debug IPC communication channel.

                Normally  this  function  should  not  be  called.  The  SendDebug  (119  )  call  will  initialize  the
                debug client when it is first called.

       Errors:   None.

    See also:    SendDebug (119  ), StartDebugServer (122  )
                7.4.3        SendBoolean

    Synopsis:    Send the value of a boolean variable

Declaration:     procedure  SendBoolean(const  Identifier:  String;const  Value:  Boolean)

    Visibility:   default

Description:     SendBoolean is a simple wrapper around SendDebug (119  ) which sends the name and value
                of a boolean value as an informational message.

       Errors:   None.

    See also:    SendDebug (119  ), SendDateTime (119  ), SendInteger (121  ), SendPointer (122  )
                7.4.4        SendDateTime

    Synopsis:    Send the value of a TDateTime variable.

Declaration:     procedure  SendDateTime(const  Identifier:  String;const  Value:  TDateTime)

    Visibility:   default

Description:     SendDateTime  is  a  simple  wrapper  around  SendDebug  (119  )  which  sends  the  name  and
                value  of  an  integer  value  as  an  informational  message.  The  value  is  converted  to  a  string
                using the DateTimeToStr (??  ) call.

       Errors:   None.

    See also:    SendDebug (119  ), SendBoolean (119  ), SendInteger (121  ), SendPointer (122  )
                7.4.5        SendDebug

    Synopsis:    Send a message to the debug server.

Declaration:     procedure  SendDebug(const  Msg:  String)

    Visibility:   default

                                                                                 119

                _______________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'DBUGINTF'__________________*
 *___________________
Description:     SendDebug sends the message Msg to the debug server as an informational message (debug
                level dlInformation).  If no debug server is running, then an attempt will be made to start
                the server first.

                The  binary  that  is  started  is  called  debugserver  and  should  be  somewhere  on  the  PATH.  A
                sample binary which writes received messages to standard output is included in the FCL, it
                is called dbugsrv.  This binary can be renamed to debugserver  or can be started before the
                program is started.

       Errors:   Errors are silently ignored, any exception messages are stored in SendError (118  ).

    See also:    SendDebugEx (120  ), SendDebugFmt (120  ), SendDebugFmtEx (120  )
                7.4.6        SendDebugEx

    Synopsis:    Send debug message other than informational messages

Declaration:     procedure  SendDebugEx(const  Msg:  String;MType:  TDebugLevel)

    Visibility:   default

Description:     SendDebugEx  allows  to  specify  the  debug  level  of  the  message  to  be  sent  in  MType.   By
                default, SendDebug (119  ) uses informational messages.

                Other than that the function of  SendDebugEx is equal to that of  SendDebug

       Errors:   None.

    See also:    SendDebug (119  ), SendDebugFmt (120  ), SendDebugFmtEx (120  )
                7.4.7        SendDebugFmt

    Synopsis:    Format and send a debug message

Declaration:     procedure  SendDebugFmt(const  Msg:  String;const  Args:  Array  of  const)

    Visibility:   default

Description:     SendDebugFmt  is  a  utility  routine  which  formats  a  message  by  passing  Msg  and  Args  to
                Format  (??  )  and  sends  the  result  to  the  debug  server  using  SendDebug  (119  ).   It  exists
                mainly to avoid the Format call in calling code.

       Errors:   None.

    See also:    SendDebug (119  ), SendDebugEx (120  ), SendDebugFmtEx (120  ), #rtl.sysutils.format (??  )
                7.4.8        SendDebugFmtEx

    Synopsis:    Format and send message with alternate type

Declaration:     procedure  SendDebugFmtEx(const  Msg:  String;const  Args:  Array  of  const;
                                                        MType:  TDebugLevel)

    Visibility:   default

Description:     SendDebugFmtEx is a utility routine which formats a message by passing Msg and Args to
                Format (??  ) and sends the result to the debug server using SendDebugEx (120  ) with Debug
                level MType.  It exists mainly to avoid the Format call in calling code.

       Errors:   None.

    See also:    SendDebug (119  ), SendDebugEx (120  ), SendDebugFmt (120  ), #rtl.sysutils.format (??  )



                                                                                 120

                _______________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'DBUGINTF'__________________*
 *___________________
                7.4.9        SendInteger

    Synopsis:    Send the value of an integer variable.

Declaration:     procedure  SendInteger(const  Identifier:  String;const  Value:  Integer;
                                                   HexNotation:  Boolean)

    Visibility:   default

Description:     SendInteger is a simple wrapper around SendDebug (119  ) which sends the name and value
                of an integer value as an informational message.  If HexNotation is True, then the value will
                be displayed using hexadecimal notation.

       Errors:   None.

    See also:    SendDebug (119  ), SendBoolean (119  ), SendDateTime (119  ), SendPointer (122  )
                7.4.10         SendMethodEnter

    Synopsis:    Send method enter message

Declaration:     procedure  SendMethodEnter(const  MethodName:  String)

    Visibility:   default

Description:     SendMethodEnter sends a "Entering MethodName" message to the debug server.  After that
                it increases the message indentation (currently 2 characters).  By sending a corresponding
                SendMethodExit (121  ), the indentation of messages can be decreased again.

                By using the SendMethodEnter and SendMethodExit methods at the beginning and end of
                a procedure/method, it is possible to visually trace program execution.

       Errors:   None.

    See also:    SendDebug (119  ), SendMethodExit (121  ), SendSeparator (122  )
                7.4.11         SendMethodExit

    Synopsis:    Send method exit message

Declaration:     procedure  SendMethodExit(const  MethodName:  String)

    Visibility:   default

Description:     SendMethodExit  sends  a  "Exiting  MethodName"  message  to  the  debug  server.  After  that
                it decreases the message indentation (currently 2 characters).  By sending a corresponding
                SendMethodEnter (121  ), the indentation of messages can be increased again.

                By using the SendMethodEnter and SendMethodExit methods at the beginning and end of
                a procedure/method, it is possible to visually trace program execution.

                Note that the indentation level will not be made negative.

       Errors:   None.

    See also:    SendDebug (119  ), SendMethodEnter (121  ), SendSeparator (122  )



                                                                                 121

                _______________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'DBUGINTF'__________________*
 *___________________
                7.4.12         SendPointer

    Synopsis:    Send the value of a pointer variable.

Declaration:     procedure  SendPointer(const  Identifier:  String;const  Value:  Pointer)

    Visibility:   default

Description:     SendInteger  is  a  simple  wrapper  around  SendDebug  (119  )  which  sends  the  name  and
                value of a pointer value as an informational message.  The pointer value is displayed using
                hexadecimal notation.

       Errors:   None.

    See also:    SendDebug (119  ), SendBoolean (119  ), SendDateTime (119  ), SendInteger (121  )
                7.4.13         SendSeparator

    Synopsis:    Send a separator message

Declaration:     procedure  SendSeparator

    Visibility:   default

Description:     SendSeparator is a simple wrapper around SendDebug (119  ) which sends a short horizontal
                line to the debug server.  It can be used to visually separate execution of blocks of code or
                blocks of values.

       Errors:   None.

    See also:    SendDebug (119  ), SendMethodEnter (121  ), SendMethodExit (121  )
                7.4.14         SetDebuggingEnabled

    Synopsis:    Temporary enables or disables debugging

Declaration:     procedure  SetDebuggingEnabled(const  AValue:  Boolean)

    Visibility:   default

Description:     SetDebuggingEnabled can be used to temporarily enable or disable sending of debug mes-
                sages:  this allows to control the amount of messages sent to the debug server without having
                to remove the SendDebug (119  ) statements.  By default, debugging is enabled.  If set to false,
                debug messages are simply discarded till debugging is enabled again.

                A value of  True enables sending of debug messages.  A value of  False disables sending.

       Errors:   None.

    See also:    GetDebuggingEnabled (118  ), SendDebug (119  )
                7.4.15         StartDebugServer

    Synopsis:    Start the debug server

Declaration:     function  StartDebugServer  :  Integer

    Visibility:   default

                                                                                 122

                _______________________________________________________CHAPTER_7.___REFERENCE_FOR_UNIT_'DBUGINTF'__________________*
 *___________________
Description:     StartDebugServer  attempts  to  start  the  debug  server.  The  process  started  is  called  de-
                bugserver and should be located in the PATH.

                Normally this function should not be called.  The SendDebug (119  ) call will attempt to start
                the server by itself if it is not yet running.

       Errors:   On error, False is returned.

    See also:    SendDebug (119  ), InitDebugClient (119  )
                                                                                 123


Chapter   8


Reference   for   unit   'dbugmsg'
8.1         Used  units
                                   Table 8.1:  Used units by unit 'dbugmsg'


                                                   __Name__________Page____
                                                     Classes          ??



8.2         Overview


dbugmsg is an auxialiary unit used in the dbugintf (117  ) unit.  It defines the message protocol
used between the debug unit and the debug server.
8.3         Constants,  types  and  variables



8.3.1        Constants

DebugServerID  :  String  =  'fpcdebugserver'


DebugServerID is a string which is used when creating the message protocol, it is used when
identifying the server in the (platform dependent) client-server protocol.


lctError  =  2


lctError is the identification of error messages.


lctIdentify  =  3


lctIdentify is sent by the client to a server when it first connects.  It's the first message,
and contains the name of client application.


lctInformation  =  0
                                                             124

                ________________________________________________________CHAPTER_8.___REFERENCE_FOR_UNIT_'DBUGMSG'__________________*
 *___________________
                lctInformation is the identification of informational messages.


                lctStop  =  -1


                lctStop is sent by the client to a server when it disconnects.


                lctWarning  =  1


                lctWarning is the identification of warning messages.
                8.3.2        Types

                TDebugMessage  =  record
                    MsgType  :  Integer;
                    MsgTimeStamp  :  TDateTime;
                    Msg  :  String;
                end



                TDebugMessage is a record that describes the message passed from the client to the server.
                It  should  not  be  passed  directly  in  shared  memory,  as  the  string  containing  the  message
                is  allocated  on  the  heap.   Instead,  the  WriteDebugMessageToStream  (126  )  and  ReadDe-
                bugMessageFromStream (125  ) can be used to read or write the message from/to a stream.
                8.4         Procedures  and  functions



                8.4.1        DebugMessageName

    Synopsis:    Return the name of the debug message

Declaration:     function  DebugMessageName(msgType:  Integer)  :  String

    Visibility:   default

Description:     DebugMessageName returns the name of the message type.  It can be used to examine the
                MsgType field of a TDebugMessage (125  ) record, and if  msgType contains a known type, it
                returns a string describing this type.

       Errors:   If  MsgType contains an unknown type, 'Unknown' is returned.
                8.4.2        ReadDebugMessageFromStream

    Synopsis:    Read a message from stream

Declaration:     procedure  ReadDebugMessageFromStream(AStream:  TStream;
                                                                            var  Msg:  TDebugMessage)

    Visibility:   default

Description:     ReadDebugMessageFromStream reads a TDebugMessage (125  ) record (Msg) from the stream
                AStream.

                The record is not read in a byte-ordering safe way, i.e.  it cannot be exchanged between little-
                and big-endian systems.

       Errors:   If the stream contains not enough bytes or is malformed, then an exception may be raised.

    See also:    TDebugMessage (125  ), WriteDebugMessageToStream (126  )



                                                                                 125

                ________________________________________________________CHAPTER_8.___REFERENCE_FOR_UNIT_'DBUGMSG'__________________*
 *___________________
                8.4.3        WriteDebugMessageToStream

    Synopsis:    Write a message to stream

Declaration:     procedure  WriteDebugMessageToStream(AStream:  TStream;
                                                                          const  Msg:  TDebugMessage)

    Visibility:   default

Description:     WriteDebugMessageFromStream writes a TDebugMessage (125  ) record (Msg) to the stream
                AStream.

                The record is not written in a byte-ordering safe way, i.e.  it cannot be exchanged between
                little- and big-endian systems.

       Errors:   A stream write error may occur if the stream cannot be written to.

    See also:    TDebugMessage (125  ), ReadDebugMessageToStream (124  )



                                                                                 126


Chapter   9


Reference   for   unit   'eventlog'
9.1         Used  units
                                    Table 9.1:  Used units by unit 'eventlog'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     sysutils         ??



9.2         Overview


The EventLog unit implements the TEventLog (129  ) component, which is a component that
can be used to send log messages to the system log (if it is available) or to a file.
9.3         Constants,  types  and  variables



9.3.1        Resource  strings

SLogCustom  =  'Custom  (%d)'


Custom message formatting string


SLogDebug  =  'Debug'


Debug message name


SLogError  =  'Error'


Error message name


SLogInfo  =  'Info'


Informational message name
                                                             127

______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'EVENTLOG'___________________________________*
 *___
SLogWarning  =  'Warning'


Warning message name
9.3.2        Types

TEventType  =  (etCustom,etInfo,etWarning,etError,etDebug)
                          Table 9.2:  Enumeration values for type TEventType


                                       __Value_____________Explanation__________________
                                         etCustom          Custom event type.
                                         etDebug           Debug event
                                         etError           Error event
                                         etInfo            Informational event
                                         etWarning         Warning event
TEventType determines the type of event.  Depending on the system logger, the log event may
end up in different places, or may be displayed in a different manner.  A suitable mapping
is  shown  for  each  system.  In  the  case  of  Windows,  the  formatting  of  the  message  is  done
differently, and a different icon is shown for each type of message.


TLogCategoryEvent  =  procedure(Sender:  TObject;var  Code:  Word)  of  object


TLogCategoryEvent is the event type for the TEventLog.OnGetCustomCategory (135  ) event
handler.  It should return a OS event catagory code for the etCustom log event type in the
Code parameter.


TLogCodeEvent  =  procedure(Sender:  TObject;var  Code:  DWord)  of  object


TLogCodeEvent is the event type for the OnGetCustomEvent (135  ) and OnGetCustomEven-
tID (135  ) event handlers.  It should return a OS system log code for the etCustom log event
or event ID type in the Code parameter.


TLogType  =  (ltSystem,ltFile)
                            Table 9.3:  Enumeration values for type TLogType


                                        __Value___________Explanation_________________
                                          ltFile          Write to file
                                          ltSystem        Use the system log
TLogType  determines  where  the  log  messages  are  written.   It  is  the  type  of  the  TEvent-
Log.LogType (132  ) property.  It can have 2 values:


ltFile    This is used to write all messages to file.  if no system logging mechanism exists, this
        is used as a fallback mechanism.

ltSystem        This is used to send all messages to the system log mechanism.  Which log mech-
        anism this is, depends on the operating system.



                                                                 128

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'EVENTLOG'___________________*
 *___________________
                9.4         ELogError



                9.4.1        Description

                ELogError is the exception used in the TEventLog (129  ) component to indicate errors.
                9.5         TEventLog



                9.5.1        Description

                TEventLog is a component which can be used to send messages to the system log.  In case
                no system log exists (such as on Windows 95/98 or DOS), the messages are written to a file.
                Messages can be logged using the general Log (131  ) call, or the specialized Warning (131  ),
                Error (131  ), Info (132  ) or Debug (132  ) calls, which have the event type predefined.
                9.5.2        Method  overview

                __Page______Property________________________Description____________________________________________________________*
 *___________
                  132       Debug                           Log a debug message
                  129       Destroy                         Clean up TEventLog instance
                  131       Error                           Log an error message to
                  130       EventTypeToString               Create a string representation of an event type
                  132       Info                            Log an informational message
                  131       Log                             Log a message to the system log.
                  130       RegisterMessageFile             Register message file
                __131_______Warning_________________________Log_a_warning_message._________________________________________________*
 *___________
                9.5.3        Property  overview

                __Page______Property_____________________________Access_______Description__________________________________________*
 *___________
                  133       Active                               rw           Activate the log mechanism
                  134       CustomLogType                        rw           Custom log type ID
                  133       DefaultEventType                     rw           Default event type for the Log (131  ) call.
                  134       EventIDOffset                        rw           Offset for event ID messages identifiers
                  133       FileName                             rw           File name for log file
                  132       Identification                       rw           Identification string for messages
                  132       LogType                              rw           Log type
                  135       OnGetCustomCategory                  rw           Event to retrieve custom message category
                  135       OnGetCustomEvent                     rw           Event to retrieve custom event Code
                  135       OnGetCustomEventID                   rw           Event to retrieve custom event ID
                  133       RaiseExceptionOnError                rw
                __134_______TimeStampFormat______________________rw___________Format_for_the_timestamp_string______________________*
 *___________
                9.5.4        TEventLog.Destroy

    Synopsis:    Clean up TEventLog instance

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy  cleans  up  the  TEventLog  instance.  It  cleans  any  log  structures  that  might  have
                been set up to perform logging, by setting the Active (133  ) property to False.



                                                                                 129

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'EVENTLOG'___________________*
 *___________________
    See also:    TEventLog.Active (133  )
                9.5.5        TEventLog.EventTypeToString

    Synopsis:    Create a string representation of an event type

Declaration:     function  EventTypeToString(E:  TEventType)  :  String

    Visibility:   public

Description:     EventTypeToString converts the event type E to a suitable string representation for logging
                purposes.  It's mainly used when writing messages to file, as the system log usually has it's
                own mechanisms for displaying the various event types.

    See also:    TEventType (128  )
                9.5.6        TEventLog.RegisterMessageFile

    Synopsis:    Register message file

Declaration:     function  RegisterMessageFile(AFileName:  String)  :  Boolean;    Virtual

    Visibility:   public

Description:     RegisterMessageFile  is  used  on  Windows  to  register  the  file  AFileName  containing  the
                formatting strings for the system messages.  This should be a file containing resource strings.
                If  AFileName is empty, the filename of the application binary is substituted.

                When a message is logged to the windows system log, Windows looks for a formatting string
                in the file registered with this call.

                There are 2 kinds of formatting strings:

                Category strings these should be numbered from 1 to 4

                1 Should contain the description of the etInfo event type.

                2 Should contain the description of the etWarning event type.

                4 Should contain the description of the etError event type.

                4 Should contain the description of the etDebug event type.

                None of these strings should have a string substitution placeholder.

                The second type of strings are the message definitions.  Their number starts at EventID-
                Offset (134  ) (default is 1000) and each string should have 1 placeholder.

                Free Pascal comes with a fclel.res resource file which contains default values for the 8 strings,
                in english.  It can be linked in the application binary with the statement


                {$R  fclel.res}


                This  file  is  generated  from  the  fclel.mc  and  fclel.rc  files  that  are  distributed  with  the  Free
                Pascal sources.

                If the strings are not registered, windows will still display the event messages, but they will
                not be formatted nicely.

                Note that while any messages logged with the event logger are displayed in the event viewern
                Windows locks the file registered here.  This usually means that the binary is locked.

                On non-windows operating systems, this call is ignored.

       Errors:   If  AFileName is invalid, false is returned.



                                                                                 130

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'EVENTLOG'___________________*
 *___________________
                9.5.7        TEventLog.Log

    Synopsis:    Log a message to the system log.

Declaration:     procedure  Log(EventType:  TEventType;Msg:  String);    Overload
                procedure  Log(EventType:  TEventType;Fmt:  String;Args:  Array  of  const)
                                      ;    Overload
                procedure  Log(Msg:  String);    Overload
                procedure  Log(Fmt:  String;Args:  Array  of  const);    Overload

    Visibility:   public

Description:     Log sends a log message to the system log.  The message is either the parameter Msg as is,
                or is formatted from the Fmt and Args parameters.  If EventType is specified, then it is used
                as the message event type.  If EventType is omitted, then the event type is determined from
                DefaultEventType (133  ).

                If EventType is etCustom, then the OnGetCustomEvent (135  ), OnGetCustomEventID (135  )
                and OnGetCustomCategory (135  ).

                The other logging calls:  Info (132  ), Warning (131  ), Error (131  ) and Debug (132  ) use the Log
                call to do the actual work.

    See also:    TEventLog.Info (132  ), TEventLog.Warning (131  ), TEventLog.Error (131  ), TEventLog.Debug
                (132  ), TEventLog.OnGetCustomEvent (135  ), TEventLog.OnGetCustomEventID (135  ), TEvent-
                Log.OnGetCustomCategory (135  )
                9.5.8        TEventLog.Warning

    Synopsis:    Log a warning message.

Declaration:     procedure  Warning(Msg:  String);    Overload
                procedure  Warning(Fmt:  String;Args:  Array  of  const);    Overload

    Visibility:   public

Description:     Warning is a utility function which logs a message with the etWarning type.  The message
                is either the parameter Msg as is, or is formatted from the Fmt and Args parameters.

    See also:    TEventLog.Log  (131  ),  TEventLog.Info  (132  ),  TEventLog.Error  (131  ),  TEventLog.Debug
                (132  )
                9.5.9        TEventLog.Error

    Synopsis:    Log an error message to

Declaration:     procedure  Error(Msg:  String);    Overload
                procedure  Error(Fmt:  String;Args:  Array  of  const);    Overload

    Visibility:   public

Description:     Error  is  a  utility  function  which  logs  a  message  with  the  etError  type.  The  message  is
                either the parameter Msg as is, or is formatted from the Fmt and Args parameters.

    See also:    TEventLog.Log (131  ), TEventLog.Info (132  ), TEventLog.Warning (131  ), TEventLog.Debug
                (132  )
                                                                                 131

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'EVENTLOG'___________________*
 *___________________
                9.5.10         TEventLog.Debug

    Synopsis:    Log a debug message

Declaration:     procedure  Debug(Msg:  String);    Overload
                procedure  Debug(Fmt:  String;Args:  Array  of  const);    Overload

    Visibility:   public

Description:     Debug  is  a  utility  function  which  logs  a  message  with  the  etDebug  type.  The  message  is
                either the parameter Msg as is, or is formatted from the Fmt and Args parameters.

    See also:    TEventLog.Log (131  ), TEventLog.Info (132  ), TEventLog.Warning (131  ), TEventLog.Error
                (131  )
                9.5.11         TEventLog.Info

    Synopsis:    Log an informational message

Declaration:     procedure  Info(Msg:  String);    Overload
                procedure  Info(Fmt:  String;Args:  Array  of  const);    Overload

    Visibility:   public

Description:     Info is a utility function which logs a message with the etInfo type.  The message is either
                the parameter Msg as is, or is formatted from the Fmt and Args parameters.

    See also:    TEventLog.Log (131  ), TEventLog.Warning (131  ), TEventLog.Error (131  ), TEventLog.Debug
                (132  )
                9.5.12         TEventLog.Identification

    Synopsis:    Identification string for messages

Declaration:     Property  Identification  :  String

    Visibility:   published

      Access:    Read,Write

Description:     Identification  is  used  as  a  string  identifying  the  source  of  the  messages  in  the  system
                log.  If it is empty, the filename part of the application binary is used.

    See also:    TEventLog.Active (133  ), TEventLog.TimeStampFormat (134  )
                9.5.13         TEventLog.LogType

    Synopsis:    Log type

Declaration:     Property  LogType  :  TLogType

    Visibility:   published

      Access:    Read,Write

Description:     LogType is the type of the log:  if it is ltSystem, then the system log is used, if it is available.
                If it is ltFile or there is no system log available, then the log messages are written to a file.
                The name for the log file is taken from the FileName (133  ) property.

    See also:    TEventLog.FileName (133  )



                                                                                 132

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'EVENTLOG'___________________*
 *___________________
                9.5.14         TEventLog.Active

    Synopsis:    Activate the log mechanism

Declaration:     Property  Active  :  Boolean

    Visibility:   published

      Access:    Read,Write

Description:     Active  determines  whether  the  log  mechanism  is  active:  if  set  to  True,  the  component
                connects to the system log mechanism, or opens the log file if needed.  Any attempt to log a
                message while the log is not active will try to set this property to True.  Disconnecting from
                the system log or closing the log file is done by setting the Active property to False.

                If the connection to the system logger fails,  or the log file cannot be opened,  then setting
                this property may result in an exception.

    See also:    TEventLog.Log (131  )
                9.5.15         TEventLog.RaiseExceptionOnError

Declaration:     Property  RaiseExceptionOnError  :  Boolean

    Visibility:   published

      Access:    Read,Write
                9.5.16         TEventLog.DefaultEventType

    Synopsis:    Default event type for the Log (131  ) call.

Declaration:     Property  DefaultEventType  :  TEventType

    Visibility:   published

      Access:    Read,Write

Description:     DefaultEventType is the event type used by the Log (131  ) call if it's EventType parameter
                is omitted.

    See also:    TEventLog.Log (131  )
                9.5.17         TEventLog.FileName

    Synopsis:    File name for log file

Declaration:     Property  FileName  :  String

    Visibility:   published

      Access:    Read,Write

Description:     FileName is the name of the log file used to log messages if no system logger is available or
                the LogType (128  ) is ltFile.  If none is specified, then the name of the application binary
                is used, with the extension replaced by .log.  The file is then located in the /tmp directory
                on unix-like systems, or in the application directory for Dos/Windows like systems.

    See also:    TEventType.LogType (128  )
                                                                                 133

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'EVENTLOG'___________________*
 *___________________
                9.5.18         TEventLog.TimeStampFormat

    Synopsis:    Format for the timestamp string

Declaration:     Property  TimeStampFormat  :  String

    Visibility:   published

      Access:    Read,Write

Description:     TimeStampFormat is the formatting string used to create a timestamp string when writing
                log messages to file.  It should have a format suitable for the FormatDateTime (??  ) call.  If
                it is left empty, then yyyy-mm-dd  hh:nn:ss.zzz is used.

    See also:    TEventLog.Identification (132  )
                9.5.19         TEventLog.CustomLogType

    Synopsis:    Custom log type ID

Declaration:     Property  CustomLogType  :  Word

    Visibility:   published

      Access:    Read,Write

Description:     CustomLogType  is  used  in  the  EventTypeToString  (130  )  to  format  the  custom  log  event
                type string.

    See also:    TEventLog.EventTypeToString (130  )
                9.5.20         TEventLog.EventIDOffset

    Synopsis:    Offset for event ID messages identifiers

Declaration:     Property  EventIDOffset  :  DWord

    Visibility:   published

      Access:    Read,Write

Description:     EventIDOffset is the offset for the message formatting strings in the windows resource file.
                This property is ignored on other platforms.

                The message strings in the file registered with the RegisterMessageFile (130  ) call are windows
                resource strings.  They each have a unique ID, which must be communicated to windows.  In
                the resource file distributed by Free Pascal, the resource strings are numbered from 1000 to
                1004.  The actual number communicated to windows is formed by adding the ordinal value
                of the message's eventtype to EventIDOffset (which is by default 1000), which means that
                by default, the string numbers are:


                1000   Custom event types

                1001   Information event type

                1002   Warning event type

                1003   Error event type

                1004   Debug event type


    See also:    TEventLog.RegisterMessageFile (130  )



                                                                                 134

                ______________________________________________________CHAPTER_9.___REFERENCE_FOR_UNIT_'EVENTLOG'___________________*
 *___________________
                9.5.21         TEventLog.OnGetCustomCategory

    Synopsis:    Event to retrieve custom message category

Declaration:     Property  OnGetCustomCategory  :  TLogCategoryEvent

    Visibility:   published

      Access:    Read,Write

Description:     OnGetCustomCategory  is  called  on  the  windows  platform  to  determine  the  category  of  a
                custom event type.  It should return an ID which will be used by windows to look up the
                string which describes the message category in the file containing the resource strings.

    See also:    TEventLog.OnGetCustomEventID (135  ), TEventLog.OnGetCustomEvent (135  )
                9.5.22         TEventLog.OnGetCustomEventID

    Synopsis:    Event to retrieve custom event ID

Declaration:     Property  OnGetCustomEventID  :  TLogCodeEvent

    Visibility:   published

      Access:    Read,Write

Description:     OnGetCustomEventID  is  called  on  the  windows  platform  to  determine  the  category  of  a
                custom event type.  It should return an ID which will be used by windows to look up the
                string which formats the message, in the file containing the resource strings.

    See also:    TEventLog.OnGetCustomCategory (135  ), TEventLog.OnGetCustomEvent (135  )
                9.5.23         TEventLog.OnGetCustomEvent

    Synopsis:    Event to retrieve custom event Code

Declaration:     Property  OnGetCustomEvent  :  TLogCodeEvent

    Visibility:   published

      Access:    Read,Write

Description:     OnGetCustomEvent  is  called  on  the  windows  platform  to  determine  the  event  code  of  a
                custom event type.  It should return an ID.

    See also:    TEventLog.OnGetCustomCategory (135  ), TEventLog.OnGetCustomEventID (135  )

                                                                                 135


Chapter   10


Reference   for   unit   'ezcgi'
10.1          Used  units
                                     Table 10.1:  Used units by unit 'ezcgi'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     strings         136
                                                     sysutils         ??



10.2          Overview


ezcgi,  written  by  Michael  Hess,  provides  a  single  class  which  offers  simple  access  to  the
CGI environment which a CGI program operates under.  It supports both GET and POST
methods.  It's intended for simple CGI programs which do not need full-blown CGI support.
File uploads are not supported by this component.

To use the unit, a descendent of the TEZCGI class should be created and the DoPost (139  )
or DoGet (139  ) methods should be overidden.
10.3          Constants,  types  and  variables



10.3.1         Constants

hexTable  =  '0123456789ABCDEF'


String constant used to convert a number to a hexadecimal code or back.
10.4          ECGIException



10.4.1         Description

Exception raised by TEZcgi (137  )



                                                             136

                _____________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'EZCGI'______________*
 *___________________
                10.5          TEZcgi



                10.5.1         Description

                TEZcgi implements all functionality to analyze the CGI environment and query the variables
                present in it.  It's main use is the exposed variables.

                Programs wishing to use this class should make a descendent class of this class and override
                the DoPost (139  ) or DoGet (139  ) methods.  To run the program, an instance of this class must
                be created, and it's Run (138  ) method should be invoked.  This will analyze the environment
                and call the DoPost or DoGet method, depending on what HTTP method was used to invoke
                the program.
                10.5.2         Method  overview

                __Page______Property_______________Description_____________________________________________________________________*
 *___________
                  137       Create                 Creates a new instance of the TEZCGI component
                  137       Destroy                Removes the TEZCGI component from memory
                  139       DoGet                  Method to handle GET requests
                  139       DoPost                 Method to handle POST requests
                  139       GetValue               Return the value of a request variable.
                  138       PutLine                Send a line of output to the web-client
                  138       Run                    Run the CGI application.
                __138_______WriteContent___________Writes_the_content_type_to_standard_output______________________________________*
 *___________
                10.5.3         Property  overview

                __Page______Property________________Access_______Description_______________________________________________________*
 *___________
                  141       Email                   rw           Email of the server administrator
                  141       Name                    rw           Name of the server administrator
                  140       Names                   r            Indexed array with available variable names.
                  139       Values                  r            Variables passed to the CGI script
                  141       VariableCount           r            Number of available variables.
                __141_______Variables_______________r____________Indexed_array_with_variables_as_name=value_pairs._________________*
 *___________
                10.5.4         TEZcgi.Create

    Synopsis:    Creates a new instance of the TEZCGI component

Declaration:     constructor  Create

    Visibility:   public

Description:     Create initializes the CGI program's environment: it reads the environment variables passed
                to the CGI program and stores them in the Variable (136  ) property.

    See also:    TZECGI.Variables (136  ), TZECGI.Names (136  ), TZECGI.Values (136  )
                10.5.5         TEZcgi.Destroy

    Synopsis:    Removes the TEZCGI component from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public



                                                                                 137

                _____________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'EZCGI'______________*
 *___________________
Description:     Destroy removes all variables from memory and then calls the inherited destroy, removing
                the TEZCGI instance from memory.

                Destroy should never be called directly.  Instead Free should be used, or FreeAndNil

    See also:    TEZcgi.Create (137  )
                10.5.6         TEZcgi.Run

    Synopsis:    Run the CGI application.

Declaration:     procedure  Run

    Visibility:   public

Description:     Run analyses the variables passed to the application, processes the request variables (it stores
                them in the Variables (136  ) property) and calls the DoPost (139  ) or DoGet (139  ) methods,
                depending on the method passed to the web server.

                After creating the instance of  TEZCGI, the Run method is the only method that should be
                called when using this component.

    See also:    TZECGI.Variables (136  ), TEZCGI.DoPost (139  ), TEZCGI.DoGet (139  )
                10.5.7         TEZcgi.WriteContent

    Synopsis:    Writes the content type to standard output

Declaration:     procedure  WriteContent(ctype:  String)

    Visibility:   public

Description:     WriteContent writes the content type cType to standard output, followed by an empty line.
                After this method was called, no more HTTP headers may be written to standard output.
                Any  HTTP  headers  should  be  written  before  WriteContent  is  called.  It  should  be  called
                from the DoPost (139  ) or DoGet (139  ) methods.

    See also:    TEZCGI.DoPost (139  ), TEZCGI.DoGet (139  ), TEZcgi.PutLine (138  )
                10.5.8         TEZcgi.PutLine

    Synopsis:    Send a line of output to the web-client

Declaration:     procedure  PutLine(sOut:  String)

    Visibility:   public

Description:     PutLine writes a line of text (sOut) to the web client (currently, to standard output).  It
                should be called only after WriteContent (138  ) was called with a content type of text.  The
                sent text is not processed in any way,  i.e.  no HTML entities or so are inserted instead of
                special HTML characters.  This should be done by the user.

       Errors:   No check is performed whether the content type is right.

    See also:    TEZcgi.WriteContent (138  )

                                                                                 138

                _____________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'EZCGI'______________*
 *___________________
                10.5.9         TEZcgi.GetValue

    Synopsis:    Return the value of a request variable.

Declaration:     function  GetValue(Index:  String;defaultValue:  String)  :  String

    Visibility:   public

Description:     GetValue returns the value of the variable named Index, and returns DefaultValue if it is
                empty or does not exist.

    See also:    TEZCGI.Values (139  )
                10.5.10          TEZcgi.DoPost

    Synopsis:    Method to handle POST requests

Declaration:     procedure  DoPost;    Virtual

    Visibility:   public

Description:     DoPost is called by the Run (138  ) method the POST method was used to invoke the CGI
                application.  It should be overridden in descendents of TEZcgi to actually handle the request.

    See also:    TEZcgi.Run (138  ), TEZcgi.DoGet (139  )
                10.5.11          TEZcgi.DoGet

    Synopsis:    Method to handle GET requests

Declaration:     procedure  DoGet;    Virtual

    Visibility:   public

Description:     DoGet  is  called  by  the  Run  (138  )  method  the  GET  method  was  used  to  invoke  the  CGI
                application.  It should be overridden in descendents of TEZcgi to actually handle the request.

    See also:    TEZcgi.Run (138  ), TEZcgi.DoPost (139  )
                10.5.12          TEZcgi.Values

    Synopsis:    Variables passed to the CGI script

Declaration:     Property  Values[Index:  String]:  String

    Visibility:   public

      Access:    Read

Description:     Values is a name-based array of variables that were passed to the script by the web server
                or the HTTP request.  The Index variable is the name of the variable whose value should be
                retrieved.  The following standard values are available:
                AUTH__TYPE            Authorization type

                CONTENT__LENGTH                    Content length

                CONTENT__TYPE                 Content type
                                                                                 139

                _____________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'EZCGI'______________*
 *___________________
                GATEWAY__INTERFACE                       Used gateway interface

                PATH__INFO          Requested URL

                PATH__TRANSLATED                    Transformed URL

                QUERY__STRING               Client query string

                REMOTE__ADDR                Address of remote client

                REMOTE__HOST               DNS name of remote client

                REMOTE__IDENT                Remote identity.

                REMOTE__USER               Remote user

                REQUEST__METHOD                    Request methods (POST or GET)

                SCRIPT__NAME              Script name

                SERVER__NAME               Server host name

                SERVER__PORT             Server port

                SERVER__PROTOCOL                    Server protocol

                SERVER__SOFTWARE                    Web server software

                HTTP__ACCEPT              Accepted responses

                HTTP__ACCEPT__CHARSET                        Accepted character sets

                HTTP__ACCEPT__ENCODING                          Accepted encodings

                HTTP__IF__MODIFIED__SINCE                       Proxy information

                HTTP__REFERER                Referring page

                HTTP__USER__AGENT                  Client software name


                Other than the standard list, any variables that were passed by the web-client request, are
                also available.  Note that the variables are case insensitive.

    See also:    TEZCGI.Variables (141  ), TEZCGI.Names (140  ), TEZCGI.GetValue (139  ), TEZcgi.VariableCount
                (141  )
                10.5.13          TEZcgi.Names

    Synopsis:    Indexed array with available variable names.

Declaration:     Property  Names[Index:  Integer]:  String

    Visibility:   public

      Access:    Read

Description:     Names provides indexed access to the available variable names.  The Index may run from 0
                to VariableCount (141  ).  Any other value will result in an exception being raised.

    See also:    TEZcgi.Variables (141  ), TEZcgi.Values (139  ), TEZcgi.GetValue (139  ), TEZcgi.VariableCount
                (141  )
                                                                                 140

                _____________________________________________________________CHAPTER_10.___REFERENCE_FOR_UNIT_'EZCGI'______________*
 *___________________
                10.5.14          TEZcgi.Variables

    Synopsis:    Indexed array with variables as name=value pairs.

Declaration:     Property  Variables[Index:  Integer]:  String

    Visibility:   public

      Access:    Read

Description:     Variables provides indexed access to the available variable names and values.  The variables
                are returned as Name=Value pairs.  The Index may run from 0 to VariableCount (141  ).  Any
                other value will result in an exception being raised.

    See also:    TEZcgi.Names (140  ), TEZcgi.Values (139  ), TEZcgi.GetValue (139  ), TEZcgi.VariableCount
                (141  )
                10.5.15          TEZcgi.VariableCount

    Synopsis:    Number of available variables.

Declaration:     Property  VariableCount  :  Integer

    Visibility:   public

      Access:    Read

Description:     TEZcgi.VariableCount returns the number of available CGI variables.  This includes both
                the standard CGI environment variables and the request variables.  The actual names and
                values can be retrieved with the Names (140  ) and Variables (141  ) properties.

    See also:    TEZcgi.Names (140  ), TEZcgi.Variables (141  ), TEZcgi.Values (139  ), TEZcgi.GetValue (139  )
                10.5.16          TEZcgi.Name

    Synopsis:    Name of the server administrator

Declaration:     Property  Name  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Name is used when displaying an error message to the user.  This should set prior to calling
                the TEZcgi.Run (138  ) method.

    See also:    TEZcgi.Run (138  ), TEZcgi.Email (141  )
                10.5.17          TEZcgi.Email

    Synopsis:    Email of the server administrator

Declaration:     Property  Email  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Email is used when displaying an error message to the user.  This should set prior to calling
                the TEZcgi.Run (138  ) method.

    See also:    TEZcgi.Run (138  ), TEZcgi.Name (141  )
                                                                                 141


Chapter   11


Reference   for   unit   'gettext'
11.1          Used  units
                                    Table 11.1:  Used units by unit 'gettext'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     sysutils         ??



11.2          Overview


The gettext unit can be used to hook into the resource string mechanism of Free Pascal to
provide  translations  of  the  resource  strings,  based  on  the  GNU  gettext  mechanism.   The
unit  provides  a  class  (TMOFile  (144  ))  to  read  the  .mo  files  with  localizations  for  various
languages.  It also provides a couple of calls to translate all resource strings in an application
based on the translations in a .mo file.
11.3          Constants,  types  and  variables



11.3.1         Constants

MOFileHeaderMagic  =  $950412de


This constant is found as the first integer in a .mo
11.3.2         Types

PLongWordArray  =  ^TLongWordArray


Pointer to a TLongWordArray (143  ) array.


PMOStringTable  =  ^TMOStringTable
                                                             142

            _______________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GETTEXT'______________________*
 *_______________
            Pointer to a TMOStringTable (143  ) array.


            PPCharArray  =  ^TPCharArray


            Pointer to a TPCharArray (143  ) array.


            TLongWordArray  =  Array[0..(1shl30)divSizeOf(LongWord)]  of  LongWord


            TLongWordArray is an array used to define the PLongWordArray (142  ) pointer.  A variable
            of  type  TLongWordArray  should  never  be  directly  declared,  as  it  would  occupy  too  much
            memory.  The PLongWordArray type can be used to allocate a dynamic number of elements.


            TMOFileHeader  =  packed  record
               magic  :  LongWord;
               revision  :  LongWord;
               nstrings  :  LongWord;
               OrigTabOffset  :  LongWord;
               TransTabOffset  :  LongWord;
               HashTabSize  :  LongWord;
               HashTabOffset  :  LongWord;
            end
            This structure describes the structure of a .mo file with string localizations.


            TMOStringInfo  =  packed  record
               length  :  LongWord;
               offset  :  LongWord;
            end
            This record is one element in the string tables describing the original and translated strings.
            It describes the position and length of the string.  The location of these tables is stored in
            the TMOFileHeader (143  ) record at the start of the file.


            TMOStringTable  =  Array[0..(1shl30)divSizeOf(TMOStringInfo)]  of  TMOStringInfo


            TMOStringTable is an array type containing TMOStringInfo (143  ) records.  It should never
            be used directly, as it would occupy too much memory.


            TPCharArray  =  Array[0..(1shl30)divSizeOf(PChar)]  of  PChar


            TLongWordArray is an array used to define the PPCharArray (143  ) pointer.  A variable of
            type TPCharArray should never be directly declared, as it would occupy too much memory.
            The PPCharArray type can be used to allocate a dynamic number of elements.
            11.4          Procedures  and  functions



            11.4.1         GetLanguageIDs

Synopsis:    Return the current language IDs



                                                                             143

                _______________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GETTEXT'__________________*
 *___________________
Declaration:     procedure  GetLanguageIDs(var  Lang:  String;var  FallbackLang:  String)

    Visibility:  default

Description:     GetLanguageIDs returns the current language IDs (an ISO string) as returned by the op-
                erating system.  On windows, the GetUserDefaultLCID and GetLocaleInfo calls are used.
                On  other  operating  systems,  the  LC_ALL,  LC_MESSAGES  or  LANG  environment  variables  are
                examined.
                11.4.2         TranslateResourceStrings

    Synopsis:    Translate the resource strings of the application.

Declaration:     procedure  TranslateResourceStrings(AFile:  TMOFile)
                procedure  TranslateResourceStrings(const  AFilename:  String)

    Visibility:   default

Description:     TranslateResourceStrings translates all the resource strings in the application based on
                the  values  in  the  .mo  file  AFileName  or  AFile.  The  procedure  creates  an  TMOFile  (144  )
                instance to read the .mo file if a filename is given.

       Errors:   If the file does not exist or is an invalid .mo file.

    See also:    TranslateUnitResourceStrings (144  ), TMOFile (144  )
                11.4.3         TranslateUnitResourceStrings

    Synopsis:    Translate the resource strings of a unit.

Declaration:     procedure  TranslateUnitResourceStrings(const  AUnitName:  String;
                                                                               AFile:  TMOFile)
                procedure  TranslateUnitResourceStrings(const  AUnitName:  String;
                                                                               const  AFilename:  String)

    Visibility:   default

Description:     TranslateUnitResourceStrings is identical in function to TranslateResourceStrings (144  ),
                but translates the strings of a single unit (AUnitName) which was used to compile the ap-
                plication.  This can be more convenient, since the resource string files are created on a unit
                basis.

    See also:    TranslateResourceStrings (144  ), TMOFile (144  )
                11.5          EMOFileError



                11.5.1         Description

                EMOFileError is raised in case an TMOFile (144  ) instance is created with an invalid .mo.
                11.6          TMOFile



                11.6.1         Description

                TMOFile is a class providing easy access to a .mo file.  It can be used to translate any of the
                strings that reside in the .mo file.  The internal structure of the .mo is completely hidden.



                                                                                 144

                _______________________________________________________CHAPTER_11.___REFERENCE_FOR_UNIT_'GETTEXT'__________________*
 *___________________
                11.6.2         Method  overview

                __Page______Property_________Description___________________________________________________________________________*
 *___________
                  145       Create           Create a new instance of the TMOFile class.
                  145       Destroy          Removes the TMOFile instance from memory
                __145_______Translate________Translate_a_string____________________________________________________________________*
 *___________
                11.6.3         TMOFile.Create

    Synopsis:    Create a new instance of the TMOFile class.

Declaration:     constructor  Create(const  AFilename:  String)
                constructor  Create(AStream:  TStream)

    Visibility:   public

Description:     Create creates a new instance of the MOFile class.  It opens the file AFileName or the stream
                AStream.  If a stream is provided, it should be seekable.

                The whole contents of the file is read into memory during the Create call.  This means that
                the stream is no longer needed after the Create call.

       Errors:   If the named file does not exist, then an exception may be raised.  If the file does not contain
                a valid TMOFileHeader (143  ) structure, then an EMOFileError (144  ) exception is raised.

    See also:    TMOFile.Destroy (145  )
                11.6.4         TMOFile.Destroy

    Synopsis:    Removes the TMOFile instance from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans the internal structures with the contents of the .mo.  After this the TMOFile
                instance is removed from memory.

    See also:    TMOFile.Create (145  )
                11.6.5         TMOFile.Translate

    Synopsis:    Translate a string

Declaration:     function  Translate(AOrig:  PChar;ALen:  Integer;AHash:  LongWord)  :  String
                function  Translate(AOrig:  String;AHash:  LongWord)  :  String
                function  Translate(AOrig:  String)  :  String

    Visibility:   public

Description:     Translate translates the string AOrig.  The string should be in the .mo file as-is.  The string
                can be given as a plain string, as a PChar (with length ALen).  If the hash value (AHash) of
                the string is not given, it is calculated.

                If the string is in the .mo file,  the translated string is returned.  If the string is not in the
                file, an empty string is returned.

       Errors:   None.

                                                                                 145


Chapter   12


Reference   for   unit   'idea'
12.1          Used  units
                                      Table 12.1:  Used units by unit 'idea'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     sysutils         ??



12.2          Overview


Besides some low level IDEA encryption routines, the IDEA unit also offers 2 streams which
offer on-the-fly encryption or decryption:  there are 2 stream objects:  A write-only encryption
stream which encrypts anything that is written to it, and a decription stream which decrypts
anything that is read from it.
12.3          Constants,  types  and  variables



12.3.1         Constants

IDEABLOCKSIZE  =  8


IDEA block size


IDEAKEYSIZE  =  16


IDEA Key size constant.


KEYLEN  =  (6  *  ROUNDS  +  4  )


Key length


ROUNDS  =  8


Number of rounds to encrypt



                                                             146

                _______________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'IDEA'_____________*
 *___________________
                12.3.2         Types

                IdeaCryptData  =  TIdeaCryptData


                Provided for backward functionality.


                IdeaCryptKey  =  TIdeaCryptKey


                Provided for backward functionality.


                IDEAkey  =  TIDEAKey


                Provided for backward functionality.


                TIdeaCryptData  =  Array[0..3]  of  Word


                TIdeaCryptData is an internal type, defined to hold data for encryption/decryption.


                TIdeaCryptKey  =  Array[0..7]  of  Word


                The actual encryption or decryption key for IDEA is 64-bit long.  This type is used to hold
                such a key.  It can be generated with the EnKeyIDEA (148  ) or DeKeyIDEA (148  ) algorithms
                depending on whether an encryption or decryption key is needed.


                TIDEAKey  =  Array[0..keylen-1]  of  Word


                The IDEA key should be filled by the user with some random data (say, a passphrase).  This
                key is used to generate the actual encryption/decryption keys.
                12.4          Procedures  and  functions



                12.4.1         CipherIdea

    Synopsis:    Encrypt or decrypt a buffer.

Declaration:     procedure  CipherIdea(Input:  TIdeaCryptData;var  outdata:  TIdeaCryptData;
                                                 z:  TIDEAKey)

    Visibility:   default

Description:     CipherIdea  encrypts  or  decrypts  a  buffer  with  data  (Input)  using  key  z.  The  resulting
                encrypted or decrypted data is returned in Output.

       Errors:   None.

    See also:    EnKeyIdea  (148  ),  DeKeyIdea  (148  ),  TIDEAEncryptStream  (149  ),  TIDEADecryptStream
                (148  )


                                                                                 147

                _______________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'IDEA'_____________*
 *___________________
                12.4.2         DeKeyIdea

    Synopsis:    Create a decryption key from an encryption key.

Declaration:     procedure  DeKeyIdea(z:  TIDEAKey;var  dk:  TIDEAKey)

    Visibility:   default

Description:     DeKeyIdea creates a decryption key based on the encryption key z.  The decryption key is
                returned in dk.  Note that only a decryption key generated from the encryption key that was
                used to encrypt the data can be used to decrypt the data.

       Errors:   None.

    See also:    EnKeyIdea (148  ), CipherIdea (147  )
                12.4.3         EnKeyIdea

    Synopsis:    Create an IDEA encryption key from a user key.

Declaration:     procedure  EnKeyIdea(UserKey:  TIdeaCryptKey;var  z:  TIDEAKey)

    Visibility:   default

Description:     EnKeyIdea creates an IDEA encryption key from user-supplied data in UserKey.  The En-
                cryption key is stored in z.

       Errors:   None.

    See also:    DeKeyIdea (148  ), CipherIdea (147  )
                12.5          EIDEAError



                12.5.1         Description

                EIDEAError is used to signal errors in the IDEA encryption decryption streams.
                12.6          TIDEADeCryptStream



                12.6.1         Description

                TIDEADecryptStream  is  a  stream  which  decrypts  anything  that  is  read  from  it  using  the
                IDEA mechanism.  It reads the encrypted data from a source stream and decrypts it using
                the CipherIDEA (147  ) algorithm.  It is a read-only stream:  it is not possible to write data
                to this stream.

                When creating a TIDEADecryptStream instance, an IDEA decryption key should be passed
                to the constructor, as well as the stream from which encrypted data should be read written.

                The encrypted data can be created with a TIDEAEncryptStream (149  ) encryption stream.
                12.6.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  149       Read            Reads data from the stream, decrypting it as needed
                __149_______Seek____________Set_position_on_the_stream_____________________________________________________________*
 *___________
                                                                                 148

                _______________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'IDEA'_____________*
 *___________________
                12.6.3         TIDEADeCryptStream.Read

    Synopsis:    Reads data from the stream, decrypting it as needed

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read attempts to read Count bytes from the stream, placing them in Buffer the bytes are
                read from the source stream and decrypted as they are read.  (bytes are read from the source
                stream in blocks of 8 bytes.  The function returns the number of bytes actually read.

       Errors:   If an error occurs when reading data from the source stream, an exception may be raised.

    See also:    TIDEADecryptStream.Write (148  ), TIDEADecryptStream.Seek (149  ), TIDEAEncryptStream
                (149  )
                12.6.4         TIDEADeCryptStream.Seek

    Synopsis:    Set position on the stream

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek will only work on a forward seek.  It emulates a forward seek by reading and discard-
                ing  bytes  from  the  input  stream.   The  TIDEADecryptStream  stream  tries  to  provide  seek
                capabilities for the following limited number of cases:


                Origin=soFromBeginning                  If  Offset is larger than the current position, then the remain-
                       ing bytes are skipped by reading them from the stream and discarding them.

                Origin=soFromCurrent                 If Offset is zero, the current position is returned.  If it is positive,
                       then Offset bytes are skipped by reading them from the stream and discarding them.


       Errors:   An EIDEAError (148  ) exception is raised if the stream does not allow the requested seek
                operation.

    See also:    TIDEADeCryptStream.Read (149  )
                12.7          TIDEAEncryptStream



                12.7.1         Description

                TIDEAEncryptStream  is  a  stream  which  encrypts  anything  that  is  written  to  it  using  the
                IDEA mechanism, and then writes the encrypted data to the destination stream using the
                CipherIDEA (147  ) algorithm.  It is a write-only stream:  it is not possible to read data from
                this stream.

                When creating a TIDEAEncryptStream instance, an IDEA encryption key should be passed
                to the constructor, as well as the stream to which encrypted data should be written.

                The resulting encrypted data can be read again with a TIDEADecryptStream (148  ) decryp-
                tion stream.



                                                                                 149

                _______________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'IDEA'_____________*
 *___________________
                12.7.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  150       Destroy         Flush data buffers and free the stream instance.
                  151       Flush           Write remaining bytes from the stream
                  150       Seek            Set stream position
                __150_______Write___________Write_bytes_to_the_stream_to_be_encrypted______________________________________________*
 *___________
                12.7.3         TIDEAEncryptStream.Destroy

    Synopsis:    Flush data buffers and free the stream instance.

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy flushes any data still remaining in the internal encryption buffer,  and then calls
                the inherited Destroy

                By default, the destination stream is not freed when the encryption stream is freed.

       Errors:   None.

    See also:    TIDEAStream.Create (151  )
                12.7.4         TIDEAEncryptStream.Write

    Synopsis:    Write bytes to the stream to be encrypted

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write  writes  Count  bytes  from  Buffer  to  the  stream,  encrypting  the  bytes  as  they  are
                written (encryption in blocks of 8 bytes).

       Errors:   If an error occurs writing to the destination stream, an error may occur.

    See also:    TIDEADecryptStream.Read (149  )
                12.7.5         TIDEAEncryptStream.Seek

    Synopsis:    Set stream position

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek return the current position if called with 0 and soFromCurrent as arguments.  With
                all other values, it will always raise an exception, since it is impossible to set the position on
                an encryption stream.

       Errors:   An EIDEAError (148  ) will be raised unless called with 0 and soFromCurrent as arguments.

    See also:    TIDEAEncryptStream.Write (150  ), EIDEAError (148  )


                                                                                 150

                _______________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'IDEA'_____________*
 *___________________
                12.7.6         TIDEAEncryptStream.Flush

    Synopsis:    Write remaining bytes from the stream

Declaration:     procedure  Flush

    Visibility:   public

Description:     Flush  writes  the  current  encryption  buffer  to  the  stream.  Encryption  always  happens  in
                blocks of 8 bytes, so if the buffer is not completely filled at the end of the writing operations, it
                must be flushed.  It should never be called directly, unless at the end of all writing operations.
                It is called automatically when the stream is destroyed.

       Errors:   None.

    See also:    TIDEAEncryptStream.Write (150  )
                12.8          TIDEAStream



                12.8.1         Description

                Do not create instances of  TIDEAStream directly.  It implements no useful functionality:  it
                serves as a common ancestor of the TIDEAEncryptStream (149  ) and TIDEADeCryptStream
                (148  ), and simply provides some fields that these descendent classes use when encrypting/de-
                crypting.  One of these classes should be created, depending on whether one wishes to encrypt
                or to decrypt.
                12.8.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __151_______Create__________Creates_a_new_instance_of_the_TIDEAStream_class________________________________________*
 *___________
                12.8.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __152_______Key_____________r____________Key_used_when_encrypting/decrypting_______________________________________*
 *___________
                12.8.4         TIDEAStream.Create

    Synopsis:    Creates a new instance of the TIDEAStream class

Declaration:     constructor  Create(AKey:  TIDEAKey;Dest:  TStream)

    Visibility:   public

Description:     Create stores the encryption/decryption key and then calls the inherited Create to store
                the Dest stream.

       Errors:   None.

    See also:    TIDEAEncryptStream (149  ), TIDEADeCryptStream (148  )



                                                                                 151

                _______________________________________________________________CHAPTER_12.___REFERENCE_FOR_UNIT_'IDEA'_____________*
 *___________________
                12.8.5         TIDEAStream.Key

    Synopsis:    Key used when encrypting/decrypting

Declaration:     Property  Key  :  TIDEAKey

    Visibility:   public

      Access:    Read

Description:     Key is the key as it was passed to the constructor of the stream.  It cannot be changed while
                data is read or written.  It is the key as it is used when encrypting/decrypting.

    See also:    CipherIdea (147  )

                                                                                 152


Chapter   13


Reference   for   unit   'inicol'
13.1          Used  units
                                     Table 13.1:  Used units by unit 'inicol'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     Inifiles        153
                                                     sysutils         ??



13.2          Overview


inicol contains an implementation of TCollection and TCollectionItem descendents which
cooperate to read and write the collection from and to a .ini file.  It uses the TCustomIniFile
(163  ) class for this.
13.3          Constants,  types  and  variables



13.3.1         Constants

KeyCount  =  'Count'


KeyCount is used as a key name when reading or writing the number of items in the collection
from the global section.


SGlobal  =  'Global'


SGlobal  is  used  as  the  default  name  of  the  global  section  when  reading  or  writing  the
collection.


                                                             153

                ___________________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'INICOL'_______________*
 *___________________
                13.4          EIniCol



                13.4.1         Description

                EIniCol is used to report error conditions in the load and save methods of TIniCollection
                (154  ).
                13.5          TIniCollection



                13.5.1         Description

                TIniCollection is a collection (??  ) descendent which has the capability to write itself to an
                .ini file.  It introduces some load and save mechanisms, which can be used to write all items
                in the collection to disk.  The items should be descendents of the type TIniCollectionItem
                (157  ).

                All methods work using a TCustomInifile class, making it possible to save to alternate file
                formats, or even databases.

                An instance of TIniCollection should never be used directly.  Instead, a descendent should
                be used, which sets the FPrefix and FSectionPrefix protected variables.
                13.5.2         Method  overview

                __Page______Property_______________Description_____________________________________________________________________*
 *___________
                  154       Load                   Loads the collection from the default filename.
                  156       LoadFromFile           Load collection from file.
                  156       LoadFromIni            Load collection from a file in .ini file format.
                  155       Save                   Save the collection to the default filename.
                  155       SaveToFile             Save collection to a file in .ini file format
                __155_______SaveToIni______________Save_the_collection_to_a_TCustomIniFile_descendent______________________________*
 *___________
                13.5.3         Property  overview

                __Page______Property_______________Access_______Description________________________________________________________*
 *___________
                  157       FileName               rw           Filename of the collection
                  157       GlobalSection          rw           Name of the global section
                  156       Prefix                 r            Prefix used in global section
                __157_______SectionPrefix__________r____________Prefix_string_for_section_names____________________________________*
 *___________
                13.5.4         TIniCollection.Load

    Synopsis:    Loads the collection from the default filename.

Declaration:     procedure  Load

    Visibility:   public

Description:     Load loads the collection from the file as specified in the FileName (157  ) property.  It calls
                the LoadFromFile (156  ) method to do this.

       Errors:   If the collection was not loaded or saved to file before this call, an EIniCol exception will
                be raised.

    See also:    TIniCollection.LoadFromFile (156  ), TIniCollection.LoadFromIni (156  ), TIniCollection.Save
                (155  ), TIniCollection.FileName (157  )



                                                                                 154

                ___________________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'INICOL'_______________*
 *___________________
                13.5.5         TIniCollection.Save

    Synopsis:    Save the collection to the default filename.

Declaration:     procedure  Save

    Visibility:   public

Description:     Save  writes  the  collection  to  the  file  as  specified  in  the  FileName  (157  )  property,  using
                GlobalSection (157  ) as the section.  It calls the SaveToFile (155  ) method to do this.

       Errors:   If the collection was not loaded or saved to file before this call, an EIniCol exception will
                be raised.

    See also:    TIniCollection.SaveToFile (155  ), TIniCollection.SaveToIni (155  ), TIniCollection.Load (154  ),
                TIniCollection.FileName (157  )
                13.5.6         TIniCollection.SaveToIni

    Synopsis:    Save the collection to a TCustomIniFile descendent

Declaration:     procedure  SaveToIni(Ini:  TCustomInifile;Section:  String);    Virtual

    Visibility:   public

Description:     SaveToIni does the actual writing.  It writes the number of elements in the global section
                (as specified by the Section argument), as well as the section name for each item in the list.
                The item names are written using the Prefix (156  ) property for the key.  After this it calls
                the SaveToIni (158  ) method of all TIniCollectionItem (157  ) instances.

                This means that the global section of the .ini file will look something like this:


                [globalsection]
                Count=3
                Prefix1=SectionPrefixFirstItemName
                Prefix2=SectionPrefixSecondItemName
                Prefix3=SectionPrefixThirdItemName


                This construct allows to re-use an ini file for multiple collections.

                After this method is called, the GlobalSection (157  ) property contains the value of Section,
                it will be used in the Save (157  ) method.

    See also:    TIniCollectionItem.SaveToIni (158  )
                13.5.7         TIniCollection.SaveToFile

    Synopsis:    Save collection to a file in .ini file format

Declaration:     procedure  SaveToFile(AFileName:  String;Section:  String)

    Visibility:   public

Description:     SaveToFile  will  create  a  TMemIniFile  instance  with  the  AFileName  argument  as  a  file-
                name.  This instance is passed on to the SaveToIni (155  ) method, together with the Section
                argument, to do the actual saving.

       Errors:   An exception may be raised if the path in AFileName does not exist.

    See also:    TIniCollection.SaveToIni (155  ), TIniCollection.LoadFromFile (156  )



                                                                                 155

                ___________________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'INICOL'_______________*
 *___________________
                13.5.8         TIniCollection.LoadFromIni

    Synopsis:    Load collection from a file in .ini file format.

Declaration:     procedure  LoadFromIni(Ini:  TCustomInifile;Section:  String);    Virtual

    Visibility:   public

Description:     LoadFromIni  will  load  the  collection  from  the  Ini  instance.  It  first  clears  the  collection,
                and reads the number of items from the global section with the name as passed through the
                Section argument.  After this, an item is created and added to the collection, and its data is
                read by calling the TIniCollectionItem.LoadFromIni (158  ) method, passing the appropriate
                section name as found in the global section.

                The  description  of  the  global  section  can  be  found  in  the  TIniCollection.SaveToIni  (155  )
                method description.

    See also:    TIniCollection.LoadFromFile (156  ), TIniCollectionItem.LoadFromIni (158  ), TIniCollection.SaveToIni
                (155  )
                13.5.9         TIniCollection.LoadFromFile

    Synopsis:    Load collection from file.

Declaration:     procedure  LoadFromFile(AFileName:  String;Section:  String)

    Visibility:   public

Description:     LoadFromFile  creates  a  TMemIniFile  instance  using  AFileName  as  the  filename.  It  calls
                LoadFromIni (156  ) using this instance and Section as the parameters.

    See also:    TIniCollection.LoadFromIni (156  ), TIniCollection.Load (154  ), TIniCollection.SaveToIni (155  ),
                TIniCollection.SaveToFile (155  )
                13.5.10          TIniCollection.Prefix

    Synopsis:    Prefix used in global section

Declaration:     Property  Prefix  :  String

    Visibility:   public

      Access:    Read

Description:     Prefix is used when writing the section names of the items in the collection to the global
                section, or when reading the names from the global section.  If the prefix is set to Item then
                the global section might look something like this:


                [MyCollection]
                Count=2
                Item1=FirstItem
                Item2=SecondItem


                A descendent of  TIniCollection should set the value of this property, it cannot be empty.

    See also:    TIniCollection.SectionPrefix (157  ), TIniCollection.GlobalSection (157  )



                                                                                 156

                ___________________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'INICOL'_______________*
 *___________________
                13.5.11          TIniCollection.SectionPrefix

    Synopsis:    Prefix string for section names

Declaration:     Property  SectionPrefix  :  String

    Visibility:   public

      Access:    Read

Description:     SectionPrefix is a string that is prepended to the section name as returned by the TIni-
                CollectionItem.SectionName  (159  )  property  to  return  the  exact  section  name.   It  can  be
                empty.

    See also:    TIniCollection.Section (154  ), TIniCollection.GlobalSection (157  )
                13.5.12          TIniCollection.FileName

    Synopsis:    Filename of the collection

Declaration:     Property  FileName  :  String

    Visibility:   public

      Access:    Read,Write

Description:     FileName is the filename as used in the last LoadFromFile (156  ) or SaveToFile (155  ) oper-
                ation.  It is used in the Load (154  ) or Save (155  ) calls.

    See also:    TIniCollection.Save  (155  ),  TIniCollection.LoadFromFile  (156  ),  TIniCollection.SaveToFile
                (155  ), TIniCollection.Load (154  )
                13.5.13          TIniCollection.GlobalSection

    Synopsis:    Name of the global section

Declaration:     Property  GlobalSection  :  String

    Visibility:   public

      Access:    Read,Write

Description:     GlobalSection contains the value of the Section argument in the LoadFromIni (156  ) or
                SaveToIni (155  ) calls.  It's used in the Load (154  ) or Save (155  ) calls.

    See also:    TIniCollection.Save  (155  ),  TIniCollection.LoadFromFile  (156  ),  TIniCollection.SaveToFile
                (155  ), TIniCollection.Load (154  )
                13.6          TIniCollectionItem



                13.6.1         Description

                TIniCollectionItem is a #rtl.classes.tcollectionitem (??  ) descendent which has some extra
                methods for saving/loading the item to or from an .ini file.

                To use this class, a descendent should be made, and the SaveToIni (158  ) and LoadFromIni
                (158  )  methods  should  be  overridden.  They  should  implement  the  actual  loading  and  sav-
                ing.   The  loading  and  saving  is  always  initiated  by  the  methods  in  TIniCollection  (154  ),
                TIniCollection.LoadFromIni (156  ) and TIniCollection.SaveToIni (155  ) respectively.



                                                                                 157

                ___________________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'INICOL'_______________*
 *___________________
                13.6.2         Method  overview

                __Page______Property_______________Description_____________________________________________________________________*
 *___________
                  159       LoadFromFile           Load item from a file
                  158       LoadFromIni            Method called when the item must be loaded
                  158       SaveToFile             Save item to a file
                __158_______SaveToIni______________Method_called_when_the_item_must_be_saved_______________________________________*
 *___________
                13.6.3         Property  overview

                __Page______Property______________Access_______Description_________________________________________________________*
 *___________
                __159_______SectionName___________rw___________Default_section_name________________________________________________*
 *___________
                13.6.4         TIniCollectionItem.SaveToIni

    Synopsis:    Method called when the item must be saved

Declaration:     procedure  SaveToIni(Ini:  TCustomInifile;Section:  String);    Virtual
                                                ;    Abstract

    Visibility:   public

Description:     SaveToIni is called by TIniCollection.SaveToIni (155  ) when it saves this item.  Descendent
                classes should override this method to save the data they need to save.  All write methods
                of the TCustomIniFile instance passed in Ini can be used, as long as the writing happens
                in the section passed in Section.

       Errors:   No checking is done to see whether the values are actually written to the correct section.

    See also:    TIniCollection.SaveToIni (155  ), TIniCollectionItem.LoadFromIni (158  ), TIniCollectionItem.SaveToFile
                (158  ), TIniCollectionItem.LoadFromFile (159  )
                13.6.5         TIniCollectionItem.LoadFromIni

    Synopsis:    Method called when the item must be loaded

Declaration:     procedure  LoadFromIni(Ini:  TCustomInifile;Section:  String);    Virtual
                                                   ;    Abstract

    Visibility:   public

Description:     LoadFromIni  is  called  by  TIniCollection.LoadFromIni  (156  )  when  it  saves  this  item.  De-
                scendent classes should override this method to load the data they need to load.  All read
                methods of the TCustomIniFile instance passed in Ini can be used, as long as the reading
                happens in the section passed in Section.

       Errors:   No checking is done to see whether the values are actually read from the correct section.

    See also:    TIniCollection.LoadFromIni (156  ), TIniCollectionItem.SaveToIni (158  ), TIniCollectionItem.LoadFromFile
                (159  ), TIniCollectionItem.SaveToFile (158  )
                13.6.6         TIniCollectionItem.SaveToFile

    Synopsis:    Save item to a file

Declaration:     procedure  SaveToFile(FileName:  String;Section:  String)
                                                                                 158

                ___________________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'INICOL'_______________*
 *___________________
    Visibility:  public

Description:     SaveToFile creates an instance of  TIniFile with the indicated FileName calls SaveToIni
                (158  ) to save the item to the indicated file in .ini format under the section Section

       Errors:   An exception can occur if the file is not writeable.

    See also:    TIniCollectionItem.SaveToIni (158  ), TIniCollectionItem.LoadFromFile (159  )
                13.6.7         TIniCollectionItem.LoadFromFile

    Synopsis:    Load item from a file

Declaration:     procedure  LoadFromFile(FileName:  String;Section:  String)

    Visibility:   public

Description:     LoadFromFile creates an instance of TMemIniFile and calls LoadFromIni (158  ) to load the
                item from the indicated file in .ini format from the section Section.

       Errors:   None.

    See also:    TIniCollectionItem.SaveToFile (158  ), TIniCollectionItem.LoadFromIni (158  )
                13.6.8         TIniCollectionItem.SectionName

    Synopsis:    Default section name

Declaration:     Property  SectionName  :  String

    Visibility:   public

      Access:    Read,Write

Description:     SectionName is the section name under which the item will be saved or from which it should
                be read.  The read/write functions should be overridden in descendents to determine a unique
                section name within the .ini file.

    See also:    TIniCollectionItem.SaveToFile (158  ), TIniCollectionItem.LoadFromIni (158  )
                13.7          TNamedIniCollection



                13.7.1         Description

                TNamedIniCollection is the collection to go with the TNamedIniCollectionItem (161  ) item
                class.  it provides some functions to look for items based on the UserData (160  ) or based on
                the Name (160  ).
                13.7.2         Method  overview

                __Page______Property____________________Description________________________________________________________________*
 *___________
                  160       FindByName                  Return the item based on its name
                  161       FindByUserData              Return the item based on its UserData
                  160       IndexOfName                 Search for an item, based on its name, and return its position
                __160_______IndexOfUserData_____________Search_for_an_item_based_on_it's_UserData_property_________________________*
 *___________

                                                                                 159

                ___________________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'INICOL'_______________*
 *___________________
                13.7.3         Property  overview

                __Page______Property______________Access______Description__________________________________________________________*
 *___________
                __161_______NamedItems____________rw__________Indexed_access_to_the_TNamedIniCollectionItem_items__________________*
 *___________
                13.7.4         TNamedIniCollection.IndexOfUserData

    Synopsis:    Search for an item based on it's UserData property

Declaration:     function  IndexOfUserData(UserData:  TObject)  :  Integer

    Visibility:   public

Description:     IndexOfUserData  searches  the  list  of  items  and  returns  the  index  of  the  item  which  has
                UserData in its UserData (160  ) property.  If no such item exists, -1 is returned.

                Note that the (linear) search starts at the last element and works it's way back to the first.

       Errors:   If no item exists, -1 is returned.

    See also:    TNamedIniCollection.IndexOfName (160  ), TNamedIniCollectionItem.UserData (161  )
                13.7.5         TNamedIniCollection.IndexOfName

    Synopsis:    Search for an item, based on its name, and return its position

Declaration:     function  IndexOfName(const  AName:  String)  :  Integer

    Visibility:   public

Description:     IndexOfName searches the list of items and returns the index of the item which has name
                equal to AName (case insentitive).  If no such item exists, -1 is returned.

                Note that the (linear) search starts at the last element and works it's way back to the first.

       Errors:   If no item exists, -1 is returned.

    See also:    TNamedIniCollection.IndexOfUserData (160  ), TNamedIniCollectionItem.Name (162  )
                13.7.6         TNamedIniCollection.FindByName

    Synopsis:    Return the item based on its name

Declaration:     function  FindByName(const  AName:  String)  :  TNamedIniCollectionItem

    Visibility:   public

Description:     FindByName returns the collection item whose name matches AName (case insensitive match).
                It calls IndexOfName (160  ) and returns the item at the found position.  If no item is found,
                Nil is returned.

       Errors:   If no item is found, Nil is returned.

    See also:    TNamedIniCollection.IndexOfName (160  ), TNamedIniCollection.FindByUserData (161  )

                                                                                 160

                ___________________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'INICOL'_______________*
 *___________________
                13.7.7         TNamedIniCollection.FindByUserData

    Synopsis:    Return the item based on its UserData

Declaration:     function  FindByUserData(UserData:  TObject)  :  TNamedIniCollectionItem

    Visibility:   public

Description:     FindByName returns the collection item whose UserData (161  ) property value matches the
                UserData parameter.  If no item is found, Nil is returned.

       Errors:   If no item is found, Nil is returned.
                13.7.8         TNamedIniCollection.NamedItems

    Synopsis:    Indexed access to the TNamedIniCollectionItem items

Declaration:     Property  NamedItems[Index:  Integer]:  TNamedIniCollectionItem;  default

    Visibility:   public

      Access:    Read,Write

Description:     NamedItem is the default property of the TNamedIniCollection collection.  It allows indexed
                access to the TNamedIniCollectionItem (161  ) items.  The index is zero based.

    See also:    TNamedIniCollectionItem (161  )
                13.8          TNamedIniCollectionItem



                13.8.1         Description

                TNamedIniCollectionItem  is  a  TIniCollectionItem  (157  )  descent  with  a  published  name
                property.  The name is used as the section name when saving the item to the ini file.
                13.8.2         Property  overview

                __Page______Property_________Access_______Description______________________________________________________________*
 *___________
                  162       Name             rw           Name of the item
                __161_______UserData_________rw___________User-defined_data________________________________________________________*
 *___________
                13.8.3         TNamedIniCollectionItem.UserData

    Synopsis:    User-defined data

Declaration:     Property  UserData  :  TObject

    Visibility:   public

      Access:    Read,Write

Description:     UserData can be used to associate an arbitrary object with the item - much like the Objects
                property of a TStrings.

                                                                                 161

                ___________________________________________________________CHAPTER_13.___REFERENCE_FOR_UNIT_'INICOL'_______________*
 *___________________
                13.8.4         TNamedIniCollectionItem.Name

    Synopsis:    Name of the item

Declaration:     Property  Name  :  String

    Visibility:   published

      Access:    Read,Write

Description:     Name is the name of this item.  It is also used as the section name when writing the collection
                item to the .ini file.

    See also:    TNamedIniCollectionItem.UserData (161  )

                                                                                 162


Chapter   14


Reference   for   unit   'IniFiles'
14.1          Used  units
                                    Table 14.1:  Used units by unit 'IniFiles'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     contnrs          52
                                                     sysutils         ??



14.2          Overview


IniFiles  provides  support  for  handling  .ini  files.   It  contains  an  implementation  completely
independent of the Windows API for handling such files.  The basic (abstract) functionality
is defined in TCustomInifile (163  ) and is implemented in TIniFile (175  ) and TMemIniFile
(184  ).  The API presented by these components is Delphi compatible.
14.3          TCustomIniFile



14.3.1         Description

TCustomIniFile implements all calls for manipulating a .ini.  It does not implement any of
this behaviour, the behaviour must be implemented in a descendent class like TIniFile (175  )
or TMemIniFile (184  ).

Since TCustomIniFile is an abstract class, it should never be created directly.  Instead, one
of the TIniFile or TMemIniFile classes should be created.
                                                             163

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.3.2         Method  overview

                __Page______Property_______________________Description_____________________________________________________________*
 *___________
                  164       Create                         Instantiate a new instance of  TCustomIniFile.
                  172       DeleteKey                      Delete a key from a section
                  165       Destroy                        Remove the TCustomIniFile instance from memory
                  171       EraseSection                   Clear a section
                  169       ReadBinaryStream               Read binary data
                  166       ReadBool
                  167       ReadDate                       Read a date value
                  168       ReadDateTime                   Read a Date/Time value
                  168       ReadFloat                      Read a floating point value
                  166       ReadInteger                    Read an integer value from the file
                  171       ReadSection                    Read the key names in a section
                  171       ReadSections                   Read the list of sections
                  171       ReadSectionValues              Read names and values of a section
                  165       ReadString                     Read a string valued key
                  168       ReadTime                       Read a time value
                  165       SectionExists                  Check if a section exists.
                  172       UpdateFile                     Update the file on disk
                  172       ValueExists                    Check if a value exists
                  170       WriteBinaryStream              Write binary data
                  167       WriteBool                      Write boolean value
                  169       WriteDate                      Write date value
                  169       WriteDateTime                  Write date/time value
                  170       WriteFloat                     Write a floating-point value
                  166       WriteInteger                   Write an integer value
                  166       WriteString                    Write a string value
                __170_______WriteTime______________________Write_time_value________________________________________________________*
 *___________
                14.3.3         Property  overview

                __Page______Property___________________Access_______Description____________________________________________________*
 *___________
                  173       CaseSensitive              rw           Are key and section names case sensitive
                  173       EscapeLineFeeds            r            Should linefeeds be escaped ?
                  172       FileName                   r            Name of the .ini file
                __173_______StripQuotes________________rw___________Should_quotes_be_stripped_from_string_values___________________*
 *___________
                14.3.4         TCustomIniFile.Create

    Synopsis:    Instantiate a new instance of  TCustomIniFile.

Declaration:     constructor  Create(const  AFileName:  String;AEscapeLineFeeds:  Boolean)
                                              ;    Virtual

    Visibility:   public

Description:     Create creates a new instance of TCustomIniFile and loads it with the data from AFileName,
                if this file exists.  If the AEscapeLineFeeds parameter is True, then lines which have their
                end-of-line  markers  escaped  with  a  backslash,  will  be  concatenated.  This  means  that  the
                following 2 lines


                Description=This  is  a  \
                line  with  a  long  text
                                                                                 164

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                is equivalent to


                Description=This  is  a  line  with  a  long  text


                By default, not escaping of linefeeds is performed (for Delphi compatibility)

       Errors:   If the file cannot be read, an exception may be raised.

    See also:    TCustomIniFile.Destroy (165  )
                14.3.5         TCustomIniFile.Destroy

    Synopsis:    Remove the TCustomIniFile instance from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans up all internal structures and then calls the inherited Destroy.

    See also:    TCustomIniFile (163  )
                14.3.6         TCustomIniFile.SectionExists

    Synopsis:    Check if a section exists.

Declaration:     function  SectionExists(const  Section:  String)  :  Boolean;    Virtual

    Visibility:   public

Description:     SectionExists  returns  True  if  a  section  with  name  Section  exists,  and  contains  keys.
                (comments are not considered keys)

    See also:    TCustomIniFile.ValueExists (172  )
                14.3.7         TCustomIniFile.ReadString

    Synopsis:    Read a string valued key

Declaration:     function  ReadString(const  Section:  String;const  Ident:  String;
                                                const  Default:  String)  :  String;    Virtual;    Abstract

    Visibility:   public

Description:     ReadString reads the key Ident in section Section, and returns the value as a string.  If
                the specified key or section do not exist, then the value in Default is returned.  Note that if
                the key exists, but is empty, an empty string will be returned.

    See also:    TCustomIniFile.WriteString (166  ), TCustomIniFile.ReadInteger (166  ), TCustomIniFile.ReadBool
                (166  ), TCustomIniFile.ReadDate (167  ), TCustomIniFile.ReadDateTime (168  ), TCustomIniFile.ReadTime
                (168  ), TCustomIniFile.ReadFloat (168  ), TCustomIniFile.ReadBinaryStream (169  )

                                                                                 165

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.3.8         TCustomIniFile.WriteString

    Synopsis:    Write a string value

Declaration:     procedure  WriteString(const  Section:  String;const  Ident:  String;
                                                   const  Value:  String);    Virtual;    Abstract

    Visibility:   public

Description:     WriteString writes the string  Value with the name Ident to the section Section,  over-
                writing any previous value that may exist there.  The section will be created if it does not
                exist.

    See also:    TCustomIniFile.ReadString (165  ), TCustomIniFile.WriteInteger (166  ), TCustomIniFile.WriteBool
                (167  ), TCustomIniFile.WriteDate (169  ), TCustomIniFile.WriteDateTime (169  ), TCustomIniFile.WriteTime
                (170  ), TCustomIniFile.WriteFloat (170  ), TCustomIniFile.WriteBinaryStream (170  )
                14.3.9         TCustomIniFile.ReadInteger

    Synopsis:    Read an integer value from the file

Declaration:     function  ReadInteger(const  Section:  String;const  Ident:  String;
                                                 Default:  LongInt)  :  LongInt;    Virtual

    Visibility:   public

Description:     ReadInteger reads the key Ident in section Section, and returns the value as an integer.
                If the specified key or section do not exist, then the value in Default is returned.  If the key
                exists, but contains an invalid integer value, Default is also returned.

    See also:    TCustomIniFile.WriteInteger (166  ), TCustomIniFile.ReadString (165  ), TCustomIniFile.ReadBool
                (166  ), TCustomIniFile.ReadDate (167  ), TCustomIniFile.ReadDateTime (168  ), TCustomIniFile.ReadTime
                (168  ), TCustomIniFile.ReadFloat (168  ), TCustomIniFile.ReadBinaryStream (169  )
                14.3.10          TCustomIniFile.WriteInteger

    Synopsis:    Write an integer value

Declaration:     procedure  WriteInteger(const  Section:  String;const  Ident:  String;
                                                     Value:  LongInt);    Virtual

    Visibility:   public

Description:     WriteInteger writes the integer Value with the name Ident to the section Section, over-
                writing any previous value that may exist there.  The section will be created if it does not
                exist.

    See also:    TCustomIniFile.ReadInteger (166  ), TCustomIniFile.WriteString (166  ), TCustomIniFile.WriteBool
                (167  ), TCustomIniFile.WriteDate (169  ), TCustomIniFile.WriteDateTime (169  ), TCustomIniFile.WriteTime
                (170  ), TCustomIniFile.WriteFloat (170  ), TCustomIniFile.WriteBinaryStream (170  )
                14.3.11          TCustomIniFile.ReadBool

    Synopsis:

Declaration:     function  ReadBool(const  Section:  String;const  Ident:  String;
                                            Default:  Boolean)  :  Boolean;    Virtual
                                                                                 166

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
    Visibility:  public

Description:     ReadString  reads  the  key  Ident  in  section  Section,  and  returns  the  value  as  a  boolean
                (valid  values  are  0  and  1).   If  the  specified  key  or  section  do  not  exist,  then  the  value  in
                Default is returned.  If the key exists, but contains an invalid integer value, False is also
                returned.

       Errors:

    See also:    TCustomIniFile.WriteBool (167  ), TCustomIniFile.ReadInteger (166  ), TCustomIniFile.ReadString
                (165  ), TCustomIniFile.ReadDate (167  ), TCustomIniFile.ReadDateTime (168  ), TCustomIniFile.ReadTime
                (168  ), TCustomIniFile.ReadFloat (168  ), TCustomIniFile.ReadBinaryStream (169  )
                14.3.12          TCustomIniFile.WriteBool

    Synopsis:    Write boolean value

Declaration:     procedure  WriteBool(const  Section:  String;const  Ident:  String;
                                                Value:  Boolean);    Virtual

    Visibility:   public

Description:     WriteBool  writes  the  boolean  Value  with  the  name  Ident  to  the  section  Section,  over-
                writing any previous value that may exist there.  The section will be created if it does not
                exist.

    See also:    TCustomIniFile.ReadBool (166  ), TCustomIniFile.WriteInteger (166  ), TCustomIniFile.WriteString
                (166  ), TCustomIniFile.WriteDate (169  ), TCustomIniFile.WriteDateTime (169  ), TCustomIniFile.WriteTime
                (170  ), TCustomIniFile.WriteFloat (170  ), TCustomIniFile.WriteBinaryStream (170  )
                14.3.13          TCustomIniFile.ReadDate

    Synopsis:    Read a date value

Declaration:     function  ReadDate(const  Section:  String;const  Ident:  String;
                                            Default:  TDateTime)  :  TDateTime;    Virtual

    Visibility:   public

Description:     ReadDate reads the key Ident in section Section, and returns the value as a date (TDateTime).
                If  the  specified  key  or  section  do  not  exist,  then  the  value  in  Default  is  returned.  If  the
                key exists, but contains an invalid date value, Default is also returned.  The international
                settings of the SysUtils are taken into account when deciding if the read value is a correct
                date.

       Errors:

    See also:    TCustomIniFile.WriteDate (169  ), TCustomIniFile.ReadInteger (166  ), TCustomIniFile.ReadBool
                (166  ),  TCustomIniFile.ReadString  (165  ),  TCustomIniFile.ReadDateTime  (168  ),  TCusto-
                mIniFile.ReadTime (168  ), TCustomIniFile.ReadFloat (168  ), TCustomIniFile.ReadBinaryStream
                (169  )

                                                                                 167

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.3.14          TCustomIniFile.ReadDateTime

    Synopsis:    Read a Date/Time value

Declaration:     function  ReadDateTime(const  Section:  String;const  Ident:  String;
                                                   Default:  TDateTime)  :  TDateTime;    Virtual

    Visibility:   public

Description:     ReadDateTime reads the key Ident in section Section, and returns the value as a date/time
                (TDateTime).   If  the  specified  key  or  section  do  not  exist,  then  the  value  in  Default  is
                returned.  If the key exists, but contains an invalid date/time value, Default is also returned.
                The international settings of the SysUtils are taken into account when deciding if the read
                value is a correct date/time.

    See also:    TCustomIniFile.WriteDateTime (169  ), TCustomIniFile.ReadInteger (166  ), TCustomIniFile.ReadBool
                (166  ), TCustomIniFile.ReadDate (167  ), TCustomIniFile.ReadString (165  ), TCustomIniFile.ReadTime
                (168  ), TCustomIniFile.ReadFloat (168  ), TCustomIniFile.ReadBinaryStream (169  )
                14.3.15          TCustomIniFile.ReadFloat

    Synopsis:    Read a floating point value

Declaration:     function  ReadFloat(const  Section:  String;const  Ident:  String;
                                              Default:  Double)  :  Double;    Virtual

    Visibility:   public

Description:     ReadFloat reads the key Ident in section Section, and returns the value as a float (Double).
                If  the  specified  key  or  section  do  not  exist,  then  the  value  in  Default  is  returned.  If  the
                key exists, but contains an invalid float value, Default is also returned.  The international
                settings of the SysUtils are taken into account when deciding if the read value is a correct
                float.

    See also:    TCustomIniFile.WriteFloat (170  ), TCustomIniFile.ReadInteger (166  ), TCustomIniFile.ReadBool
                (166  ), TCustomIniFile.ReadDate (167  ), TCustomIniFile.ReadDateTime (168  ), TCustomIniFile.ReadTime
                (168  ), TCustomIniFile.ReadString (165  ), TCustomIniFile.ReadBinaryStream (169  )
                14.3.16          TCustomIniFile.ReadTime

    Synopsis:    Read a time value

Declaration:     function  ReadTime(const  Section:  String;const  Ident:  String;
                                            Default:  TDateTime)  :  TDateTime;    Virtual

    Visibility:   public

Description:     ReadTime reads the key Ident in section Section, and returns the value as a time (TDateTime).
                If  the  specified  key  or  section  do  not  exist,  then  the  value  in  Default  is  returned.  If  the
                key exists, but contains an invalid time value, Default is also returned.  The international
                settings of the SysUtils are taken into account when deciding if the read value is a correct
                time.

       Errors:

    See also:    TCustomIniFile.WriteTime (170  ), TCustomIniFile.ReadInteger (166  ), TCustomIniFile.ReadBool
                (166  ), TCustomIniFile.ReadDate (167  ), TCustomIniFile.ReadDateTime (168  ), TCustomIniFile.ReadString
                (165  ), TCustomIniFile.ReadFloat (168  ), TCustomIniFile.ReadBinaryStream (169  )



                                                                                 168

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.3.17          TCustomIniFile.ReadBinaryStream

    Synopsis:    Read binary data

Declaration:     function  ReadBinaryStream(const  Section:  String;const  Name:  String;
                                                         Value:  TStream)  :  Integer;    Virtual

    Visibility:   public

Description:     ReadBinaryStream  reads  the  key  Name  in  section  Section,  and  returns  the  value  in  the
                stream Value.  If the specified key or section do not exist,  then the contents of  Value are
                left untouched.  The stream is not cleared prior to adding data to it.

                The data is interpreted as a series of 2-byte hexadecimal values, each representing a byte in
                the data stream, i.e, it should always be an even number of hexadecimal characters.

    See also:    TCustomIniFile.WriteBinaryStream (170  ), TCustomIniFile.ReadInteger (166  ), TCustomIniFile.ReadBool
                (166  ), TCustomIniFile.ReadDate (167  ), TCustomIniFile.ReadDateTime (168  ), TCustomIniFile.ReadTime
                (168  ), TCustomIniFile.ReadFloat (168  ), TCustomIniFile.ReadString (165  )
                14.3.18          TCustomIniFile.WriteDate

    Synopsis:    Write date value

Declaration:     procedure  WriteDate(const  Section:  String;const  Ident:  String;
                                                Value:  TDateTime);    Virtual

    Visibility:   public

Description:     WriteDate writes the date Value with the name Ident to the section Section, overwriting
                any previous value that may exist there.  The section will be created if it does not exist.  The
                date is written using the internationalization settings in the SysUtils unit.

       Errors:

    See also:    TCustomIniFile.ReadDate (167  ), TCustomIniFile.WriteInteger (166  ), TCustomIniFile.WriteBool
                (167  ),  TCustomIniFile.WriteString  (166  ),  TCustomIniFile.WriteDateTime  (169  ),  TCusto-
                mIniFile.WriteTime (170  ), TCustomIniFile.WriteFloat (170  ), TCustomIniFile.WriteBinaryStream
                (170  )
                14.3.19          TCustomIniFile.WriteDateTime

    Synopsis:    Write date/time value

Declaration:     procedure  WriteDateTime(const  Section:  String;const  Ident:  String;
                                                      Value:  TDateTime);    Virtual

    Visibility:   public

Description:     WriteDateTime writes the date/time Value with the name Ident to the section Section,
                overwriting any previous value that may exist there.  The section will be created if it does
                not  exist.  The  date/time  is  written  using  the  internationalization  settings  in  the  SysUtils
                unit.

    See also:    TCustomIniFile.ReadDateTime (168  ), TCustomIniFile.WriteInteger (166  ), TCustomIniFile.WriteBool
                (167  ), TCustomIniFile.WriteDate (169  ), TCustomIniFile.WriteString (166  ), TCustomIniFile.WriteTime
                (170  ), TCustomIniFile.WriteFloat (170  ), TCustomIniFile.WriteBinaryStream (170  )


                                                                                 169

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.3.20          TCustomIniFile.WriteFloat

    Synopsis:    Write a floating-point value

Declaration:     procedure  WriteFloat(const  Section:  String;const  Ident:  String;
                                                 Value:  Double);    Virtual

    Visibility:   public

Description:     WriteFloat writes the time Value with the name Ident to the section Section, overwriting
                any previous value that may exist there.  The section will be created if it does not exist.  The
                floating point value is written using the internationalization settings in the SysUtils unit.

    See also:    TCustomIniFile.ReadFloat (168  ), TCustomIniFile.WriteInteger (166  ), TCustomIniFile.WriteBool
                (167  ), TCustomIniFile.WriteDate (169  ), TCustomIniFile.WriteDateTime (169  ), TCustomIniFile.WriteTime
                (170  ), TCustomIniFile.WriteString (166  ), TCustomIniFile.WriteBinaryStream (170  )
                14.3.21          TCustomIniFile.WriteTime

    Synopsis:    Write time value

Declaration:     procedure  WriteTime(const  Section:  String;const  Ident:  String;
                                                Value:  TDateTime);    Virtual

    Visibility:   public

Description:     WriteTime writes the time Value with the name Ident to the section Section, overwriting
                any previous value that may exist there.  The section will be created if it does not exist.  The
                time is written using the internationalization settings in the SysUtils unit.

    See also:    TCustomIniFile.ReadTime (168  ), TCustomIniFile.WriteInteger (166  ), TCustomIniFile.WriteBool
                (167  ), TCustomIniFile.WriteDate (169  ), TCustomIniFile.WriteDateTime (169  ), TCustomIniFile.WriteString
                (166  ), TCustomIniFile.WriteFloat (170  ), TCustomIniFile.WriteBinaryStream (170  )
                14.3.22          TCustomIniFile.WriteBinaryStream

    Synopsis:    Write binary data

Declaration:     procedure  WriteBinaryStream(const  Section:  String;const  Name:  String;
                                                             Value:  TStream);    Virtual

    Visibility:   public

Description:     WriteBinaryStream writes the binary data in Value with the name Ident to the section
                Section, overwriting any previous value that may exist there.  The section will be created if
                it does not exist.

                The binary data is encoded using a 2-byte hexadecimal value per byte in the data stream.
                The data stream must be seekable, so it's size can be determined.  The data stream is not
                repositioned, it must be at the correct position.

    See also:    TCustomIniFile.ReadBinaryStream (169  ), TCustomIniFile.WriteInteger (166  ), TCustomIniFile.WriteBool
                (167  ), TCustomIniFile.WriteDate (169  ), TCustomIniFile.WriteDateTime (169  ), TCustomIniFile.WriteTime
                (170  ), TCustomIniFile.WriteFloat (170  ), TCustomIniFile.WriteString (166  )


                                                                                 170

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.3.23          TCustomIniFile.ReadSection

    Synopsis:    Read the key names in a section

Declaration:     procedure  ReadSection(const  Section:  String;Strings:  TStrings);    Virtual
                                                   ;    Abstract

    Visibility:   public

Description:     ReadSection will return the names of the keys in section Section in Strings, one string
                per key.  If a non-existing section is specified, the list is cleared.  To return the values of the
                keys as well, the ReadSectionValues (171  ) method should be used.

    See also:    TCustomIniFile.ReadSections (171  ), TCustomIniFile.SectionExists (165  ), TCustomIniFile.ReadSectionValues
                (171  )
                14.3.24          TCustomIniFile.ReadSections

    Synopsis:    Read the list of sections

Declaration:     procedure  ReadSections(Strings:  TStrings);    Virtual;    Abstract

    Visibility:   public

Description:     ReadSections returns the names of existing sections in Strings.  It also returns names of
                empty sections.

    See also:    TCustomIniFile.SectionExists (165  ), TCustomIniFile.ReadSectionValues (171  ), TCustomIniFile.ReadSection
                (171  )
                14.3.25          TCustomIniFile.ReadSectionValues

    Synopsis:    Read names and values of a section

Declaration:     procedure  ReadSectionValues(const  Section:  String;Strings:  TStrings)
                                                             ;    Virtual;    Abstract

    Visibility:   public

Description:     ReadSectionValues returns the keys and their values in the section Section in Strings.
                They are returned as Key=Value strings, one per key, so the Values property of the stringlist
                can be used to read the values.  To retrieve just the names of the available keys, ReadSection
                (171  ) can be used.

    See also:    TCustomIniFile.SectionExists (165  ), TCustomIniFile.ReadSections (171  ), TCustomIniFile.ReadSection
                (171  )
                14.3.26          TCustomIniFile.EraseSection

    Synopsis:    Clear a section

Declaration:     procedure  EraseSection(const  Section:  String);    Virtual;    Abstract

    Visibility:   public

Description:     EraseSection deletes all values from the section named Section and removes the section
                from the ini file.  If the section didn't exist prior to a call to EraseSection, nothing happens.

    See also:    TCustomIniFile.SectionExists (165  ), TCustomIniFile.ReadSections (171  ), TCustomIniFile.DeleteKey
                (172  )



                                                                                 171

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.3.27          TCustomIniFile.DeleteKey

    Synopsis:    Delete a key from a section

Declaration:     procedure  DeleteKey(const  Section:  String;const  Ident:  String);    Virtual
                                                ;    Abstract

    Visibility:   public

Description:     DeleteKey deletes the key Ident from section Section.  If the key or section didn't exist
                prior to the DeleteKey call, nothing happens.

    See also:    TCustomIniFile.EraseSection (171  )
                14.3.28          TCustomIniFile.UpdateFile

    Synopsis:    Update the file on disk

Declaration:     procedure  UpdateFile;    Virtual;    Abstract

    Visibility:   public

Description:     UpdateFile writes the in-memory image of the ini-file to disk.  To speed up operation of
                the  inifile  class,  the  whole  ini-file  is  read  into  memory  when  the  class  is  created,  and  all
                operations are performed in-memory.  If  CacheUpdates is set to True,  any changes to the
                inifile are only in memory, until they are committed to disk with a call to UpdateFile.  If
                CacheUpdates is set to False, then all operations which cause a change in the .ini file will
                immediatly be committed to disk with a call to UpdateFile.  Since the whole file is written
                to disk, this may have serious impact on performance.

    See also:    TIniFile.CacheUpdates (178  )
                14.3.29          TCustomIniFile.ValueExists

    Synopsis:    Check if a value exists

Declaration:     function  ValueExists(const  Section:  String;const  Ident:  String)
                                                   :  Boolean;    Virtual

    Visibility:   public

Description:     ValueExists checks whether the key Ident exists in section Section.  It returns True if a
                key was found, or False if not.  The key may be empty.

    See also:    TCustomIniFile.SectionExists (165  )
                14.3.30          TCustomIniFile.FileName

    Synopsis:    Name of the .ini file

Declaration:     Property  FileName  :  String

    Visibility:   public

      Access:    Read

Description:     FileName is the name of the ini file on disk.  It should be specified when the TCustomIniFile
                instance is created.  Contrary to the Delphi implementation, if no path component is present
                in the filename, the filename is not searched in the windows directory.

    See also:    TCustomIniFile.Create (164  )



                                                                                 172

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.3.31          TCustomIniFile.EscapeLineFeeds

    Synopsis:    Should linefeeds be escaped ?

Declaration:     Property  EscapeLineFeeds  :  Boolean

    Visibility:   public

      Access:    Read

Description:     EscapeLineFeeds  determines  whether  escaping  of  linefeeds  is  enabled:  For  a  description
                of this feature,  see Create (164  ),  as the value of this property must be specified when the
                TCustomIniFile instance is created.

                By default, EscapeLineFeeds is False.

    See also:    TCustomIniFile.Create (164  ), TCustomIniFile.CaseSensitive (173  )
                14.3.32          TCustomIniFile.CaseSensitive

    Synopsis:    Are key and section names case sensitive

Declaration:     Property  CaseSensitive  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     CaseSensitive  determines  whether  searches  for  sections  and  keys  are  performed  case-
                sensitive or not.  By default, they are not case sensitive.

    See also:    TCustomIniFile.EscapeLineFeeds (173  )
                14.3.33          TCustomIniFile.StripQuotes

    Synopsis:    Should quotes be stripped from string values

Declaration:     Property  StripQuotes  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     StripQuotes determines whether quotes around string values are stripped from the value
                when reading the values from file.  By default,  quotes are not stripped (this is Delphi and
                Windows compatible).
                14.4          THashedStringList



                14.4.1         Description

                THashedStringList is a TStringList (??  ) descendent which creates has values for the strings
                and names (in the case of a name-value pair) stored in it.  The IndexOf (174  ) and IndexOf-
                Name (174  ) functions make use of these hash values to quicklier locate a value.


                                                                                 173

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.4.2         Method  overview

                __Page______Property_______________Description_____________________________________________________________________*
 *___________
                  174       Create                 Instantiates a new instance of  THashedStringList
                  174       Destroy                Clean up instance
                  174       IndexOf                Returns the index of a string in the list of strings
                __174_______IndexOfName____________Return_the_index_of_a_name_in_the_list_of_name=value_pairs______________________*
 *___________
                14.4.3         THashedStringList.Create

    Synopsis:    Instantiates a new instance of  THashedStringList

Declaration:     constructor  Create

    Visibility:   public

Description:     Create calls the inherited Create, and then instantiates the hash tables.

       Errors:   If no enough memory is available, an exception may be raised.

    See also:    THashedStringList.Destroy (174  )
                14.4.4         THashedStringList.Destroy

    Synopsis:    Clean up instance

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the hash tables and then calls the inherited Destroy.

    See also:    THashedStringList.Create (174  )
                14.4.5         THashedStringList.IndexOf

    Synopsis:    Returns the index of a string in the list of strings

Declaration:     function  IndexOf(const  S:  String)  :  Integer;    Override

    Visibility:   public

Description:     IndexOf overrides the TStringList.IndexOf (163  ) method and uses the hash values to look
                for the location of  S.

    See also:    TStringList.IndexOf (163  ), THashedStringList.IndexOfName (174  )
                14.4.6         THashedStringList.IndexOfName

    Synopsis:    Return the index of a name in the list of name=value pairs

Declaration:     function  IndexOfName(const  Name:  String)  :  Integer;    Override

    Visibility:   public

Description:     IndexOfName overrides the TStrings.IndexOfName (163  ) method and uses the hash values
                of the names to look for the location of  Name.

    See also:    TStrings.IndexOfName (163  ), THashedStringList.IndexOf (174  )



                                                                                 174

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.5          TIniFile



                14.5.1         Description

                TIniFile is an implementation of TCustomIniFile (163  ) which does the same as TMemI-
                niFile (184  ),  namely it reads the whole file into memory.  Unlike TMemIniFile it does not
                cache updates in memory, but immediatly writes any changes to disk.

                TIniFile introduces no new methods, it just implements the abstract methods introduced
                in TCustomIniFile
                14.5.2         Method  overview

                __Page______Property______________________Description______________________________________________________________*
 *___________
                  175       Create                        Create a new instance of  TIniFile
                  178       DeleteKey                     Delete key
                  175       Destroy                       Remove the TIniFile instance from memory
                  177       EraseSection
                  176       ReadSection                   Read the key names in a section
                  177       ReadSectionRaw                Read raw section
                  177       ReadSections                  Read section names
                  177       ReadSectionValues
                  176       ReadString                    Read a string
                  178       UpdateFile                    Update the file on disk
                __176_______WriteString___________________Write_string_to_file_____________________________________________________*
 *___________
                14.5.3         Property  overview

                __Page______Property________________Access_______Description_______________________________________________________*
 *___________
                  178       CacheUpdates            rw           Should changes be kept in memory
                __178_______Stream__________________r____________Stream_from_which_ini_file_was_read_______________________________*
 *___________
                14.5.4         TIniFile.Create

    Synopsis:    Create a new instance of  TIniFile

Declaration:     constructor  Create(const  AFileName:  String;AEscapeLineFeeds:  Boolean)
                                              ;    Override
                constructor  Create(AStream:  TStream;AEscapeLineFeeds:  Boolean)

    Visibility:   public

Description:     Create creates a new instance of TIniFile and initializes the class by reading the file from
                disk  if  the  filename  AFileName  is  specified,  or  from  stream  in  case  AStream  is  specified.
                It  also  sets  most  variables  to  their  initial  values,  i.e.  AEscapeLineFeeds  is  saved  prior  to
                reading the file, and Cacheupdates is set to False.

    See also:    TCustomIniFile (163  ), TMemIniFile (184  )
                14.5.5         TIniFile.Destroy

    Synopsis:    Remove the TIniFile instance from memory

Declaration:     destructor  Destroy;    Override
                                                                                 175

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
    Visibility:  public

Description:     Destroy writes any pending changes to disk, and cleans up the TIniFile structures, and
                then calls the inherited Destroy, effectively removing the instance from memory.

       Errors:   If an error happens when the file is written to disk, an exception will be raised.

    See also:    TCustomIniFile.UpdateFile (172  ), TIniFile.CacheUpdates (178  )
                14.5.6         TIniFile.ReadString

    Synopsis:    Read a string

Declaration:     function  ReadString(const  Section:  String;const  Ident:  String;
                                                const  Default:  String)  :  String;    Override

    Visibility:   public

Description:     ReadString implements the TCustomIniFile.ReadString (165  ) abstract method by looking
                at the in-memory copy of the ini file and returning the string found there.

    See also:    TCustomIniFile.ReadString (165  )
                14.5.7         TIniFile.WriteString

    Synopsis:    Write string to file

Declaration:     procedure  WriteString(const  Section:  String;const  Ident:  String;
                                                   const  Value:  String);    Override

    Visibility:   public

Description:     WriteString implements the TCustomIniFile.WriteString (166  ) abstract method by writing
                the string to the in-memory copy of the ini file.  If CacheUpdates (178  ) property is False,
                then the whole file is immediatly written to disk as well.

       Errors:   If an error happens when the file is written to disk, an exception will be raised.
                14.5.8         TIniFile.ReadSection

    Synopsis:    Read the key names in a section

Declaration:     procedure  ReadSection(const  Section:  String;Strings:  TStrings)
                                                   ;    Override

    Visibility:   public

Description:     ReadSection reads the key names from Section into Strings, taking the in-memory copy
                of the ini file.  This is the implementation for the abstract TCustomIniFile.ReadSection (171  )

    See also:    TCustomIniFile.ReadSection (171  ), TIniFile.ReadSectionRaw (177  )


                                                                                 176

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.5.9         TIniFile.ReadSectionRaw

    Synopsis:    Read raw section

Declaration:     procedure  ReadSectionRaw(const  Section:  String;Strings:  TStrings)

    Visibility:   public

Description:     ReadSectionRaw  returns  the  contents  of  the  section  Section  as  it  is:  this  includes  the
                comments in the section.  (these are also stored in memory)

    See also:    TIniFile.ReadSection (176  ), TCustomIniFile.ReadSection (171  )
                14.5.10          TIniFile.ReadSections

    Synopsis:    Read section names

Declaration:     procedure  ReadSections(Strings:  TStrings);    Override

    Visibility:   public

Description:     ReadSections is the implementation of TCustomIniFile.ReadSections (171  ).  It operates on
                the in-memory copy of the inifile, and places all section names in Strings.

    See also:    TIniFile.ReadSection (176  ), TCustomIniFile.ReadSections (171  ), TIniFile.ReadSectionValues
                (177  )
                14.5.11          TIniFile.ReadSectionValues

    Synopsis:

Declaration:     procedure  ReadSectionValues(const  Section:  String;Strings:  TStrings)
                                                             ;    Override

    Visibility:   public

Description:     ReadSectionValues is the implementation of TCustomIniFile.ReadSectionValues (171  ).  It
                operates on the in-memory copy of the inifile, and places all key names from Section together
                with their values in Strings.

    See also:    TIniFile.ReadSection (176  ), TCustomIniFile.ReadSectionValues (171  ), TIniFile.ReadSections
                (177  )
                14.5.12          TIniFile.EraseSection

    Synopsis:

Declaration:     procedure  EraseSection(const  Section:  String);    Override

    Visibility:   public

Description:     Erasesection deletes the section Section from memory, if CacheUpdates (178  ) is False,
                then  the  file  is  immediatly  updated  on  disk.   This  method  is  the  implementation  of  the
                abstract TCustomIniFile.EraseSection (171  ) method.

    See also:    TCustomIniFile.EraseSection (171  ), TIniFile.ReadSection (176  ), TIniFile.ReadSections (177  )



                                                                                 177

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.5.13          TIniFile.DeleteKey

    Synopsis:    Delete key

Declaration:     procedure  DeleteKey(const  Section:  String;const  Ident:  String)
                                                ;    Override

    Visibility:   public

Description:     DeleteKey deletes the Ident from the section Section.  This operation is performed on the
                in-memory copy of the ini file.  if CacheUpdates (178  ) is False, then the file is immediatly
                updated on disk.

    See also:    TIniFile.CacheUpdates (178  )
                14.5.14          TIniFile.UpdateFile

    Synopsis:    Update the file on disk

Declaration:     procedure  UpdateFile;    Override

    Visibility:   public

Description:     UpdateFile writes the in-memory data for the ini file to disk.  The whole file is written.  If
                the ini file was instantiated from a stream, then the stream is updated.  Note that the stream
                must be seekable for this to work correctly.  The ini file is marked as 'clean' after a call to
                UpdateFile (i.e.  not in need of writing to disk).

       Errors:   If an error occurs when writing to stream or disk, an exception may be raised.

    See also:    TIniFile.CacheUpdates (178  )
                14.5.15          TIniFile.Stream

    Synopsis:    Stream from which ini file was read

Declaration:     Property  Stream  :  TStream

    Visibility:   public

      Access:    Read

Description:     Stream is the stream which was used to create the IniFile.  The UpdateFile (178  ) method
                will use this stream to write changes to.

    See also:    TIniFile.Create (175  ), TIniFile.UpdateFile (178  )
                14.5.16          TIniFile.CacheUpdates

    Synopsis:    Should changes be kept in memory

Declaration:     Property  CacheUpdates  :  Boolean

    Visibility:   public

      Access:    Read,Write
                                                                                 178

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
Description:     CacheUpdates determines how to deal with changes to the ini-file data:  if set to True then
                changes are kept in memory till the file is written to disk with a call to UpdateFile (178  ).  If
                it is set to False then each call that changes the data of the ini-file will result in a call to
                UpdateFile.  This is the default behaviour, but it may aversely affect performance.

    See also:    TIniFile.UpdateFile (178  )
                14.6          TIniFileKey



                14.6.1         Description

                TIniFileKey is used to keep the key/value pairs in the ini file in memory.  It is an internal
                structure, used internally by the TIniFile (175  ) class.
                14.6.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __179_______Create__________Create_a_new_instance_of__TIniFileKey__________________________________________________*
 *___________
                14.6.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  179       Ident           rw           Key name
                __180_______Value___________rw___________Key_value_________________________________________________________________*
 *___________
                14.6.4         TIniFileKey.Create

    Synopsis:    Create a new instance of  TIniFileKey

Declaration:     constructor  Create(AIdent:  String;AValue:  String)

    Visibility:   public

Description:     Create instantiates a new instance of  TIniFileKey on the heap.  It fills Ident (179  ) with
                AIdent and Value (180  ) with AValue.

    See also:    TIniFileKey.Ident (179  ), TIniFileKey.Value (180  )
                14.6.5         TIniFileKey.Ident

    Synopsis:    Key name

Declaration:     Property  Ident  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Ident is the key value part of the key/value pair.

    See also:    TIniFileKey.Value (180  )


                                                                                 179

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.6.6         TIniFileKey.Value

    Synopsis:    Key value

Declaration:     Property  Value  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Value is the value part of the key/value pair.

    See also:    TIniFileKey.Ident (179  )
                14.7          TIniFileKeyList



                14.7.1         Description

                TIniFileKeyList maintains a list of TIniFileKey (179  ) instances on behalf of the TIniFile-
                Section (181  ) class.  It stores they keys of one section of the .ini files.
                14.7.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  180       Clear           Clear the list
                __180_______Destroy_________Free_the_instance______________________________________________________________________*
 *___________
                14.7.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __181_______Items___________r____________Indexed_access_to_TIniFileKey_items_in_the_list___________________________*
 *___________
                14.7.4         TIniFileKeyList.Destroy

    Synopsis:    Free the instance

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy clears up the list using Clear (180  ) and then calls the inherited destroy.

    See also:    TIniFileKeyList.Clear (180  )
                14.7.5         TIniFileKeyList.Clear

    Synopsis:    Clear the list

Declaration:     procedure  Clear;    Override

    Visibility:   public

Description:     Clear removes all TIniFileKey (179  ) instances from the list, and frees the instances.

    See also:    TIniFileKey (179  )

                                                                                 180

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.7.6         TIniFileKeyList.Items

    Synopsis:    Indexed access to TIniFileKey items in the list

Declaration:     Property  Items[Index:  Integer]:  TIniFileKey;  default

    Visibility:   public

      Access:    Read

Description:     Items  provides  indexed  access  to  the  TIniFileKey  (179  )  items  in  the  list.   The  index  is
                zero-based and runs from 0 to Count-1.

    See also:    TIniFileKey (179  )
                14.8          TIniFileSection



                14.8.1         Description

                TIniFileSection is a class which represents a section in the .ini, and is used internally by
                the TIniFile (175  ) class (one instance of TIniFileSection is created for each section in the
                file  by  the  TIniFileSectionList  (182  )  list).  The  name  of  the  section  is  stored  in  the  Name
                (182  )  property,  and  the  key/value  pairs  in  this  section  are  available  in  the  KeyList  (182  )
                property.
                14.8.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  181       Create          Create a new section object
                  182       Destroy         Free the section object from memory
                __181_______Empty___________Is_the_section_empty___________________________________________________________________*
 *___________
                14.8.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  182       KeyList         r            List of key/value pairs in this section
                __182_______Name____________r____________Name_of_the_section_______________________________________________________*
 *___________
                14.8.4         TIniFileSection.Empty

    Synopsis:    Is the section empty

Declaration:     function  Empty  :  Boolean

    Visibility:   public

Description:     Empty returns True if the section contains no key values (even if they are empty).  It may
                contain comments.
                14.8.5         TIniFileSection.Create

    Synopsis:    Create a new section object

Declaration:     constructor  Create(AName:  String)

                                                                                 181

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
    Visibility:  public

Description:     Create instantiates a new TIniFileSection class, and sets the name to AName.  It allocates
                a TIniFileKeyList (180  ) instance to keep all the key/value pairs for this section.

    See also:    TIniFileKeyList (180  )
                14.8.6         TIniFileSection.Destroy

    Synopsis:    Free the section object from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the key list, and then calls the inherited Destroy, removing the TIniFileSection
                instance from memory.

    See also:    TIniFileSection.Create (181  ), TIniFileKeyList (180  )
                14.8.7         TIniFileSection.Name

    Synopsis:    Name of the section

Declaration:     Property  Name  :  String

    Visibility:   public

      Access:    Read

Description:     Name is the name of the section in the file.

    See also:    TIniFileSection.KeyList (182  )
                14.8.8         TIniFileSection.KeyList

    Synopsis:    List of key/value pairs in this section

Declaration:     Property  KeyList  :  TIniFileKeyList

    Visibility:   public

      Access:    Read

Description:     KeyList is the TIniFileKeyList (180  ) instance that is used by the TIniFileSection to keep
                the key/value pairs of the section.

    See also:    TIniFileSection.Name (182  ), TIniFileKeyList (180  )
                14.9          TIniFileSectionList



                14.9.1         Description

                TIniFileSectionList maintains a list of TIniFileSection (181  ) instances, one for each sec-
                tion in an .ini file.  TIniFileSectionList is used internally by the TIniFile (175  ) class to
                represent the sections in the file.

                                                                                 182

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.9.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  183       Clear           Clear the list
                __183_______Destroy_________Free_the_object_from_memory____________________________________________________________*
 *___________
                14.9.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __183_______Items___________r____________Indexed_access_to_all_the_section_objects_in_the_list_____________________*
 *___________
                14.9.4         TIniFileSectionList.Destroy

    Synopsis:    Free the object from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy calls Clear (183  ) to clear the section list and the calls the inherited Destroy

    See also:    TIniFileSectionList.Clear (183  )
                14.9.5         TIniFileSectionList.Clear

    Synopsis:    Clear the list

Declaration:     procedure  Clear;    Override

    Visibility:   public

Description:     Clear removes all TIniFileSection (181  ) items from the list, and frees the items it removes
                from the list.

    See also:    TIniFileSection (181  ), TIniFileSectionList.Items (183  )
                14.9.6         TIniFileSectionList.Items

    Synopsis:    Indexed access to all the section objects in the list

Declaration:     Property  Items[Index:  Integer]:  TIniFileSection;  default

    Visibility:   public

      Access:    Read

Description:     Items provides indexed access to all the section objects in the list.  Index should run from
                0 to Count-1.

    See also:    TIniFileSection (181  ), TIniFileSectionList.Clear (183  )
                                                                                 183

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
                14.10            TMemIniFile



                14.10.1          Description

                TMemIniFile is a simple descendent of TIniFile (175  ) which introduces some extra methods
                to be compatible to the Delphi implementation of  TMemIniFile.  The FPC implementation
                of  TIniFile  is  implemented  as  a  TMemIniFile,  except  that  TIniFile  does  not  cache  its
                updates, and TMemIniFile does.
                14.10.2          Method  overview

                __Page______Property___________Description_________________________________________________________________________*
 *___________
                  184       Clear              Clear the data
                  184       Create             Create a new instance of  TMemIniFile
                  184       GetStrings         Get contents of ini file as stringlist
                  185       Rename             Rename the ini file
                __185_______SetStrings_________Set_data_from_a_stringlist__________________________________________________________*
 *___________
                14.10.3          TMemIniFile.Create

    Synopsis:    Create a new instance of  TMemIniFile

Declaration:     constructor  Create(const  AFileName:  String;AEscapeLineFeeds:  Boolean)
                                              ;    Override

    Visibility:   public

Description:     Create simply calls the inherited Create (175  ), and sets the CacheUpdates (178  ) to True
                so updates will be kept in memory till they are explicitly written to disk.

    See also:    TIniFile.Create (175  ), TIniFile.CacheUpdates (178  )
                14.10.4          TMemIniFile.Clear

    Synopsis:    Clear the data

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear removes all sections and key/value pairs from memory.  If CacheUpdates (178  ) is set
                to False then the file on disk will immediatly be emptied.

    See also:    TMemIniFile.SetStrings (185  ), TMemIniFile.GetStrings (184  )
                14.10.5          TMemIniFile.GetStrings

    Synopsis:    Get contents of ini file as stringlist

Declaration:     procedure  GetStrings(List:  TStrings)

    Visibility:   public

Description:     GetStrings  returns  the  whole  contents  of  the  ini  file  in  a  single  stringlist,  List.   This
                includes comments and empty sections.

                The GetStrings call can be used to get data for a call to SetStrings (185  ),  which can be
                used to copy data between 2 in-memory ini files.



                                                                                 184

                _________________________________________________________CHAPTER_14.___REFERENCE_FOR_UNIT_'INIFILES'_______________*
 *___________________
    See also:    TMemIniFile.SetStrings (185  ), TMemIniFile.Clear (184  )
                14.10.6          TMemIniFile.Rename

    Synopsis:    Rename the ini file

Declaration:     procedure  Rename(const  AFileName:  String;Reload:  Boolean)

    Visibility:   public

Description:     Rename  will  rename  the  ini  file  with  the  new  name  AFileName.   If  Reload  is  True  then
                the in-memory contents will be cleared and replaced with the contents found in AFileName,
                if  it  exists.   If  Reload  is  False,  the  next  call  to  UpdateFile  will  replace  the  contents  of
                AFileName with the in-memory data.

    See also:    TIniFile.UpdateFile (178  )
                14.10.7          TMemIniFile.SetStrings

    Synopsis:    Set data from a stringlist

Declaration:     procedure  SetStrings(List:  TStrings)

    Visibility:   public

Description:     SetStrings sets the in-memory data from the List stringlist.  The data is first cleared.

                The SetStrings call can be used to set the data of the ini file to a list of strings obtained with
                GetStrings (184  ).  The two calls combined can be used to copy data between 2 in-memory
                ini files.

    See also:    TMemIniFile.GetStrings (184  ), TMemIniFile.Clear (184  )

                                                                                 185


Chapter   15


Reference   for   unit   'iostream'
15.1          Used  units
                                   Table 15.1:  Used units by unit 'iostream'


                                                   __Name__________Page____
                                                     Classes          ??



15.2          Overview


The  iostream  implements  a  descendent  of  THandleStream  (??  )  streams  that  can  be  used
to read from standard input and write to standard output and standard diagnostic output
(stderr).
15.3          Constants,  types  and  variables



15.3.1         Types

TIOSType  =  (iosInput,iosOutPut,iosError)
                           Table 15.2:  Enumeration values for type TIOSType


         __Value_____________Explanation______________________________________________________________________________
           iosError          The stream can be used to write to standard diagnostic output
           iosInput          The stream can be used to read from standard input
           iosOutPut         The stream can be used to write to standard output
TIOSType is passed to the Create (187  ) constructor of TIOStream (187  ), it determines what
kind of stream is created.



                                                             186

                _____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'IOSTREAM'___________________*
 *___________________
                15.4          EIOStreamError



                15.4.1         Description

                Error thrown in case of an invalid operation on a TIOStream (187  ).
                15.5          TIOStream



                15.5.1         Description

                TIOStream can be used to create a stream which reads from or writes to the standard input,
                output or stderr file descriptors.  It is a descendent of  THandleStream.  The type of stream
                that  is  created  is  determined  by  the  TIOSType  (186  )  argument  to  the  constructor.   The
                handle of the standard input, output or stderr file descriptors is determined automatically.

                The  TIOStream  keeps  an  internal  Position,  and  attempts  to  provide  minimal  Seek  (188  )
                behaviour based on this position.
                15.5.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  187       Create          Construct a new instance of TIOStream (187  )
                  187       Read            Read data from the stream.
                  188       Seek            Set the stream position
                  188       SetSize         Set the size of the stream
                __188_______Write___________Write_data_to_the_stream_______________________________________________________________*
 *___________
                15.5.3         TIOStream.Create

    Synopsis:    Construct a new instance of TIOStream (187  )

Declaration:     constructor  Create(aIOSType:  TIOSType)

    Visibility:   public

Description:     Create creates a new instance of TIOStream (187  ), which can subsequently be used

       Errors:   No checking is performed to see whether the requested file descriptor is actually open for
                reading/writing.  In that case, subsequent calls to Read or Write or seek will fail.

    See also:    TIOStream.Read (187  ), TIOStream.Write (188  )
                15.5.4         TIOStream.Read

    Synopsis:    Read data from the stream.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read checks first whether the type of the stream allows reading (type is iosInput).  If not,
                it raises a EIOStreamError (187  ) exception.  If the stream can be read, it calls the inherited
                Read to actually read the data.

       Errors:   An EIOStreamError exception is raised if the stream does not allow reading.

    See also:    TIOSType (186  ), TIOStream.Write (188  )



                                                                                 187

                _____________________________________________________CHAPTER_15.___REFERENCE_FOR_UNIT_'IOSTREAM'___________________*
 *___________________
                15.5.5         TIOStream.Write

    Synopsis:    Write data to the stream

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write  checks  first  whether  the  type  of  the  stream  allows  writing  (type  is  iosOutput  or
                iosError).  If not, it raises a EIOStreamError (187  ) exception.  If the stream can be written
                to, it calls the inherited Write to actually read the data.

       Errors:   An EIOStreamError exception is raised if the stream does not allow writing.

    See also:    TIOSType (186  ), TIOStream.Read (187  )
                15.5.6         TIOStream.SetSize

    Synopsis:    Set the size of the stream

Declaration:     procedure  SetSize(NewSize:  LongInt);    Override

    Visibility:   public

Description:     SetSize  overrides  the  standard  SetSize  implementation.   It  always  raises  an  exception,
                because the standard input, output and stderr files have no size.

       Errors:   An EIOStreamError exception is raised when this method is called.

    See also:    EIOStreamError (187  )
                15.5.7         TIOStream.Seek

    Synopsis:    Set the stream position

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek overrides the standard Seek implementation.  Normally, standard input, output and
                stderr  are  not  seekable.   The  TIOStream  stream  tries  to  provide  seek  capabilities  for  the
                following limited number of cases:


                Origin=soFromBeginning                  If  Offset is larger than the current position, then the remain-
                       ing  bytes  are  skipped  by  reading  them  from  the  stream  and  discarding  them,  if  the
                       stream is of type iosInput.

                Origin=soFromCurrent                 If Offset is zero, the current position is returned.  If it is positive,
                       then Offset bytes are skipped by reading them from the stream and discarding them,
                       if the stream is of type iosInput.


                All other cases will result in a EIOStreamError exception.

       Errors:   An  EIOStreamError  (187  )  exception  is  raised  if  the  stream  does  not  allow  the  requested
                seek operation.

    See also:    EIOStreamError (187  )



                                                                                 188


            Chapter   16


            Reference   for   unit   'Pipes'
            16.1          Used  units
                                                 Table 16.1:  Used units by unit 'Pipes'


                                                               __Name__________Page_____
                                                                 Classes          ??
                                                                 sysutils         ??



            16.2          Overview


            The Pipes unit implements streams that are wrappers around the OS's pipe functionality.  It
            creates a pair of streams, and what is written to one stream can be read from another.
            16.3          Constants,  types  and  variables



            16.3.1         Constants

            ENoSeekMsg  =  'Cannot  seek  on  pipes'


            Constant used in EPipeSeek (190  ) exception.


            EPipeMsg  =  'Failed  to  create  pipe.'


            Constant used in EPipeCreation (190  ) exception.
            16.4          Procedures  and  functions



            16.4.1         CreatePipeHandles

Synopsis:    Function to create a set of pipe handles

                                                                         189

                _____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'PIPES'______________*
 *___________________
Declaration:     function  CreatePipeHandles(var  Inhandle:  THandle;var  OutHandle:  THandle)
                                                            :  Boolean

    Visibility:  default

Description:     CreatePipeHandles  provides  an  OS-independent  way  to  create  a  set  of  pipe  filehandles.
                These handles are inheritable to child processes.  The reading end of the pipe is returned in
                InHandle, the writing end in OutHandle.

       Errors:   On error, False is returned.

    See also:    CreatePipeStreams (190  )
                16.4.2         CreatePipeStreams

    Synopsis:    Create a pair of pipe stream.

Declaration:     procedure  CreatePipeStreams(var  InPipe:  TInputPipeStream;
                                                             var  OutPipe:  TOutputPipeStream)

    Visibility:   default

Description:     CreatePipeStreams creates a set of pipe file descriptors with CreatePipeHandles (189  ), and
                if that call is succesfull, a pair of streams is created:  InPipe and OutPipe.

       Errors:   If no pipe handles could be created, an EPipeCreation (190  ) exception is raised.

    See also:    CreatePipeHandles (189  ), TInputPipeStream (190  ), TOutputPipeStream (192  )
                16.5          EPipeCreation



                16.5.1         Description

                Exception raised when an error occurred during the creation of a pipe pair.
                16.6          EPipeError



                16.6.1         Description

                Exception raised when an invalid operation is performed on a pipe stream.
                16.7          EPipeSeek



                16.7.1         Description

                Exception raised when an invalid seek operation is attempted on a pipe.
                16.8          TInputPipeStream



                16.8.1         Description

                TInputPipeStream is created by the CreatePipeStreams (190  ) call to represent the reading
                end  of  a  pipe.  It  is  a  TStream  (??  )  descendent  which  does  not  allow  writing,  and  which
                mimics the seek operation.



                                                                                 190

                _____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'PIPES'______________*
 *___________________
                16.8.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  192       Read            Read data from the stream to a buffer.
                  191       Seek            Set the current position of the stream
                __191_______Write___________Write_data_to_the_stream.______________________________________________________________*
 *___________
                16.8.3         Property  overview

                __Page______Property_______________________Access_______Description________________________________________________*
 *___________
                __192_______NumBytesAvailable______________r____________Number_of_bytes_available_for_reading._____________________*
 *___________
                16.8.4         TInputPipeStream.Write

    Synopsis:    Write data to the stream.

Declaration:     function  Write(const  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write overrides the parent implementation of  Write.  On a TInputPipeStream will always
                raise an exception, as the pipe is read-only.

       Errors:   An ENoWritePipe (189  ) exception is raised when this function is called.

    See also:    TInputPipeStream.Read (192  ), TInputPipeStream.Seek (191  )
                16.8.5         TInputPipeStream.Seek

    Synopsis:    Set the current position of the stream

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek overrides the standard Seek implementation.  Normally,  pipe streams stderr are not
                seekable.  The TInputPipeStream stream tries to provide seek capabilities for the following
                limited number of cases:


                Origin=soFromBeginning                  If  Offset is larger than the current position, then the remain-
                       ing bytes are skipped by reading them from the stream and discarding them.

                Origin=soFromCurrent                 If Offset is zero, the current position is returned.  If it is positive,
                       then Offset bytes are skipped by reading them from the stream and discarding them,
                       if the stream is of type iosInput.


                All other cases will result in a EPipeSeek exception.

       Errors:   An  EPipeSeek  (190  )  exception  is  raised  if  the  stream  does  not  allow  the  requested  seek
                operation.

    See also:    EPipeSeek (190  ), #rtl.classes.tstream.seek (??  )

                                                                                 191

                _____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'PIPES'______________*
 *___________________
                16.8.6         TInputPipeStream.Read

    Synopsis:    Read data from the stream to a buffer.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read calls the inherited read and adjusts the internal position pointer of the stream.

       Errors:   None.

    See also:    TInputPipeStream.Write (191  ), TInputPipeStream.Seek (191  )
                16.8.7         TInputPipeStream.NumBytesAvailable

    Synopsis:    Number of bytes available for reading.

Declaration:     Property  NumBytesAvailable  :  DWord

    Visibility:   public

      Access:    Read

Description:     NumBytesAvailable  is  the  number  of  bytes  available  for  reading.  This  is  the  number  of
                bytes in the OS buffer for the pipe.  It is not a number of bytes in an internal buffer.

                If this number is nonzero, then reading NumBytesAvailable bytes from the stream will not
                block  the  process.   Reading  more  than  NumBytesAvailable  bytes  will  block  the  process,
                while it waits for the requested number of bytes to become available.

    See also:    TInputPipeStream.Read (192  )
                16.9          TOutputPipeStream



                16.9.1         Description

                TOutputPipeStream is created by the CreatePipeStreams (190  ) call to represent the writing
                end of a pipe.  It is a TStream (??  ) descendent which does not allow reading.
                16.9.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  193       Read            Read data from the stream.
                __192_______Seek____________Sets_the_position_in_the_stream________________________________________________________*
 *___________
                16.9.3         TOutputPipeStream.Seek

    Synopsis:    Sets the position in the stream

Declaration:     function  Seek(Offset:  LongInt;Origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek is overridden in TOutputPipeStream.  Calling this method will always raise an excep-
                tion:  an output pipe is not seekable.

       Errors:   An EPipeSeek (190  ) exception is raised if this method is called.



                                                                                 192

                _____________________________________________________________CHAPTER_16.___REFERENCE_FOR_UNIT_'PIPES'______________*
 *___________________
                16.9.4         TOutputPipeStream.Read

    Synopsis:    Read data from the stream.

Declaration:     function  Read(var  Buffer;Count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read overrides the parent Read implementation.  It always raises an exception,  because a
                output pipe is write-only.

       Errors:   An ENoReadPipe (189  ) exception is raised when this function is called.

    See also:    TOutputPipeStream.Seek (192  )

                                                                                 193


Chapter   17


Reference   for   unit   'pooledmm'
17.1          Used  units
                                  Table 17.1:  Used units by unit 'pooledmm'


                                                   __Name__________Page____
                                                     Classes          ??



17.2          Overview


pooledmm is a memory manager class which uses pools of blocks.  Since it is a higher-level
implementation  of  a  memory  manager  which  works  on  top  of  the  FPC  memory  manager,
It also offers more debugging and analysis tools.  It is used mainly in the LCL and Lazarus
IDE.
17.3          Constants,  types  and  variables



17.3.1         Types

PPooledMemManagerItem  =  ^TPooledMemManagerItem


PPooledMemManagerItem is a pointer type,  pointing to a TPooledMemManagerItem (195  )
item, used in a linked list.


TEnumItemsMethod  =  procedure(Item:  Pointer)  of  object


TEnumItemsMethod  is  a  prototype  for  the  callback  used  in  the  TNonFreePooledMemMan-
ager.EnumerateItems (196  ) call.  The parameter Item will be set to each of the pointers in
the item list of TNonFreePooledMemManager (195  ).


TPooledMemManagerItem  =  record
    Next  :  PPooledMemManagerItem;
end

                                                             194

                ___________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'POOLEDMM'_____________________*
 *___________________
                TPooledMemManagerItem is used internally by the TPooledMemManager (197  ) class to main-
                tain the free list block.  It simply points to the next free block.
                17.4          TNonFreePooledMemManager



                17.4.1         Description

                TNonFreePooledMemManager keeps a list of fixed-size memory blocks in memory.  Each block
                has the same size, making it suitable for storing a lot of records of the same type.  It does
                not free the items stored in it, except when the list is cleared as a whole.

                It allocates memory for the blocks in a exponential way, i.e.  each time a new block of memory
                must be allocated, it's size is the double of the last block.  The first block will contain 8 items.
                17.4.2         Method  overview

                __Page______Property___________________Description_________________________________________________________________*
 *___________
                  195       Clear                      Clears the memory
                  195       Create                     Creates a new instance of  TNonFreePooledMemManager
                  196       Destroy                    Removes the TNonFreePooledMemManager instance from mem-
                                                       ory
                  196       EnumerateItems             Enumerate all items in the list
                __196_______NewItem____________________Return_a_pointer_to_a_new_memory_block______________________________________*
 *___________
                17.4.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __196_______ItemSize________r____________Size_of_an_item_in_the_list_______________________________________________*
 *___________
                17.4.4         TNonFreePooledMemManager.Clear

    Synopsis:    Clears the memory

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear  clears  all  blocks  from  memory,  freeing  the  allocated  memory  blocks.   None  of  the
                pointers returned by NewItem (196  ) is valid after a call to Clear

    See also:    TNonFreePooledMemManager.NewItem (196  )
                17.4.5         TNonFreePooledMemManager.Create

    Synopsis:    Creates a new instance of  TNonFreePooledMemManager

Declaration:     constructor  Create(TheItemSize:  Integer)

    Visibility:   public

Description:     Create  creates  a  new  instance  of  TNonFreePooledMemManager  and  sets  the  item  size  to
                TheItemSize.

       Errors:   If not enough memory is available, an exception may be raised.

    See also:    TNonFreePooledMemManager.ItemSize (196  )



                                                                                 195

                ___________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'POOLEDMM'_____________________*
 *___________________
                17.4.6         TNonFreePooledMemManager.Destroy

    Synopsis:    Removes the TNonFreePooledMemManager instance from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy clears the list, clears the internal structures, and then calls the inherited Destroy.

                Destroy should never be called directly.  Instead Free should be used, or FreeAndNil

    See also:    TNonFreePooledMemManager.Create (195  ), TNonFreePooledMemManager.Clear (195  )
                17.4.7         TNonFreePooledMemManager.NewItem

    Synopsis:    Return a pointer to a new memory block

Declaration:     function  NewItem  :  Pointer

    Visibility:   public

Description:     NewItem returns a pointer to an unused memory block of size ItemSize (196  ).  It will allocate
                new memory on the heap if necessary.

                Note that there is no way to mark the memory block as free, except by clearing the whole
                list.

       Errors:   If no more memory is available, an exception may be raised.

    See also:    TNonFreePooledMemManager.Clear (195  )
                17.4.8         TNonFreePooledMemManager.EnumerateItems

    Synopsis:    Enumerate all items in the list

Declaration:     procedure  EnumerateItems(const  Method:  TEnumItemsMethod)

    Visibility:   public

Description:     EnumerateItems will enumerate over all items in the list, passing the items to Method.  This
                can be used to execute certain operations on all items in the list.  (for example, simply list
                them)
                17.4.9         TNonFreePooledMemManager.ItemSize

    Synopsis:    Size of an item in the list

Declaration:     Property  ItemSize  :  Integer

    Visibility:   public

      Access:    Read

Description:     ItemSize is the size of a single block in the list.  It's a fixed size determined when the list
                is created.

    See also:    TNonFreePooledMemManager.Create (195  )



                                                                                 196

                ___________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'POOLEDMM'_____________________*
 *___________________
                17.5          TPooledMemManager



                17.5.1         Description

                TPooledMemManager  is  a  class  which  maintains  a  linked  list  of  blocks,  represented  by  the
                TPooledMemManagerItem (195  ) record.  It should not be used directly, but should be de-
                scended from and the descendent should implement the actual memory manager.
                17.5.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  197       Clear           Clears the list
                  197       Create          Creates a new instance of the TPooledMemManager class
                __197_______Destroy_________Removes_an_instance_of__TPooledMemManager_class_from_memory____________________________*
 *___________
                17.5.3         Property  overview

                __Page______Property________________________________Access_______Description_______________________________________*
 *___________
                  199       AllocatedCount                          r            Total number of allocated items in the list
                  198       Count                                   r            Number of items in the list
                  199       FreeCount                               r            Number of free items in the list
                  199       FreedCount                              r            Total number of freed items in the list.
                  198       MaximumFreeCountRatio                   rw           Maximum  ratio  of  free  items  over  total
                                                                                 items
                __198_______MinimumFreeCount________________________rw___________Minimum_count_of_free_items_in_the_list___________*
 *___________
                17.5.4         TPooledMemManager.Clear

    Synopsis:    Clears the list

Declaration:     procedure  Clear

    Visibility:   public

Description:     Clear clears the list, it disposes all items in the list.

    See also:    TPooledMemManager.FreedCount (199  )
                17.5.5         TPooledMemManager.Create

    Synopsis:    Creates a new instance of the TPooledMemManager class

Declaration:     constructor  Create

    Visibility:   public

Description:     Create initializes all necessary properties and then calls the inherited create.

    See also:    TPooledMemManager.Destroy (197  )
                17.5.6         TPooledMemManager.Destroy

    Synopsis:    Removes an instance of  TPooledMemManager class from memory

Declaration:     destructor  Destroy;    Override



                                                                                 197

                ___________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'POOLEDMM'_____________________*
 *___________________
    Visibility:  public

Description:     Destroy calls Clear (197  ) and then calls the inherited destroy.

                Destroy should never be called directly.  Instead Free should be used, or FreeAndNil

    See also:    TPooledMemManager.Create (197  )
                17.5.7         TPooledMemManager.MinimumFreeCount

    Synopsis:    Minimum count of free items in the list

Declaration:     Property  MinimumFreeCount  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     MinimumFreeCount is the minimum number of free items in the linked list.  When disposing
                an item in the list, the number of items is checked, and only if the required number of free
                items is present, the item is actually freed.

                The default value is 100000

    See also:    TPooledMemManager.MaximumFreeCountRatio (198  )
                17.5.8         TPooledMemManager.MaximumFreeCountRatio

    Synopsis:    Maximum ratio of free items over total items

Declaration:     Property  MaximumFreeCountRatio  :  Integer

    Visibility:   public

      Access:    Read,Write

Description:     MaximumFreeCountRatio  is  the  maximum  ratio  (divided  by  8)  of  free  elements  over  the
                total amount of elements:  When disposing an item in the list, if the number of free items is
                higher than this ratio, the item is freed.

                The default value is 8.

    See also:    TPooledMemManager.MinimumFreeCount (198  )
                17.5.9         TPooledMemManager.Count

    Synopsis:    Number of items in the list

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read

Description:     Count is the total number of items allocated from the list.

    See also:    TPooledMemManager.FreeCount (199  ), TPooledMemManager.AllocatedCount (199  ), TPooled-
                MemManager.FreedCount (199  )



                                                                                 198

                ___________________________________________________CHAPTER_17.___REFERENCE_FOR_UNIT_'POOLEDMM'_____________________*
 *___________________
                17.5.10          TPooledMemManager.FreeCount

    Synopsis:    Number of free items in the list

Declaration:     Property  FreeCount  :  Integer

    Visibility:   public

      Access:    Read

Description:     FreeCount is the current total number of free items in the list.

    See also:    TPooledMemManager.Count (198  ), TPooledMemManager.AllocatedCount (199  ), TPooled-
                MemManager.FreedCount (199  )
                17.5.11          TPooledMemManager.AllocatedCount

    Synopsis:    Total number of allocated items in the list

Declaration:     Property  AllocatedCount  :  Int64

    Visibility:   public

      Access:    Read

Description:     AllocatedCount is the total number of newly allocated items on the list.

    See also:    TPooledMemManager.Count (198  ), TPooledMemManager.FreeCount (199  ), TPooledMem-
                Manager.FreedCount (199  )
                17.5.12          TPooledMemManager.FreedCount

    Synopsis:    Total number of freed items in the list.

Declaration:     Property  FreedCount  :  Int64

    Visibility:   public

      Access:    Read

Description:     FreedCount is the total number of elements actually freed in the list.

    See also:    TPooledMemManager.Count (198  ), TPooledMemManager.FreeCount (199  ), TPooledMem-
                Manager.AllocatedCount (199  )
                                                                                 199


Chapter   18


Reference   for   unit   'process'
18.1          Used  units
                                    Table 18.1:  Used units by unit 'process'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     Pipes           189
                                                     sysutils         ??



18.2          Overview


The  Process  unit  contains  the  code  for  the  TProcess  (202  )  component,  a  cross-platform
component to start and control other programs, offering also access to standard input and
output for these programs.

TProcess does not handle wildcard expansion, does not support complex pipelines as in Unix.
If this behaviour is desired, the shell can be executed with the pipeline as the command it
should execute.
18.3          Constants,  types  and  variables



18.3.1         Types

TProcessOption  =  (poRunSuspended,poWaitOnExit,poUsePipes,
                              poStderrToOutPut,poNoConsole,poNewConsole,
                              poDefaultErrorMode,poNewProcessGroup,poDebugProcess,
                              poDebugOnlyThisProcess)


When a new process is started using TProcess.Execute (205  ), these options control the way
the process is started.  Note that not all options are supported on all platforms.


TProcessOptions=  Set  of  (poDebugOnlyThisProcess,poDebugProcess,
                                         poDefaultErrorMode,poNewConsole,



                                                             200

________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________________________*
 *___

                       Table 18.2:  Enumeration values for type TProcessOption



__Value__________________________________Explanation_______________________________________________________________________________*
 *___________
  poDebugOnlyThisProcess                 Do not follow processes started by this process (Win32 only)
  poDebugProcess                         Allow debugging of the process (Win32 only)
  poDefaultErrorMode                     Use default error handling.
  poNewConsole                           Start a new console window for the process (Win32 only)
  poNewProcessGroup                      Start the process in a new process group (Win32 only)
  poNoConsole                            Do not allow access to the console window for the process (Win32 only)
  poRunSuspended                         Start the process in suspended state.
  poStderrToOutPut                       Redirect standard error to the standard output stream.
  poUsePipes                             Use pipes to redirect standard input and output.
  poWaitOnExit                           Wait for the process to terminate before returning.

                                         poNewProcessGroup,poNoConsole,poRunSuspended,
                                         poStderrToOutPut,poUsePipes,poWaitOnExit)


Set of TProcessOption (200  ).


TProcessPriority  =  (ppHigh,ppIdle,ppNormal,ppRealTime)
                       Table 18.3:  Enumeration values for type TProcessPriority



__Value________________Explanation_____________________________________________________________________________________________
  ppHigh               The process runs at higher than normal priority.
  ppIdle               The process only runs when the system is idle (i.e.  has nothing else to do)
  ppNormal             The process runs at normal priority.
  ppRealTime           The process runs at real-time priority.
This  enumerated  type  determines  the  priority  of  the  newly  started  process.   It  translates
to  default  platform  specific  constants.  If  finer  control  is  needed,  then  platform-dependent
mechanism need to be used to set the priority.


TShowWindowOptions  =  (swoNone,swoHIDE,swoMaximize,swoMinimize,
                                    swoRestore,swoShow,swoShowDefault,
                                    swoShowMaximized,swoShowMinimized,
                                    swoshowMinNOActive,swoShowNA,swoShowNoActivate,
                                    swoShowNormal)


This type describes what the new process' main window should look like.  Most of these have
only effect on Windows.  They are ignored on other systems.


TStartupOption  =  (suoUseShowWindow,suoUseSize,suoUsePosition,
                             suoUseCountChars,suoUseFillAttribute)


These options are mainly for Win32, and determine what should be done with the application
once it's started.



                                                                 201

________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________________________*
 *___

                  Table 18.4:  Enumeration values for type TShowWindowOptions


     __Value______________________________Explanation____________________________________________________________________
       swoHIDE                            The main window is hidden.
       swoMaximize                        The main window is maximized.
       swoMinimize                        The main window is minimized.
       swoNone                            Allow system to position the window.
       swoRestore                         Restore the previous position.
       swoShow                            Show the main window.
       swoShowDefault                     When showing Show the main window on
       swoShowMaximized                   The main window is shown maximized
       swoShowMinimized                   The main window is shown minimized
       swoshowMinNOActive                 The main window is shown minimized but not activated
       swoShowNA                          The main window is shown but not activated
       swoShowNoActivate                  The main window is shown but not activated
       swoShowNormal                      The main window is shown normally

                       Table 18.5:  Enumeration values for type TStartupOption



__Value___________________________Explanation______________________________________________________________________________________*
 *___
  suoUseCountChars                Use the console character width as specified in TProcess (202  ).
  suoUseFillAttribute             Use the console fill attribute as specified in TProcess (202  ).
  suoUsePosition                  Use the window sizes as specified in TProcess (202  ).
  suoUseShowWindow                Use the Show Window options specified in TShowWindowOption (201  )
  suoUseSize                      Use the window sizes as specified in TProcess (202  )

TStartupOptions=  Set  of  (suoUseCountChars,suoUseFillAttribute,
                                         suoUsePosition,suoUseShowWindow,suoUseSize)


Set of TStartUpOption (201  ).
18.4          EProcess



18.4.1         Description

Exception raised when an error occurs in a TProcess routine.
18.5          TProcess



18.5.1         Description

TProcess is a component that can be used to start and control other processes (program-
s/binaries).  It  contains  a  lot  of  options  that  control  how  the  process  is  started.  Many  of
these are Win32 specific, and have no effect on other platforms, so they should be used with
care.

The simplest way to use this component is to create an instance, set the CommandLine (211  )
property  to  the  full  pathname  of  the  program  that  should  be  executed,  and  call  Execute
                                                                 202

________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________________________*
 *___
(205  ).  To determine whether the process is still running (i.e.  has not stopped executing),
the Running (214  ) property can be checked.

More advanced techniques can be used with the Options (213  ) settings.
18.5.2         Method  overview

__Page______Property______________Description_________________________________________________________________________________
  205       CloseInput            Close the input stream of the process
  205       CloseOutput           Close the output stream of the process
  206       CloseStderr           Close the error stream of the process
  204       Create                Create a new instance of the TProcess class.
  204       Destroy               Destroy this instance of  TProcess
  205       Execute               Execute the program with the given options
  206       Resume                Resume execution of a suspended process
  206       Suspend               Suspend a running process
  207       Terminate             Terminate a running process
__207_______WaitOnExit____________Wait_for_the_program_to_stop_executing._____________________________________________________


                                                                 203

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
                18.5.3         Property  overview

                __Page______Property____________________Access_______Description___________________________________________________*
 *___________
                  211       Active                      rw           Start or stop the process.
                  211       ApplicationName             rw           Name of the application to start
                  211       CommandLine                 rw           Command-line to execute
                  212       ConsoleTitle                rw           Title of the console window
                  212       CurrentDirectory            rw           Working directory of the process.
                  212       Desktop                     rw           Desktop on which to start the process.
                  212       Environment                 rw           Environment variables for the new process
                  210       ExitStatus                  r            Exit status of the process.
                  217       FillAttribute               rw           Color attributes of the characters in the console win-
                                                                     dow (Windows only)
                  207       Handle                      r            Handle of the process
                  210       InheritHandles              rw           Should the created process inherit the open handles
                                                                     of the current process.
                  209       Input                       r            Stream connected to standard input of the process.
                  213       Options                     rw           Options to be used when starting the process.
                  209       Output                      r            Stream connected to standard output of the process.
                  213       Priority                    rw           Priority at which the process is running.
                  208       ProcessHandle               r            Alias for Handle (207  )
                  208       ProcessID                   r            ID of the process.
                  214       Running                     r            Determines wheter the process is still running.
                  215       ShowWindow                  rw           Determines how the process main window is shown
                                                                     (Windows only)
                  214       StartupOptions              rw           Additional (Windows) startup options
                  210       Stderr                      r            Stream connected to standard diagnostic output of
                                                                     the process.
                  208       ThreadHandle                r            Main process thread handle
                  209       ThreadID                    r            ID of the main process thread
                  215       WindowColumns               rw           Number  of  columns  in  console  window  (windows
                                                                     only)
                  216       WindowHeight                rw           Height of the process main window
                  216       WindowLeft                  rw           X-coordinate of the initial window (Windows only)
                  207       WindowRect                  rw           Positions for the main program window.
                  216       WindowRows                  rw           Number of rows in console window (Windows only)
                  217       WindowTop                   rw           Y-coordinate of the initial window (Windows only)
                __217_______WindowWidth_________________rw___________Height_of_the_process_main_window_(Windows_only)______________*
 *___________
                18.5.4         TProcess.Create

    Synopsis:    Create a new instance of the TProcess class.

Declaration:     constructor  Create(AOwner:  TComponent);    Override

    Visibility:   public

Description:     Create creates a new instance of the TProcess class.  After calling the inherited constructor,
                it simply sets some default values.
                18.5.5         TProcess.Destroy

    Synopsis:    Destroy this instance of  TProcess

Declaration:     destructor  Destroy;    Override



                                                                                 204

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
    Visibility:  public

Description:     Destroy cleans up this instance of  TProcess.  Prior to calling the inherited destructor, it
                cleans  up  any  streams  that  may  have  been  created.   If  a  process  was  started  and  is  still
                executed,  it  is  not  stopped,  but  the  standard  input/output/stderr  streams  are  no  longer
                available, because they have been destroyed.

       Errors:   None.

    See also:    TProcess.Create (204  )
                18.5.6         TProcess.Execute

    Synopsis:    Execute the program with the given options

Declaration:     procedure  Execute;    Virtual

    Visibility:   public

Description:     Execute  actually  executes  the  program  as  specified  in  CommandLine  (211  ),  applying  as
                much as of the specified options as supported on the current platform.

                If the poWaitOnExit option is specified in Options (213  ), then the call will only return when
                the program has finished executing (or if an error occured).  If this option is not given, the
                call returns immediatly, but the WaitOnExit (207  ) call can be used to wait for it to close,
                or the Running (214  ) call can be used to check whether it is still running.

                The TProcess.Terminate (207  ) call can be used to terminate the program if it is still running,
                or the Suspend (206  ) call can be used to temporarily stop the program's execution.

                The ExitStatus (210  ) function can be used to check the program's exit status, after it has
                stopped executing.

       Errors:   On error a EProcess (202  ) exception is raised.

    See also:    TProcess.Running  (214  ),  TProcess.WaitOnExit  (207  ),  TProcess.Terminate  (207  ),  TPro-
                cess.Suspend (206  ), TProcess.Resume (206  ), TProcess.ExitStatus (210  )
                18.5.7         TProcess.CloseInput

    Synopsis:    Close the input stream of the process

Declaration:     procedure  CloseInput;    Virtual

    Visibility:   public

Description:     CloseInput closes the input file descriptor of the process, that is, it closes the handle of the
                pipe to standard input of the process.

    See also:    TProcess.Input (209  ), TProcess.StdErr (210  ), TProcess.Output (209  ), TProcess.CloseOutput
                (205  ), TProcess.CloseStdErr (206  )
                18.5.8         TProcess.CloseOutput

    Synopsis:    Close the output stream of the process

Declaration:     procedure  CloseOutput;    Virtual

    Visibility:   public



                                                                                 205

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
Description:     CloseOutput closes the output file descriptor of the process, that is, it closes the handle of
                the pipe to standard output of the process.

    See also:    TProcess.Output (209  ), TProcess.Input (209  ), TProcess.StdErr (210  ), TProcess.CloseInput
                (205  ), TProcess.CloseStdErr (206  )
                18.5.9         TProcess.CloseStderr

    Synopsis:    Close the error stream of the process

Declaration:     procedure  CloseStderr;    Virtual

    Visibility:   public

Description:     CloseStdErr closes the standard error file descriptor of the process,  that is,  it closes the
                handle of the pipe to standard error output of the process.

    See also:    TProcess.Output (209  ), TProcess.Input (209  ), TProcess.StdErr (210  ), TProcess.CloseInput
                (205  ), TProcess.CloseStdErr (206  )
                18.5.10          TProcess.Resume

    Synopsis:    Resume execution of a suspended process

Declaration:     function  Resume  :  Integer;    Virtual

    Visibility:   public

Description:     Resume should be used to let a suspended process resume it's execution.  It should be called
                in particular when the poRunSuspended flag is set in Options (213  ).

       Errors:   None.

    See also:    TProcess.Suspend (206  ), TProcess.Options (213  ), TProcess.Execute (205  ), TProcess.Terminate
                (207  )
                18.5.11          TProcess.Suspend

    Synopsis:    Suspend a running process

Declaration:     function  Suspend  :  Integer;    Virtual

    Visibility:   public

Description:     Suspend suspends a running process.  If the call is successful, the process is suspended:  it
                stops running, but can be made to execute again using the Resume (206  ) call.

                Suspend is fundamentally different from TProcess.Terminate (207  ) which actually stops the
                process.

       Errors:   On error, a nonzero result is returned.

    See also:    TProcess.Options (213  ), TProcess.Resume (206  ), TProcess.Terminate (207  ), TProcess.Execute
                (205  )


                                                                                 206

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
                18.5.12          TProcess.Terminate

    Synopsis:    Terminate a running process

Declaration:     function  Terminate(AExitCode:  Integer)  :  Boolean;    Virtual

    Visibility:   public

Description:     Terminate stops the execution of the running program.  It effectively stops the program.

                On  Windows,  the  program  will  report  an  exit  code  of  AExitCode,  on  other  systems,  this
                value is ignored.

       Errors:   On error, a nonzero value is returned.

    See also:    TProcess.ExitStatus (210  ), TProcess.Suspend (206  ), TProcess.Execute (205  ), TProcess.WaitOnExit
                (207  )
                18.5.13          TProcess.WaitOnExit

    Synopsis:    Wait for the program to stop executing.

Declaration:     function  WaitOnExit  :  Boolean

    Visibility:   public

Description:     WaitOnExit waits for the running program to exit.  It returns True if the wait was succesful,
                or False if there was some error waiting for the program to exit.

                Note that the return value of this function has changed.  The old return value was a DWord
                with  a  platform  dependent  error  code.   To  make  things  consistent  and  cross-platform,  a
                boolean return type was used.

       Errors:   On  error,  False  is  returned.   No  extended  error  information  is  available,  as  it  is  highly
                system dependent.

    See also:    TProcess.ExitStatus (210  ), TProcess.Terminate (207  ), TProcess.Running (214  )
                18.5.14          TProcess.WindowRect

    Synopsis:    Positions for the main program window.

Declaration:     Property  WindowRect  :  Trect

    Visibility:   public

      Access:    Read,Write

Description:     WindowRect can be used to specify the position of
                18.5.15          TProcess.Handle

    Synopsis:    Handle of the process

Declaration:     Property  Handle  :  THandle

    Visibility:   public

      Access:    Read

                                                                                 207

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
Description:     Handle identifies the process.  In Unix systems, this is the process ID. On windows, this is
                the process handle.  It can be used to signal the process.

                The handle is only valid after TProcess.Execute (205  ) has been called.  It is not reset after
                the process stopped.

    See also:    TProcess.ThreadHandle (208  ), TProcess.ProcessID (208  ), TProcess.ThreadID (209  )
                18.5.16          TProcess.ProcessHandle

    Synopsis:    Alias for Handle (207  )

Declaration:     Property  ProcessHandle  :  THandle

    Visibility:   public

      Access:    Read

Description:     ProcessHandle equals Handle (207  ) and is provided for completeness only.

    See also:    TProcess.Handle  (207  ),  TProcess.ThreadHandle  (208  ),  TProcess.ProcessID  (208  ),  TPro-
                cess.ThreadID (209  )
                18.5.17          TProcess.ThreadHandle

    Synopsis:    Main process thread handle

Declaration:     Property  ThreadHandle  :  THandle

    Visibility:   public

      Access:    Read

Description:     ThreadHandle is the main process thread handle.  On Unix, this is the same as the process
                ID, on Windows, this may be a different handle than the process handle.

                The handle is only valid after TProcess.Execute (205  ) has been called.  It is not reset after
                the process stopped.

    See also:    TProcess.Handle (207  ), TProcess.ProcessID (208  ), TProcess.ThreadID (209  )
                18.5.18          TProcess.ProcessID

    Synopsis:    ID of the process.

Declaration:     Property  ProcessID  :  Integer

    Visibility:   public

      Access:    Read

Description:     ProcessID  is  the  ID  of  the  process.  It  is  the  same  as  the  handle  of  the  process  on  Unix
                systems, but on Windows it is different from the process Handle.

                The ID is only valid after TProcess.Execute (205  ) has been called.  It is not reset after the
                process stopped.

    See also:    TProcess.Handle (207  ), TProcess.ThreadHandle (208  ), TProcess.ThreadID (209  )


                                                                                 208

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
                18.5.19          TProcess.ThreadID

    Synopsis:    ID of the main process thread

Declaration:     Property  ThreadID  :  Integer

    Visibility:   public

      Access:    Read

Description:     ProcessID is the ID of the main process thread.  It is the same as the handle of the main
                proces thread (or the process itself) on Unix systems, but on Windows it is different from
                the thread Handle.

                The ID is only valid after TProcess.Execute (205  ) has been called.  It is not reset after the
                process stopped.

    See also:    TProcess.ProcessID (208  ), TProcess.Handle (207  ), TProcess.ThreadHandle (208  )
                18.5.20          TProcess.Input

    Synopsis:    Stream connected to standard input of the process.

Declaration:     Property  Input  :  TOutputPipeStream

    Visibility:   public

      Access:    Read

Description:     Input is a stream which is connected to the process' standard input file handle.  Anything
                written to this stream can be read by the process.

                The Input stream is only instantiated when the poUsePipes flag is used in Options (213  ).

                Note  that  writing  to  the  stream  may  cause  the  calling  process  to  be  suspended  when  the
                created  process  is  not  reading  from  it's  input,  or  to  cause  errors  when  the  process  has
                terminated.

    See also:    TProcess.OutPut (209  ),  TProcess.StdErr (210  ),  TProcess.Options (213  ),  TProcessOption
                (200  )
                18.5.21          TProcess.Output

    Synopsis:    Stream connected to standard output of the process.

Declaration:     Property  Output  :  TInputPipeStream

    Visibility:   public

      Access:    Read

Description:     Output is a stream which is connected to the process' standard output file handle.  Anything
                written to standard output by the created process can be read from this stream.

                The Output stream is only instantiated when the poUsePipes flag is used in Options (213  ).

                The Output stream also contains any data written to standard diagnostic output (stderr)
                when the poStdErrToOutPut flag is used in Options (213  ).

                Note  that  reading  from  the  stream  may  cause  the  calling  process  to  be  suspended  when
                the created process is not writing anything to standard output, or to cause errors when the
                process has terminated.

    See also:    TProcess.InPut  (209  ),  TProcess.StdErr  (210  ),  TProcess.Options  (213  ),  TProcessOption
                (200  )



                                                                                 209

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
                18.5.22          TProcess.Stderr

    Synopsis:    Stream connected to standard diagnostic output of the process.

Declaration:     Property  Stderr  :  TInputPipeStream

    Visibility:   public

      Access:    Read

Description:     StdErr is a stream which is connected to the process' standard diagnostic output file handle
                (StdErr).  Anything  written  to  standard  diagnostic  output  by  the  created  process  can  be
                read from this stream.

                The StdErr stream is only instantiated when the poUsePipes flag is used in Options (213  ).

                The  Output  stream  equals  the  Output  (209  )  when  the  poStdErrToOutPut  flag  is  used  in
                Options (213  ).

                Note  that  reading  from  the  stream  may  cause  the  calling  process  to  be  suspended  when
                the created process is not writing anything to standard output, or to cause errors when the
                process has terminated.

    See also:    TProcess.InPut  (209  ),  TProcess.Output  (209  ),  TProcess.Options  (213  ),  TProcessOption
                (200  )
                18.5.23          TProcess.ExitStatus

    Synopsis:    Exit status of the process.

Declaration:     Property  ExitStatus  :  Integer

    Visibility:   public

      Access:    Read

Description:     ExitStatus contains the exit status as reported by the process when it stopped executing.
                The value of this property is only meaningful when the process is no longer running.  If it is
                not running then the value is zero.

    See also:    TProcess.Running (214  ), TProcess.Terminate (207  )
                18.5.24          TProcess.InheritHandles

    Synopsis:    Should the created process inherit the open handles of the current process.

Declaration:     Property  InheritHandles  :  Boolean

    Visibility:   public

      Access:    Read,Write

Description:     InheritHandles determines whether the created process inherits the open handles of the
                current process (value True) or not (False).

                On Unix, setting this variable has no effect.

    See also:    TProcess.InPut (209  ), TProcess.Output (209  ), TProcess.StdErr (210  )

                                                                                 210

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
                18.5.25          TProcess.Active

    Synopsis:    Start or stop the process.

Declaration:     Property  Active  :  Boolean

    Visibility:   published

      Access:    Read,Write

Description:     Active starts the process if it is set to True, or terminates the process if set to False.  It's
                mostly intended for use in an IDE.

    See also:    TProcess.Execute (205  ), TProcess.Terminate (207  )
                18.5.26          TProcess.ApplicationName

    Synopsis:    Name of the application to start

Declaration:     Property  ApplicationName  :  String

    Visibility:   published

      Access:    Read,Write

Description:     ApplicationName is an alias for TProcess.CommandLine (211  ).  It's mostly foruse in the
                Windows  CreateProcess  call.  If  CommandLine  is  not  set,  then  ApplicationName  will  be
                used instead.

                Note that either CommandLine or ApplicationName must be set prior to calling Execute.

    See also:    TProcess.CommandLine (211  )
                18.5.27          TProcess.CommandLine

    Synopsis:    Command-line to execute

Declaration:     Property  CommandLine  :  String

    Visibility:   published

      Access:    Read,Write

Description:     CommandLine is the command-line to be executed:  this is the name of the program to be
                executed, followed by any options it should be passed.

                If  the  command  to  be  executed  or  any  of  the  arguments  contains  whitespace  (space,  tab
                character, linefeed character) it should be enclosed in single or double quotes.

                If no absolute pathname is given for the command to be executed, it is searched for in the
                PATH environment variable.  On Windows, the current directory always will be searched first.
                On other platforms, this is not so.

                Note that either CommandLine or ApplicationName must be set prior to calling Execute.

    See also:    TProcess.ApplicationName (211  )
                                                                                 211

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
                18.5.28          TProcess.ConsoleTitle

    Synopsis:    Title of the console window

Declaration:     Property  ConsoleTitle  :  String

    Visibility:   published

      Access:    Read,Write

Description:     ConsoleTitle  is  used  on  Windows  when  executing  a  console  application:  it  specifies  the
                title caption of the console window.  On other platforms, this property is currently ignored.

                Changing this property after the process was started has no effect.

    See also:    TProcess.WindowColumns (215  ), TProcess.WindowRows (216  )
                18.5.29          TProcess.CurrentDirectory

    Synopsis:    Working directory of the process.

Declaration:     Property  CurrentDirectory  :  String

    Visibility:   published

      Access:    Read,Write

Description:     CurrentDirectory specifies the working directory of the newly started process.

                Changing this property after the process was started has no effect.

    See also:    TProcess.Environment (212  )
                18.5.30          TProcess.Desktop

    Synopsis:    Desktop on which to start the process.

Declaration:     Property  Desktop  :  String

    Visibility:   published

      Access:    Read,Write

Description:     DeskTop  is  used  on  Windows  to  determine  on  which  desktop  the  process'  main  window
                should be shown.  Leaving this empty means the process is started on the same desktop as
                the currently running process.

                Changing this property after the process was started has no effect.

                On unix, this parameter is ignored.

    See also:    TProcess.Input (209  ), TProcess.Output (209  ), TProcess.StdErr (210  )
                18.5.31          TProcess.Environment

    Synopsis:    Environment variables for the new process

Declaration:     Property  Environment  :  TStrings

    Visibility:   published

      Access:    Read,Write



                                                                                 212

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
Description:     Environment contains the environment for the new process; it's a list of Name=Value pairs,
                one per line.

                If it is empty, the environment of the current process is passed on to the new process.

    See also:    TProcess.Options (213  )
                18.5.32          TProcess.Options

    Synopsis:    Options to be used when starting the process.

Declaration:     Property  Options  :  TProcessOptions

    Visibility:   published

      Access:    Read,Write

Description:     Options determine how the process is started.  They should be set before the Execute (205  )
                call is made.



                                                                       Table 18.6:



                __option__________________________________Meaning__________________________________________________________________*
 *____________________________
                  poRunSuspended                          Start the process in suspended state.
                  poWaitOnExit                            Wait for the process to terminate before returning.
                  poUsePipes                              Use pipes to redirect standard input and output.
                  poStderrToOutPut                        Redirect standard error to the standard output stream.
                  poNoConsole                             Do not allow access to the console window for the process (Win32 only)
                  poNewConsole                            Start a new console window for the process (Win32 only)
                  poDefaultErrorMode                      Use default error handling.
                  poNewProcessGroup                       Start the process in a new process group (Win32 only)
                  poDebugProcess                          Allow debugging of the process (Win32 only)
                  poDebugOnlyThisProcess                  Do not follow processes started by this process (Win32 only)

    See also:    TProcessOption (200  ), TProcessOptions (201  ), TProcess.Priority (213  ), TProcess.StartUpOptions
                (214  )
                18.5.33          TProcess.Priority

    Synopsis:    Priority at which the process is running.

Declaration:     Property  Priority  :  TProcessPriority

    Visibility:   published

      Access:    Read,Write

Description:     Priority determines the priority at which the process is running.

                Note that not all priorities can be set by any user.  Usually, only users witha dministrative
                rights (the root user on Unix) can set a higher process priority.

                On unix, the process priority is mapped on Nice values as follows:

    See also:    TProcessPriority (201  )
                                                                                 213

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________

                                                                       Table 18.7:



                __Priority____________Meaning______________________________________________________________________________________*
 *____________
                  ppHigh              The process runs at higher than normal priority.
                  ppIdle              The process only runs when the system is idle (i.e.  has nothing else to do)
                  ppNormal            The process runs at normal priority.
                  ppRealTime          The process runs at real-time priority.

                                                                       Table 18.8:

                                                            __Priority____________Nice_value_______
                                                              ppHigh              20
                                                              ppIdle              20
                                                              ppNormal            0
                                                              ppRealTime          -20

                18.5.34          TProcess.StartupOptions

    Synopsis:    Additional (Windows) startup options

Declaration:     Property  StartupOptions  :  TStartupOptions

    Visibility:   published

      Access:    Read,Write

Description:     StartUpOptions  contains  additional  startup  options,  used  mostly  on  Windows  system.
                They determine which other window layout properties are taken into account when starting
                the new process.



                                                                       Table 18.9:

                 _Priority____________________________Meaning______________________________________________________________________*
 *____________
                   suoUseShowWindow                   Use the Show Window options specified in ShowWindow (215  )
                   suoUseSize                         Use the specified window sizes
                   suoUsePosition                     Use the specified window sizes.
                   suoUseCountChars                   Use the specified console character width.
                   suoUseFillAttribute                Use the console fill attribute specified in FillAttribute (217  ).
    See also:    TProcess.ShowWindow (215  ), TProcess.WindowHeight (216  ), TProcess.WindowWidth (217  ),
                TProcess.WindowLeft (216  ), TProcess.WindowTop (217  ), TProcess.WindowColumns (215  ),
                TProcess.WindowRows (216  ), TProcess.FillAttribute (217  )
                18.5.35          TProcess.Running

    Synopsis:    Determines wheter the process is still running.

Declaration:     Property  Running  :  Boolean

    Visibility:   published
                                                                                 214

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
      Access:    Read

Description:     Running can be read to determine whether the process is still running.

    See also:    TProcess.Terminate (207  ), TProcess.Active (211  ), TProcess.ExitStatus (210  )
                18.5.36          TProcess.ShowWindow

    Synopsis:    Determines how the process main window is shown (Windows only)

Declaration:     Property  ShowWindow  :  TShowWindowOptions

    Visibility:   published

      Access:    Read,Write

Description:     ShowWindow determines how the process' main window is shown.  It is useful only on Win-
                dows.



                                                                      Table 18.10:

                   __Option____________________________Meaning_____________________________________________________________________*
 *________
                     swoNone                           Allow system to position the window.
                     swoHIDE                           The main window is hidden.
                     swoMaximize                       The main window is maximized.
                     swoMinimize                       The main window is minimized.
                     swoRestore                        Restore the previous position.
                     swoShow                           Show the main window.
                     swoShowDefault                    When showing Show the main window on a default position
                     swoShowMaximized                  The main window is shown maximized
                     swoShowMinimized                  The main window is shown minimized
                     swoshowMinNOActive                The main window is shown minimized but not activated
                     swoShowNA                         The main window is shown but not activated
                     swoShowNoActivate                 The main window is shown but not activated
                     swoShowNormal                     The main window is shown normally



                18.5.37          TProcess.WindowColumns

    Synopsis:    Number of columns in console window (windows only)

Declaration:     Property  WindowColumns  :  Cardinal

    Visibility:   published

      Access:    Read,Write

Description:     WindowColumns is the number of columns in the console window, used to run the command
                in.  This property is only effective if suoUseCountChars is specified in StartupOptions (214  )

    See also:    TProcess.WindowHeight (216  ), TProcess.WindowWidth (217  ), TProcess.WindowLeft (216  ),
                TProcess.WindowTop  (217  ),  TProcess.WindowRows  (216  ),  TProcess.FillAttribute  (217  ),
                TProcess.StartupOptions (214  )
                                                                                 215

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
                18.5.38          TProcess.WindowHeight

    Synopsis:    Height of the process main window

Declaration:     Property  WindowHeight  :  Cardinal

    Visibility:   published

      Access:    Read,Write

Description:     WindowHeight is the initial height (in pixels) of the process' main window.  This property
                is only effective if  suoUseSize is specified in StartupOptions (214  )

    See also:    TProcess.WindowWidth  (217  ),  TProcess.WindowLeft  (216  ),  TProcess.WindowTop  (217  ),
                TProcess.WindowColumns (215  ), TProcess.WindowRows (216  ), TProcess.FillAttribute (217  ),
                TProcess.StartupOptions (214  )
                18.5.39          TProcess.WindowLeft

    Synopsis:    X-coordinate of the initial window (Windows only)

Declaration:     Property  WindowLeft  :  Cardinal

    Visibility:   published

      Access:    Read,Write

Description:     WindowLeft is the initial X coordinate (in pixels) of the process' main window, relative to
                the left border of the desktop.  This property is only effective if suoUsePosition is specified
                in StartupOptions (214  )

    See also:    TProcess.WindowHeight (216  ), TProcess.WindowWidth (217  ), TProcess.WindowTop (217  ),
                TProcess.WindowColumns (215  ), TProcess.WindowRows (216  ), TProcess.FillAttribute (217  ),
                TProcess.StartupOptions (214  )
                18.5.40          TProcess.WindowRows

    Synopsis:    Number of rows in console window (Windows only)

Declaration:     Property  WindowRows  :  Cardinal

    Visibility:   published

      Access:    Read,Write

Description:     WindowRows  is  the  number  of  rows  in  the  console  window,  used  to  run  the  command  in.
                This property is only effective if  suoUseCountChars is specified in StartupOptions (214  )

    See also:    TProcess.WindowHeight (216  ), TProcess.WindowWidth (217  ), TProcess.WindowLeft (216  ),
                TProcess.WindowTop (217  ), TProcess.WindowColumns (215  ), TProcess.FillAttribute (217  ),
                TProcess.StartupOptions (214  )
                                                                                 216

                ________________________________________________________CHAPTER_18.___REFERENCE_FOR_UNIT_'PROCESS'_________________*
 *___________________
                18.5.41          TProcess.WindowTop

    Synopsis:    Y-coordinate of the initial window (Windows only)

Declaration:     Property  WindowTop  :  Cardinal

    Visibility:   published

      Access:    Read,Write

Description:     WindowTop is the initial Y coordinate (in pixels) of the process' main window,  relative to
                the top border of the desktop.  This property is only effective if suoUsePosition is specified
                in StartupOptions (214  )

    See also:    TProcess.WindowHeight (216  ), TProcess.WindowWidth (217  ), TProcess.WindowLeft (216  ),
                TProcess.WindowColumns (215  ), TProcess.WindowRows (216  ), TProcess.FillAttribute (217  ),
                TProcess.StartupOptions (214  )
                18.5.42          TProcess.WindowWidth

    Synopsis:    Height of the process main window (Windows only)

Declaration:     Property  WindowWidth  :  Cardinal

    Visibility:   published

      Access:    Read,Write

Description:     WindowWidth is the initial width (in pixels) of the process' main window.  This property is
                only effective if  suoUseSize is specified in StartupOptions (214  )

    See also:    TProcess.WindowHeight (216  ),  TProcess.WindowLeft (216  ),  TProcess.WindowTop (217  ),
                TProcess.WindowColumns (215  ), TProcess.WindowRows (216  ), TProcess.FillAttribute (217  ),
                TProcess.StartupOptions (214  )
                18.5.43          TProcess.FillAttribute

    Synopsis:    Color attributes of the characters in the console window (Windows only)

Declaration:     Property  FillAttribute  :  Cardinal

    Visibility:   published

      Access:    Read,Write

Description:     FillAttribute is a WORD value which specifies the background and foreground colors of
                the console window.

    See also:    TProcess.WindowHeight (216  ), TProcess.WindowWidth (217  ), TProcess.WindowLeft (216  ),
                TProcess.WindowTop (217  ), TProcess.WindowColumns (215  ), TProcess.WindowRows (216  ),
                TProcess.StartupOptions (214  )
                                                                                 217


Chapter   19


Reference   for   unit   'rttiutils'
19.1          Used  units
                                   Table 19.1:  Used units by unit 'rttiutils'


                                                   __Name__________Page_____
                                                     Classes           ??
                                                     StrUtils         218
                                                     sysutils          ??
                                                     typinfo           ??



19.2          Overview


The rttiutils unit is a unit providing simplified access to the RTTI information from published
properties  using  the  TPropInfoList  (220  )  class.   This  access  can  be  used  when  saving  or
restoring form properties at runtime, or for persisting other objects whose RTTI is available:
the  TPropsStorage  (223  )  class  can  be  used  for  this.  The  implementation  is  based  on  the
apputils unit from RXLib by AO ROSNO  and Master-Bank
19.3          Constants,  types  and  variables



19.3.1         Constants

sPropNameDelimiter  :  String  =  '_'


Separator used when constructing section/key names
19.3.2         Types

TEraseSectEvent  =  procedure(const  ASection:  String)  of  object


TEraseSectEvent is used by TPropsStorage (223  ) to clear a storage section, in a .ini file like
fashion:  The  call  should  remove  all  keys  in  the  section  ASection,  and  remove  the  section
from storage.



                                                             218

                ______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'RTTIUTILS'_________________*
 *___________________
                TFindComponentEvent  =  function(const  Name:  String)  :  TComponent


                TFindComponentEvent should return the component instance for the component with name
                path Name.  The name path should be relative to the global list of loaded components.


                TReadStrEvent  =  function(const  ASection:  String;const  Item:  String;
                                                         const  Default:  String)  :  String  of  object


                TReadStrEvent is used by TPropsStorage (223  ) to read strings from a storage mechanism,
                in a .ini file like fashion:  The call should read the string in ASection with key Item, and if
                it does not exist, Default should be returned.


                TWriteStrEvent  =  procedure(const  ASection:  String;const  Item:  String;
                                                            const  Value:  String)  of  object


                TWriteStrEvent is used by TPropsStorage (223  ) to write strings to a storage mechanism,
                in a .ini file like fashion:  The call should write the string Value in ASection with key Item.
                The section and key should be created if they didn't exist yet.
                19.3.3         Variables

                FindGlobalComponentCallBack  :  TFindComponentEvent


                FindGlobalComponentCallBack  is  called  by  UpdateStoredList  (220  )  whenever  it  needs  to
                resolve component references.  It should be set to a routine that locates a loaded component
                in the global list of loaded components.
                19.4          Procedures  and  functions



                19.4.1         CreateStoredItem

    Synopsis:    Concatenates component and property name

Declaration:     function  CreateStoredItem(const  CompName:  String;const  PropName:  String)
                                                           :  String

    Visibility:   default

Description:     CreateStoredItem  concatenates  CompName  and  PropName  if  they  are  both  empty.   The
                names are separated by a dot (.)  character.  If either of the names is empty, an empty string
                is returned.

                This function can be used to create items for the list of properties such as used in Update-
                StoredList (220  ), TPropsStorage.StoreObjectsProps (225  ) or TPropsStorage.LoadObjectsProps
                (224  ).

    See also:    ParseStoredItem  (219  ),  UpdateStoredList  (220  ),  TPropsStorage.StoreObjectsProps  (225  ),
                TPropsStorage.LoadObjectsProps (224  )
                19.4.2         ParseStoredItem

    Synopsis:    Split a property reference to component reference and property name

                                                                                 219

                ______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'RTTIUTILS'_________________*
 *___________________
Declaration:     function  ParseStoredItem(const  Item:  String;var  CompName:  String;
                                                       var  PropName:  String)  :  Boolean

    Visibility:  default

Description:     ParseStoredItem parses the property reference Item and splits it in a reference to a compo-
                nent (returned in CompName) and a name of a property (returned in PropName).  This function
                basically does the opposite of CreateStoredItem (219  ).  Note that both names should be non-
                empty, i.e., at least 1 dot character must appear in Item.

       Errors:   If an error occurred during parsing, False is returned.

    See also:    CreateStoredItem (219  ), UpdateStoredList (220  ), TPropsStorage.StoreObjectsProps (225  ),
                TPropsStorage.LoadObjectsProps (224  )
                19.4.3         UpdateStoredList

    Synopsis:    Update a stringlist with object references

Declaration:     procedure  UpdateStoredList(AComponent:  TComponent;AStoredList:  TStrings;
                                                           FromForm:  Boolean)

    Visibility:   default

Description:     UpdateStoredList will parse the strings in AStoredList using ParseStoredItem (219  ) and
                will replace the Objects properties with the instance of the object whose name each property
                path  in  the  list  refers  to.  If  FromForm  is  True,  then  all  instances  are  searched  relative  to
                AComponent, i.e.  they must be owned by AComponent.  If  FromForm is False the instances
                are searched in the global list of streamed components.  (the FindGlobalComponentCallBack
                (219  ) callback must be set for the search to work correctly in this case)

                If a component cannot be found,  the reference string to the property is removed from the
                stringlist.

       Errors:   If  AComponent is Nil, an exception may be raised.

    See also:    ParseStoredItem (219  ), TPropsStorage.StoreObjectsProps (225  ), TPropsStorage.LoadObjectsProps
                (224  ), FindGlobalComponentCallBack (219  )
                19.5          TPropInfoList



                19.5.1         Description

                TPropInfoList  is  a  class  which  can  be  used  to  maintain  a  list  with  information  about
                published properties of a class (or an instance).  It is used internally by TPropsStorage (223  )
                19.5.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  221       Contains        Check whether a certain property is included
                  221       Create          Create a new instance of  TPropInfoList
                  222       Delete          Delete property information from the list
                  221       Destroy         Remove the TPropInfoList instance from memory
                  221       Find            Retrieve property information based on name
                __222_______Intersect_______Intersect_2_property_lists_____________________________________________________________*
 *___________

                                                                                 220

                ______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'RTTIUTILS'_________________*
 *___________________
                19.5.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  222       Count           r            Number of items in the list
                __222_______Items___________r____________Indexed_access_to_the_property_type_pointers______________________________*
 *___________
                19.5.4         TPropInfoList.Create

    Synopsis:    Create a new instance of  TPropInfoList

Declaration:     constructor  Create(AObject:  TObject;Filter:  TTypeKinds)

    Visibility:   public

Description:     Create allocates and initializes a new instance of  TPropInfoList on the heap.  It retrieves
                a  list  of  published  properties  from  AObject:  if  Filter  is  empty,  then  all  properties  are
                retrieved.  If it is not empty, then only properties of the kind specified in the set are retrieved.
                Instance should not be Nil

    See also:    TPropInfoList.Destroy (221  )
                19.5.5         TPropInfoList.Destroy

    Synopsis:    Remove the TPropInfoList instance from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the internal structures maintained by TPropInfoList and then calls the
                inherited Destroy.

    See also:    TPropInfoList.Create (221  )
                19.5.6         TPropInfoList.Contains

    Synopsis:    Check whether a certain property is included

Declaration:     function  Contains(P:  PPropInfo)  :  Boolean

    Visibility:   public

Description:     Contains checks whether P is included in the list of properties, and returns True if it does.
                If  P cannot be found, False is returned.

    See also:    TPropInfoList.Find (221  ), TPropInfoList.Intersect (222  )
                19.5.7         TPropInfoList.Find

    Synopsis:    Retrieve property information based on name

Declaration:     function  Find(const  AName:  String)  :  PPropInfo

    Visibility:   public

Description:     Find returns a pointer to the type information of the property AName.  If no such information
                is available, the function returns Nil.  The search is performed case insensitive.

    See also:    TPropInfoList.Intersect (222  ), TPropInfoList.Contains (221  )



                                                                                 221

                ______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'RTTIUTILS'_________________*
 *___________________
                19.5.8         TPropInfoList.Delete

    Synopsis:    Delete property information from the list

Declaration:     procedure  Delete(Index:  Integer)

    Visibility:   public

Description:     Delete deletes the property information at position Index from the list.  It's mainly of use
                in the Intersect (222  ) call.

       Errors:   No checking on the validity of  Index is performed.

    See also:    TPropInfoList.Intersect (222  )
                19.5.9         TPropInfoList.Intersect

    Synopsis:    Intersect 2 property lists

Declaration:     procedure  Intersect(List:  TPropInfoList)

    Visibility:   public

Description:     Intersect reduces the list of properties to the ones also contained in List, i.e.  all properties
                which are not also present in List are removed.

    See also:    TPropInfoList.Delete (222  ), TPropInfoList.Contains (221  )
                19.5.10          TPropInfoList.Count

    Synopsis:    Number of items in the list

Declaration:     Property  Count  :  Integer

    Visibility:   public

      Access:    Read

Description:     Count is the number of property type pointers in the list.

    See also:    TPropInfoList.Items (222  )
                19.5.11          TPropInfoList.Items

    Synopsis:    Indexed access to the property type pointers

Declaration:     Property  Items[Index:  Integer]:  PPropInfo;  default

    Visibility:   public

      Access:    Read

Description:     Items provides access to the property type pointers stored in the list.  Index runs from 0
                to Count-1.

    See also:    TPropInfoList.Count (222  )

                                                                                 222

                ______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'RTTIUTILS'_________________*
 *___________________
                19.6          TPropsStorage



                19.6.1         Description

                TPropsStorage provides a mechanism to store properties from any class which has published
                properties (usually a TPersistent descendent) in a storage mechanism.

                TPropsStorage does not handle the storage by itself, instead, the storage is handled through
                a series of callbacks to read and/or write strings.  Conversion of property types to string is
                handled by TPropsStorage itself:  all that needs to be done is set the 3 handlers.  The storage
                mechanism is assumed to have the structure of an .ini file :  sections with key/value pairs.
                The three callbacks should take this into account, but they do not need to create an actual
                .ini file.
                19.6.2         Method  overview

                __Page______Property______________________Description______________________________________________________________*
 *___________
                  223       LoadAnyProperty               Load a property value
                  224       LoadObjectsProps              Load a list of component properties
                  224       LoadProperties                Load a list of properties
                  223       StoreAnyProperty              Store a property value
                  225       StoreObjectsProps             Store a list of component properties
                __224_______StoreProperties_______________Store_a_list_of_properties_______________________________________________*
 *___________
                19.6.3         Property  overview

                __Page______Property__________________Access_______Description_____________________________________________________*
 *___________
                  226       AObject                   rw           Object to load or store properties from
                  227       OnEraseSection            rw           Erase a section in storage
                  226       OnReadString              rw           Read a string value from storage
                  227       OnWriteString             rw           Write a string value to storage
                  226       Prefix                    rw           Prefix to use in storage
                __226_______Section___________________rw___________Section_name_for_storage________________________________________*
 *___________
                19.6.4         TPropsStorage.StoreAnyProperty

    Synopsis:    Store a property value

Declaration:     procedure  StoreAnyProperty(PropInfo:  PPropInfo)

    Visibility:   public

Description:     StoreAnyProperty stores the property with information specified in PropInfo in the storage
                mechanism.  The property value is retrieved from the object instance specified in the AObject
                (226  ) property of  TPropsStorage.

       Errors:   If the property pointer is invalid or AObject is invalid, an exception will be raised.

    See also:    TPropsStorage.AObject (226  ), TPropsStorage.LoadAnyProperty (223  ), TPropsStorage.LoadProperties
                (224  ), TPropsStorage.StoreProperties (224  )
                19.6.5         TPropsStorage.LoadAnyProperty

    Synopsis:    Load a property value
                                                                                 223

                ______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'RTTIUTILS'_________________*
 *___________________
Declaration:     procedure  LoadAnyProperty(PropInfo:  PPropInfo)

    Visibility:  public

Description:     LoadAnyProperty loads the property with information specified in PropInfo from the stor-
                age mechanism.  The value is then applied to the object instance specified in the AObject
                (226  ) property of  TPropsStorage.

       Errors:   If the property pointer is invalid or AObject is invalid, an exception will be raised.

    See also:    TPropsStorage.AObject (226  ), TPropsStorage.StoreAnyProperty (223  ), TPropsStorage.LoadProperties
                (224  ), TPropsStorage.StoreProperties (224  )
                19.6.6         TPropsStorage.StoreProperties

    Synopsis:    Store a list of properties

Declaration:     procedure  StoreProperties(PropList:  TStrings)

    Visibility:   public

Description:     StoreProperties stores the values of all properties in PropList in the storage mechanism.
                The list should contain names of published properties of the AObject (226  ) object.

       Errors:   If an invalid property name is specified, an exception will be raised.

    See also:    TPropsStorage.AObject (226  ), TPropsStorage.StoreAnyProperty (223  ), TPropsStorage.LoadProperties
                (224  ), TPropsStorage.LoadAnyProperty (223  )
                19.6.7         TPropsStorage.LoadProperties

    Synopsis:    Load a list of properties

Declaration:     procedure  LoadProperties(PropList:  TStrings)

    Visibility:   public

Description:     LoadProperties loads the values of all properties in PropList from the storage mechanism.
                The list should contain names of published properties of the AObject (226  ) object.

       Errors:   If an invalid property name is specified, an exception will be raised.

    See also:    TPropsStorage.AObject (226  ), TPropsStorage.StoreAnyProperty (223  ), TPropsStorage.StoreProperties
                (224  ), TPropsStorage.LoadAnyProperty (223  )
                19.6.8         TPropsStorage.LoadObjectsProps

    Synopsis:    Load a list of component properties

Declaration:     procedure  LoadObjectsProps(AComponent:  TComponent;StoredList:  TStrings)

    Visibility:   public

Description:     LoadObjectsProps loads a list of component properties, relative to AComponent:  the names
                of the component properties to load are specified as follows:


                ComponentName1.PropertyName
                ComponentName2.Subcomponent1.PropertyName



                                                                                 224

                ______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'RTTIUTILS'_________________*
 *___________________
                The  component  instances  will  be  located  relative  to  AComponent,  and  must  therefore  be
                names of components owned by AComponent, followed by a valid property of these compo-
                nents.  If the componentname is missing, the property name will be assumed to be a property
                of  AComponent itself.

                The Objects property of the stringlist should be filled with the instances of the components
                the property references refer to:  they can be filled with the UpdateStoredList (220  ) call.

                For example, to load the checked state of a checkbox named 'CBCheckMe' and the caption of
                a button named 'BPressMe', both owned by a form, the following strings should be passed:


                CBCheckMe.Checked
                BPressMe.Caption


                and the ACompontent should be the form component that owns the button and checkbox.

                Note that this call removes the value of the AObject (226  ) property.

       Errors:   If an invalid component is specified, an exception will be raised.

    See also:    UpdateStoredList (220  ), TPropsStorage.StoreObjectsProps (225  ), TPropsStorage.LoadProperties
                (224  ), TPropsStorage.LoadAnyProperty (223  )
                19.6.9         TPropsStorage.StoreObjectsProps

    Synopsis:    Store a list of component properties

Declaration:     procedure  StoreObjectsProps(AComponent:  TComponent;StoredList:  TStrings)

    Visibility:   public

Description:     StoreObjectsProps  stores  a  list  of  component  properties,  relative  to  AComponent:   the
                names of the component properties to store are specified as follows:


                ComponentName1.PropertyName
                ComponentName2.Subcomponent1.PropertyName


                The  component  instances  will  be  located  relative  to  AComponent,  and  must  therefore  be
                names of components owned by AComponent, followed by a valid property of these compo-
                nents.  If the componentname is missing, the property name will be assumed to be a property
                of  AComponent itself.

                The Objects property of the stringlist should be filled with the instances of the components
                the property references refer to:  they can be filled with the UpdateStoredList (220  ) call.

                For example, to store the checked state of a checkbox named 'CBCheckMe' and the caption
                of a button named 'BPressMe', both owned by a form, the following strings should be passed:


                CBCheckMe.Checked
                BPressMe.Caption


                and the ACompontent should be the form component that owns the button and checkbox.

                Note that this call removes the value of the AObject (226  ) property.

    See also:    UpdateStoredList (220  ), TPropsStorage.LoadObjectsProps (224  ), TPropsStorage.LoadProperties
                (224  ), TPropsStorage.LoadAnyProperty (223  )


                                                                                 225

                ______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'RTTIUTILS'_________________*
 *___________________
                19.6.10          TPropsStorage.AObject

    Synopsis:    Object to load or store properties from

Declaration:     Property  AObject  :  TObject

    Visibility:   public

      Access:    Read,Write

Description:     AObject  is  the  object  instance  whose  properties  will  be  loaded  or  stored  with  any  of  the
                methods in the TPropsStorage class.  Note that a call to StoreObjectProps (225  ) or Load-
                ObjectProps (224  ) will destroy any value that this property might have.

    See also:    TPropsStorage.LoadProperties (224  ), TPropsStorage.LoadAnyProperty (223  ), TPropsStor-
                age.StoreProperties (224  ), TPropsStorage.StoreAnyProperty (223  ), TPropsStorage.StoreObjectsProps
                (225  ), TPropsStorage.LoadObjectsProps (224  )
                19.6.11          TPropsStorage.Prefix

    Synopsis:    Prefix to use in storage

Declaration:     Property  Prefix  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Prefix is prepended to all property names to form the key name when writing a property
                to storage, or when reading a value from storage.  This is useful when storing properties of
                multiple forms in a single section.

    See also:    TPropsStorage.Section (226  )
                19.6.12          TPropsStorage.Section

    Synopsis:    Section name for storage

Declaration:     Property  Section  :  String

    Visibility:   public

      Access:    Read,Write

Description:     Section is used as the section name when writing values to storage.  Note that when writing
                properties of subcomponents, their names will be appended to the value specified here.

    See also:    TPropsStorage.Section (226  )
                19.6.13          TPropsStorage.OnReadString

    Synopsis:    Read a string value from storage

Declaration:     Property  OnReadString  :  TReadStrEvent

    Visibility:   public

      Access:    Read,Write

                                                                                 226

                ______________________________________________________CHAPTER_19.___REFERENCE_FOR_UNIT_'RTTIUTILS'_________________*
 *___________________
Description:     OnReadString is the event handler called whenever TPropsStorage needs to read a string
                from storage.  It should be set whenever properties need to be loaded, or an exception will
                be raised.

    See also:    TPropsStorage.OnWriteString (227  ), TPropsStorage.OnEraseSection (227  ), TReadStrEvent
                (219  )
                19.6.14          TPropsStorage.OnWriteString

    Synopsis:    Write a string value to storage

Declaration:     Property  OnWriteString  :  TWriteStrEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnWriteString is the event handler called whenever TPropsStorage needs to write a string
                to storage.  It should be set whenever properties need to be stored, or an exception will be
                raised.

    See also:    TPropsStorage.OnReadString (226  ), TPropsStorage.OnEraseSection (227  ), TWriteStrEvent
                (219  )
                19.6.15          TPropsStorage.OnEraseSection

    Synopsis:    Erase a section in storage

Declaration:     Property  OnEraseSection  :  TEraseSectEvent

    Visibility:   public

      Access:    Read,Write

Description:     OnEraseSection  is  the  event  handler  called  whenever  TPropsStorage  needs  to  clear  a
                complete storage section.  It should be set whenever stringlist properties need to be stored,
                or an exception will be raised.

    See also:    TPropsStorage.OnReadString (226  ), TPropsStorage.OnWriteString (227  ), TEraseSectEvent
                (218  )
                                                                                 227


Chapter   20


Reference   for   unit   'simpleipc'
20.1          Used  units
                                  Table 20.1:  Used units by unit 'simpleipc'


                                                   __Name__________Page_____
                                                     Classes          ??
                                                     sysutils         ??



20.2          Overview


The SimpleIPC unit provides classes to implement a simple, one-way IPC mechanism using
string  messages.   It  provides  a  TSimpleIPCServer  (239  )  component  for  the  server,  and  a
TSimpleIPCClient (235  ) component for the client.  The components are cross-platform, and
should work both on Windows and unix-like systems.
20.3          Constants,  types  and  variables



20.3.1         Resource  strings

SErrActive  =  'This  operation  is  illegal  when  the  server  is  active.'


Error message if client/server is active.


SErrInActive  =  'This  operation  is  illegal  when  the  server  is  inactive.'


Error message if client/server is not active.


SErrServerNotActive  =  'Server  with  ID  %s  is  not  active.'


Error message if server is not active



                                                             228

_____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________________________*
 *___
20.3.2         Constants

MsgVersion  =  1


Current version of the messaging protocol


mtString  =  1


String message type


mtUnknown  =  0


Unknown message type
20.3.3         Types

TIPCClientCommClass  =  Class  of  TIPCClientComm


TIPCClientCommClass is used by TSimpleIPCClient (235  ) to decide which kind of commu-
nication channel to set up.


TIPCServerCommClass  =  Class  of  TIPCServerComm


TIPCServerCommClass is used by TSimpleIPCServer (239  ) to decide which kind of commu-
nication channel to set up.


TMessageType  =  LongInt


TMessageType is provided for backward compatibility with earlier versions of the simpleipc
unit.


TMsgHeader  =  packed  record
    Version  :  Byte;
    MsgType  :  TMessageType;
    MsgLen  :  Integer;
end
TMsgHeader  is  used  internally  by  the  IPC  client  and  server  components  to  transmit  data.
The Version field denotes the protocol version.  The MsgType field denotes the type of data
(mtString for string messages), and MsgLen is the length of the message which will follow.
20.3.4         Variables

DefaultIPCClientClass  :  TIPCClientCommClass  =  nil


DefaultIPCClientClass is filled with a class pointer indicating which kind of communica-
tion protocol class should be instantiated by the TSimpleIPCClient (235  ) class.  It is set to a
default value by the default implementation in the SimpleIPC unit, but can be set to another
class if another method of transport is desired.  (it should match the communication protocol
used by the server, obviously).



                                                                 229

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                DefaultIPCServerClass  :  TIPCServerCommClass  =  nil


                DefaultIPCServerClass is filled with a class pointer indicating which kind of communica-
                tion protocol class should be instantiated by the TSimpleIPCServer (239  ) class.  It is set to a
                default value by the default implementation in the SimpleIPC unit, but can be set to another
                class if another method of transport is desired.
                20.4          EIPCError



                20.4.1         Description

                EIPCError is the exception used by the various classes in the SimpleIPC unit to report errors.
                20.5          TIPCClientComm



                20.5.1         Description

                TIPCClientComm is an abstract component which implements the client-side communication
                protocol.  The behaviour expected of this class must be implemented in a platform-dependent
                descendent class.

                The  TSimpleIPCClient  (235  )  class  does  not  implement  the  messaging  protocol  by  itself.
                Instead,  it  creates  an  instance  of  a  (platform  dependent)  descendent  of  TIPCClientComm
                which handles the internals of the commnication protocol.

                The server side of the messaging protocol is handled by the TIPCServerComm (232  ) com-
                ponent.  The descenent components must always be implemented in pairs.
                20.5.2         Method  overview

                __Page______Property_________________Description___________________________________________________________________*
 *___________
                  231       Connect                  Connect to the server
                  230       Create                   Create a new instance of the TIPCClientComm
                  231       Disconnect               Disconnect from the server
                  232       SendMessage              Send a message
                __231_______ServerRunning____________Check_if_the_server_is_running._______________________________________________*
 *___________
                20.5.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  232       Owner           r            TSimpleIPCClient instance for which communication must
                _________________________________________be_handled._______________________________________________________________*
 *___________
                20.5.4         TIPCClientComm.Create

    Synopsis:    Create a new instance of the TIPCClientComm

Declaration:     constructor  Create(AOwner:  TSimpleIPCClient);    Virtual

    Visibility:   public

Description:     Create  instantiates  a  new  instance  of  the  TIPCClientComm  class,  and  stores  the  AOwner
                reference to the TSimpleIPCClient (235  ) instance for which it will handle communitation.
                It can be retrieved later using the Owner (232  ) property.



                                                                                 230

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
    See also:    TIPCClientComm.Owner (232  ), TSimpleIPCClient (235  )
                20.5.5         TIPCClientComm.Connect

    Synopsis:    Connect to the server

Declaration:     procedure  Connect;    Virtual;    Abstract

    Visibility:   public

Description:     Connect must establish a communication channel with the server.  The server endpoint must
                be constructed from the ServerID (235  ) and ServerInstance (238  ) properties of the owning
                TSimpleIPCClient (235  ) instance.

                Connect  is  called  by  the  TSimpleIPCClient.Connect  (236  )  call  or  when  the  Active  (235  )
                property is set to True

                Messages can be sent only after Connect was called succesfully.

       Errors:   If the connection setup fails, or the connection was already set up , then an exception may
                be raised.

    See also:    TSimpleIPCClient.Connect (236  ), TSimpleIPC.Active (235  ), TIPCClientComm.Disconnect
                (231  )
                20.5.6         TIPCClientComm.Disconnect

    Synopsis:    Disconnect from the server

Declaration:     procedure  Disconnect;    Virtual;    Abstract

    Visibility:   public

Description:     Disconnect closes the communication channel with the server.  Any calls to SendMessage
                are invalid after Disconnect was called.

                Disconnect  is  called  by  the  TSimpleIPCClient.Disconnect  (237  )  call  or  when  the  Active
                (235  ) property is set to False.

                Messages can no longer be sent after Disconnect was called.

       Errors:   If the connection shutdown fails, or the connection was already shut down, then an exception
                may be raised.

    See also:    TSimpleIPCClient.Disconnect (237  ), TSimpleIPC.Active (235  ), TIPCClientComm.Connect
                (231  )
                20.5.7         TIPCClientComm.ServerRunning

    Synopsis:    Check if the server is running.

Declaration:     function  ServerRunning  :  Boolean;    Virtual;    Abstract

    Visibility:   public

Description:     ServerRunning returns True if the server endpoint of the communication channel can be
                found,  or  False  if  not.   The  server  endpoint  should  be  obtained  from  the  ServerID  and
                InstanceID properties of the owning TSimpleIPCClient (235  ) component.

    See also:    TSimpleIPCClient.InstanceID (235  ), TSimpleIPCClient.ServerID (235  )



                                                                                 231

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                20.5.8         TIPCClientComm.SendMessage

    Synopsis:    Send a message

Declaration:     procedure  SendMessage(MsgType:  TMessageType;Stream:  TStream);    Virtual
                                                   ;    Abstract

    Visibility:   public

Description:     SendMessage  should  deliver  the  message  with  type  MsgType  and  data  in  Stream  to  the
                server.  It should not return until the message was delivered.

       Errors:   If the delivery of the message fails, an exception will be raised.
                20.5.9         TIPCClientComm.Owner

    Synopsis:    TSimpleIPCClient instance for which communication must be handled.

Declaration:     Property  Owner  :  TSimpleIPCClient

    Visibility:   public

      Access:    Read

Description:     Owner is the TSimpleIPCClient (235  ) instance for which the communication must be han-
                dled.  It  cannot  be  changed,  and  must  be  specified  when  the  TIPCClientComm  instance  is
                created.

    See also:    TSimpleIPCClient (235  ), TIPCClientComm.Create (230  )
                20.6          TIPCServerComm



                20.6.1         Description

                TIPCServerComm is an abstract component which implements the server-side communication
                protocol.  The behaviour expected of this class must be implemented in a platform-dependent
                descendent class.

                The  TSimpleIPCServer  (239  )  class  does  not  implement  the  messaging  protocol  by  itself.
                Instead,  it  creates  an  instance  of  a  (platform  dependent)  descendent  of  TIPCServerComm
                which handles the internals of the commnication protocol.

                The client side of the messaging protocol is handled by the TIPCClientComm (230  ) compo-
                nent.  The descenent components must always be implemented in pairs.
                20.6.2         Method  overview

                __Page______Property_______________Description_____________________________________________________________________*
 *___________
                  233       Create                 Create a new instance of the communication handler
                  234       PeekMessage            See if a message is available.
                  234       ReadMessage            Read message from the channel.
                  233       StartServer            Start the server-side of the communication channel
                __233_______StopServer_____________Stop_the_server_side_of_the_communication_channel.______________________________*
 *___________


                                                                                 232

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                20.6.3         Property  overview

                __Page______Property___________Access_______Description____________________________________________________________*
 *___________
                  234       InstanceID         r            Unique identifier for the communication channel.
                __234_______Owner______________r____________TSimpleIPCServer_instance_for_which_to_handle_transport________________*
 *___________
                20.6.4         TIPCServerComm.Create

    Synopsis:    Create a new instance of the communication handler

Declaration:     constructor  Create(AOwner:  TSimpleIPCServer);    Virtual

    Visibility:   public

Description:     Create initializes a new instance of the communication handler.  It simply saves the AOwner
                parameter in the Owner (234  ) property.

    See also:    TIPCServerComm.Owner (234  )
                20.6.5         TIPCServerComm.StartServer

    Synopsis:    Start the server-side of the communication channel

Declaration:     procedure  StartServer;    Virtual;    Abstract

    Visibility:   public

Description:     StartServer sets up the server-side of the communication channel.  After StartServer was
                called, a client can connect to the communication channel, and send messages to the server.

                It  is  called  when  the  TSimpleIPC.Active  (235  )  property  of  the  TSimpleIPCServer  (239  )
                instance is set to True.

       Errors:   In case of an error, an EIPCError (230  ) exception is raised.

    See also:    TSimpleIPCServer (239  ), TSimpleIPC.Active (235  )
                20.6.6         TIPCServerComm.StopServer

    Synopsis:    Stop the server side of the communication channel.

Declaration:     procedure  StopServer;    Virtual;    Abstract

    Visibility:   public

Description:     StartServer closes down the server-side of the communication channel.  After StartServer
                was  called,  a  client  can  no  longer  connect  to  the  communication  channel,  or  even  send
                messages to the server if it was previously connected (i.e.  it will be disconnected).

                It  is  called  when  the  TSimpleIPC.Active  (235  )  property  of  the  TSimpleIPCServer  (239  )
                instance is set to False.

       Errors:   In case of an error, an EIPCError (230  ) exception is raised.

    See also:    TSimpleIPCServer (239  ), TSimpleIPC.Active (235  )


                                                                                 233

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                20.6.7         TIPCServerComm.PeekMessage

    Synopsis:    See if a message is available.

Declaration:     function  PeekMessage(TimeOut:  Integer)  :  Boolean;    Virtual;    Abstract

    Visibility:   public

Description:     PeekMessage can be used to see if a message is available:  it returns True if a message is
                available.  It will wait maximum TimeOut milliseconds for a message to arrive.  If no message
                was available after this time, it will return False.

                If a message was available, it can be read with the ReadMessage (234  ) call.

    See also:    TIPCServerComm.ReadMessage (234  )
                20.6.8         TIPCServerComm.ReadMessage

    Synopsis:    Read message from the channel.

Declaration:     procedure  ReadMessage;    Virtual;    Abstract

    Visibility:   public

Description:     ReadMessage  reads  the  message  for  the  channel,  and  stores  the  information  in  the  data
                structures in the Owner class.

                ReadMessage is a blocking call:  if no message is available, the program will wait till a message
                arrives.  Use PeekMessage (234  ) to see if a message is available.

    See also:    TSimpleIPCServer (239  )
                20.6.9         TIPCServerComm.Owner

    Synopsis:    TSimpleIPCServer instance for which to handle transport

Declaration:     Property  Owner  :  TSimpleIPCServer

    Visibility:   public

      Access:    Read

Description:     Owner refers to the TSimpleIPCServer (239  ) instance for which this instance of TSimpleIPCServer
                handles the transport.  It is specified when the TIPCServerComm is created.

    See also:    TSimpleIPCServer (239  )
                20.6.10          TIPCServerComm.InstanceID

    Synopsis:    Unique identifier for the communication channel.

Declaration:     Property  InstanceID  :  String

    Visibility:   public

      Access:    Read

Description:     InstanceID returns a textual representation which uniquely identifies the communication
                channel on the server.  The value is system dependent, and should be usable by the client-side
                to establish a communication channel with this instance.



                                                                                 234

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                20.7          TSimpleIPC



                20.7.1         Description

                TSimpleIPC is the common ancestor for the TSimpleIPCServer (239  ) and TSimpleIPCClient
                (235  ) classes.  It implements some common properties between client and server.
                20.7.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                  235       Active          rw           Communication channel active
                __235_______ServerID________rw___________Unique_server_identification______________________________________________*
 *___________
                20.7.3         TSimpleIPC.Active

    Synopsis:    Communication channel active

Declaration:     Property  Active  :  Boolean

    Visibility:   published

      Access:    Read,Write

Description:     Active can be set to True to set up the client or server end of the communication channel.
                For the server this means that the server end is set up, for the client it means that the client
                tries to connect to the server with ServerID (235  ) identification.

    See also:    TSimpleIPC.ServerID (235  )
                20.7.4         TSimpleIPC.ServerID

    Synopsis:    Unique server identification

Declaration:     Property  ServerID  :  String

    Visibility:   published

      Access:    Read,Write

Description:     ServerID  is  the  unique  server  identification:  on  the  server,  it  determines  how  the  server
                channel is set up, on the client it determines the server with which to connect.

    See also:    TSimpleIPC.Active (235  )
                20.8          TSimpleIPCClient



                20.8.1         Description

                TSimpleIPCClient is the client side of the simple IPC communication protocol.  The client
                program should create a TSimpleIPCClient instance, set its ServerID (235  ) property to the
                unique  name  for  the  server  it  wants  to  send  messages  to,  and  then  set  the  Active  (235  )
                property to True (or call Connect (235  )).

                After the connection with the server was established, messages can be sent to the server with
                the SendMessage (237  ) or SendStringMessage (238  ) calls.

                                                                                 235

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                20.8.2         Method  overview

                __Page______Property____________________________Description________________________________________________________*
 *___________
                  236       Connect                             Connect to the server
                  236       Create                              Create a new instance of  TSimpleIPCClient
                  236       Destroy                             Remove the TSimpleIPCClient instance from memory
                  237       Disconnect                          Disconnect from the server
                  237       SendMessage                         Send a message to the server
                  238       SendStringMessage                   Send a string message to the server
                  238       SendStringMessageFmt                Send a formatted string message
                __237_______ServerRunning_______________________Check_if_the_server_is_running.____________________________________*
 *___________
                20.8.3         Property  overview

                __Page______Property________________Access_______Description_______________________________________________________*
 *___________
                __238_______ServerInstance__________rw___________Server_instance_identification____________________________________*
 *___________
                20.8.4         TSimpleIPCClient.Create

    Synopsis:    Create a new instance of  TSimpleIPCClient

Declaration:     constructor  Create(AOwner:  TComponent);    Override

    Visibility:   public

Description:     Create instantiates a new instance of the TSimpleIPCClient class.  It initializes the data
                structures needed to handle the client side of the communication.

    See also:    TSimpleIPCClient.Destroy (236  )
                20.8.5         TSimpleIPCClient.Destroy

    Synopsis:    Remove the TSimpleIPCClient instance from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy disconnects the client from the server if need be, and cleans up the internal data
                structures  maintained  by  TSimpleIPCClient  and  then  calls  the  inherited  Destroy,  which
                will remove the instance from memory.

                Never call Destroy directly, use the Free method instead or the FreeAndNil procedure in
                SysUtils.

    See also:    TSimpleIPCClient.Create (236  )
                20.8.6         TSimpleIPCClient.Connect

    Synopsis:    Connect to the server

Declaration:     procedure  Connect

    Visibility:   public
                                                                                 236

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
Description:     Connect connects to the server indicated in the ServerID (235  ) and InstanceID (235  ) prop-
                erties.  Connect is called automatically if the Active (235  ) property is set to True.

                After  a  successful  call  to  Connect,  messages  can  be  sent  to  the  server  using  SendMessage
                (237  ) or SendStringMessage (238  ).

                Calling Connect if the connection is already open has no effect.

       Errors:   If creating the connection fails, an EIPCError (230  ) exception may be raised.

    See also:    TSimpleIPC.ServerID (235  ), TSimpleIPCClient.InstanceID (235  ), TSimpleIPC.Active (235  ),
                TSimpleIPCClient.SendMessage (237  ), TSimpleIPCClient.SendStringMessage (238  ), TSim-
                pleIPCClient.Disconnect (237  )
                20.8.7         TSimpleIPCClient.Disconnect

    Synopsis:    Disconnect from the server

Declaration:     procedure  Disconnect

    Visibility:   public

Description:     Disconnect shuts down the connection with the server as previously set up with Connect
                (236  ).  Disconnect is called automatically if the Active (235  ) property is set to False.

                After  a  successful  call  to  Disconnect,  messages  can  no  longer  be  sent  to  the  server.  At-
                tempting to do so will result in an exception.

                Calling Disconnect if there is no connection has no effect.

       Errors:   If creating the connection fails, an EIPCError (230  ) exception may be raised.

    See also:    TSimpleIPC.Active (235  ), TSimpleIPCClient.Connect (236  )
                20.8.8         TSimpleIPCClient.ServerRunning

    Synopsis:    Check if the server is running.

Declaration:     function  ServerRunning  :  Boolean

    Visibility:   public

Description:     ServerRunning verifies if the server indicated in the ServerID (235  ) and InstanceID (235  )
                properties is running.  It returns True if the server communication endpoint can be reached,
                False otherwise.  This function can be called before a connection is made.

    See also:    TSimpleIPCClient.Connect (236  )
                20.8.9         TSimpleIPCClient.SendMessage

    Synopsis:    Send a message to the server

Declaration:     procedure  SendMessage(MsgType:  TMessageType;Stream:  TStream)

    Visibility:   public

Description:     SendMessage sends a message of type MsgType and data from stream to the server.  The
                client must be connected for this call to work.

       Errors:   In case an error occurs, or there is no connection to the server, an EIPCError (230  ) exception
                is raised.

    See also:    TSimpleIPCClient.Connect (236  ), TSimpleIPCClient.SendStringMessage (238  )



                                                                                 237

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                20.8.10          TSimpleIPCClient.SendStringMessage

    Synopsis:    Send a string message to the server

Declaration:     procedure  SendStringMessage(const  Msg:  String)
                procedure  SendStringMessage(MsgType:  TMessageType;const  Msg:  String)

    Visibility:   public

Description:     SendStringMessage sends a string message with type MsgTyp and data Msg to the server.
                This is a convenience function:  a small wrapper around the SendMessage (237  ) method

       Errors:   Same as for SendMessage.

    See also:    TSimpleIPCClient.SendMessage (237  ), TSimpleIPCClient.Connect (236  ), TSimpleIPCClient.SendStringMessageFmt
                (238  )
                20.8.11          TSimpleIPCClient.SendStringMessageFmt

    Synopsis:    Send a formatted string message

Declaration:     procedure  SendStringMessageFmt(const  Msg:  String;Args:  Array  of  const)
                procedure  SendStringMessageFmt(MsgType:  TMessageType;const  Msg:  String;
                                                                  Args:  Array  of  const)

    Visibility:   public

Description:     SendStringMessageFmt sends a string message with type MsgTyp and message formatted
                from Msg and Args to the server.  This is a convenience function:  a small wrapper around
                the SendStringMessage (238  ) method

       Errors:   Same as for SendMessage.

    See also:    TSimpleIPCClient.SendMessage (237  ), TSimpleIPCClient.Connect (236  ), TSimpleIPCClient.SendStringMessage
                (238  )
                20.8.12          TSimpleIPCClient.ServerInstance

    Synopsis:    Server instance identification

Declaration:     Property  ServerInstance  :  String

    Visibility:   public

      Access:    Read,Write

Description:     ServerInstance should be used in case a particular instance of the server identified with
                ServerID should be contacted.  This must be used if the server has its GLobal (242  ) property
                set to False, and should match the server's InstanceID (242  ) property.

    See also:    TSimpleIPC.ServerID (235  ), TSimpleIPCServer.Global (242  ), TSimpleIPCServer.InstanceID
                (242  )


                                                                                 238

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                20.9          TSimpleIPCServer



                20.9.1         Description

                TSimpleIPCServer is the server side of the simple IPC communication protocol.  The server
                program  should  create  a  TSimpleIPCServer  instance,  set  its  ServerID  (235  )  property  to
                a  unique  name  for  the  system,  and  then  set  the  Active  (235  )  property  to  True  (or  call
                StartServer (240  )).

                After the server was started, it can check for availability of messages with the PeekMessage
                (240  ) call, and read the message with ReadMessage (239  ).
                20.9.2         Method  overview

                __Page______Property___________________Description_________________________________________________________________*
 *___________
                  239       Create                     Create a new instance of  TSimpleIPCServer
                  239       Destroy                    Remove the TSimpleIPCServer instance from memory
                  241       GetMessageData             Read the data of the last message in a stream
                  240       PeekMessage                Check if a client message is available.
                  240       StartServer                Start the server
                __240_______StopServer_________________Stop_the_server_____________________________________________________________*
 *___________
                20.9.3         Property  overview

                __Page______Property________________Access_______Description_______________________________________________________*
 *___________
                  242       Global                  rw           Is the server reachable to all users or not
                  242       InstanceID              r            Instance ID
                  241       MsgData                 r            Last message data
                  241       MsgType                 r            Last message type
                  242       OnMessage               rw           Event triggered when a pessage arrives
                __241_______StringMessage___________r____________Last_message_as_a_string._________________________________________*
 *___________
                20.9.4         TSimpleIPCServer.Create

    Synopsis:    Create a new instance of  TSimpleIPCServer

Declaration:     constructor  Create(AOwner:  TComponent);    Override

    Visibility:   public

Description:     Create instantiates a new instance of the TSimpleIPCServer class.  It initializes the data
                structures needed to handle the server side of the communication.

    See also:    TSimpleIPCServer.Destroy (239  )
                20.9.5         TSimpleIPCServer.Destroy

    Synopsis:    Remove the TSimpleIPCServer instance from memory

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy stops the server, cleans up the internal data structures maintained by TSimpleIPCServer
                and then calls the inherited Destroy, which will remove the instance from memory.
                                                                                 239

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                Never call Destroy directly, use the Free method instead or the FreeAndNil procedure in
                SysUtils.

    See also:    TSimpleIPCServer.Create (239  )
                20.9.6         TSimpleIPCServer.StartServer

    Synopsis:    Start the server

Declaration:     procedure  StartServer

    Visibility:   public

Description:     StartServer starts the server side of the communication channel.  It is called automatically
                when the Active property is set to True.  It creates the internal communication object (a
                TIPCServerComm (232  ) descendent) and activates the communication channel.

                After this method was called, clients can connect and send messages.

                Prior to calling this method, the ServerID (235  ) property must be set.

       Errors:   If an error occurs a EIPCError (230  ) exception may be raised.

    See also:    TIPCServerComm  (232  ),  TSimpleIPC.Active  (235  ),  TSimpleIPC.ServerID  (235  ),  TSim-
                pleIPCServer.StopServer (240  )
                20.9.7         TSimpleIPCServer.StopServer

    Synopsis:    Stop the server

Declaration:     procedure  StopServer

    Visibility:   public

Description:     StopServer stops the server side of the communication channel.  It is called automatically
                when the Active property is set to False.  It deactivates the communication channel and
                frees the internal communication object (a TIPCServerComm (232  ) descendent).

    See also:    TIPCServerComm  (232  ),  TSimpleIPC.Active  (235  ),  TSimpleIPC.ServerID  (235  ),  TSim-
                pleIPCServer.StartServer (240  )
                20.9.8         TSimpleIPCServer.PeekMessage

    Synopsis:    Check if a client message is available.

Declaration:     function  PeekMessage(TimeOut:  Integer;DoReadMessage:  Boolean)  :  Boolean

    Visibility:   public

Description:     PeekMessage checks if a message from a client is available.  It will return True if a message
                is  available.   The  call  will  wait  for  TimeOut  milliseconds  for  a  message  to  arrive:  if  after
                TimeOut milliseconds, no message is available, the function will return False.

                If  DoReadMessage is True then PeekMessage will read the message.  If it is False, it does
                not read the message.  The message should then be read manually with ReadMessage (239  ).

    See also:    TSimpleIPCServer.ReadMessage (239  )



                                                                                 240

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                20.9.9         TSimpleIPCServer.GetMessageData

    Synopsis:    Read the data of the last message in a stream

Declaration:     procedure  GetMessageData(Stream:  TStream)

    Visibility:   public

Description:     GetMessageData reads the data of the last message from TSimpleIPCServer.MsgData (241  )
                and stores it in stream Stream.  If no data was available, the stream will be cleared.

                This function will return valid data only after a succesful call to ReadMessage (239  ).  It will
                also not clear the data buffer.

    See also:    TSimpleIPCServer.StringMessage  (241  ),  TSimpleIPCServer.MsgData  (241  ),  TSimpleIPC-
                Server.MsgType (241  )
                20.9.10          TSimpleIPCServer.StringMessage

    Synopsis:    Last message as a string.

Declaration:     Property  StringMessage  :  String

    Visibility:   public

      Access:    Read

Description:     StringMessage is the content of the last message as a string.

                This property will contain valid data only after a succesful call to ReadMessage (239  ).

    See also:    TSimpleIPCServer.GetMessageData (241  )
                20.9.11          TSimpleIPCServer.MsgType

    Synopsis:    Last message type

Declaration:     Property  MsgType  :  TMessageType

    Visibility:   public

      Access:    Read

Description:     MsgType contains the message type of the last message.

                This property will contain valid data only after a succesful call to ReadMessage (239  ).

    See also:    TSimpleIPCServer.ReadMessage (239  )
                20.9.12          TSimpleIPCServer.MsgData

    Synopsis:    Last message data

Declaration:     Property  MsgData  :  TStream

    Visibility:   public

      Access:    Read

Description:     MsgData contains the actual data from the last read message.  If the data is a string, then
                StringMessage (241  ) is better suited to read the data.

                This property will contain valid data only after a succesful call to ReadMessage (239  ).

    See also:    TSimpleIPCServer.StringMessage (241  ), TSimpleIPCServer.ReadMessage (239  )



                                                                                 241

                _____________________________________________________CHAPTER_20.___REFERENCE_FOR_UNIT_'SIMPLEIPC'__________________*
 *___________________
                20.9.13          TSimpleIPCServer.InstanceID

    Synopsis:    Instance ID

Declaration:     Property  InstanceID  :  String

    Visibility:   public

      Access:    Read

Description:     InstanceID  is  the  unique  identifier  for  this  server  communication  channel  endpoint,  and
                will be appended to the ServerID (239  ) property to form the unique server endpoint which
                a client should use.

    See also:    TSimpleIPCServer.ServerID (239  ), TSimpleIPCServer.GlobalID (239  )
                20.9.14          TSimpleIPCServer.Global

    Synopsis:    Is the server reachable to all users or not

Declaration:     Property  Global  :  Boolean

    Visibility:   published

      Access:    Read,Write

Description:     Global indicates whether the server is reachable to all users (True) or if it is private to the
                current process (False).  In the latter case, the unique channel endpoint identification may
                change:  a unique identification of the current process is appended to the ServerID name.

    See also:    TSimpleIPCServer.ServerID (239  ), TSimpleIPCServer.InstanceID (242  )
                20.9.15          TSimpleIPCServer.OnMessage

    Synopsis:    Event triggered when a pessage arrives

Declaration:     Property  OnMessage  :  TNotifyEvent

    Visibility:   published

      Access:    Read,Write

Description:     OnMessage is called by ReadMessage (239  ) when a message has been read.  The actual mes-
                sage data can be retrieved with one of the StringMessage (241  ), MsgData (241  ) or MsgType
                (241  ) properties.

    See also:    TSimpleIPCServer.StringMessage  (241  ),  TSimpleIPCServer.MsgData  (241  ),  TSimpleIPC-
                Server.MsgType (241  )

                                                                                 242


                Chapter   21


                Reference   for   unit   'streamcoll'
                21.1          Used  units
                                                  Table 21.1:  Used units by unit 'streamcoll'


                                                                   __Name__________Page_____
                                                                     Classes          ??
                                                                     sysutils         ??



                21.2          Overview


                The streamcoll unit contains the implentation of a collection (and corresponding collection
                item) which implements routines for saving or loading the collection to/from a stream.  The
                collection item should implement 2 routines to implement the streaming; the streaming itself
                is not performed by the TStreamCollection (246  ) collection item.

                The  streaming  performed  here  is  not  compatible  with  the  streaming  implemented  in  the
                Classes  unit  for  components.  It  is  independent  of  the  latter  and  can  be  used  without  a
                component to hold the collection.

                The  collection  item  introduces  mostly  protected  methods,  and  the  unit  contains  a  lot  of
                auxiliary routines which aid in streaming.
                21.3          Procedures  and  functions



                21.3.1         ColReadBoolean

    Synopsis:    Read a boolean value from a stream

Declaration:     function  ColReadBoolean(S:  TStream)  :  Boolean

    Visibility:   default

Description:     ColReadBoolean reads a boolean from the stream S as it was written by ColWriteBoolean
                (245  ) and returns the read value.  The value cannot be read and written across systems that
                have different endian values.



                                                                             243

                ________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'STREAMCOLL'______________________*
 *___________________
    See also:    ColReadDateTime  (244  ),  ColWriteBoolean  (245  ),  ColReadString  (245  ),  ColReadInteger
                (244  ), ColReadFloat (244  ), ColReadCurrency (244  )
                21.3.2         ColReadCurrency

    Synopsis:    Read a currency value from the stream

Declaration:     function  ColReadCurrency(S:  TStream)  :  Currency

    Visibility:   default

Description:     ColReadCurrency reads a currency value from the stream S as it was written by ColWrite-
                Currency  (245  )  and  returns  the  read  value.  The  value  cannot  be  read  and  written  across
                systems that have different endian values.

    See also:    ColReadDateTime (244  ), ColReadBoolean (243  ), ColReadString (245  ), ColReadInteger (244  ),
                ColReadFloat (244  ), ColWriteCurrency (245  )
                21.3.3         ColReadDateTime

    Synopsis:    Read a TDateTime value from a stream

Declaration:     function  ColReadDateTime(S:  TStream)  :  TDateTime

    Visibility:   default

Description:     ColReadDateTime reads a currency value from the stream S as it was written by ColWrite-
                DateTime (245  ) and returns the read value.  The value cannot be read and written across
                systems that have different endian values.

    See also:    ColWriteDateTime  (245  ),  ColReadBoolean  (243  ),  ColReadString  (245  ),  ColReadInteger
                (244  ), ColReadFloat (244  ), ColReadCurrency (244  )
                21.3.4         ColReadFloat

    Synopsis:    Read a floating point value from a stream

Declaration:     function  ColReadFloat(S:  TStream)  :  Double

    Visibility:   default

Description:     ColReadFloat reads a double value from the stream S as it was written by ColWriteFloat
                (246  ) and returns the read value.  The value cannot be read and written across systems that
                have different endian values.

    See also:    ColReadDateTime (244  ), ColReadBoolean (243  ), ColReadString (245  ), ColReadInteger (244  ),
                ColWriteFloat (246  ), ColReadCurrency (244  )
                21.3.5         ColReadInteger

    Synopsis:    Read a 32-bit integer from a stream.

Declaration:     function  ColReadInteger(S:  TStream)  :  Integer

    Visibility:   default


                                                                                 244

                ________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'STREAMCOLL'______________________*
 *___________________
Description:     ColReadInteger reads a 32-bit integer from the stream S as it was written by ColWriteIn-
                teger (246  ) and returns the read value.  The value cannot be read and written across systems
                that have different endian values.

    See also:    ColReadDateTime  (244  ),  ColReadBoolean  (243  ),  ColReadString  (245  ),  ColWriteInteger
                (246  ), ColReadFloat (244  ), ColReadCurrency (244  )
                21.3.6         ColReadString

    Synopsis:    Read a string from a stream

Declaration:     function  ColReadString(S:  TStream)  :  String

    Visibility:   default

Description:     ColReadStream reads a string value from the stream S as it was written by ColWriteString
                (246  ) and returns the read value.  The value cannot be read and written across systems that
                have different endian values.

    See also:    ColReadDateTime  (244  ),  ColReadBoolean  (243  ),  ColWriteString  (246  ),  ColReadInteger
                (244  ), ColReadFloat (244  ), ColReadCurrency (244  )
                21.3.7         ColWriteBoolean

    Synopsis:    Write a boolean to a stream

Declaration:     procedure  ColWriteBoolean(S:  TStream;AValue:  Boolean)

    Visibility:   default

Description:     ColWriteBoolean writes the boolean AValue to the stream.  S.

    See also:    ColReadBoolean  (243  ),  ColWriteString  (246  ),  ColWriteInteger  (246  ),  ColWriteCurrency
                (245  ), ColWriteDateTime (245  ), ColWriteFloat (246  )
                21.3.8         ColWriteCurrency

    Synopsis:    Write a currency value to stream

Declaration:     procedure  ColWriteCurrency(S:  TStream;AValue:  Currency)

    Visibility:   default

Description:     ColWriteCurrency writes the currency AValue to the stream S.

    See also:    ColWriteBoolean  (245  ),  ColWriteString  (246  ),  ColWriteInteger  (246  ),  ColWriteDateTime
                (245  ), ColWriteFloat (246  ), ColReadCurrency (244  )
                21.3.9         ColWriteDateTime

    Synopsis:    Write a TDateTime value to stream

Declaration:     procedure  ColWriteDateTime(S:  TStream;AValue:  TDateTime)

    Visibility:   default

Description:     ColWriteDateTime writes the TDateTimeAValue to the stream S.

    See also:    ColReadDateTime  (244  ),  ColWriteBoolean  (245  ),  ColWriteString  (246  ),  ColWriteInteger
                (246  ), ColWriteFloat (246  ), ColWriteCurrency (245  )



                                                                                 245

                ________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'STREAMCOLL'______________________*
 *___________________
                21.3.10          ColWriteFloat

    Synopsis:    Write floating point value to stream

Declaration:     procedure  ColWriteFloat(S:  TStream;AValue:  Double)

    Visibility:   default

Description:     ColWriteFloat writes the double AValue to the stream S.

    See also:    ColWriteDateTime  (245  ),  ColWriteBoolean  (245  ),  ColWriteString  (246  ),  ColWriteInteger
                (246  ), ColReadFloat (244  ), ColWriteCurrency (245  )
                21.3.11          ColWriteInteger

    Synopsis:    Write a 32-bit integer to a stream

Declaration:     procedure  ColWriteInteger(S:  TStream;AValue:  Integer)

    Visibility:   default

Description:     ColWriteInteger writes the 32-bit integer AValue to the stream S. No endianness is ob-
                served.

    See also:    ColWriteBoolean  (245  ),  ColWriteString  (246  ),  ColReadInteger  (244  ),  ColWriteCurrency
                (245  ), ColWriteDateTime (245  )
                21.3.12          ColWriteString

    Synopsis:    Write a string value to the stream

Declaration:     procedure  ColWriteString(S:  TStream;AValue:  String)

    Visibility:   default

Description:     ColWriteString writes the string value AValue to the stream S.

    See also:    ColWriteBoolean  (245  ),  ColReadString  (245  ),  ColWriteInteger  (246  ),  ColWriteCurrency
                (245  ), ColWriteDateTime (245  ), ColWriteFloat (246  )
                21.4          EStreamColl



                21.4.1         Description

                Exception raised when an error occurs when streaming the collection.
                21.5          TStreamCollection



                21.5.1         Description

                TStreamCollection is a TCollection (??  ) descendent which implements 2 calls LoadFrom-
                Stream (247  ) and SaveToStream (247  ) which load and save the contents of the collection to
                a stream.

                The collection items must be descendents of the TStreamCollectionItem (248  ) class for the
                streaming to work correctly.

                Note that the stream must be used to load collections of the same type.



                                                                                 246

                ________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'STREAMCOLL'______________________*
 *___________________
                21.5.2         Method  overview

                __Page______Property____________________Description________________________________________________________________*
 *___________
                  247       LoadFromStream              Load the collection from a stream
                __247_______SaveToStream________________Load_the_collection_from_the_stream._______________________________________*
 *___________
                21.5.3         Property  overview

                __Page______Property__________Access_______Description_____________________________________________________________*
 *___________
                  247       Streaming         r            Indicates whether the collection is currently being written
                ___________________________________________to_stream_______________________________________________________________*
 *___________
                21.5.4         TStreamCollection.LoadFromStream

    Synopsis:    Load the collection from a stream

Declaration:     procedure  LoadFromStream(S:  TStream)

    Visibility:   public

Description:     LoadFromStream loads the collection from the stream S, if the collection was saved using
                SaveToStream (247  ).  It reads the number of items in the collection, and then creates and
                loads the items one by one from the stream.

       Errors:   An exception may be raised if the stream contains invalid data.

    See also:    TStreamCollection.SaveToStream (247  )
                21.5.5         TStreamCollection.SaveToStream

    Synopsis:    Load the collection from the stream.

Declaration:     procedure  SaveToStream(S:  TStream)

    Visibility:   public

Description:     SaveToStream saves the collection to the stream S so it can be read from the stream with
                LoadFromStream (247  ).  It does this by writing the number of collection items to the stream,
                and then streaming all items in the collection by calling their SaveToStream method.

       Errors:   None.

    See also:    TStreamCollection.LoadFromStream (247  )
                21.5.6         TStreamCollection.Streaming

    Synopsis:    Indicates whether the collection is currently being written to stream

Declaration:     Property  Streaming  :  Boolean

    Visibility:   public

      Access:    Read

Description:     Streaming is set to True if the collection is written to or loaded from stream,  and is set
                again to False if the streaming process is finished.

    See also:    TStreamCollection.LoadFromStream (247  ), TStreamCollection.SaveToStream (247  )



                                                                                 247

________________________________________________CHAPTER_21.___REFERENCE_FOR_UNIT_'STREAMCOLL'______________________________________*
 *___
21.6          TStreamCollectionItem



21.6.1         Description

TStreamCollectionItem is a TCollectionItem (??  ) descendent which implements 2 abstract
routines:  LoadFromStream  and  SaveToStream  which  must  be  overridden  in  a  descendent
class.

These 2 routines will be called by the TStreamCollection (246  ) to save or load the item from
the stream.

                                                                 248


                Chapter   22


                Reference   for   unit   'streamex'
                22.1          Used  units
                                                   Table 22.1:  Used units by unit 'streamex'


                                                                   __Name__________Page____
                                                                     Classes          ??



                22.2          Overview


                streamex implements some extensions to be used together with streams from the classes unit.
                22.3          TBidirBinaryOb jectReader



                22.3.1         Description

                TBidirBinaryObjectReader is a class descendent from TBinaryObjectReader (??  ), which
                implements the necessary support for BiDi data:  the position in the stream (not available
                in the standard streaming) is emulated.
                22.3.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __249_______Position________rw___________Position_in_the_stream____________________________________________________*
 *___________
                22.3.3         TBidirBinaryObjectReader.Position

    Synopsis:    Position in the stream

Declaration:     Property  Position  :  LongInt

    Visibility:   public

      Access:    Read,Write



                                                                             249

                _____________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'STREAMEX'___________________*
 *___________________
Description:     Position  exposes  the  position  of  the  stream  in  the  reader  for  use  in  the  TDelphiReader
                (250  ) class.

    See also:    TDelphiReader (250  )
                22.4          TBidirBinaryOb jectWriter



                22.4.1         Description

                TBidirBinaryObjectReader  is  a  class  descendent  from  TBinaryObjectWriter  (??  ),  which
                implements the necessary support for BiDi data.
                22.4.2         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __250_______Position________rw___________Position_in_the_stream____________________________________________________*
 *___________
                22.4.3         TBidirBinaryObjectWriter.Position

    Synopsis:    Position in the stream

Declaration:     Property  Position  :  LongInt

    Visibility:   public

      Access:    Read,Write

Description:     Position  exposes  the  position  of  the  stream  in  the  writer  for  use  in  the  TDelphiWriter
                (252  ) class.

    See also:    TDelphiWriter (252  )
                22.5          TDelphiReader



                22.5.1         Description

                TDelphiReader is a descendent of  TReader which has support for BiDi Streaming.  It over-
                rides the stream reading methods for strings, and makes sure the stream can be positioned
                in the case of strings.  For this purpose, it makes use of the TBidirBinaryObjectReader (249  )
                driver class.
                22.5.2         Method  overview

                __Page______Property__________Description__________________________________________________________________________*
 *___________
                  251       GetDriver         Return the driver class as a TBidirBinaryObjectReader (249  ) class
                  251       Read              Read data from stream
                __251_______ReadStr___________Overrides_the_standard_ReadStr_method________________________________________________*
 *___________
                22.5.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __251_______Position________rw___________Position_in_the_stream____________________________________________________*
 *___________
                                                                                 250

                _____________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'STREAMEX'___________________*
 *___________________
                22.5.4         TDelphiReader.GetDriver

    Synopsis:    Return the driver class as a TBidirBinaryObjectReader (249  ) class

Declaration:     function  GetDriver  :  TBidirBinaryObjectReader

    Visibility:   public

Description:     GetDriver simply returns the used driver and typecasts it as TBidirBinaryObjectReader
                (249  ) class.

    See also:    TBidirBinaryObjectReader (249  )
                22.5.5         TDelphiReader.ReadStr

    Synopsis:    Overrides the standard ReadStr method

Declaration:     function  ReadStr  :  String

    Visibility:   public

Description:     ReadStr makes sure the TBidirBinaryObjectReader (249  ) methods are used, to store addi-
                tional information about the stream position when reading the strings.

    See also:    TBidirBinaryObjectReader (249  )
                22.5.6         TDelphiReader.Read

    Synopsis:    Read data from stream

Declaration:     procedure  Read(var  Buf;Count:  LongInt);    Override

    Visibility:   public

Description:     Read  reads  raw  data  from  the  stream.  It  reads  Count  bytes  from  the  stream  and  places
                them in Buf.  It forces the use of the TBidirBinaryObjectReader (249  ) class when reading.

    See also:    TBidirBinaryObjectReader (249  ), TDelphiReader.Position (251  )
                22.5.7         TDelphiReader.Position

    Synopsis:    Position in the stream

Declaration:     Property  Position  :  LongInt

    Visibility:   public

      Access:    Read,Write

Description:     Position in the stream.

    See also:    TDelphiReader.Read (251  )



                                                                                 251

                _____________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'STREAMEX'___________________*
 *___________________
                22.6          TDelphiWriter



                22.6.1         Description

                TDelphiWriter is a descendent of  TWriter which has support for BiDi Streaming.  It over-
                rides the stream writing methods for strings, and makes sure the stream can be positioned
                in the case of strings.  For this purpose, it makes use of the TBidirBinaryObjectWriter (250  )
                driver class.
                22.6.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  252       FlushBuffer         Flushes the stream buffer
                  252       GetDriver           Return the driver class as a TBidirBinaryObjectWriter (250  ) class
                  252       Write               Write raw data to the stream
                  253       WriteStr            Write a string to the stream
                __253_______WriteValue__________Write_value_type___________________________________________________________________*
 *___________
                22.6.3         Property  overview

                __Page______Property________Access_______Description_______________________________________________________________*
 *___________
                __253_______Position________rw___________Position_in_the_stream____________________________________________________*
 *___________
                22.6.4         TDelphiWriter.GetDriver

    Synopsis:    Return the driver class as a TBidirBinaryObjectWriter (250  ) class

Declaration:     function  GetDriver  :  TBidirBinaryObjectWriter

    Visibility:   public

Description:     GetDriver  simply  returns  the  used  driver  and  typecasts  it  as  TBidirBinaryObjectWriter
                (250  ) class.

    See also:    TBidirBinaryObjectWriter (250  )
                22.6.5         TDelphiWriter.FlushBuffer

    Synopsis:    Flushes the stream buffer

Declaration:     procedure  FlushBuffer

    Visibility:   public

Description:     FlushBuffer  flushes  the  internal  buffer  of  the  writer.   It  simply  calls  the  FlushBuffer
                method of the driver class.
                22.6.6         TDelphiWriter.Write

    Synopsis:    Write raw data to the stream

Declaration:     procedure  Write(const  Buf;Count:  LongInt);    Override

    Visibility:   public

Description:     Write writes Count bytes from Buf to the buffer, updating the position as needed.



                                                                                 252

                _____________________________________________________CHAPTER_22.___REFERENCE_FOR_UNIT_'STREAMEX'___________________*
 *___________________
                22.6.7         TDelphiWriter.WriteStr

    Synopsis:    Write a string to the stream

Declaration:     procedure  WriteStr(const  Value:  String)

    Visibility:   public

Description:     WriteStr writes a string to the stream,  forcing the use of the TBidirBinaryObjectWriter
                (250  ) class methods, which update the position of the stream.

    See also:    TBidirBinaryObjectWriter (250  )
                22.6.8         TDelphiWriter.WriteValue

    Synopsis:    Write value type

Declaration:     procedure  WriteValue(Value:  TValueType)

    Visibility:   public

Description:     WriteValue overrides the same method in TWriter to force the use of the TBidirBinary-
                ObjectWriter (250  ) methods, which update the position of the stream.

    See also:    TBidirBinaryObjectWriter (250  )
                22.6.9         TDelphiWriter.Position

    Synopsis:    Position in the stream

Declaration:     Property  Position  :  LongInt

    Visibility:   public

      Access:    Read,Write

Description:     Position exposes the position in the stream as exposed by the TBidirBinaryObjectWriter
                (250  ) instance used when streaming.

    See also:    TBidirBinaryObjectWriter (250  )


                                                                                 253


                Chapter   23


                Reference   for   unit   'StreamIO'
                23.1          Used  units
                                                  Table 23.1:  Used units by unit 'StreamIO'


                                                                   __Name__________Page_____
                                                                     Classes          ??
                                                                     sysutils         ??



                23.2          Overview


                The  StreamIO  unit  implements  a  call  to  reroute  the  input  or  output  of  a  text  file  to  a
                descendents of TStream (??  ).

                This allows to use the standard pascal Read (??  ) and Write (??  ) functions (with all their
                possibilities), on streams.
                23.3          Procedures  and  functions



                23.3.1         AssignStream

    Synopsis:    Assign a text file to a stream.

Declaration:     procedure  AssignStream(var  F:  Textfile;Stream:  TStream)

    Visibility:   default

Description:     AssignStream  assigns  the  stream  Stream  to  file  F.  The  file  can  subsequently  be  used  to
                write to the stream, using the standard Write (??  ) calls.

                Before writing, call Rewrite (??  ) on the stream.  Before reading, call Reset (??  ).

       Errors:   if  Stream is Nil, an exception will be raised.

    See also:    #rtl.classes.TStream (??  ), GetStream (255  )


                                                                             254

                _____________________________________________________CHAPTER_23.___REFERENCE_FOR_UNIT_'STREAMIO'___________________*
 *___________________
                23.3.2         GetStream

    Synopsis:    Return the stream, associated with a file.

Declaration:     function  GetStream(var  F:  TTextRec)  :  TStream

    Visibility:   default

Description:     GetStream  returns  the  instance  of  the  stream  that  was  associated  with  the  file  F  using
                AssignStream (254  ).

       Errors:   An invalid class reference will be returned if the file was not associated with a stream.

    See also:    AssignStream (254  ), #rtl.classes.TStream (??  )

                                                                                 255


Chapter   24


Reference   for   unit   'syncob js'
24.1          Used  units
                                   Table 24.1:  Used units by unit 'syncobjs'


                                                   __Name__________Page_____
                                                     sysutils         ??



24.2          Overview


The syncobjs unit implements some classes which can be used when synchronizing threads
in routines or classes that are used in multiple threads at once.  The TCriticalSection (257  )
class is a wrapper around low-level critical section routines (semaphores or mutexes).  The
TEventObject  (259  )  class  can  be  used  to  send  messages  between  threads  (also  known  as
conditional variables in Posix threads).
24.3          Constants,  types  and  variables



24.3.1         Constants

INFINITE  =  Cardinal  (  -  1  )


Constant denoting an infinite timeout.
24.3.2         Types

PSecurityAttributes  =  Pointer


PSecurityAttributes is a dummy type used in non-windows implementations, so the calls
remain Delphi compatible.


TEvent  =  TEventObject
                                                             256

______________________________________________________CHAPTER_24.___REFERENCE_FOR_UNIT_'SYNCOBJS'__________________________________*
 *___
TEvent is a simple alias for the TEventObject (259  ) class.


TEventHandle  =  Pointer


TEventHandle is an opaque type and should not be used in user code.


TWaitResult  =  (wrSignaled,wrTimeout,wrAbandoned,wrError)
                         Table 24.2:  Enumeration values for type TWaitResult


                   __Value__________________Explanation_____________________________________________________
                     wrAbandoned            Wait operation was abandoned.
                     wrError                An error occurred during the wait operation.
                     wrSignaled             Event was signaled (triggered)
                     wrTimeout              Time-out period expired



TWaitResult is used to report the result of a wait operation.
24.4          TCriticalSection



24.4.1         Description

TCriticalSection is a class wrapper around the low-level TRTLCriticalSection routines.
It simply calls the RTL routines in the system unit for critical section support.

A critical section is a resource which can be owned by only 1 caller:  it can be used to make
sure that in a multithreaded application only 1 thread enters pieces of code protected by the
critical section.

Typical usage is to protect a piece of code with the following code (MySection is a TCriticalSection
instance):


//  Previous  code
    MySection.Acquire;
    Try
       //  Protected  code
    Finally
       MySection.Release;
    end;
    //  Other  code.


The protected code can be executed by only 1 thread at a time.  This is useful for instance
for list operations in multithreaded environments.
24.4.2         Method  overview

__Page______Property________Description_______________________________________________________________________________________
  258       Acquire         Enter the critical section
  259       Create          Create a new critical section.
  259       Destroy         Destroy the criticalsection instance
  258       Enter           Alias for Acquire
  258       Leave           Alias for Release
__258_______Release_________Leave_the_critical_section________________________________________________________________________



                                                                 257

                ______________________________________________________CHAPTER_24.___REFERENCE_FOR_UNIT_'SYNCOBJS'__________________*
 *___________________
                24.4.3         TCriticalSection.Acquire

    Synopsis:    Enter the critical section

Declaration:     procedure  Acquire;    Override

    Visibility:   public

Description:     Acquire  attempts  to  enter  the  critical  section.   It  will  suspend  the  calling  thread  if  the
                critical section is in use by another thread, and will resume as soon as the other thread has
                released the critical section.

    See also:    TCriticalSection.Release (258  )
                24.4.4         TCriticalSection.Release

    Synopsis:    Leave the critical section

Declaration:     procedure  Release;    Override

    Visibility:   public

Description:     Release leaves the critical section.  It will free the critical section so another thread waiting
                to enter the critical section will be awakened,  and will enter the critical section.  This call
                always returns immediatly.

    See also:    TCriticalSection.Acquire (258  )
                24.4.5         TCriticalSection.Enter

    Synopsis:    Alias for Acquire

Declaration:     procedure  Enter

    Visibility:   public

Description:     Enter just calls Acquire (258  ).

    See also:    TCriticalSection.Leave (258  ), TCriticalSection.Acquire (258  )
                24.4.6         TCriticalSection.Leave

    Synopsis:    Alias for Release

Declaration:     procedure  Leave

    Visibility:   public

Description:     Leave just calls Release (258  )

    See also:    TCriticalSection.Release (258  ), TCriticalSection.Enter (258  )
                                                                                 258

                ______________________________________________________CHAPTER_24.___REFERENCE_FOR_UNIT_'SYNCOBJS'__________________*
 *___________________
                24.4.7         TCriticalSection.Create

    Synopsis:    Create a new critical section.

Declaration:     constructor  Create

    Visibility:   public

Description:     Create initializes a new critical section,  and initializes the system objects for the critical
                section.  It should be created only once for all threads, all threads should use the same critical
                section instance.

    See also:    TCriticalSection.Destroy (259  )
                24.4.8         TCriticalSection.Destroy

    Synopsis:    Destroy the criticalsection instance

Declaration:     destructor  Destroy;    Override

    Visibility:   public

Description:     Destroy releases the system critical section resources, and removes the TCriticalSection
                instance from memory.

       Errors:   Any threads trying to enter the critical section when it is destroyed, will start running with
                an error (an exception should be raised).

    See also:    TCriticalSection.Create (259  ), TCriticalSection.Acquire (258  )
                24.5          TEventOb ject



                24.5.1         Description

                TEventObject encapsulates the BasicEvent implementation of the system unit in a class.
                The event can be used to notify other threads of a change in conditions.  (in POSIX terms,
                this  is  a  conditional  variable).   A  thread  that  wishes  to  notify  other  threads  creates  an
                instance of  TEventObject with a certain name, and posts events to it.  Other threads that
                wish to be notified of these events should create their own instances of  TEventObject with
                the same name, and wait for events to arrive.
                24.5.2         Method  overview

                __Page______Property____________Description________________________________________________________________________*
 *___________
                  260       Create              Create a new event object
                  260       destroy             Clean up the event and release from memory
                  260       ResetEvent          Reset the event
                  260       SetEvent            Set the event
                __261_______WaitFor_____________Wait_for_the_event_to_be_set.______________________________________________________*
 *___________
                24.5.3         Property  overview

                __Page______Property______________Access_______Description_________________________________________________________*
 *___________
                __261_______ManualReset___________r____________Should_the_event_be_reset_manually__________________________________*
 *___________

                                                                                 259

                ______________________________________________________CHAPTER_24.___REFERENCE_FOR_UNIT_'SYNCOBJS'__________________*
 *___________________
                24.5.4         TEventObject.Create

    Synopsis:    Create a new event object

Declaration:     constructor  Create(EventAttributes:  PSecurityAttributes;
                                              AManualReset:  Boolean;InitialState:  Boolean;
                                              const  Name:  String)

    Visibility:   public

Description:     Create  creates  a  new  event  object  with  unique  name  AName.  The  object  will  be  created
                security attributes EventAttributes (windows only).

                The AManualReset indicates whether the event must be reset manually (if it is False, the
                event  is  reset  immediatly  after  the  first  thread  waiting  for  it  is  notified).   InitialState
                determines whether the event is initially set or not.

    See also:    TEventObject.ManualReset (261  ), TEventObject.ResetEvent (260  )
                24.5.5         TEventObject.destroy

    Synopsis:    Clean up the event and release from memory

Declaration:     destructor  destroy;    Override

    Visibility:   public

Description:     Destroy  cleans  up  the  low-level  resources  allocated  for  this  event  and  releases  the  event
                instance from memory.

    See also:    TEventObject.Create (260  )
                24.5.6         TEventObject.ResetEvent

    Synopsis:    Reset the event

Declaration:     procedure  ResetEvent

    Visibility:   public

Description:     ResetEvent  turns  off  the  event.   Any  WaitFor  (261  )  operation  will  suspend  the  calling
                thread.

    See also:    TEventObject.SetEvent (260  ), TEventObject.WaitFor (261  )
                24.5.7         TEventObject.SetEvent

    Synopsis:    Set the event

Declaration:     procedure  SetEvent

    Visibility:   public

Description:     SetEvent sets the event.  If the ManualReset (261  ) is True any thread that was waiting for
                the event to be set (using WaitFor (261  )) will resume it's operation.  After the event was set,
                any thread that executes WaitFor will return at once.  If  ManualReset is False,  only one
                thread will be notified that the event was set, and the event will be immediatly reset after
                that.

    See also:    TEventObject.WaitFor (261  ), TEventObject.ManualReset (261  )



                                                                                 260

                ______________________________________________________CHAPTER_24.___REFERENCE_FOR_UNIT_'SYNCOBJS'__________________*
 *___________________
                24.5.8         TEventObject.WaitFor

    Synopsis:    Wait for the event to be set.

Declaration:     function  WaitFor(Timeout:  Cardinal)  :  TWaitResult

    Visibility:   public

Description:     WaitFor  should  be  used  in  threads  that  should  be  notified  when  the  event  is  set.  When
                WaitFor is called,  and the event is not set,  the thread will be suspended.  As soon as the
                event is set by some other thread (using SetEvent (260  )) or the timeout period (TimeOut)
                has expired, the WaitFor function returns.  The return value depends on the condition that
                caused the WaitFor function to return.

                The  calling  thread  will  wait  indefinitely  when  the  constant  INFINITE  is  specified  for  the
                TimeOut parameter.

    See also:    TEventObject.SetEvent (260  )
                24.5.9         TEventObject.ManualReset

    Synopsis:    Should the event be reset manually

Declaration:     Property  ManualReset  :  Boolean

    Visibility:   public

      Access:    Read

Description:     Should the event be reset manually
                24.6          THandleOb ject



                24.6.1         Description

                THandleObject is a parent class for synchronization classes that need to store an operating
                system handle.  It introduces a property Handle (262  ) which can be used to store the oper-
                ating system handle.  The handle is in no way manipulated by THandleObject, only storage
                is provided.
                24.6.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __261_______destroy_________Free_the_instance______________________________________________________________________*
 *___________
                24.6.3         Property  overview

                __Page______Property__________Access______Description______________________________________________________________*
 *___________
                  262       Handle            r           Handle for this object
                __262_______LastError_________r___________Last_operating_system_error______________________________________________*
 *___________
                24.6.4         THandleObject.destroy

    Synopsis:    Free the instance

Declaration:     destructor  destroy;    Override



                                                                                 261

                ______________________________________________________CHAPTER_24.___REFERENCE_FOR_UNIT_'SYNCOBJS'__________________*
 *___________________
    Visibility:  public

Description:     Destroy does nothing in the Free Pascal implementation of  THandleObject.
                24.6.5         THandleObject.Handle

    Synopsis:    Handle for this object

Declaration:     Property  Handle  :  TEventHandle

    Visibility:   public

      Access:    Read

Description:     Handle provides read-only access to the operating system handle of this instance.  The public
                access is read-only, descendent classes should set the handle by accessing it's protected field
                FHandle directly.
                24.6.6         THandleObject.LastError

    Synopsis:    Last operating system error

Declaration:     Property  LastError  :  Integer

    Visibility:   public

      Access:    Read

Description:     LastError provides read-only access to the last operating system error code for operations
                on Handle (262  ).

    See also:    THandleObject.Handle (262  )
                24.7          TSimpleEvent



                24.7.1         Description

                TSimpleEvent is a simple descendent of the TEventObject (259  ) class.  It creates an event
                with no name, which must be reset manually, and which is initially not set.
                24.7.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                __262_______Create__________Creates_a_new_TSimpleEvent_instance____________________________________________________*
 *___________
                24.7.3         TSimpleEvent.Create

    Synopsis:    Creates a new TSimpleEvent instance

Declaration:     constructor  Create

    Visibility:   default

Description:     Create  instantiates  a  new  TSimpleEvent  instance.   It  simply  calls  the  inherited  Create
                (260  ) with Nil for the security attributes, an empty name, AManualReset set to True, and
                InitialState to False.

    See also:    TEventObject.Create (260  )



                                                                                 262

                ______________________________________________________CHAPTER_24.___REFERENCE_FOR_UNIT_'SYNCOBJS'__________________*
 *___________________
                24.8          TSynchroOb ject



                24.8.1         Description

                TSynchroObject  is  an  abstract  synchronization  resource  object.   It  implements  2  virtual
                methods  Acquire  (263  )  which  can  be  used  to  acquire  the  resource,  and  Release  (263  )  to
                release the resource.
                24.8.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  263       Acquire         Acquire synchronization resource
                __263_______Release_________Release_previously_acquired_synchronization_resource___________________________________*
 *___________
                24.8.3         TSynchroObject.Acquire

    Synopsis:    Acquire synchronization resource

Declaration:     procedure  Acquire;    Virtual

    Visibility:   default

Description:     Acquire does nothing in TSynchroObject.  Descendent classes must override this method
                to acquire the resource they manage.

    See also:    TSynchroObject.Release (263  )
                24.8.4         TSynchroObject.Release

    Synopsis:    Release previously acquired synchronization resource

Declaration:     procedure  Release;    Virtual

    Visibility:   default

Description:     Release does nothing in TSynchroObject.  Descendent classes must override this method
                to release the resource they acquired through the Acquire (263  ) call.

    See also:    TSynchroObject.Acquire (263  )
                                                                                 263


Chapter   25


Reference   for   unit   'zstream'
25.1          Used  units
                                   Table 25.1:  Used units by unit 'zstream'


                                                   __Name__________Page____
                                                     Classes          ??
                                                     gzio            264
                                                     zbase           264



25.2          Overview


The  ZStream  unit  implements  a  TStream  (??  )  descendent  (TCompressionStream  (265  ))
which  uses  the  deflate  algorithm  to  compress  everything  that  is  written  to  it.   The  com-
pressed data is written to the output stream, which is specified when the compressor class
is created.

Likewise,  a  TStream  descendent  is  implemented  which  reads  data  from  an  input  stream
(TDecompressionStream (268  )) and decompresses it with the inflate algorithm.
25.3          Constants,  types  and  variables



25.3.1         Types

Tcompressionlevel  =  (clnone,clfastest,cldefault,clmax)


Compression level for the deflate algorithm


Tgzopenmode  =  (gzopenread,gzopenwrite)


Open mode for gzip file.
                                                             264

_______________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'ZSTREAM'__________________________________*
 *___

                      Table 25.2:  Enumeration values for type Tcompressionlevel


                          __Value__________Explanation_______________________________________________
                            cldefault       Use default compression
                            clfastest       Use fast (but less) compression.
                            clmax           Use maximum compression
                            clnone          Do not use compression, just copy data.

                         Table 25.3:  Enumeration values for type Tgzopenmode


                                     __Value_______________Explanation____________________
                                       gzopenread          Open file for reading
                                       gzopenwrite         Open file for writing

25.4          Ecompressionerror



25.4.1         Description

ECompressionError is the exception class used by the TCompressionStream (265  ) class.
25.5          Edecompressionerror



25.5.1         Description

EDecompressionError is the exception class used by the TDeCompressionStream (268  ) class.
25.6          Egzfileerror



25.6.1         Description

Egzfileerror is the exception class used to report errors by the Tgzfilestream (270  ) class.
25.7          Ezliberror



25.7.1         Description

Errors  which  occur  in  the  zstream  unit  are  signaled  by  raising  an  EZLibError  exception
descendent.
25.8          Tcompressionstream



25.8.1         Description

TCompressionStream

                                                                 265

                _______________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'ZSTREAM'__________________*
 *___________________
                25.8.2         Method  overview

                __Page______Property________________________Description____________________________________________________________*
 *___________
                  266       create                          Create a new instance of the compression stream.
                  266       destroy                         Flushe  data  to  the  output  stream  and  destroys  the  com-
                                                            pression stream.
                  267       flush                           Flush remaining data to the target stream
                  267       get_compressionrate             Get the current compression rate
                __266_______write___________________________Write_data_to_the_stream_______________________________________________*
 *___________
                25.8.3         Tcompressionstream.create

    Synopsis:    Create a new instance of the compression stream.

Declaration:     constructor  create(level:  Tcompressionlevel;dest:  TStream;
                                              Askipheader:  Boolean)

    Visibility:   public

Description:     Create  creates  a  new  instance  of  the  compression  stream.   It  merely  calls  the  inherited
                constructor with the destination stream Dest and stores the compression level.

                If  ASkipHeader is set to True,  the method will not write the block header to the stream.
                This is required for deflated data in a zip file.

                Note that the compressed data is only completely written after the compression stream is
                destroyed.

    See also:    TCompressionStream.Destroy (266  )
                25.8.4         Tcompressionstream.destroy

    Synopsis:    Flushe data to the output stream and destroys the compression stream.

Declaration:     destructor  destroy;    Override

    Visibility:   public

Description:     Destroy  flushes  the  output  stream:  any  compressed  data  not  yet  written  to  the  output
                stream are written, and the deflate structures are cleaned up.

       Errors:   None.

    See also:    TCompressionStream.Create (266  )
                25.8.5         Tcompressionstream.write

    Synopsis:    Write data to the stream

Declaration:     function  write(const  buffer;count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write  takes  Count  bytes  from  Buffer  and  comresseses  (deflates)  them.  The  compressed
                result is written to the output stream.

       Errors:   If an error occurs, an ECompressionError (265  ) exception is raised.

    See also:    TCompressionStream.Read (265  ), TCompressionStream.Seek (265  )
                                                                                 266

                _______________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'ZSTREAM'__________________*
 *___________________
                25.8.6         Tcompressionstream.flush

    Synopsis:    Flush remaining data to the target stream

Declaration:     procedure  flush

    Visibility:   public

Description:     flush writes any remaining data in the memory buffers to the target stream, and clears the
                memory buffer.
                25.8.7         Tcompressionstream.get__compressionrate

    Synopsis:    Get the current compression rate

Declaration:     function  get_compressionrate  :  single

    Visibility:   public

Description:     get_compressionrate returns the percentage of the number of written compressed bytes
                relative to the number of written bytes.

       Errors:   If no bytes were written, an exception is raised.
                25.9          Tcustomzlibstream



                25.9.1         Description

                TCustomZlibStream  serves  as  the  ancestor  class  for  the  TCompressionStream  (265  )  and
                TDeCompressionStream (268  ) classes.

                It introduces support for a progess handler, and stores the input or output stream.
                25.9.2         Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  267       create          Create a new instance of  TCustomZlibStream
                __268_______destroy_________Clear_up_instance______________________________________________________________________*
 *___________
                25.9.3         Tcustomzlibstream.create

    Synopsis:    Create a new instance of  TCustomZlibStream

Declaration:     constructor  create(stream:  TStream)

    Visibility:   public

Description:     Create  creates  a  new  instance  of  TCustomZlibStream.   It  stores  a  reference  to  the  in-
                put/output stream, and initializes the deflate compression mechanism so they can be used
                by the descendents.

    See also:    TCompressionStream (265  ), TDecompressionStream (268  )



                                                                                 267

                _______________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'ZSTREAM'__________________*
 *___________________
                25.9.4         Tcustomzlibstream.destroy

    Synopsis:    Clear up instance

Declaration:     destructor  destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the internal memory buffer and calls the inherited destroy.

    See also:    Tcustomzlibstream.create (267  )
                25.10            Tdecompressionstream



                25.10.1          Description

                TDecompressionStream  performs  the  inverse  operation  of  TCompressionStream  (265  ).  A
                read operation reads data from an input stream and decompresses (inflates) the data it as
                it goes along.

                The decompression stream reads it's compressed data from a stream with deflated data.  This
                data can be created e.g.  with a TCompressionStream (265  ) compression stream.
                25.10.2          Method  overview

                __Page______Property________________________Description____________________________________________________________*
 *___________
                  268       create                          Creates  a  new  instance  of  the  TDecompressionStream
                                                            stream
                  269       destroy                         Destroys the TDecompressionStream instance
                  270       get_compressionrate             Get the current compression rate
                  269       read                            Read data from the compressed stream
                __269_______seek____________________________Move_stream_position_to_a_certain_location_in_the_stream.______________*
 *___________
                25.10.3          Tdecompressionstream.create

    Synopsis:    Creates a new instance of the TDecompressionStream stream

Declaration:     constructor  create(Asource:  TStream;Askipheader:  Boolean)

    Visibility:   public

Description:     Create creates and initializes a new instance of the TDecompressionStream class.  It calls
                the inherited Create and passes it the Source stream.  The source stream is the stream from
                which the compressed (deflated) data is read.

                If ASkipHeader is true, then the gzip data header is skipped, allowing TDecompressionStream
                to read deflated data in a .zip file.  (this data does not have the gzip header record prepended
                to it).

                Note that the source stream is by default not owned by the decompression stream,  and is
                not freed when the decompression stream is destroyed.

    See also:    TDecompressionStream.Destroy (269  )



                                                                                 268

                _______________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'ZSTREAM'__________________*
 *___________________
                25.10.4          Tdecompressionstream.destroy

    Synopsis:    Destroys the TDecompressionStream instance

Declaration:     destructor  destroy;    Override

    Visibility:   public

Description:     Destroy cleans up the inflate structure, and then simply calls the inherited destroy.

                By default the source stream is not freed when calling Destroy.

    See also:    TDecompressionStream.Create (268  )
                25.10.5          Tdecompressionstream.read

    Synopsis:    Read data from the compressed stream

Declaration:     function  read(var  buffer;count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Read will read data from the compressed stream until the decompressed data size is Count
                or there is no more compressed data available.  The decompressed data is written in Buffer.
                The function returns the number of bytes written in the buffer.

       Errors:   If an error occurs, an EDeCompressionError (265  ) exception is raised.

    See also:    TCompressionStream.Write (266  )
                25.10.6          Tdecompressionstream.seek

    Synopsis:    Move stream position to a certain location in the stream.

Declaration:     function  seek(offset:  LongInt;origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek overrides the standard Seek implementation.  There are a few differences between the
                implementation of  Seek in Free Pascal compared to Delphi:


                      oIn Free Pascal,  you can perform any seek.  In case of a forward seek,  the Free Pascal
                       implementation will read some bytes until the desired position is reached, in case of a
                       backward seek it will seek the source stream backwards to the position it had at the
                       creation time of the TDecompressionStream and then again read some bytes until the
                       desired position has been reached.

                      oIn Free Pascal, a seek with soFromBeginning will reset the source stream to the position
                       it had when the TDecompressionStream was created.  In Delphi, the source stream is
                       reset to position 0.  This means that at creation time the source stream must always be
                       at the start of the zstream, you cannot use TDecompressionStream.Seek to reset the
                       source stream to the begin of the file.


       Errors:   An EDecompressionError (265  ) exception is raised if the stream does not allow the requested
                seek operation.

    See also:    TDecompressionStream.Read (269  )



                                                                                 269

                _______________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'ZSTREAM'__________________*
 *___________________
                25.10.7          Tdecompressionstream.get__compressionrate

    Synopsis:    Get the current compression rate

Declaration:     function  get_compressionrate  :  single

    Visibility:   public

Description:     get_compressionrate returns the percentage of the number of read compressed bytes rel-
                ative to the total number of read bytes.

       Errors:   If no bytes were written, an exception is raised.
                25.11            TGZFileStream



                25.11.1          Description

                TGZFileStream can be used to read data from a gzip file, or to write data to a gzip file.
                25.11.2          Method  overview

                __Page______Property________Description____________________________________________________________________________*
 *___________
                  270       create          Create a new instance of  TGZFileStream
                  271       destroy         Removes TGZFileStream instance
                  270       read            Read data from the compressed file
                  271       seek            Set the position in the compressed stream.
                __271_______write___________Write_data_to_be_compressed____________________________________________________________*
 *___________
                25.11.3          TGZFileStream.create

    Synopsis:    Create a new instance of  TGZFileStream

Declaration:     constructor  create(filename:  ansistring;filemode:  Tgzopenmode)

    Visibility:   public

Description:     Create creates a new instance of the TGZFileStream class.  It opens FileName for reading or
                writing, depending on the FileMode parameter.  It is not possible to open the file read-write.
                If the file is opened for reading, it must exist.

                If  the  file  is  opened  for  reading,  the  TGZFileStream.Read  (270  )  method  can  be  used  for
                reading the data in uncompressed form.

                If  the  file  is  opened  for  writing,  any  data  written  using  the  TGZFileStream.Write  (271  )
                method will be stored in the file in compressed (deflated) form.

       Errors:   If the file is not found, an EZlibError (265  ) exception is raised.

    See also:    TGZFileStream.Destroy (271  ), TGZOpenMode (264  )
                25.11.4          TGZFileStream.read

    Synopsis:    Read data from the compressed file

Declaration:     function  read(var  buffer;count:  LongInt)  :  LongInt;    Override

    Visibility:   public
                                                                                 270

                _______________________________________________________CHAPTER_25.___REFERENCE_FOR_UNIT_'ZSTREAM'__________________*
 *___________________
Description:     Read overrides the Read method of TStream to read the data from the compressed file.  The
                Buffer  parameter  indicates  where  the  read  data  should  be  stored.  The  Count  parameter
                specifies the number of bytes (uncompressed ) that should be read from the compressed file.
                Note that it is not possible to read from the stream if it was opened in write mode.

                The function returns the number of uncompressed bytes actually read.

       Errors:   If  Buffer points to an invalid location, or does not have enough room for Count bytes, an
                exception will be raised.

    See also:    TGZFileStream.Create (270  ), TGZFileStream.Write (271  ), TGZFileStream.Seek (271  )
                25.11.5          TGZFileStream.write

    Synopsis:    Write data to be compressed

Declaration:     function  write(const  buffer;count:  LongInt)  :  LongInt;    Override

    Visibility:   public

Description:     Write writes Count bytes from Buffer to the compressed file.  The data is compressed as
                it is written, so ideally, less than Count bytes end up in the compressed file.  Note that it is
                not possible to write to the stream if it was opened in read mode.

                The function returns the number of (uncompressed) bytes that were actually written.

       Errors:   In case of an error, an EZlibError (265  ) exception is raised.

    See also:    TGZFileStream.Create (270  ), TGZFileStream.Read (270  ), TGZFileStream.Seek (271  )
                25.11.6          TGZFileStream.seek

    Synopsis:    Set the position in the compressed stream.

Declaration:     function  seek(offset:  LongInt;origin:  Word)  :  LongInt;    Override

    Visibility:   public

Description:     Seek  sets  the  position  to  Offset  bytes,  starting  from  Origin.   Not  all  combinations  are
                possible, see TDecompressionStream.Seek (269  ) for a list of possibilities.

       Errors:   In case an impossible combination is asked, an EZlibError (265  ) exception is raised.

    See also:    TDecompressionStream.Seek (269  )
                25.11.7          TGZFileStream.destroy

    Synopsis:    Removes TGZFileStream instance

Declaration:     destructor  destroy;    Override

    Visibility:   public

Description:     Destroy closes the file and releases the TGZFileStream instance from memory.

    See also:    TGZFileStream.Create (270  )

                                                                                 271
