home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 February / Chip_2000-02_cd.bin / zkuste / freesoft / freepascal / units.txt < prev    next >
Text File  |  1999-12-19  |  762KB  |  21,922 lines
  1. Free Pascal supplied units :
  2. Reference guide.
  3.  
  4.                         Reference guide for standard Free Pascal units.
  5.                                                                     1.6
  6.                                                              July 1999
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16. Micha¿el Van Canneyt
  17. Florian Kl¿ampfl
  18.  
  19.  
  20.  
  21. Contents
  22.  
  23. 1 The CRT unit.                                                                    21
  24.   1.1 Types, Variables, Constants . . . . . . . . . . . . . . . . . . . . . . . 21
  25.   1.2 Procedures and Functions . . . . . . . . . . . . . . . . . . . . . . . . 22
  26.        AssignCrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
  27.        BigCursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
  28.        ClrEol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
  29.        ClrScr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
  30.        CursorO  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
  31.        CursorOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
  32.        Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
  33.        DelLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
  34.        GotoXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
  35.        HighVideo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
  36.        InsLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
  37.        KeyPressed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
  38.        LowVideo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
  39.        NormVideo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
  40.        NoSound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
  41.        ReadKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
  42.        Sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
  43.        TextBackground . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
  44.        TextColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
  45.        WhereX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
  46.        WhereY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  47.        Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  48.  
  49. 2 The DOS unit.                                                                    33
  50.   2.1 Types, Variables, Constants . . . . . . . . . . . . . . . . . . . . . . . 33
  51.        Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
  52.        Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
  53.        Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  54.  
  55.  
  56.                                          1
  57.  
  58.  
  59.  
  60.                                                                         CONTENTS
  61.  
  62.  
  63.   2.2 Functions and Procedures . . . . . . . . . . . . . . . . . . . . . . . . 36
  64.        AddDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
  65.        DiskFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
  66.        DiskSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
  67.        DosExitCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
  68.        DosVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
  69.        EnvCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
  70.        EnvStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
  71.        Exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
  72.        FExpand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
  73.        FindClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
  74.        FindFirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
  75.        FindNext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
  76.        FSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
  77.        FSplit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
  78.        GetCBreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
  79.        GetDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
  80.        GetEnv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
  81.        GetFAttr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
  82.        GetFTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
  83.        GetIntVec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
  84.        GetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
  85.        GetVerify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
  86.        Intr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
  87.        Keep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
  88.        MSDos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
  89.        PackTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
  90.        SetCBreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
  91.        SetDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  92.        SetFAttr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  93.        SetFTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  94.        SetIntVec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  95.        SetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
  96.        SetVerify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
  97.        SwapVectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
  98.        UnPackTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
  99.  
  100. 3 The GETOPTS unit.                                                                50
  101.   3.1 Types, Constants and variables : . . . . . . . . . . . . . . . . . . . . 50
  102.        Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
  103.  
  104.  
  105.                                          2
  106.  
  107.  
  108.  
  109.                                                                         CONTENTS
  110.  
  111.  
  112.        Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
  113.        Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
  114.   3.2 Procedures and functions . . . . . . . . . . . . . . . . . . . . . . . . 51
  115.        GetLongOpts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
  116.        Getopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
  117.  
  118. 4 The GO32 unit                                                                     54
  119.   4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
  120.   4.2 Protected mode memory organization . . . . . . . . . . . . . . . . . 54
  121.        What is DPMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
  122.        Selectors and descriptors . . . . . . . . . . . . . . . . . . . . . . . . . 54
  123.        FPC specialities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
  124.        dos memory access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
  125.        I/O port access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
  126.        Processor access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
  127.        Interrupt redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
  128.        Handling interrupts with DPMI . . . . . . . . . . . . . . . . . . . . . 56
  129.        Protected mode interrupts vs. Real mode interrupts . . . . . . . . . 56
  130.        Creating own interrupt handlers . . . . . . . . . . . . . . . . . . . . 56
  131.        Disabling interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
  132.        Hardware interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
  133.        Software interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
  134.        Real mode callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
  135.   4.3 Types, Variables and Constants . . . . . . . . . . . . . . . . . . . . . 62
  136.        Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
  137.        Predefined types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
  138.        Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
  139.   4.4 Functions and Procedures . . . . . . . . . . . . . . . . . . . . . . . . 64
  140.        allocate ldt descriptors . . . . . . . . . . . . . . . . . . . . . . . . . 64
  141.        allocate memory block . . . . . . . . . . . . . . . . . . . . . . . . . 66
  142.        copyfromdos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  143.        copytodos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  144.        create code segment alias descriptor . . . . . . . . . . . . . . . . 67
  145.        disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  146.        dosmemfillchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
  147.        dosmemfillword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
  148.        dosmemget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
  149.        dosmemmove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
  150.        dosmemput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
  151.        enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
  152.  
  153.  
  154.                                          3
  155.  
  156.  
  157.  
  158.                                                                  CONTENTS
  159.  
  160.  
  161. free ldt descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
  162. free memory block . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
  163. free rm callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
  164. get cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
  165. get descriptor access rights . . . . . . . . . . . . . . . . . . . . . . 71
  166. get ds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
  167. get linear addr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
  168. get meminfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
  169. get next selector increment value . . . . . . . . . . . . . . . . . . 73
  170. get page size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
  171. get pm interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
  172. get rm callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
  173. get rm interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
  174. get run mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
  175. get segment base address . . . . . . . . . . . . . . . . . . . . . . . 78
  176. get segment limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
  177. get ss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
  178. global dos alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
  179. global dos free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
  180. inportb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
  181. inportl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
  182. inportw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
  183. lock code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
  184. lock data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
  185. lock linear region . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
  186. outportb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
  187. outportl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
  188. outportw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
  189. realintr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
  190. seg fillchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
  191. seg fillword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
  192. segment to descriptor . . . . . . . . . . . . . . . . . . . . . . . . . 85
  193. seg move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
  194. set descriptor access rights . . . . . . . . . . . . . . . . . . . . . . 86
  195. set pm interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
  196. set rm interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
  197. set segment base address . . . . . . . . . . . . . . . . . . . . . . . 88
  198. set segment limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
  199. tb size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
  200. transfer bu er . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
  201.  
  202.  
  203.                                   4
  204.  
  205.  
  206.  
  207.                                                                         CONTENTS
  208.  
  209.  
  210.        unlock code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
  211.        unlock data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
  212.        unlock linear region . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
  213.  
  214. 5 The GRAPH unit.                                                                   91
  215.   5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
  216.        Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
  217.   5.2 Constants, Types and Variables . . . . . . . . . . . . . . . . . . . . . 91
  218.        Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
  219.   5.3 Functions and procedures . . . . . . . . . . . . . . . . . . . . . . . . 92
  220.        Arc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
  221.        Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
  222.        Bar3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
  223.        Circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
  224.        ClearDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
  225.        ClearViewPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
  226.        CloseGraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
  227.        DetectGraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
  228.        DrawPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
  229.        Ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
  230.        FillEllipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
  231.        FillPoly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
  232.        FloodFill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
  233.        GetArcCoords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
  234.        GetAspectRatio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
  235.        GetBkColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
  236.        GetColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
  237.        GetDefaultPalette . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
  238.        GetDriverName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
  239.        GetFillPattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
  240.        GetFillSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
  241.        GetGraphMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
  242.        GetImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
  243.        GetLineSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
  244.        GetMaxColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
  245.        GetMaxMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
  246.        GetMaxX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
  247.        GetMaxY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
  248.        GetModeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
  249.        GetModeRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
  250.  
  251.  
  252.                                          5
  253.  
  254.  
  255.  
  256.                                                                  CONTENTS
  257.  
  258.  
  259. GetPalette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
  260. GetPaletteSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
  261. GetPixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
  262. GetTextSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
  263. GetViewSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
  264. GetX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
  265. GetY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
  266. GraphDefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
  267. GraphErrorMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
  268. GraphResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
  269. ImageSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
  270. InitGraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
  271. InstallUserDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
  272. InstallUserFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
  273. Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
  274. LineRel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
  275. LineTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
  276. MoveRel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
  277. MoveTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
  278. OutText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
  279. OutTextXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
  280. PieSlice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
  281. PutImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
  282. PutPixel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
  283. Rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
  284. RegisterBGIDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
  285. RegisterBGIFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
  286. RestoreCRTMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
  287. Sector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
  288. SetActivePage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
  289. SetAllPallette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
  290. SetAspectRatio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
  291. SetBkColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
  292. SetColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
  293. SetFillPattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
  294. SetFillStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
  295. SetGraphBufSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
  296. SetGraphMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
  297. SetLineStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
  298. SetPalette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
  299.  
  300.  
  301.                                   6
  302.  
  303.  
  304.  
  305.                                                                         CONTENTS
  306.  
  307.  
  308.        SetRGBPalette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
  309.        SetTextJustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
  310.        SetTextStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
  311.        SetUserCharSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
  312.        SetViewPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
  313.        SetVisualPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
  314.        SetWriteMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
  315.        TextHeight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
  316.        TextWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
  317.  
  318. 6 The HEAPTRC unit.                                                               109
  319.   6.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
  320.   6.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
  321.   6.3 Constants, Types and variables . . . . . . . . . . . . . . . . . . . . . 111
  322.   6.4 Functions and procedures . . . . . . . . . . . . . . . . . . . . . . . . 111
  323.        DumpHeap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
  324.        MarkHeap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
  325.        SetExtraInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
  326.  
  327. 7 The IPC unit.                                                                   114
  328.   7.1 Types, Constants and variables : . . . . . . . . . . . . . . . . . . . . 114
  329.        Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
  330.        Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
  331.        Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
  332.   7.2 Functions and procedures . . . . . . . . . . . . . . . . . . . . . . . . 119
  333.        ftok . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
  334.        msgget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
  335.        msgsnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
  336.        msgrcv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
  337.        msgctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
  338.        semget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
  339.        semop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
  340.        semctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
  341.        shmget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
  342.        shmat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
  343.        shmdt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
  344.        shmctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
  345.  
  346. 8 The LINUX unit.                                                                 133
  347.   8.1 Type, Variable and Constant declarations . . . . . . . . . . . . . . . 133
  348.        Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
  349.  
  350.  
  351.                                          7
  352.  
  353.  
  354.  
  355.                                                                        CONTENTS
  356.  
  357.  
  358.      Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
  359.      Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
  360. 8.2 Functions and procedures . . . . . . . . . . . . . . . . . . . . . . . . 139
  361.      Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
  362.      AssignPipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
  363.      AssignStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
  364.      BaseName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
  365.      CFMakeRaw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
  366.      CFSetISpeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
  367.      CFSetOSpeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
  368.      Chown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
  369.      Chmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
  370.      CloseDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
  371.      DirName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
  372.      Dup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
  373.      Dup2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
  374.      EpochToLocal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
  375.      Execl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
  376.      Execle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
  377.      Execlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
  378.      Execv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
  379.      Execve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
  380.      Execvp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
  381.      FD ZERO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
  382.      FD Clr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
  383.      FD IsSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
  384.      FD Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
  385.      fdClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
  386.      fdFlush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
  387.      fdOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
  388.      fdRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
  389.      fdSeek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
  390.      fdTruncate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
  391.      fdWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
  392.      FExpand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
  393.      FLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
  394.      FSStat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
  395.      FSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
  396.      FStat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
  397.      Fcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
  398.  
  399.  
  400.                                         8
  401.  
  402.  
  403.  
  404.                                                                    CONTENTS
  405.  
  406.  
  407. Fcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
  408. Fork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
  409. GetDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
  410. GetDomainName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
  411. GetEGid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
  412. GetEUid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
  413. GetEnv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
  414. GetEpochTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
  415. GetFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
  416. GetGid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
  417. GetHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
  418. GetPid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
  419. GetPPid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
  420. GetPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
  421. GetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
  422. GetUid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
  423. Glob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
  424. GlobFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
  425. IOCtl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
  426. IOperm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
  427. IsATTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
  428. S ISBLK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
  429. S ISCHR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
  430. S ISDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
  431. S ISFIFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
  432. S ISLNK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
  433. S ISREG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
  434. S ISSOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
  435. Kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
  436. LStat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
  437. Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
  438. LocalToEpoch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
  439. MkFifo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
  440. Nice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
  441. OpenDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
  442. PClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
  443. POpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
  444. ReadDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
  445. SeekDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
  446. Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
  447.  
  448.  
  449.                                    9
  450.  
  451.  
  452.  
  453.                                                                          CONTENTS
  454.  
  455.  
  456.        SelectText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
  457.        SetPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
  458.        Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
  459.        SigAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
  460.        SigPending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
  461.        SigProcMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
  462.        SigSuspend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
  463.        Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
  464.        SymLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
  465.        TCDrain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
  466.        TCFlow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
  467.        TCFlush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
  468.        TCGetAttr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
  469.        TCGetPGrp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
  470.        TCSendBreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
  471.        TCSetAttr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
  472.        TCSetPGrp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
  473.        TTYName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
  474.        TellDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
  475.        Umask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
  476.        Uname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
  477.        UnLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
  478.        Utime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
  479.        WaitPid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
  480.  
  481. 9 The MMX unit                                                                     191
  482.   9.1 Variables, Types and constants . . . . . . . . . . . . . . . . . . . . . 191
  483.   9.2 Functions and Procedures . . . . . . . . . . . . . . . . . . . . . . . . 192
  484.        Emms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
  485.  
  486. 10 The Mouse unit                                                                  193
  487.   10.1 Constants, types and variables . . . . . . . . . . . . . . . . . . . . . 193
  488.   10.2 Functions and procedures . . . . . . . . . . . . . . . . . . . . . . . . 194
  489.        GetLastButtonPress . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
  490.        GetLastButtonRelease . . . . . . . . . . . . . . . . . . . . . . . . . . 195
  491.        GetMouseState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
  492.        HideMouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
  493.        InitMouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
  494.        LPressed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
  495.        MPressed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
  496.        RPressed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
  497.  
  498.                                          10
  499.  
  500.  
  501.  
  502.                                                                         CONTENTS
  503.  
  504.  
  505.        SetMouseAscii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
  506.        SetMouseHideWindow . . . . . . . . . . . . . . . . . . . . . . . . . . 199
  507.        SetMousePos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
  508.        SetMouseShape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
  509.        SetMouseSpeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
  510.        SetMouseWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
  511.        SetMouseXRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
  512.        SetMouseYRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
  513.        ShowMouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
  514.  
  515. 11 The Objects unit.                                                              204
  516.   11.1 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
  517.   11.2 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
  518.   11.3 Procedures and Functions . . . . . . . . . . . . . . . . . . . . . . . . 206
  519.        NewStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
  520.        DisposeStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
  521.        Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
  522.        RegisterObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
  523.        RegisterType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
  524.        LongMul . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
  525.        LongDiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
  526.   11.4 TRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
  527.        TRect.Empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
  528.        TRect.Equals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
  529.        TRect.Contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
  530.        TRect.Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
  531.        TRect.Union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
  532.        TRect.Intersect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
  533.        TRect.Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
  534.        TRect.Grow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
  535.        TRect.Assign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
  536.   11.5 TObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
  537.        TObject.Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
  538.        TObject.Free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
  539.        TObject.Done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
  540.   11.6 TStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
  541.        TStream.Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
  542.        TStream.StrRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
  543.        TStream.GetPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
  544.        TStream.GetSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
  545.  
  546.  
  547.                                          11
  548.  
  549.  
  550.  
  551.                                                                       CONTENTS
  552.  
  553.  
  554.      TStream.ReadStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
  555.      TStream.Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
  556.      TStream.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
  557.      TStream.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
  558.      TStream.Flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
  559.      TStream.Truncate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
  560.      TStream.Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
  561.      TStream.StrWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
  562.      TStream.WriteStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
  563.      TStream.Seek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
  564.      TStream.Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
  565.      TStream.Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
  566.      TStream.Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
  567.      TStream.CopyFrom . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
  568. 11.7 TDosStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
  569.      TDosStream.Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
  570.      TDosStream.Done . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
  571.      TDosStream.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
  572.      TDosStream.Truncate . . . . . . . . . . . . . . . . . . . . . . . . . . 225
  573.      TDosStream.Seek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
  574.      TDosStream.Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
  575.      TDosStream.Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
  576.      TDosStream.Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
  577. 11.8 TBufStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
  578.      TBufStream.Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
  579.      TBufStream.Done . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
  580.      TBufStream.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
  581.      TBufStream.Flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
  582.      TBufStream.Truncate . . . . . . . . . . . . . . . . . . . . . . . . . . 230
  583.      TBufStream.Seek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
  584.      TBufStream.Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
  585.      TBufStream.Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
  586.      TBufStream.Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
  587. 11.9 TMemoryStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
  588.      TMemoryStream.Init . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
  589.      TMemoryStream.Done . . . . . . . . . . . . . . . . . . . . . . . . . . 232
  590.      TMemoryStream.Truncate . . . . . . . . . . . . . . . . . . . . . . . . 233
  591.      TMemoryStream.Read . . . . . . . . . . . . . . . . . . . . . . . . . . 233
  592.      TMemoryStream.Write . . . . . . . . . . . . . . . . . . . . . . . . . . 234
  593. 11.10TCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
  594.  
  595.  
  596.                                       12
  597.  
  598.  
  599.  
  600.                                                                       CONTENTS
  601.  
  602.  
  603.      TCollection.Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
  604.      TCollection.Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
  605.      TCollection.Done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
  606.      TCollection.At . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
  607.      TCollection.IndexOf . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
  608.      TCollection.GetItem . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
  609.      TCollection.LastThat . . . . . . . . . . . . . . . . . . . . . . . . . . 238
  610.      TCollection.FirstThat . . . . . . . . . . . . . . . . . . . . . . . . . . 239
  611.      TCollection.Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
  612.      TCollection.FreeAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
  613.      TCollection.DeleteAll . . . . . . . . . . . . . . . . . . . . . . . . . . 241
  614.      TCollection.Free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
  615.      TCollection.Insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
  616.      TCollection.Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
  617.      TCollection.AtFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
  618.      TCollection.FreeItem . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
  619.      TCollection.AtDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
  620.      TCollection.ForEach . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
  621.      TCollection.SetLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
  622.      TCollection.Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
  623.      TCollection.AtPut . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
  624.      TCollection.AtInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
  625.      TCollection.Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
  626.      TCollection.PutItem . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
  627. 11.11TSortedCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
  628.      TSortedCollection.Init . . . . . . . . . . . . . . . . . . . . . . . . . . 249
  629.      TSortedCollection.Load . . . . . . . . . . . . . . . . . . . . . . . . . 250
  630.      TSortedCollection.KeyOf . . . . . . . . . . . . . . . . . . . . . . . . 250
  631.      TSortedCollection.IndexOf . . . . . . . . . . . . . . . . . . . . . . . . 250
  632.      TSortedCollection.Compare . . . . . . . . . . . . . . . . . . . . . . . 250
  633.      TSortedCollection.Search . . . . . . . . . . . . . . . . . . . . . . . . 251
  634.      TSortedCollection.Insert . . . . . . . . . . . . . . . . . . . . . . . . . 252
  635.      TSortedCollection.Store . . . . . . . . . . . . . . . . . . . . . . . . . 253
  636. 11.12TStringCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
  637.      TStringCollection.GetItem . . . . . . . . . . . . . . . . . . . . . . . . 254
  638.      TStringCollection.Compare . . . . . . . . . . . . . . . . . . . . . . . 254
  639.      TStringCollection.FreeItem . . . . . . . . . . . . . . . . . . . . . . . 255
  640.      TStringCollection.PutItem . . . . . . . . . . . . . . . . . . . . . . . . 255
  641. 11.13TStrCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
  642.      TStrCollection.GetItem . . . . . . . . . . . . . . . . . . . . . . . . . 256
  643.  
  644.  
  645.                                        13
  646.  
  647.  
  648.  
  649.                                                                         CONTENTS
  650.  
  651.  
  652.        TStrCollection.Compare . . . . . . . . . . . . . . . . . . . . . . . . . 256
  653.        TStrCollection.FreeItem . . . . . . . . . . . . . . . . . . . . . . . . . 257
  654.        TStrCollection.PutItem . . . . . . . . . . . . . . . . . . . . . . . . . 257
  655.   11.14TUnSortedStrCollection . . . . . . . . . . . . . . . . . . . . . . . . . 257
  656.        TUnSortedStrCollection.Insert . . . . . . . . . . . . . . . . . . . . . 258
  657.   11.15TResourceCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
  658.        TResourceCollection.KeyOf . . . . . . . . . . . . . . . . . . . . . . . 259
  659.        TResourceCollection.GetItem . . . . . . . . . . . . . . . . . . . . . . 259
  660.        TResourceCollection.FreeItem . . . . . . . . . . . . . . . . . . . . . . 259
  661.        TResourceCollection.PutItem . . . . . . . . . . . . . . . . . . . . . . 260
  662.   11.16TResourceFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
  663.        TResourceFile Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
  664.        TResourceFile.Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
  665.        TResourceFile.Done . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
  666.        TResourceFile.Count . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
  667.        TResourceFile.KeyAt . . . . . . . . . . . . . . . . . . . . . . . . . . 261
  668.        TResourceFile.Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
  669.        TResourceFile.SwitchTo . . . . . . . . . . . . . . . . . . . . . . . . . 261
  670.        TResourceFile.Flush . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
  671.        TResourceFile.Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
  672.        TResourceFile.Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
  673.   11.17TStringList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
  674.        TStringList.Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
  675.        TStringList.Done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
  676.        TStringList.Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
  677.   11.18TStrListMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
  678.        TStrListMaker.Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
  679.        TStrListMaker.Done . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
  680.        TStrListMaker.Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
  681.        TStrListMaker.Store . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
  682.  
  683. 12 The PRINTER unit.                                                              265
  684.   12.1 Types, Constants and variables : . . . . . . . . . . . . . . . . . . . . 265
  685.   12.2 Procedures and functions . . . . . . . . . . . . . . . . . . . . . . . . 265
  686.        AssignLst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
  687.  
  688. 13 The SOCKETS unit.                                                              267
  689.   13.1 Types, Constants and variables : . . . . . . . . . . . . . . . . . . . . 267
  690.   13.2 Functions and Procedures . . . . . . . . . . . . . . . . . . . . . . . . 268
  691.        Accept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
  692.        Accept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
  693.  
  694.                                          14
  695.  
  696.  
  697.  
  698.                                                                         CONTENTS
  699.  
  700.  
  701.        Accept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
  702.        Accept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
  703.        Bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
  704.        Bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
  705.        Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
  706.        Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
  707.        Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
  708.        Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
  709.        GetPeerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
  710.        GetSocketName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
  711.        GetSocketOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
  712.        Listen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
  713.        Recv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
  714.        Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
  715.        SetSocketOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
  716.        Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
  717.        Sock2File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
  718.        Sock2Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
  719.        Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
  720.        SocketPair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
  721.        Str2UnixSockAddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
  722.  
  723. 14 The STRINGS unit.                                                              279
  724.   14.1 Functions and procedures. . . . . . . . . . . . . . . . . . . . . . . . . 279
  725.        StrAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
  726.        StrCat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
  727.        StrComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
  728.        StrCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
  729.        StrDispose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
  730.        StrECopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
  731.        StrEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
  732.        StrIComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
  733.        StrLCat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
  734.        StrLComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
  735.        StrLCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
  736.        StrLen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
  737.        StrLIComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
  738.        StrLower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
  739.        StrMove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
  740.        StrNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
  741.  
  742.  
  743.                                          15
  744.  
  745.  
  746.  
  747.                                                                          CONTENTS
  748.  
  749.  
  750.        StrPas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
  751.        StrPCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
  752.        StrPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
  753.        StrRScan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
  754.        StrScan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
  755.        StrUpper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
  756.  
  757. 15 The SYSUTILS unit.                                                             290
  758.   15.1 Constants and types . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
  759.   15.2 Date and time functions . . . . . . . . . . . . . . . . . . . . . . . . . 293
  760.        Date and time formatting characters . . . . . . . . . . . . . . . . . . 293
  761.        TDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
  762.        Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
  763.        DateTimeToFileDate . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
  764.        DateTimeToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
  765.        DateTimeToString . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
  766.        DateTimeToSystemTime . . . . . . . . . . . . . . . . . . . . . . . . . 296
  767.        DateTimeToTimeStamp . . . . . . . . . . . . . . . . . . . . . . . . . 297
  768.        DateToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
  769.        DayOfWeek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
  770.        DecodeDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
  771.        DecodeTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
  772.        EncodeDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
  773.        EncodeTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
  774.        FileDateToDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
  775.        FormatDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
  776.        IncMonth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
  777.        IsLeapYear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
  778.        MSecsToTimeStamp . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
  779.        Now . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
  780.        StrToDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
  781.        StrToDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
  782.        StrToTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
  783.        SystemTimeToDateTime . . . . . . . . . . . . . . . . . . . . . . . . . 305
  784.        Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
  785.        TimeStampToDateTime . . . . . . . . . . . . . . . . . . . . . . . . . 306
  786.        TimeStampToMSecs . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
  787.        TimeToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
  788.   15.3 Disk functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
  789.        AddDisk (Linux only) . . . . . . . . . . . . . . . . . . . . . . . . . . 307
  790.  
  791.  
  792.                                          16
  793.  
  794.  
  795.  
  796.                                                                       CONTENTS
  797.  
  798.  
  799.      CreateDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
  800.      DiskFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
  801.      DiskSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
  802.      GetCurrentDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
  803.      RemoveDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
  804.      SetCurrentDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
  805. 15.4 File handling functions . . . . . . . . . . . . . . . . . . . . . . . . . . 311
  806.      ChangeFileExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
  807.      DeleteFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
  808.      DoDirSeparators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
  809.      ExpandFileName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
  810.      ExpandUNCFileName . . . . . . . . . . . . . . . . . . . . . . . . . . 313
  811.      ExtractFileDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
  812.      ExtractFileDrive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
  813.      ExtractFileExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
  814.      ExtractFileName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
  815.      ExtractFilePath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
  816.      ExtractRelativePath . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
  817.      FileAge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
  818.      FileClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
  819.      FileCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
  820.      FileExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
  821.      FileGetAttr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
  822.      FileGetDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
  823.      FileOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
  824.      FileRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
  825.      FileSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
  826.      FileSeek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
  827.      FileSetAttr (Not on Linux) . . . . . . . . . . . . . . . . . . . . . . . 321
  828.      FileSetDate (Not on Linux) . . . . . . . . . . . . . . . . . . . . . . . 321
  829.      FileTruncate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
  830.      FileWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
  831.      FindClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
  832.      FindFirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
  833.      FindNext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
  834.      GetDirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
  835.      RenameFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
  836.      SetDirSeparators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
  837. 15.5 PChar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
  838.      Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
  839.  
  840.  
  841.                                        17
  842.  
  843.  
  844.  
  845.                                                                        CONTENTS
  846.  
  847.  
  848.      StrAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
  849.      StrBufSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
  850.      StrDispose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
  851.      StrPCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
  852.      StrPLCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
  853.      StrPas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
  854. 15.6 String handling functions . . . . . . . . . . . . . . . . . . . . . . . . 328
  855.      AdjustLineBreaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
  856.      AnsiCompareStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
  857.      AnsiCompareText . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
  858.      AnsiExtractQuotedStr . . . . . . . . . . . . . . . . . . . . . . . . . . 330
  859.      AnsiLastChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
  860.      AnsiLowerCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
  861.      AnsiQuotedStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
  862.      AnsiStrComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
  863.      AnsiStrIComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
  864.      AnsiStrLastChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
  865.      AnsiStrLComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
  866.      AnsiStrLIComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
  867.      AnsiStrLower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
  868.      AnsiStrUpper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
  869.      AnsiUpperCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
  870.      AppendStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
  871.      AssignStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
  872.      BCDToInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
  873.      CompareMem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
  874.      CompareStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
  875.      CompareText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
  876.      DisposeStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
  877.      FloatToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
  878.      FloatToStrF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
  879.      FloatToText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
  880.      FmtStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
  881.      Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
  882.      FormatBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
  883.      IntToHex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
  884.      IntToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
  885.      IsValidIdent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
  886.      LeftStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
  887.      LoadStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
  888.  
  889.  
  890.                                        18
  891.  
  892.  
  893.  
  894.                                                                  CONTENTS
  895.  
  896.  
  897. LowerCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
  898. NewStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
  899. QuotedStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
  900. RightStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
  901. StrFmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
  902. StrLFmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
  903. StrToInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
  904. StrToIntDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
  905. Trim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
  906. TrimLeft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
  907. TrimRight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
  908. UpperCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.                                   19
  947.  
  948.  
  949.  
  950.                                                                        CONTENTS
  951.  
  952.  
  953. About this guide
  954.  
  955. This document describes all constants, types, variables, functions and procedures
  956. as they are declared in the units that come standard with Free Pascal.
  957. Throughout this document, we will refer to functions, types and variables with
  958. typewriter font. Functions and procedures gave their own subsections, and for
  959. each function or procedure we have the following topics:
  960.  
  961. Declaration The exact declaration of the function.
  962.  
  963. Description What does the procedure exactly do ?
  964.  
  965. Errors What errors can occur.
  966.  
  967. See Also Cross references to other related functions/commands.
  968.  
  969. The cross-references come in two flavors:
  970.  
  971.    * References to other functions in this manual. In the printed copy, a number
  972.      will appear after this reference. It refers to the page where this function is
  973.      explained. In the on-line help pages, this is a hyperlink, on which you can
  974.      click to jump to the declaration.
  975.  
  976.    * References to Unix manual pages. (For Linux related things only) they are
  977.      printed in typewriter font, and the number after it is the Unix manual
  978.      section.
  979.  
  980. The chapters are ordered alphabetically. The functions and procedures in most
  981. cases also, but don't count on it. Use the table of contents for quick lookup.
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.                                           20
  1008.  
  1009.  
  1010.  
  1011. Chapter 1
  1012.  
  1013. The CRT unit.
  1014.  
  1015. This chapter describes the CRT unit for Free Pascal, both under dos and linux.
  1016. The unit was first written for dos by Florian kl¿ampfl. The unit was ported to
  1017. linux by Mark May1, and enhanced by Micha¿el Van Canneyt and Peter Vreman.
  1018. It works on the linux console, and in xterm and rxvt windows under X-Windows.
  1019. The functionality for both is the same, except that under linux the use of an early
  1020. implementation (versions 0.9.1 an earlier of the compiler) the crt unit automatically
  1021. cleared the screen at program startup. This chapter is divided in two sections.
  1022.  
  1023.    * The first section lists the pre-defined constants, types and variables.
  1024.  
  1025.    * The second section describes the functions which appear in the interface part
  1026.       of the CRT unit.
  1027.  
  1028.  
  1029. 1.1 Types, Variables, Constants
  1030.  
  1031. Color definitions :
  1032.  
  1033.   Black = 0;
  1034.   Blue = 1;
  1035.   Green = 2;
  1036.   Cyan = 3;
  1037.   Red = 4;
  1038.   Magenta = 5;
  1039.   Brown = 6;
  1040.   LightGray = 7;
  1041.   DarkGray = 8;
  1042.   LightBlue = 9;
  1043.   LightGreen = 10;
  1044.   LightCyan = 11;
  1045.   LightRed = 12;
  1046.   LightMagenta = 13;
  1047.   Yellow = 14;
  1048.   White = 15;
  1049.   Blink = 128;
  1050.  
  1051. Miscellaneous constants
  1052.   1Current e-mail address mmay@dnaco.net
  1053.  
  1054.  
  1055.                                             21
  1056.  
  1057.  
  1058.  
  1059.                                                       1.2. PROCEDURES AND FUNCTIONS
  1060.  
  1061.  
  1062.               TextAttr: Byte = $07;
  1063.               TextChar: Char = ' ';
  1064.               CheckBreak: Boolean = True;
  1065.               CheckEOF: Boolean = False;
  1066.               CheckSnow: Boolean = False;
  1067.               DirectVideo: Boolean = False;
  1068.               LastMode: Word = 3;
  1069.               WindMin: Word = $0;
  1070.               WindMax: Word = $184f;
  1071.               ScreenWidth = 80;
  1072.               ScreenHeight = 25;
  1073.  
  1074.            Some variables for compatibility with Turbo Pascal. However, they're not used by
  1075.            Free Pascal.
  1076.  
  1077.            varcheckbreak : boolean;
  1078.               checkeof : boolean;
  1079.               checksnow : boolean;
  1080.  
  1081.            The following constants define screen modes on a dos system:
  1082.  
  1083.            Const
  1084.               bw40 = 0;
  1085.               co40 = 1;
  1086.               bw80 = 2;
  1087.               co80 = 3;
  1088.               mono = 7;
  1089.  
  1090.            The TextAttr variable controls the attributes with which characters are written to
  1091.            screen.
  1092.  
  1093.            var TextAttr : byte;
  1094.  
  1095.            The DirectVideo variable controls the writing to the screen. If it is True, the the
  1096.            cursor is set via direct port access. If False, then the BIOS is used. This is defined
  1097.            under dos only.
  1098.  
  1099.            var DirectVideo : Boolean;
  1100.  
  1101.            The Lastmode variable tells you which mode was last selected for the screen. It is
  1102.            defined on dos only.
  1103.  
  1104.            var lastmode : Word;
  1105.  
  1106.  
  1107.            1.2 Procedures and Functions
  1108.  
  1109.            AssignCrt
  1110. Declaration: Procedure AssignCrt (Var F: Text);
  1111.  
  1112. Description: Assigns a file F to the console. Everything written to the file F goes to the console
  1113.            instead. If the console contains a window, everything is written to the window
  1114.            instead.
  1115.  
  1116.                                                      22
  1117.  
  1118.  
  1119.  
  1120.                                                         1.2. PROCEDURES AND FUNCTIONS
  1121.  
  1122.  
  1123.      Errors: None.
  1124.  
  1125.    See also: Window (31)
  1126.  
  1127.            Program Example1 ;
  1128.             uses Crt ;
  1129.  
  1130.             { Program to demonstrate the AssignCrt f u n c t i o n . }
  1131.  
  1132.             varF : Text ;
  1133.             begin
  1134.                AssignCrt ( F ) ;
  1135.               Rewrite ( F ) ; { Don ' t f o r g e t to open f o r output ! }
  1136.               WriteLn ( F, ' This i s w r i t t e n to the Assigned F i l e ' ) ;
  1137.                Close ( F ) ;
  1138.            end .
  1139.  
  1140.  
  1141.            BigCursor
  1142. Declaration: Procedure BigCursor ;
  1143.  
  1144. Description: Makes the cursor a big rectangle. Not implemented on linux.
  1145.  
  1146.      Errors: None.
  1147.  
  1148.    See also: CursorOn (24), CursorO  (24)
  1149.  
  1150.  
  1151.            ClrEol
  1152. Declaration: Procedure ClrEol ;
  1153.  
  1154. Description: ClrEol clears the current line, starting from the cursor position, to the end of the
  1155.            window. The cursor doesn't move
  1156.  
  1157.      Errors: None.
  1158.  
  1159.    See also: DelLine (25), InsLine (26), ClrScr (24)
  1160.  
  1161.            Program Example9 ;
  1162.             uses Crt ;
  1163.  
  1164.             { Program to demonstrate the C l r E o l f u n c t i o n . }
  1165.  
  1166.             begin
  1167.               Write ( ' This l i n e w i l l be c l e a r e d from the ' ,
  1168.                         ' c u r s o r p o s t i o n u n t i l the r i g h t of the screen ' ) ;
  1169.               GotoXY(27, WhereY) ;
  1170.               ReadKey ;
  1171.                ClrEol ;
  1172.               WriteLn ;
  1173.            end .
  1174.  
  1175.  
  1176.  
  1177.  
  1178.                                                         23
  1179.  
  1180.  
  1181.  
  1182.                                                      1.2. PROCEDURES AND FUNCTIONS
  1183.  
  1184.  
  1185.            ClrScr
  1186. Declaration: Procedure ClrScr ;
  1187.  
  1188. Description: ClrScr clears the current window (using the current colors), and sets the cursor in
  1189.            the top left corner of the current window.
  1190.  
  1191.      Errors: None.
  1192.  
  1193.    See also: Window (31)
  1194.  
  1195.            Program Example8 ;
  1196.            uses Crt ;
  1197.  
  1198.            { Program to demonstrate the Clr Scr f u n c t i o n . }
  1199.  
  1200.            begin
  1201.               Writeln ( ' Press any key to c l e a r the screen ' ) ;
  1202.               ReadKey ;
  1203.               ClrScr ;
  1204.               Writeln ( ' Have fun with the c l e a r e d screen ' ) ;
  1205.            end .
  1206.  
  1207.  
  1208.            CursorO 
  1209. Declaration: Procedure CursorOff ;
  1210.  
  1211. Description: Switches the cursor o  (i.e. the cursor is no longer visible). Not implemented on
  1212.            linux.
  1213.  
  1214.      Errors: None.
  1215.  
  1216.    See also: CursorOn (24), BigCursor (23)
  1217.  
  1218.  
  1219.            CursorOn
  1220. Declaration: Procedure CursorOn ;
  1221.  
  1222. Description: Switches the cursor on. Not implemented on linux.
  1223.  
  1224.      Errors: None.
  1225.  
  1226.    See also: BigCursor (23), CursorO  (24)
  1227.  
  1228.  
  1229.            Delay
  1230. Declaration: Procedure Delay (DTime: Word);
  1231.  
  1232. Description: Delay waits a specified number of milliseconds. The number of specified seconds
  1233.            is an approximation, and may be o  a lot, if system load is high.
  1234.  
  1235.      Errors: None
  1236.  
  1237.    See also: Sound (29), NoSound (28)
  1238.  
  1239.  
  1240.  
  1241.  
  1242.                                                     24
  1243.  
  1244.  
  1245.  
  1246.                                                            1.2. PROCEDURES AND FUNCTIONS
  1247.  
  1248.  
  1249.             Program Example15 ;
  1250.             uses Crt ;
  1251.  
  1252.             { Program to demonstrate the Delay f u n c t i o n . }
  1253.             vari : longint ;
  1254.             begin
  1255.                WriteLn ( ' Counting Down' ) ;
  1256.                for i :=10 downto 1 do
  1257.                 begin
  1258.                       WriteLn ( i ) ;
  1259.                       Delay ( 1 0 0 0 ) ; {Wait one second }
  1260.                 end ;
  1261.                WriteLn ( 'BOOM! ! ! ' ) ;
  1262.             end .
  1263.  
  1264.  
  1265.            DelLine
  1266. Declaration: Procedure DelLine ;
  1267.  
  1268. Description: DelLine removes the current line. Lines following the current line are scrolled 1
  1269.            line up, and an empty line is inserted at the bottom of the current window. The
  1270.            cursor doesn't move.
  1271.  
  1272.      Errors: None.
  1273.  
  1274.    See also: ClrEol (23), InsLine (26), ClrScr (24)
  1275.  
  1276.             Program Example10 ;
  1277.             uses Crt ;
  1278.  
  1279.             { Program to demonstrate the I n s L i n e f u n c t i o n . }
  1280.  
  1281.             begin
  1282.                ClrScr ;
  1283.                WriteLn ;
  1284.                WriteLn ( ' Line 1' ) ;
  1285.                WriteLn ( ' Line 2' ) ;
  1286.                WriteLn ( ' Line 2' ) ;
  1287.                WriteLn ( ' Line 3' ) ;
  1288.                WriteLn ;
  1289.                WriteLn ( ' Oops , Line 2 i s l i s t e d twice , ' ,
  1290.                              ' l e t ' ' s d e l e t e the l i n e at the c u r s o r p o s t i o n ' ) ;
  1291.               GotoXY ( 1 , 3 ) ;
  1292.               ReadKey ;
  1293.                DelLine ;
  1294.               GotoXY( 1 , 1 0 ) ;
  1295.             end .
  1296.  
  1297.  
  1298.            GotoXY
  1299. Declaration: Procedure GotoXY (X: Byte; Y: Byte);
  1300.  
  1301.  
  1302.  
  1303.                                                           25
  1304.  
  1305.  
  1306.  
  1307.                                                        1.2. PROCEDURES AND FUNCTIONS
  1308.  
  1309.  
  1310. Description: Positions the cursor at (X,Y), X in horizontal, Y in vertical direction relative to the
  1311.             origin of the current window. The origin is located at (1,1), the upper-left corner
  1312.             of the window.
  1313.  
  1314.      Errors: None.
  1315.  
  1316.    See also: WhereX (30), WhereY (31), Window (31)
  1317.  
  1318.             Program Example6 ;
  1319.             uses Crt ;
  1320.  
  1321.             { Program to demonstrate the GotoXY f u n c t i o n . }
  1322.  
  1323.             begin
  1324.                ClrScr ;
  1325.                GotoXY( 1 0 , 1 0 ) ;
  1326.                Write ( ' 1 0 , 1 0 ' ) ;
  1327.                GotoXY( 7 0 , 2 0 ) ;
  1328.                Write ( ' 7 0 , 2 0 ' ) ;
  1329.                GotoXY( 1 , 2 2 ) ;
  1330.             end .
  1331.  
  1332.  
  1333.             HighVideo
  1334. Declaration: Procedure HighVideo ;
  1335.  
  1336. Description: HighVideo switches the output to highlighted text. (It sets the high intensity bit
  1337.             of the video attribute)
  1338.  
  1339.      Errors: None.
  1340.  
  1341.    See also: TextColor (30), TextBackground (29), LowVideo (27), NormVideo (28)
  1342.  
  1343.             Program Example14 ;
  1344.             uses Crt ;
  1345.  
  1346.             { Program to demonstrate the LowVideo , HighVideo , NormVideo f u n c t i o n s . }
  1347.  
  1348.             begin
  1349.                LowVideo ;
  1350.                WriteLn ( ' This i s w r i t t e n with LowVideo ' ) ;
  1351.                HighVideo ;
  1352.                WriteLn ( ' This i s w r i t t e n with HighVideo ' ) ;
  1353.                NormVideo ;
  1354.                WriteLn ( ' This i s w r i t t e n with NormVideo ' ) ;
  1355.             end .
  1356.  
  1357.  
  1358.             InsLine
  1359. Declaration: Procedure InsLine ;
  1360.  
  1361. Description: InsLine inserts an empty line at the current cursor position. Lines following the
  1362.             current line are scrolled 1 line down, causing the last line to disappear from the
  1363.             window. The cursor doesn't move.
  1364.  
  1365.  
  1366.                                                       26
  1367.  
  1368.  
  1369.  
  1370.                                                        1.2. PROCEDURES AND FUNCTIONS
  1371.  
  1372.  
  1373.      Errors: None.
  1374.    See also: ClrEol (23), DelLine (25), ClrScr (24)
  1375.  
  1376.            Program Example10 ;
  1377.             uses Crt ;
  1378.  
  1379.             { Program to demonstrate the I n s L i n e f u n c t i o n . }
  1380.  
  1381.             begin
  1382.                ClrScr ;
  1383.               WriteLn ;
  1384.               WriteLn ( ' Line 1' ) ;
  1385.               WriteLn ( ' Line 3' ) ;
  1386.               WriteLn ;
  1387.               WriteLn ( ' Oops , f o r g o t Line 2, l e t ' ' s i n s e r t at the c u r s o r p o s t i o n ' ) ;
  1388.               GotoXY ( 1 , 3 ) ;
  1389.               ReadKey ;
  1390.                I n s L i n e ;
  1391.               Write ( ' Line 2' ) ;
  1392.               GotoXY( 1 , 1 0 ) ;
  1393.            end .
  1394.  
  1395.  
  1396.            KeyPressed
  1397. Declaration: Function KeyPressed : Boolean;
  1398. Description: The Keypressed function scans the keyboard bu er and sees if a key has been
  1399.            pressed. If this is the case, True is returned. If not, False is returned. The Shift,
  1400.            Alt, Ctrl keys are not reported. The key is not removed from the bu er, and can
  1401.            hence still be read after the KeyPressed function has been called.
  1402.      Errors: None.
  1403.    See also: ReadKey (28)
  1404.  
  1405.            Program Example2 ;
  1406.             uses Crt ;
  1407.  
  1408.             { Program to demonstrate the KeyPressed f u n c t i o n . }
  1409.  
  1410.             begin
  1411.               WriteLn ( ' Waiting u n t i l a key i s p r es s ed ' ) ;
  1412.               repeat
  1413.                u n t i l KeyPressed ;
  1414.              { The key i s not Read ,
  1415.                 so i t should a l s o be outputted at the commandline }
  1416.            end .
  1417.  
  1418.  
  1419.            LowVideo
  1420. Declaration: Procedure LowVideo ;
  1421. Description: LowVideo switches the output to non-highlighted text. (It clears the high intensity
  1422.            bit of the video attribute)
  1423.  
  1424.                                                        27
  1425.  
  1426.  
  1427.  
  1428.                                                     1.2. PROCEDURES AND FUNCTIONS
  1429.  
  1430.  
  1431.      Errors: None.
  1432.  
  1433.    See also: TextColor (30), TextBackground (29), HighVideo (26), NormVideo (28)
  1434.  
  1435.            For an example, see HighVideo (26)
  1436.  
  1437.  
  1438.            NormVideo
  1439. Declaration: Procedure NormVideo ;
  1440.  
  1441. Description: NormVideo switches the output to the defaults, read at startup. (The defaults are
  1442.            read from the cursor position at startup)
  1443.  
  1444.      Errors: None.
  1445.  
  1446.    See also: TextColor (30), TextBackground (29), LowVideo (27), HighVideo (26)
  1447.  
  1448.            For an example, see HighVideo (26)
  1449.  
  1450.  
  1451.            NoSound
  1452. Declaration: Procedure NoSound ;
  1453.  
  1454. Description: Stops the speaker sound. This is not supported in linux
  1455.  
  1456.      Errors: None.
  1457.  
  1458.    See also: Sound (29)
  1459.  
  1460.            Program Example16 ;
  1461.            uses Crt ;
  1462.  
  1463.            { Program to demonstrate the Sound and NoSound f u n c t i o n . }
  1464.  
  1465.            vari : longint ;
  1466.            begin
  1467.               WriteLn ( ' You w i l l hear some tones from your speaker ' ) ;
  1468.               while ( i <15000) do
  1469.                begin
  1470.                       inc ( i , 5 0 0 ) ;
  1471.                       Sound ( i ) ;
  1472.                       Delay ( 1 0 0 ) ;
  1473.                end ;
  1474.               WriteLn ( ' Quiet now ! ' ) ;
  1475.               NoSound ; { Stop n o i s e }
  1476.            end .
  1477.  
  1478.  
  1479.            ReadKey
  1480. Declaration: Function ReadKey : Char;
  1481.  
  1482.  
  1483.  
  1484.  
  1485.                                                    28
  1486.  
  1487.  
  1488.  
  1489.                                                       1.2. PROCEDURES AND FUNCTIONS
  1490.  
  1491.  
  1492. Description: The ReadKey function reads 1 key from the keyboard bu er, and returns this. If
  1493.            an extended or function key has been pressed, then the zero ASCII code is returned.
  1494.            You can then read the scan code of the key with a second ReadKey call. Remark.
  1495.            Key mappings under Linux can cause the wrong key to be reported by ReadKey,
  1496.            so caution is needed when using ReadKey.
  1497.  
  1498.      Errors: None.
  1499.  
  1500.   See also: KeyPressed (27)
  1501.  
  1502.            Program Example3 ;
  1503.            uses Crt ;
  1504.  
  1505.            { Program to demonstrate the ReadKey f u n c t i o n . }
  1506.  
  1507.            varch : char ;
  1508.            begin
  1509.               writeln ( ' Press Left / Right , Esc=Quit ' ) ;
  1510.               repeat
  1511.                     ch :=ReadKey ;
  1512.                     case ch of
  1513.                       #0 : begin
  1514.                                ch :=ReadKey ; {Read ScanCode }
  1515.                                case ch of
  1516.                                  #75 : WriteLn ( ' Left ' ) ;
  1517.                                  #77 : WriteLn ( ' Right ' ) ;
  1518.                                end ;
  1519.                              end ;
  1520.                     #27 : WriteLn ( ' ESC' ) ;
  1521.                     end ;
  1522.               u n t i l ch=#27 { Esc }
  1523.            end .
  1524.  
  1525.  
  1526.            Sound
  1527. Declaration: Procedure Sound (hz : word);
  1528.  
  1529. Description: Sounds the speaker at a frequency of hz. This is not supported in linux
  1530.  
  1531.      Errors: None.
  1532.  
  1533.   See also: NoSound (28)
  1534.  
  1535.  
  1536.            TextBackground
  1537. Declaration: Procedure TextBackground (CL: Byte);
  1538.  
  1539. Description: TextBackground sets the background color to CL. CL can be one of the predefined
  1540.            color constants.
  1541.  
  1542.      Errors: None.
  1543.  
  1544.   See also: TextColor (30), HighVideo (26), LowVideo (27), NormVideo (28)
  1545.  
  1546.  
  1547.  
  1548.                                                       29
  1549.  
  1550.  
  1551.  
  1552.                                                        1.2. PROCEDURES AND FUNCTIONS
  1553.  
  1554.  
  1555.            Program Example13 ;
  1556.            uses Crt ;
  1557.  
  1558.            { Program to demonstrate the TextBackground f u n c t i o n . }
  1559.  
  1560.            begin
  1561.               TextColor ( White ) ;
  1562.               WriteLn ( ' This i s w r i t t e n in with the d e f a u l t background c o l o r ' ) ;
  1563.               TextBackground ( Green ) ;
  1564.               WriteLn ( ' This i s w r i t t e n in with a Green background ' ) ;
  1565.               TextBackground ( Brown ) ;
  1566.               WriteLn ( ' This i s w r i t t e n in with a Brown background ' ) ;
  1567.               TextBackground ( Black ) ;
  1568.               WriteLn ( ' Back with a black background ' ) ;
  1569.            end .
  1570.  
  1571.  
  1572.            TextColor
  1573. Declaration: Procedure TextColor (CL: Byte);
  1574.  
  1575. Description: TextColor sets the foreground color to CL. CL can be one of the predefined color
  1576.            constants.
  1577.  
  1578.      Errors: None.
  1579.  
  1580.    See also: TextBackground (29), HighVideo (26), LowVideo (27), NormVideo (28)
  1581.  
  1582.            Program Example12 ;
  1583.            uses Crt ;
  1584.  
  1585.            { Program to demonstrate the TextColor f u n c t i o n . }
  1586.  
  1587.            begin
  1588.               WriteLn ( ' This i s w r i t t e n in the d e f a u l t c o l o r ' ) ;
  1589.               TextColor ( Red ) ;
  1590.               WriteLn ( ' This i s w r i t t e n in Red ' ) ;
  1591.               TextColor ( White ) ;
  1592.               WriteLn ( ' This i s w r i t t e n in White ' ) ;
  1593.               TextColor ( LightBlue ) ;
  1594.               WriteLn ( ' This i s w r i t t e n in Light Blue ' ) ;
  1595.            end .
  1596.  
  1597.  
  1598.            WhereX
  1599. Declaration: Function WhereX : Byte;
  1600.  
  1601. Description: WhereX returns the current X-coordinate of the cursor, relative to the current
  1602.            window. The origin is (1,1), in the upper-left corner of the window.
  1603.  
  1604.      Errors: None.
  1605.  
  1606.    See also: GotoXY (25), WhereY (31), Window (31)
  1607.  
  1608.  
  1609.  
  1610.  
  1611.                                                       30
  1612.  
  1613.  
  1614.  
  1615.                                                         1.2. PROCEDURES AND FUNCTIONS
  1616.  
  1617.  
  1618.            Program Example7 ;
  1619.            uses Crt ;
  1620.  
  1621.            { Program to demonstrate the WhereX and WhereY f u n c t i o n s . }
  1622.  
  1623.            begin
  1624.               Writeln ( ' Cursor p o s t i o n : X=' , WhereX, ' Y=' , WhereY) ;
  1625.            end .
  1626.  
  1627.  
  1628.            WhereY
  1629. Declaration: Function WhereY : Byte;
  1630.  
  1631. Description: WhereY returns the current Y-coordinate of the cursor, relative to the current
  1632.            window. The origin is (1,1), in the upper-left corner of the window.
  1633.  
  1634.      Errors: None.
  1635.  
  1636.    See also: GotoXY (25), WhereX (30), Window (31)
  1637.  
  1638.            Program Example7 ;
  1639.            uses Crt ;
  1640.  
  1641.            { Program to demonstrate the WhereX and WhereY f u n c t i o n s . }
  1642.  
  1643.            begin
  1644.               Writeln ( ' Cursor p o s t i o n : X=' , WhereX, ' Y=' , WhereY) ;
  1645.            end .
  1646.  
  1647.  
  1648.            Window
  1649. Declaration: Procedure Window (X1, Y1, X2, Y2: Byte);
  1650.  
  1651. Description: Window creates a window on the screen, to which output will be sent. (X1,Y1) are
  1652.            the coordinates of the upper left corner of the window, (X2,Y2) are the coordinates
  1653.            of the bottom right corner of the window. These coordinates are relative to the
  1654.            entire screen, with the top left corner equal to (1,1) Further coordinate operations,
  1655.            except for the next Window call, are relative to the window's top left corner.
  1656.  
  1657.      Errors: None.
  1658.  
  1659.    See also: GotoXY (25), WhereX (30), WhereY (31), ClrScr (24)
  1660.  
  1661.            Program Example5 ;
  1662.            uses Crt ;
  1663.  
  1664.            { Program to demonstrate the Window f u n c t i o n . }
  1665.  
  1666.            begin
  1667.               ClrScr ;
  1668.               WriteLn ( ' Creating a window from 30,10 to 5 0 , 2 0 ' ) ;
  1669.               Window ( 3 0 , 1 0 , 5 0 , 2 0 ) ;
  1670.               WriteLn ( ' We are now w r i t i n g in t h i s small window we j u s t cr eat ed , we ' +
  1671.                             ' can ' ' t get o u t s i d e i t when w r i t i n g long l i n e s l i k e t h i s one ' ) ;
  1672.  
  1673.  
  1674.                                                         31
  1675.  
  1676.  
  1677.  
  1678.                                           1.2. PROCEDURES AND FUNCTIONS
  1679.  
  1680.  
  1681.   Write ( ' Press any key to c l e a r the window ' ) ;
  1682.   ReadKey ;
  1683.   ClrScr ;
  1684.   Write ( ' The window i s c l e a r e d , p r e s s any key to r e s t o r e to f u l l s c r e e n ' ) ;
  1685.   ReadKey ;
  1686. { F u l l Screen i s 80 x25 }
  1687.   Window ( 1 , 1 , 8 0 , 2 5 ) ;
  1688.   Clrscr ;
  1689.   Writeln ( ' Back in F u l l Screen ' ) ;
  1690. end .
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.                                           32
  1734.  
  1735.  
  1736.  
  1737. Chapter 2
  1738.  
  1739. The DOS unit.
  1740.  
  1741. This chapter describes the DOS unit for Free pascal, both under dos and linux.
  1742. The unit was first written for dos by Florian kl¿ampfl. The unit was ported to
  1743. linux by Mark May1, and enhanced by Micha¿el Van Canneyt. Under linux, some
  1744. of the functionality is lost, as it is either impossible or meaningless to implement
  1745. it. Other than that, the functionality for both operating systems is the same. This
  1746. chapter is divided in two sections.
  1747.  
  1748.    * The first section lists the pre-defined constants, types and variables.
  1749.    * The second section describes the functions which appear in the interface part
  1750.      of the DOS unit.
  1751.  
  1752. 2.1 Types, Variables, Constants
  1753.  
  1754. Constants
  1755. The DOS unit implements the following constants:
  1756.  
  1757.   {Bitmasks for CPU Flags}
  1758.   fcarry =        $0001;
  1759.   fparity =       $0004;
  1760.   fauxiliary = $0010;
  1761.   fzero =         $0040;
  1762.   fsign =         $0080;
  1763.   foverflow = $0800;
  1764.   {Bitmasks for file attribute}
  1765.   readonly =      $01;
  1766.   hidden =        $02;
  1767.   sysfile =       $04;
  1768.   volumeid =      $08;
  1769.   directory = $10;
  1770.   archive =       $20;
  1771.   anyfile =       $3F;
  1772.   fmclosed =      $D7B0;
  1773.   fminput =       $D7B1;
  1774.   fmoutput =      $D7B2;
  1775.   fminout =       $D7B3;
  1776.   1Current e-mail address mmay@dnaco.net
  1777.  
  1778.  
  1779.                                             33
  1780.  
  1781.  
  1782.  
  1783.                                         2.1. TYPES, VARIABLES, CONSTANTS
  1784.  
  1785.  
  1786. Types
  1787. The following string types are defined for easy handling of filenames :
  1788.  
  1789.   ComStr = String[127]; { For command-lines }
  1790.   PathStr = String[79]; { For full path for file names }
  1791.   DirStr = String[67]; { For Directory and (DOS) drive string }
  1792.   NameStr = String[8];           { For Name of file }
  1793.   ExtStr = String[4];            { For Extension of file }
  1794.  
  1795. Under linux, these strings all have length 255.
  1796.  
  1797. {$PACKRECORDS 1}
  1798.   SearchRec = Record
  1799.         Fill : array[1..21] of byte;
  1800.         { Fill replaced with declarations below, for Linux}
  1801.         Attr : Byte; {attribute of found file}
  1802.         Time : LongInt; {last modify date of found file}
  1803.         Size : LongInt; {file size of found file}
  1804.         Reserved : Word; {future use}
  1805.         Name : String[255]; {name of found file}
  1806.         SearchSpec: String[255]; {search pattern}
  1807.         NamePos: Word; {end of path, start of name position}
  1808.         End;
  1809.  
  1810. Under linux, the Fill array is replaced with the following:
  1811.  
  1812.         SearchNum: LongInt; {to track which search this is}
  1813.         SearchPos: LongInt; {directory position}
  1814.         DirPtr: LongInt; {directory pointer for reading directory}
  1815.         SearchType: Byte; {0=normal, 1=open will close}
  1816.         SearchAttr: Byte; {attribute we are searching for}
  1817.         Fill: Array[1..07] of Byte; {future use}
  1818.  
  1819. This is because the searching meachanism on Unix systems is substantially di erent
  1820. from dos's, and the calls have to be mimicked.
  1821.  
  1822. const
  1823.   filerecnamelength = 255;
  1824. type
  1825.   FileRec = Packed Record
  1826.         Handle,
  1827.         Mode,
  1828.         RecSize    : longint;
  1829.         _private : array[1..32] of byte;
  1830.         UserData : array[1..16] of byte;
  1831.         name       : array[0..filerecnamelength] of char;
  1832.   End;
  1833.  
  1834. FileRec is used for internal representation of typed and untyped files. Text files
  1835. are handled by the following types :
  1836.  
  1837. const
  1838.   TextRecNameLength = 256;
  1839.   TextRecBufSize         = 256;
  1840.  
  1841.                                          34
  1842.  
  1843.  
  1844.  
  1845.                                            2.1. TYPES, VARIABLES, CONSTANTS
  1846.  
  1847.  
  1848. type
  1849.   TextBuf = array[0..TextRecBufSize-1] of char;
  1850.   TextRec = Packed Record
  1851.         Handle,
  1852.         Mode,
  1853.         bufsize,
  1854.         _private,
  1855.         bufpos,
  1856.         bufend          : longint;
  1857.         bufptr          : ^textbuf;
  1858.         openfunc,
  1859.         inoutfunc,
  1860.         flushfunc,
  1861.         closefunc : pointer;
  1862.         UserData : array[1..16] of byte;
  1863.         name            : array[0..textrecnamelength-1] of char;
  1864.         buffer          : textbuf;
  1865.   End;
  1866.  
  1867. Remark that this is not binary compatible with the Turbo Pascal definition of
  1868. TextRec, since the sizes of the di erent fields are di erent.
  1869.  
  1870.         Registers = record
  1871.           case i : integer of
  1872.                 0 : (ax,f1,bx,f2,cx,f3,dx,f4,bp,f5,si,
  1873.                         f51,di,f6,ds,f7,es,f8,flags,fs,gs : word);
  1874.                 1 : (al,ah,f9,f10,bl,bh,f11,f12,
  1875.                         cl,ch,f13,f14,dl,dh : byte);
  1876.                 2 : (eax, ebx, ecx, edx, ebp, esi, edi : longint);
  1877.                 End;
  1878.  
  1879. The registers type is used in the MSDos call.
  1880.  
  1881.   DateTime = record
  1882.         Year: Word;
  1883.         Month: Word;
  1884.         Day: Word;
  1885.         Hour: Word;
  1886.         Min: Word;
  1887.         Sec: word;
  1888.         End;
  1889.  
  1890. The DateTime type is used in PackTime (47) and UnPackTime (49) for setting/reading
  1891. file times with GetFTime (44) and SetFTime (48).
  1892.  
  1893.  
  1894. Variables
  1895.         DosError : integer;
  1896.  
  1897. The DosError variable is used by the procedures in the dos unit to report errors.
  1898. It can have the following values :
  1899.  
  1900.  
  1901.  
  1902.                                             35
  1903.  
  1904.  
  1905.  
  1906.                                                         2.2. FUNCTIONS AND PROCEDURES
  1907.  
  1908.  
  1909.                                             2    File not found.
  1910.                                             3    path not found.
  1911.                                             5    Access denied.
  1912.                                             6    Invalid handle.
  1913.                                             8    Not enough memory.
  1914.                                             10 Invalid environment.
  1915.                                             11 Invalid format.
  1916.                                             18 No more files.
  1917.  
  1918.            Other values are possible, but are not documented.
  1919.  
  1920.  
  1921.            2.2 Functions and Procedures
  1922.  
  1923.            AddDisk
  1924. Declaration: Procedure AddDisk (Const S : String);
  1925.  
  1926. Description: AddDisk adds a filename S to the internal list of disks. It is implemented for
  1927.            linux only. This list is used to determine which disks to use in the DiskFree (36)
  1928.            and DiskSize (37) calls. The DiskFree (36) and DiskSize (37) functions need a file
  1929.            on the specified drive, since this is required for the statfs system call. The names
  1930.            are added sequentially. The dos initialization code presets the first three disks to:
  1931.  
  1932.                *'.' for the current drive,
  1933.                *'/fd0/.' for the first floppy-drive.
  1934.                *'/fd1/.' for the second floppy-drive.
  1935.                *'/' for the first hard disk.
  1936.  
  1937.            The first call to AddDisk will therefore add a name for the second harddisk, The
  1938.            second call for the third drive, and so on until 23 drives have been added (corre-
  1939.            sponding to drives 'D:' to 'Z:')
  1940.  
  1941.     Errors: None
  1942.  
  1943.   See also: DiskFree (36), DiskSize (37)
  1944.  
  1945.  
  1946.            DiskFree
  1947. Declaration: Function DiskFree (Drive: byte) : longint;
  1948.  
  1949. Description: DiskFree returns the number of free bytes on a disk. The parameter Drive indi-
  1950.            cates which disk should be checked. This parameter is 1 for floppy a:, 2 for floppy
  1951.            b:, etc. A value of 0 returns the free space on the current drive. Typically, the free
  1952.            space is the size of a disk block, multiplied by the number of free blocks on the disk.
  1953.            For linux only:
  1954.            The diskfree and disksize functions need a file on the specified drive, since this
  1955.            is required for the statfs system call. These filenames are set in the initialization
  1956.            of the dos unit, and have been preset to :
  1957.  
  1958.                *'.' for the current drive,
  1959.                *'/fd0/.' for the first floppy-drive.
  1960.                *'/fd1/.' for the second floppy-drive.
  1961.                *'/' for the first hard disk.
  1962.  
  1963.                                                        36
  1964.  
  1965.  
  1966.  
  1967.                                                         2.2. FUNCTIONS AND PROCEDURES
  1968.  
  1969.  
  1970.            There is room for 1-26 drives. You can add a drive with the AddDisk (36) procedure.
  1971.            These settings can be coded in dos.pp, in the initialization part.
  1972.  
  1973.      Errors: -1 when a failure occurs, or an invalid drivenr is given.
  1974.  
  1975.    See also: DiskSize (37), AddDisk (36)
  1976.  
  1977.            Program Example6 ;
  1978.            uses Dos ;
  1979.  
  1980.            { Program to demonstrate the DiskSiz e and DiskFree f u n c t i o n . }
  1981.  
  1982.            begin
  1983.               WriteLn ( ' This p a r t i t i o n s i z e has ' , DiskSize ( 0 ) , ' bytes ' ) ;
  1984.               WriteLn ( ' C u r r e n t l y ' , DiskFree ( 0 ) , ' bytes are f r e e ' ) ;
  1985.            end .
  1986.  
  1987.  
  1988.            DiskSize
  1989. Declaration: Function DiskSize (Drive: byte) : longint;
  1990.  
  1991. Description: DiskSize returns the total size (in bytes) of a disk. The parameter Drive indicates
  1992.            which disk should be checked. This parameter is 1 for floppy a:, 2 for floppy b:,
  1993.            etc. A value of 0 returns the size of the current drive. For linux only:
  1994.            The diskfree and disksize functions need a file on the specified drive, since this
  1995.            is required for the statfs system call. These filenames are set in the initialization
  1996.            of the dos unit, and have been preset to :
  1997.  
  1998.                *'.' for the current drive,
  1999.                *'/fd0/.' for the first floppy-drive.
  2000.                *'/fd1/.' for the second floppy-drive.
  2001.                *'/' for the first hard disk.
  2002.  
  2003.            There is room for 1-26 drives. You can add a drive with the AddDisk (36) procedure.
  2004.            These settings can be coded in dos.pp, in the initialization part.
  2005.  
  2006.      Errors: -1 when a failure occurs, or an invalid drive number is given.
  2007.  
  2008.    See also: DiskFree (36), AddDisk (36)
  2009.  
  2010.            For an example, see DiskFree (36).
  2011.  
  2012.  
  2013.            DosExitCode
  2014. Declaration: Function DosExitCode : Word;
  2015.  
  2016. Description: DosExitCode contains (in the low byte) the exit-code of a program executed with
  2017.            the Exec call.
  2018.  
  2019.      Errors: None.
  2020.  
  2021.    See also: Exec (39)
  2022.  
  2023.  
  2024.  
  2025.  
  2026.                                                       37
  2027.  
  2028.  
  2029.  
  2030.                                                         2.2. FUNCTIONS AND PROCEDURES
  2031.  
  2032.  
  2033.                Program Example5 ;
  2034.                uses Dos ;
  2035.  
  2036.                { Program to demonstrate the Exec and DosExitCode f u n c t i o n . }
  2037.  
  2038.                begin
  2039.                {$IFDEF LINUX}
  2040.                  WriteLn ( ' Executing / bin / l s -la ' ) ;
  2041.                  Exec ( '/ bin / l s ' , '- la ' ) ;
  2042.                {$ELSE}
  2043.                  WriteLn ( ' Executing Dir ' ) ;
  2044.                  Exec ( GetEnv ( ' COMSPEC' ) , '/ C d i r ' ) ;
  2045.                {$ENDIF}
  2046.                  WriteLn ( ' Program r e t u r n e d with ExitCode ' , DosExitCode ) ;
  2047.                end .
  2048.  
  2049.  
  2050.            DosVersion
  2051. Declaration: Function DosVersion : Word;
  2052. Description: DosVersion returns the dos version number. On linux systems, it returns the
  2053.            Linux version (The first 2 numbers, e.g Linux version 2.1.76 will give you DosVersion
  2054.            2.1)
  2055.     Errors: None.
  2056.   See also:
  2057.                Program Example1 ;
  2058.                uses Dos ;
  2059.  
  2060.                { Program to demonstrate the DosVersion f u n c t i o n . }
  2061.  
  2062.                varOS          : st r in g [ 3 2 ] ;
  2063.                  Version : word ;
  2064.                begin
  2065.                {$IFDEF LINUX}
  2066.                  OS:= ' Linux ' ;
  2067.                {$ENDIF}
  2068.                {$IFDEF DOS}
  2069.                  OS:= ' Dos ' ;
  2070.                {$ENDIF}
  2071.                  Version := DosVersion ;
  2072.                  WriteLn ( ' Current ' , OS, ' v e r s i o n i s ' , Lo( Version ) , ' . ' , Hi ( Version ) ) ;
  2073.                end .
  2074.  
  2075.  
  2076.            EnvCount
  2077. Declaration: Function EnvCount : longint;
  2078. Description: EnvCount returns the number of environment variables.
  2079.     Errors: None.
  2080.   See also: EnvStr (39), Dos:GetEnv (43)
  2081.  
  2082.  
  2083.                                                         38
  2084.  
  2085.  
  2086.  
  2087.                                                           2.2. FUNCTIONS AND PROCEDURES
  2088.  
  2089.  
  2090.            EnvStr
  2091. Declaration: Function EnvStr (Index: integer) : string;
  2092.  
  2093. Description: EnvStr returns the Index-th Name=Value pair from the list of environment vari-
  2094.            ables. The index of the first pair is zero.
  2095.  
  2096.      Errors: The length is limited to 255 characters. This may cause problems under linux.
  2097.            The linux unit solves this problem.
  2098.  
  2099.    See also: EnvCount (38), Dos:GetEnv (43)
  2100.  
  2101.            Program Example13 ;
  2102.             uses Dos ;
  2103.  
  2104.             { Program to demonstrate the EnvCount and EnvStr f u n c t i o n . }
  2105.  
  2106.             vari : Longint ;
  2107.             begin
  2108.               WriteLn ( ' Current Environment i s : ' ) ;
  2109.                for i :=1 to EnvCount do
  2110.                 WriteLn ( EnvStr ( i ) ) ;
  2111.            end .
  2112.  
  2113.  
  2114.            Exec
  2115. Declaration: Procedure Exec (const Path: pathstr; const ComLine: comstr);
  2116.  
  2117. Description: Exec executes the program in Path, with the options given by ComLine. After the
  2118.            program has terminated, the procedure returns. The Exit value of the program can
  2119.            be consulted with the DosExitCode function.
  2120.  
  2121.      Errors: Errors are reported in DosError.
  2122.  
  2123.    See also: DosExitCode (37)
  2124.  
  2125.            For an example, see DosExitCode (37)
  2126.  
  2127.  
  2128.            FExpand
  2129. Declaration: Function FExpand (const path: pathstr) : pathstr;
  2130.  
  2131. Description: FExpand takes its argument and expands it to a complete filename, i.e. a filename
  2132.            starting from the root directory of the current drive, prepended with the drive-letter
  2133.            (under dos). The resulting name is converted to uppercase on dos systems. Under
  2134.            linux, the name is left as it is. (filenames are case sensitive under Unix)
  2135.  
  2136.      Errors: FSplit (42)
  2137.            Program Example5 ;
  2138.             uses Dos ;
  2139.  
  2140.             { Program to demonstrate the Exec and DosExitCode f u n c t i o n . }
  2141.  
  2142.             begin
  2143.  
  2144.                                                      39
  2145.  
  2146.  
  2147.  
  2148.                                                          2.2. FUNCTIONS AND PROCEDURES
  2149.  
  2150.  
  2151.                 {$IFDEF LINUX}
  2152.                   WriteLn ( ' Executing / bin / l s -la ' ) ;
  2153.                   Exec ( '/ bin / l s ' , '- la ' ) ;
  2154.                 {$ELSE}
  2155.                   WriteLn ( ' Executing Dir ' ) ;
  2156.                   Exec ( GetEnv ( ' COMSPEC' ) , '/ C d i r ' ) ;
  2157.                 {$ENDIF}
  2158.                   WriteLn ( ' Program r e t u r n e d with ExitCode ' , DosExitCode ) ;
  2159.                 end .
  2160.    See also:
  2161.  
  2162.  
  2163.            FindClose
  2164. Declaration: Procedure FindClose (Var F: SearchRec);
  2165.  
  2166. Description: linux only Under linux, the findfirst/findnext calls have to be mimicked.
  2167.            An internal table of file descriptors is kept. When using di erent searchrecs at
  2168.            the same time, the system may run out of file descriptors for directories. The
  2169.            linux implementation of the dos unit therefore keeps a table of open directories,
  2170.            and when the table is full, closes one of the directories, and reopens another. This
  2171.            system is adequate but slow if you use a lot of searchrecs. So, to speed up the
  2172.            findfirst/findnext system, the FindClose call was implemented. When you don't
  2173.            need a searchrec any more, you can tell this to the dos unit by issuing a FindClose
  2174.            call. The directory which is kept open for this searchrec is then closed, and the
  2175.            table slot freed. It is recommended to use the linux call Glob when looking for
  2176.            files.
  2177.  
  2178.      Errors: None.
  2179.  
  2180.    See also: Glob (167).
  2181.  
  2182.  
  2183.            FindFirst
  2184. Declaration: Procedure FindFirst (const Path: pathstr; Attr: word; var F: SearchRec);
  2185.  
  2186. Description: FindFirst searches the file specified in Path, checks the atrributes specified in
  2187.            Attr. It returns a SearchRec record for further searching in F. Path can contain
  2188.            the wildcard characters ? (matches any single character) and * (matches 0 ore
  2189.            more arbitrary characters). In this case FindFirst will return the first file which
  2190.            matches the specified criteria. If DosError is di erent from zero, no file(s) matching
  2191.            the criteria was(were) found.
  2192.  
  2193.      Errors: Errors are reported in DosError.
  2194.  
  2195.    See also: FindNext (41), FindClose (40)
  2196.  
  2197.                 Program Example7 ;
  2198.                 uses Dos ;
  2199.  
  2200.                 { Program to demonstrate the F i n d F i r s t and FindNext f u n c t i o n . }
  2201.  
  2202.                 varDir : SearchRec ;
  2203.                 begin
  2204.  
  2205.  
  2206.                                                          40
  2207.  
  2208.  
  2209.  
  2210.                                                          2.2. FUNCTIONS AND PROCEDURES
  2211.  
  2212.  
  2213.               FindFirst ( '   .   ' , $20 , Dir ) ;
  2214.               WriteLn ( ' FileName ' +Space ( 3 2 ) , ' F i l e S i z e ' : 9 ) ;
  2215.               while ( DosError =0) do
  2216.                 begin
  2217.                       Writeln ( Dir . Name+Space (40- Length ( Dir . Name) ) , Dir . Size : 9 ) ;
  2218.                       FindNext ( Dir ) ;
  2219.                 end ;
  2220.               FindClose ( Dir ) ;
  2221.            end .
  2222.  
  2223.  
  2224.            FindNext
  2225. Declaration: Procedure FindNext (var f: searchRec);
  2226.  
  2227. Description: FindNext takes as an argument a SearchRec from a previous FindNext call, or a
  2228.            FindFirst call, and tries to find another file which matches the criteria, specified
  2229.            in the FindFirst call. If DosError is di erent from zero, no more files matching
  2230.            the criteria were found.
  2231.  
  2232.      Errors: DosError is used to report errors.
  2233.  
  2234.    See also: FindFirst (40), FindClose (40)
  2235.  
  2236.            For an example, see FindFirst (40).
  2237.  
  2238.  
  2239.            FSearch
  2240. Declaration: Function FSearch (Path: pathstr; DirList: string) : pathstr;
  2241.  
  2242. Description: FSearch searches the file Path in all directories listed in DirList. The full name
  2243.            of the found file is returned. DirList must be a list of directories, separated by
  2244.            semi-colons (or colons under linux). When no file is found, an empty string is
  2245.            returned.
  2246.  
  2247.      Errors: None.
  2248.  
  2249.    See also: FExpand (39)
  2250.  
  2251.            Program Example10 ;
  2252.             uses Dos ;
  2253.  
  2254.             { Program to demonstrate the FSearch f u n c t i o n . }
  2255.  
  2256.             vars : string ;
  2257.             begin
  2258.               s := FSearch ( ParamStr ( 1 ) , GetEnv ( ' PATH' ) ) ;
  2259.                i f s=' ' then
  2260.                 WriteLn ( ParamStr ( 1 ) , ' not Found in PATH' )
  2261.               else
  2262.                 Writeln ( ParamStr ( 1 ) , ' Found in PATH at ' , s ) ;
  2263.            end .
  2264.  
  2265.  
  2266.  
  2267.  
  2268.                                                         41
  2269.  
  2270.  
  2271.  
  2272.                                                                2.2. FUNCTIONS AND PROCEDURES
  2273.  
  2274.  
  2275.            FSplit
  2276. Declaration: Procedure FSplit (path: pathstr;
  2277.            var dir: dirstr; var name: namestr; var ext: extstr);
  2278.  
  2279. Description: FSplit splits a full file name into 3 parts : A Path, a Name and an extension (in
  2280.            ext.) Under linux, the extension is taken to be all letters after the last dot (.).
  2281.  
  2282.      Errors: None.
  2283.  
  2284.    See also: FSearch (41)
  2285.  
  2286.            Program Example12 ;
  2287.            uses Dos ;
  2288.  
  2289.            { Program to demonstrate the F S p l i t f u n c t i o n . }
  2290.  
  2291.            varPath,Name, Ext : string ;
  2292.            begin
  2293.                  F S p l i t ( ParamStr ( 1 ) , Path , Name, Ext ) ;
  2294.                  WriteLn ( ' S p l i t t e d ' , ParamStr ( 1 ) , ' in : ' ) ;
  2295.                  WriteLn ( ' Path            : ' , Path ) ;
  2296.                  WriteLn ( ' Name            : ' , Name) ;
  2297.                  WriteLn ( ' Extension : ' , Ext ) ;
  2298.            end .
  2299.  
  2300.  
  2301.            GetCBreak
  2302. Declaration: Procedure GetCBreak (var breakvalue: boolean);
  2303.  
  2304. Description: GetCBreak gets the status of CTRL-Break checking under dos. When BreakValue
  2305.            is false, then dos only checks for the CTRL-Break key-press when I/O is per-
  2306.            formed. When it is set to True, then a check is done at every system call.
  2307.  
  2308.      Errors: Under Linux, this exists but is not implemented, i.e. the call does nothing.
  2309.  
  2310.    See also: SetCBreak (47)
  2311.  
  2312.  
  2313.            GetDate
  2314. Declaration: Procedure GetDate (var year, month, mday, wday: word);
  2315.  
  2316. Description: GetDate returns the system's date. Year is a number in the range 1980..2099.mday
  2317.            is the day of the month, wday is the day of the week, starting with Sunday as day
  2318.            0.
  2319.  
  2320.      Errors: None.
  2321.  
  2322.    See also: GetTime (45),SetDate (48)
  2323.  
  2324.            Program Example2 ;
  2325.            uses Dos ;
  2326.  
  2327.            { Program to demonstrate the GetDate f u n c t i o n . }
  2328.  
  2329.  
  2330.                                                            42
  2331.  
  2332.  
  2333.  
  2334.                                                         2.2. FUNCTIONS AND PROCEDURES
  2335.  
  2336.  
  2337.            const
  2338.               DayStr : array [ 0 . . 6 ] of st rin g [3]=( ' Sun ' , ' Mon' , ' Tue ' , ' Wed' , ' Thu ' , ' F r i ' , ' Sat ' ) ;
  2339.               MonthStr : array [ 1 . . 1 2 ] of str ing [3]=( ' Jan ' , ' Feb ' , ' Mar ' , ' Apr ' , ' May' , ' Jun ' ,
  2340.                                                                      ' Jul ' , ' Aug ' , ' Sep ' , ' Oct ' , ' Nov ' , ' Dec ' ) ;
  2341.            varYear ,Month,Day,WDay : word;
  2342.            begin
  2343.               GetDate ( Year , Month , Day , WDay) ;
  2344.               WriteLn ( ' Current date ' ) ;
  2345.               WriteLn ( DayStr [ WDay] , ' , ' , Day , ' ' , MonthStr [ Month ] , ' ' , Year , ' . ' ) ;
  2346.            end .
  2347.  
  2348.  
  2349.            GetEnv
  2350. Declaration: Function GetEnv (EnvVar: String) : String;
  2351.  
  2352. Description: Getenv returns the value of the environment variable EnvVar. Under linux, case is
  2353.            important when looking for EnvVar. When there is no environment variable EnvVar
  2354.            defined, an empty string is returned.
  2355.  
  2356.      Errors: None.
  2357.  
  2358.    See also: EnvCount (38), EnvStr (39)
  2359.  
  2360.            Program Example14 ;
  2361.            uses Dos ;
  2362.  
  2363.            { Program to demonstrate the GetEnv f u n c t i o n . }
  2364.  
  2365.            begin
  2366.               WriteLn ( ' Current PATH i s ' , GetEnv ( ' PATH' ) ) ;
  2367.            end .
  2368.  
  2369.  
  2370.            GetFAttr
  2371. Declaration: Procedure GetFAttr (var F; var Attr: word);
  2372.  
  2373. Description: GetFAttr returns the file attributes of the file-variable f. F can be a untyped
  2374.            or typed file, or of type Text. f must have been assigned, but not opened. The
  2375.            attributes can be examined with the following constants :
  2376.  
  2377.                *ReadOnly = 01h
  2378.                *Hidden = 02h
  2379.                *SysFile = 04h
  2380.                *VolumeId = 08h
  2381.                *Directory = 10h
  2382.                *Archive = 20h
  2383.                *AnyFile = 3fh
  2384.  
  2385.            Under linux, supported attributes are:
  2386.  
  2387.                *Directory
  2388.                *ReadOnly if the current process doesn't have access to the file.
  2389.  
  2390.                                                        43
  2391.  
  2392.  
  2393.  
  2394.                                                        2.2. FUNCTIONS AND PROCEDURES
  2395.  
  2396.  
  2397.                    *Hidden for files whose name starts with a dot ('.').
  2398.  
  2399.     Errors: Errors are reported in DosError
  2400.  
  2401.   See also: SetFAttr (48)
  2402.  
  2403.            Program Example8 ;
  2404.            uses Dos ;
  2405.  
  2406.            { Program to demonstrate the GetFAttr f u n c t i o n . }
  2407.  
  2408.            varAttr : Word;
  2409.               f          : File ;
  2410.            begin
  2411.               Assign ( f , ParamStr ( 1 ) ) ;
  2412.               GetFAttr ( f , Attr ) ;
  2413.               WriteLn ( ' F i l e ' , ParamStr ( 1 ) , ' has a t t r i b u t e ' , Attr ) ;
  2414.               i f ( Attr and $20 )<>0 then WriteLn ( '- Archive ' ) ;
  2415.               i f ( Attr and $10 )<>0 then WriteLn ( '- D i r e c t o r y ' ) ;
  2416.               i f ( Attr and $4 )<>0 then WriteLn ( '- Read-Only ' ) ;
  2417.               i f ( Attr and $2 )<>0 then WriteLn ( '- System ' ) ;
  2418.               i f ( Attr and $1 )<>0 then WriteLn ( '- Hidden ' ) ;
  2419.            end .
  2420.  
  2421.  
  2422.            GetFTime
  2423. Declaration: Procedure GetFTime (var F; var Time: longint);
  2424.  
  2425. Description: GetFTime returns the modification time of a file. This time is encoded and must
  2426.            be decoded with UnPackTime. F must be a file type, which has been assigned, and
  2427.            opened.
  2428.  
  2429.     Errors: Errors are reported in DosError
  2430.  
  2431.   See also: SetFTime (48), PackTime (47),UnPackTime (49)
  2432.  
  2433.            Program Example9 ;
  2434.            uses Dos ;
  2435.  
  2436.            { Program to demonstrate the GetFTime f u n c t i o n . }
  2437.  
  2438.            Function L0 (w: word ) : st ring ;
  2439.            vars : string ;
  2440.            begin
  2441.               Str (w, s ) ;
  2442.               i f w<10 then
  2443.                    L0:= ' 0 ' +s
  2444.               else
  2445.                    L0:= s ;
  2446.            end ;
  2447.  
  2448.            varf          : File ;
  2449.  
  2450.                                                       44
  2451.  
  2452.  
  2453.  
  2454.                                                           2.2. FUNCTIONS AND PROCEDURES
  2455.  
  2456.  
  2457.               Time : Longint ;
  2458.               DT      : DateTime ;
  2459.            begin
  2460.               Assign ( f , ParamStr ( 1 ) ) ;
  2461.               Reset ( f ) ;
  2462.               GetFTime ( f , Time ) ;
  2463.               Close ( f ) ;
  2464.               UnPackTime ( Time, DT) ;
  2465.               Write ( ' F i l e ' , ParamStr ( 1 ) , ' i s l a s t modified on ' ) ;
  2466.               Writeln ( L0 (DT. Month ) , '-' , L0 (DT. Day ) , '-' , DT. Year ,
  2467.                                ' at ' , L0 (DT. Hour ) , ' : ' , L0 (DT. Min ) ) ;
  2468.            end .
  2469.  
  2470.  
  2471.            GetIntVec
  2472. Declaration: Procedure GetIntVec (IntNo: byte; var Vector: pointer);
  2473.  
  2474. Description: GetIntVec returns the address of interrupt vector IntNo.
  2475.  
  2476.      Errors: None. Under linux, this call exists bout isn't implemented, i.e. it does nothing.
  2477.  
  2478.   See also: SetIntVec (48)
  2479.  
  2480.  
  2481.            GetTime
  2482. Declaration: Procedure GetTime (var hour, minute, second, sec100: word);
  2483.  
  2484. Description: GetTime returns the system's time. Hour is a on a 24-hour time scale. sec100 is
  2485.            in hundredth of a second.
  2486.  
  2487.      Errors: None.
  2488.  
  2489.   See also: GetDate (42), SetTime (49)
  2490.  
  2491.            Program Example3 ;
  2492.            uses Dos ;
  2493.  
  2494.            { Program to demonstrate the GetTime f u n c t i o n . }
  2495.  
  2496.            Function L0 (w: word ) : str ing ;
  2497.            vars : string ;
  2498.            begin
  2499.               Str (w, s ) ;
  2500.               i f w<10 then
  2501.                L0:= ' 0 ' +s
  2502.               else
  2503.                L0:= s ;
  2504.            end ;
  2505.  
  2506.            varHour,Min, Sec , HSec : word;
  2507.            begin
  2508.               GetTime ( Hour , Min , Sec , HSec ) ;
  2509.               WriteLn ( ' Current time ' ) ;
  2510.  
  2511.                                                          45
  2512.  
  2513.  
  2514.  
  2515.                                                           2.2. FUNCTIONS AND PROCEDURES
  2516.  
  2517.  
  2518.               WriteLn ( L0 ( Hour ) , ' : ' , L0 ( Min ) , ' : ' , L0 ( Sec ) ) ;
  2519.            end .
  2520.  
  2521.  
  2522.            GetVerify
  2523. Declaration: Procedure GetVerify (var verify: boolean);
  2524.  
  2525. Description: GetVerify returns the status of the verify flag under dos. When Verify is True,
  2526.            then dos checks data which are written to disk, by reading them after writing. If
  2527.            Verify is False, then data written to disk are not verified.
  2528.  
  2529.     Errors: Under linux, Verify is always True.
  2530.  
  2531.   See also: SetVerify (49)
  2532.  
  2533.  
  2534.            Intr
  2535. Declaration: Procedure Intr (IntNo: byte; var Regs: registers);
  2536.  
  2537. Description: Intr executes a software interrupt number IntNo (must be between 0 and 255),
  2538.            with processor registers set to Regs. After the interrupt call returned, the processor
  2539.            registers are saved in Regs.
  2540.  
  2541.     Errors: Under linux this call does nothing, because interrupts are managed by the kernel.
  2542.            The only allowed interrupt is 80h, the kernel entry interrupt.
  2543.  
  2544.   See also: MSDos (46), see the linux unit.
  2545.  
  2546.  
  2547.            Keep
  2548. Declaration: Procedure Keep (ExitCode: word);
  2549.  
  2550. Description: Keep terminates the program, but stays in memory. This is used for TSR (Termi-
  2551.            nate Stay Resident) programs which catch some interrupt. ExitCode is the same
  2552.            parameter as the Halt function takes.
  2553.  
  2554.     Errors: Under linux, this call does nothing.
  2555.  
  2556.   See also: Halt ()
  2557.  
  2558.  
  2559.            MSDos
  2560. Declaration: Procedure MSDos (var regs: registers);
  2561.  
  2562. Description: MSDos executes an MS-dos call (int 21h). This is the same as doing a Intr call
  2563.            with an interrupt number of 21h.
  2564.  
  2565.     Errors: None.
  2566.  
  2567.   See also: Intr (46)
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.                                                          46
  2576.  
  2577.  
  2578.  
  2579.                                                          2.2. FUNCTIONS AND PROCEDURES
  2580.  
  2581.  
  2582.           PackTime
  2583. Declaration: Procedure PackTime (var T: datetime; var P: longint);
  2584.  
  2585. Description: UnPackTime converts the date and time specified in T to a packed-time format
  2586.           which can be fed to SetFTime.
  2587.  
  2588.     Errors: None.
  2589.  
  2590.   See also: SetFTime (48), FindFirst (40), FindNext (41), UnPackTime (49)
  2591.  
  2592.           Program Example4 ;
  2593.           uses Dos ;
  2594.  
  2595.           { Program to demonstrate the PackTime and UnPackTime f u n c t i o n s . }
  2596.  
  2597.           varDT : DateTime;
  2598.              Time : l o n g i n t ;
  2599.           begin
  2600.              with DT do
  2601.               begin
  2602.                      Year :=1998;
  2603.                      Month :=11;
  2604.                      Day :=11;
  2605.                      Hour :=11;
  2606.                      Min :=11;
  2607.                      Sec :=11;
  2608.               end ;
  2609.              PackTime (DT, Time ) ;
  2610.              WriteLn ( ' Packed Time : ' , Time ) ;
  2611.              UnPackTime ( Time, DT) ;
  2612.              WriteLn ( ' Unpacked Again : ' ) ;
  2613.              with DT do
  2614.               begin
  2615.                      WriteLn ( ' Year    ' , Year ) ;
  2616.                      WriteLn ( ' Month ' , Month ) ;
  2617.                      WriteLn ( ' Day     ' , Day ) ;
  2618.                      WriteLn ( ' Hour    ' , Hour ) ;
  2619.                      WriteLn ( ' Min     ' , Min ) ;
  2620.                      WriteLn ( ' Sec     ' , Sec ) ;
  2621.               end ;
  2622.           end .
  2623.  
  2624.  
  2625.           SetCBreak
  2626. Declaration: Procedure SetCBreak (breakvalue: boolean);
  2627.  
  2628. Description: SetCBreak sets the status of CTRL-Break checking under dos. When BreakValue
  2629.           is false, then dos only checks for the CTRL-Break key-press when I/O is per-
  2630.           formed. When it is set to True, then a check is done at every system call.
  2631.  
  2632.     Errors: Under Linux, this call exists but is not implemented, i.e. it does nothing.
  2633.  
  2634.   See also: GetCBreak (42)
  2635.  
  2636.  
  2637.                                                          47
  2638.  
  2639.  
  2640.  
  2641.                                                        2.2. FUNCTIONS AND PROCEDURES
  2642.  
  2643.  
  2644.            SetDate
  2645. Declaration: Procedure SetDate (year,month,day: word);
  2646.  
  2647. Description: SetDate sets the system's internal date. Year is a number between 1980 and 2099.
  2648.  
  2649.      Errors: On a linux machine, this is not implemented (allthough a procedure exists, it just
  2650.            doesn't do anything. The setting of the date is a root-only privilege, and is hence
  2651.            not implemented.
  2652.  
  2653.    See also: Dos:GetDate (42), SetTime (49)
  2654.  
  2655.  
  2656.            SetFAttr
  2657. Declaration: Procedure SetFAttr (var F; Attr: word);
  2658.  
  2659. Description: SetFAttr sets the file attributes of the file-variable F. F can be a untyped or typed
  2660.            file, or of type Text. F must have been assigned, but not opened. The attributes
  2661.            can be a sum of the following constants:
  2662.  
  2663.                *ReadOnly = 01h
  2664.                *Hidden = 02h
  2665.                *SysFile = 04h
  2666.                *VolumeId = 08h
  2667.                *Directory = 10h
  2668.                *Archive = 20h
  2669.                *AnyFile = 3fh
  2670.  
  2671.      Errors: Errors are reported in DosError. Under linux the call exists, but is not imple-
  2672.            mented, i.e. it does nothing.
  2673.  
  2674.    See also: GetFAttr (43)
  2675.  
  2676.  
  2677.            SetFTime
  2678. Declaration: Procedure SetFTime (var F; Time: longint);
  2679.  
  2680. Description: SetFTime sets the modification time of a file, this time is encoded and must be
  2681.            encoded with PackTime. F must be a file type, which has been assigned, and opened.
  2682.  
  2683.      Errors: Errors are reported in DosError
  2684.  
  2685.    See also: GetFTime (44), PackTime (47),UnPackTime (49)
  2686.  
  2687.  
  2688.            SetIntVec
  2689. Declaration: Procedure SetIntVec (IntNo: byte; Vector: pointer);
  2690.  
  2691. Description: SetIntVec sets interrupt vector IntNo to Vector. Vector should point to an
  2692.            interrupt procedure.
  2693.  
  2694.      Errors: Under linux, this call exists but is not implemented, the kernel manages all inter-
  2695.            rupts.
  2696.  
  2697.    See also: GetIntVec (45)
  2698.  
  2699.  
  2700.                                                      48
  2701.  
  2702.  
  2703.  
  2704.                                                       2.2. FUNCTIONS AND PROCEDURES
  2705.  
  2706.  
  2707.            SetTime
  2708. Declaration: Procedure SetTime (hour,minute,second,sec100: word);
  2709.  
  2710. Description: SetTime sets the system's internal clock. The Hour parameter is on a 24-hour time
  2711.            scale.
  2712.  
  2713.      Errors: this call exists, but is not implemented on linux, as setting the time is a root-only
  2714.            privilege.
  2715.  
  2716.    See also: Dos:GetTime (45), SetDate (48)
  2717.  
  2718.  
  2719.            SetVerify
  2720. Declaration: Procedure SetVerify (verify: boolean);
  2721.  
  2722. Description: SetVerify sets the status of the verify flag under dos. When Verify is True,
  2723.            then dos checks data which are written to disk, by reading them after writing. If
  2724.            Verify is False, then data written to disk are not verified.
  2725.  
  2726.      Errors: Under linux, Verify is always True.
  2727.  
  2728.    See also: SetVerify (49)
  2729.  
  2730.  
  2731.            SwapVectors
  2732. Declaration: Procedure SwapVectors ;
  2733.  
  2734. Description: SwapVectors swaps the contents of the internal table of interrupt vectors with the
  2735.            current contents of the interrupt vectors. This is called typically in before and after
  2736.            an Exec call.
  2737.  
  2738.      Errors: Under linux this call does nothing, as the interrupt vectors are managed by the
  2739.            kernel.
  2740.  
  2741.    See also: Exec (39), SetIntVec (48)
  2742.  
  2743.  
  2744.            UnPackTime
  2745. Declaration: Procedure UnPackTime (p: longint; var T: datetime);
  2746.  
  2747. Description: UnPackTime converts the file-modification time in p to a DateTime record. The
  2748.            file-modification time can be returned by GetFTime, FindFirst or FindNext calls.
  2749.  
  2750.      Errors: None.
  2751.  
  2752.    See also: GetFTime (44), FindFirst (40), FindNext (41), PackTime (47)
  2753.  
  2754.            For an example, see PackTime (47).
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.                                                      49
  2765.  
  2766.  
  2767.  
  2768. Chapter 3
  2769.  
  2770. The GETOPTS unit.
  2771.  
  2772. This document describes the GETOPTS unit for Free Pascal. It was written for
  2773. linux by Micha¿el Van Canneyt. It also works under DOS and Tp7. The chapter
  2774. is divided in 2 sections:
  2775.  
  2776.    * The first section lists types, constants and variables from the interface part of
  2777.       the unit.
  2778.  
  2779.    * The second section describes the functions defined in the unit.
  2780.  
  2781.  
  2782. 3.1 Types, Constants and variables :
  2783.  
  2784. Constants
  2785. No Argument=0 : Specifies that a long option does not take an argument.
  2786. Required Argument=1 : Specifies that a long option needs an argument.
  2787. Optional Argument=2 : Specifies that a long option optionally takes an argument.
  2788. EndOfOptions=#255 : Returned by getopt, getlongopts to indicate that there are
  2789. no more options.
  2790.  
  2791.  
  2792. Types
  2793. TOption = record
  2794.   Name       : String;
  2795.   Has_arg : Integer;
  2796.   Flag       : PChar;
  2797.   Value      : Char;
  2798.   end;
  2799. POption = ^TOption;
  2800.  
  2801. The option type is used to communicate the long options to GetLongOpts. The
  2802. Name field is the name of the option. Has arg specifies if the option wants an argu-
  2803. ment, Flag is a pointer to a char, which is set to Value, if it is non-nil. POption
  2804. is a pointer to a Option record. It is used as an argument to the GetLongOpts
  2805. function.
  2806.  
  2807.  
  2808.  
  2809.  
  2810.                                          50
  2811.  
  2812.  
  2813.  
  2814.                                                     3.2. PROCEDURES AND FUNCTIONS
  2815.  
  2816.  
  2817.           Variables
  2818.           OptArg:String Is set to the argument of an option, if the option needs one.
  2819.           Optind:Longint Is the index of the current paramstr(). When all options have
  2820.           been processed, optind is the index of the first non-option parameter. This is a
  2821.           read-only variable. Note that it can become equal to paramcount+1
  2822.           OptErr:Boolean Indicates whether getopt() prints error messages.
  2823.           OptOpt:Char In case of an error, contains the character causing the error.
  2824.  
  2825.  
  2826.           3.2 Procedures and functions
  2827.  
  2828.           GetLongOpts
  2829. Declaration: Function GetLongOpts (Shortopts : String, LongOpts : POption; var Longint
  2830.           : Longint ) : Char;
  2831.  
  2832. Description: Returns the next option found on the command-line, taking into account long
  2833.           options as well. If no more options are found, returns EndOfOptions. If the option
  2834.           requires an argument, it is returned in the OptArg variable. ShortOptions is a
  2835.           string containing all possible one-letter options. (see Getopt (51) for its description
  2836.           and use) LongOpts is a pointer to the first element of an array of Option records,
  2837.           the last of which needs a name of zero length. The function tries to match the
  2838.           names even partially (i.e. --app will match e.g. the append option), but will
  2839.           report an error in case of ambiguity. If the option needs an argument, set Has arg
  2840.           to Required argument, if the option optionally has an argument, set Has arg
  2841.           to Optional argument. If the option needs no argument, set Has arg to zero.
  2842.           Required arguments can be specified in two ways :
  2843.  
  2844.              1. Pasted to the option : --option=value
  2845.              2. As a separate argument : --option value
  2846.  
  2847.           Optional arguments can only be specified through the first method.
  2848.  
  2849.     Errors: see Getopt (51), getopt (3)
  2850.  
  2851.   See also: Getopt
  2852.  
  2853.  
  2854.           Getopt
  2855. Declaration: Function Getopt (Shortopts : String) : Char;
  2856.  
  2857. Description: Returns the next option found on the command-line. If no more options are
  2858.           found, returns EndOfOptions. If the option requires an argument, it is returned
  2859.           in the OptArg variable. ShortOptions is a string containing all possible one-letter
  2860.           options. If a letter is followed by a colon (:), then that option needs an argument.
  2861.           If a letter is followed by 2 colons, the option has an optional argument. If the first
  2862.           character of shortoptions is a '+' then options following a non-option are regarded
  2863.           as non-options (standard Unix behavior). If it is a '-', then all non-options are
  2864.           treated as arguments of a option with character #0. This is useful for applications
  2865.           that require their options in the exact order as they appear on the command-line.
  2866.           If the first character of shortoptions is none of the above, options and non-options
  2867.           are permuted, so all non-options are behind all options. This allows options and
  2868.           non-options to be in random order on the command line.
  2869.  
  2870.  
  2871.  
  2872.                                                     51
  2873.  
  2874.  
  2875.  
  2876.                                                    3.2. PROCEDURES AND FUNCTIONS
  2877.  
  2878.  
  2879.   Errors: Errors are reported through giving back a '?' character. OptOpt then gives the
  2880.         character which caused the error. If OptErr is True then getopt prints an error-
  2881.         message to stdout.
  2882.  
  2883. See also: GetLongOpts (51), getopt (3)
  2884.  
  2885.         program t e s t o p t ;
  2886.  
  2887.         { Program to depmonstrate the getopts f u n c t i o n . }
  2888.  
  2889.         { Valid calls to this program are
  2890.            optex --verbose --add me --d e l e t e you
  2891.            optex --append --c r e a t e c h i l d
  2892.            optex -ab -c me -d you
  2893.           and so on
  2894.         }uses getopts ;
  2895.         var c : char ;
  2896.               o p t i o n i n d e x : Longint ;
  2897.               theopts : array [ 1 . . 7 ] of TOption ;
  2898.  
  2899.         begin
  2900.            with theopts [ 1 ] do
  2901.             begin
  2902.              name:= ' add ' ;
  2903.               has arg :=1;
  2904.               f l a g := n i l ;
  2905.               value :=#0;
  2906.           end ;
  2907.            with theopts [ 2 ] do
  2908.             begin
  2909.              name:= ' append ' ;
  2910.               has arg :=0;
  2911.               f l a g := n i l ;
  2912.               value :=#0;
  2913.           end ;
  2914.            with theopts [ 3 ] do
  2915.             begin
  2916.              name:= ' d e l e t e ' ;
  2917.               has arg :=1;
  2918.               f l a g := n i l ;
  2919.               value :=#0;
  2920.           end ;
  2921.            with theopts [ 4 ] do
  2922.             begin
  2923.              name:= ' verbose ' ;
  2924.               has arg :=0;
  2925.               f l a g := n i l ;
  2926.               value :=#0;
  2927.           end ;
  2928.            with theopts [ 5 ] do
  2929.             begin
  2930.  
  2931.  
  2932.                                                    52
  2933.  
  2934.  
  2935.  
  2936.                                                          3.2. PROCEDURES AND FUNCTIONS
  2937.  
  2938.  
  2939.          name:= ' c r e a t e ' ;
  2940.          has arg :=1;
  2941.          f l a g := n i l ;
  2942.          value := ' c '
  2943.   end ;
  2944.   with theopts [ 6 ] do
  2945.     begin
  2946.          name:= ' f i l e ' ;
  2947.          has arg :=1;
  2948.          f l a g := n i l ;
  2949.          value :=#0;
  2950.   end ;
  2951.   with theopts [ 7 ] do
  2952.     begin
  2953.          name:= ' ' ;
  2954.          has arg :=0;
  2955.          f l a g := n i l ;
  2956.   end ;
  2957.   c :=#0;
  2958.   repeat
  2959.          c := g e t l o n g o p t s ( ' abc : d : 0 1 2 ' , @theopts [ 1 ] , o p t i o n i n d e x ) ;
  2960.          case c of
  2961.             ' 1 ' , ' 2 ' , ' 3 ' , ' 4 ' , ' 5 ' , ' 6 ' , ' 7 ' , ' 8 ' , ' 9 ' :
  2962.                 begin
  2963.                 writeln ( ' Got optind : ' , c )
  2964.                 end ;
  2965.             #0 : begin
  2966.                       write ( ' Long option : ' , theopts [ o p t i o n i n d e x ] . name) ;
  2967.                       i f theopts [ o p t i o n i n d e x ] . has arg >0 then
  2968.                           writeln ( ' With value                      : ' , optarg )
  2969.                       else
  2970.                           writeln
  2971.                       end ;
  2972.             ' a ' : writeln ( ' Option a . ' ) ;
  2973.             ' b ' : writeln ( ' Option b . ' ) ;
  2974.             ' c ' : writeln ( ' Option c : ' , optarg ) ;
  2975.             ' d ' : writeln ( ' Option d : ' , optarg ) ;
  2976.             ' ? ' , ' : ' : writeln ( ' Error with opt : ' , optopt ) ;
  2977.     end ; { case }
  2978.  u n t i l c=e n d o f o p t i o n s ;
  2979.  i f optind <=paramcount then
  2980.          begin
  2981.          write ( ' Non o p t i o n s : ' ) ;
  2982.          while optind <=paramcount do
  2983.             begin
  2984.             write ( paramstr ( optind ) , ' ' ) ;
  2985.             inc ( optind )
  2986.             end ;
  2987.          writeln
  2988.          end
  2989. end .
  2990.  
  2991.  
  2992.  
  2993.  
  2994.                                                          53
  2995.  
  2996.  
  2997.  
  2998. Chapter 4
  2999.  
  3000. The GO32 unit
  3001.  
  3002. This chapter of the documentation describe the GO32 unit for the Free Pascal com-
  3003. piler under dos. It was donated by Thomas Schatzl (tom at work@geocities.com),
  3004. for which my thanks. This unit was first written for dos by Florian Klaempfl. This
  3005. chapter is divided in three sections. The first section is an introduction to the GO32
  3006. unit. The second section lists the pre-defined constants, types and variables. The
  3007. third section describes the functions which appear in the interface part of the GO32
  3008. unit.
  3009.  
  3010.  
  3011. 4.1 Introduction
  3012.  
  3013. These docs contain information about the GO32 unit. Only the GO32V2 DPMI
  3014. mode is discussed by me here due to the fact that new applications shouldn't be
  3015. created with the older GO32V1 model. The former is much more advanced and
  3016. better. Additionally a lot of functions only work in DPMI mode anyway. I hope
  3017. the following explanations and introductions aren't too confusing at all. If you
  3018. notice an error or bug send it to the FPC mailing list or directly to me. So let's get
  3019. started and happy and error free coding I wish you....            Thomas Schatzl, 25.
  3020. August 1998
  3021.  
  3022.  
  3023. 4.2 Protected mode memory organization
  3024.  
  3025. What is DPMI
  3026. The dos Protected Mode Interface helps you with various aspects of protected mode
  3027. programming. These are roughly divided into descriptor handling, access to dos
  3028. memory, management of interrupts and exceptions, calls to real mode functions and
  3029. other stu . Additionally it automatically provides swapping to disk for memory in-
  3030. tensive applications. A DPMI host (either a Windows dos box or CWSDPMI.EXE)
  3031. provides these functions for your programs.
  3032.  
  3033.  
  3034. Selectors and descriptors
  3035. Descriptors are a bit like real mode segments; they describe (as the name implies) a
  3036. memory area in protected mode. A descriptor contains information about segment
  3037. length, its base address and the attributes of it (i.e. type, access rights, ...). These
  3038.  
  3039.  
  3040.                                           54
  3041.  
  3042.  
  3043.  
  3044.                          4.2. PROTECTED MODE MEMORY ORGANIZATION
  3045.  
  3046.  
  3047. descriptors are stored internally in a so-called descriptor table, which is basically an
  3048. array of such descriptors. Selectors are roughly an index into this table. Because
  3049. these 'segments' can be up to 4 GB in size, 32 bits aren't su cient anymore to
  3050. describe a single memory location like in real mode. 48 bits are now needed to
  3051. do this, a 32 bit address and a 16 bit sized selector. The GO32 unit provides the
  3052. tseginfo record to store such a pointer. But due to the fact that most of the time
  3053. data is stored and accessed in the %ds selector, FPC assumes that all pointers point
  3054. to a memory location of this selector. So a single pointer is still only 32 bits in size.
  3055. This value represents the o set from the data segment base address to this memory
  3056. location.
  3057.  
  3058.  
  3059. FPC specialities
  3060. The %ds and %es selector MUST always contain the same value or some system
  3061. routines may crash when called. The %fs selector is preloaded with the DOSMEM-
  3062. SELECTOR variable at startup, and it MUST be restored after use, because again
  3063. FPC relys on this for some functions. Luckily we asm programmers can still use
  3064. the %gs selector for our own purposes, but for how long ? See also: get cs (71),
  3065. get ds (72), gett ss (79), allocate ldt descriptors (64), free ldt descriptor (70),
  3066. segment to descriptor (85), get next selector increment value (73), get segment base address
  3067. (78), set segment base address (88), set segment limit (88), create code segment alias descriptor
  3068. (67)
  3069.  
  3070.  
  3071. dos memory access
  3072. dos memory is accessed by the predefined dosmemselector selector; the GO32
  3073. unit additionally provides some functions to help you with standard tasks, like
  3074. copying memory from heap to dos memory and the likes. Because of this it is
  3075. strongly recommened to use them, but you are still free to use the provided standard
  3076. memory accessing functions which use 48 bit pointers. The third, but only thought
  3077. for compatibility purposes, is using the mem[]-arrays. These arrays map the whole
  3078. 1 Mb dos space. They shouldn't be used within new programs. To convert a
  3079. segment:o set real mode address to a protected mode linear address you have to
  3080. multiply the segment by 16 and add its o set. This linear address can be used
  3081. in combination with the DOSMEMSELECTOR variable. See also: dosmemget
  3082. (69), dosmemput (70), dosmemmove (69), dosmemfillchar (68), dosmemfillword (69),
  3083. mem[]-arrays, seg move (86), seg fillchar (84), seg fillword (85).
  3084.  
  3085.  
  3086. I/O port access
  3087. The I/O port access is done via the various inportb (81), outportb (83) functions
  3088. which are available. Additionally Free Pascal supports the Turbo Pascal PORT[]-
  3089. arrays but it is by no means recommened to use them, because they're only for
  3090. compatibility purposes. See also: outportb (83), inportb (81), PORT[]-arrays
  3091.  
  3092.  
  3093. Processor access
  3094. These are some functions to access various segment registers (%cs, %ds, %ss) which
  3095. makes your work a bit easier. See also: get cs (71), get ds (72), get ss (79)
  3096.  
  3097.  
  3098.  
  3099.  
  3100.                                            55
  3101.  
  3102.  
  3103.  
  3104.                           4.2. PROTECTED MODE MEMORY ORGANIZATION
  3105.  
  3106.  
  3107. Interrupt redirection
  3108. Interrupts are program interruption requests, which in one or another way get to
  3109. the processor; there's a distinction between software and hardware interrupts. The
  3110. former are explicitely called by an 'int' instruction and are a bit comparable to
  3111. normal functions. Hardware interrupts come from external devices like the keyboard
  3112. or mouse. These functions are called handlers.
  3113.  
  3114.  
  3115. Handling interrupts with DPMI
  3116. The interrupt functions are real-mode procedures; they normally can't be called in
  3117. protected mode without the risk of an protection fault. So the DPMI host creates
  3118. an interrupt descriptor table for the application. Initially all software interrupts
  3119. (except for int 31h, 2Fh and 21h function 4Ch) or external hardware interrupts
  3120. are simply directed to a handler that reflects the interrupt in real-mode, i.e. the
  3121. DPMI host's default handlers switch the CPU to real-mode, issue the interrupt
  3122. and switch back to protected mode. The contents of general registers and flags are
  3123. passed to the real mode handler and the modified registers and flags are returned
  3124. to the protected mode handler. Segment registers and stack pointer are not passed
  3125. between modes.
  3126.  
  3127.  
  3128. Protected mode interrupts vs. Real mode interrupts
  3129. As mentioned before, there's a distinction between real mode interrupts and pro-
  3130. tected mode interrupts; the latter are protected mode programs, while the former
  3131. must be real mode programs. To call a protected mode interrupt handler, an as-
  3132. sembly 'int' call must be issued, while the other is called via the realintr() or intr()
  3133. function. Consequently, a real mode interrupt then must either reside in dos mem-
  3134. ory (í1MB) or the application must allocate a real mode callback address via the
  3135. get rm callback() function.
  3136.  
  3137.  
  3138. Creating own interrupt handlers
  3139. Interrupt redirection with FPC pascal is done via the set pm interrupt() for pro-
  3140. tected mode interrupts or via the set rm interrupt() for real mode interrupts.
  3141.  
  3142.  
  3143. Disabling interrupts
  3144. The GO32 unit provides the two procedures disable() and enable() to disable and
  3145. enable all interrupts.
  3146.  
  3147.  
  3148. Hardware interrupts
  3149. Hardware interrupts are generated by hardware devices when something unusual
  3150. happens; this could be a keypress or a mouse move or any other action. This
  3151. is done to minimize CPU time, else the CPU would have to check all installed
  3152. hardware for data in a big loop (this method is called 'polling') and this would take
  3153. much time. A standard IBM-PC has two interrupt controllers, that are responsible
  3154. for these hardware interrupts: both allow up to 8 di erent interrupt sources (IRQs,
  3155. interrupt requests). The second controller is connected to the first through IRQ
  3156. 2 for compatibility reasons, e.g. if controller 1 gets an IRQ 2, he hands the IRQ
  3157. over to controller 2. Because of this up to 15 di erent hardware interrupt sources
  3158.  
  3159.                                           56
  3160.  
  3161.  
  3162.  
  3163.                                 4.2. PROTECTED MODE MEMORY ORGANIZATION
  3164.  
  3165.  
  3166. can be handled. IRQ 0 through IRQ 7 are mapped to interrupts 8h to Fh and
  3167. the second controller (IRQ 8 to 15) is mapped to interrupt 70h to 77h. All of the
  3168. code and data touched by these handlers MUST be locked (via the various locking
  3169. functions) to avoid page faults at interrupt time. Because hardware interrupts are
  3170. called (as in real mode) with interrupts disabled, the handler has to enable them
  3171. before it returns to normal program execution. Additionally a hardware interrupt
  3172. must send an EOI (end of interrupt) command to the responsible controller; this
  3173. is acomplished by sending the value 20h to port 20h (for the first controller) or
  3174. A0h (for the second controller). The following example shows how to redirect the
  3175. keyboard interrupt.
  3176. Program K e y c l i c k ;
  3177.  
  3178. uses c r t ,
  3179.           go32 ;
  3180.  
  3181. const kbdint = $9 ;
  3182.  
  3183. var o l d i n t 9 h a n d l e r : t s e g i n f o ;
  3184.          newint9 handler : t s e g i n f o ;
  3185.  
  3186.          c l i c k p r o c : p o i n t e r ;
  3187.  
  3188. {$ASMMODE DIRECT}
  3189. procedure int9 handler ; assembler ;
  3190. asm cli
  3191.      pushal
  3192.     movw %cs : INT9 DS, % ax
  3193.     movw %ax , % ds
  3194.     movw %ax , % es
  3195.     movw U GO32 DOSMEMSELECTOR, % ax
  3196.     movw %ax , % fs
  3197.      c a l l   CLICKPROC
  3198.      popal
  3199.  
  3200.      ljmp %cs : OLDHANDLER
  3201.  
  3202. INT9 DS : . word 0
  3203. OLDHANDLER:
  3204.                  . long 0
  3205.                  . word 0
  3206. end ;
  3207.  
  3208. procedure int9 dummy ; begin end ;
  3209.  
  3210. procedure c l i c k e r ;
  3211. begin sound (500); delay (10); nosound ;
  3212. end ;
  3213.  
  3214. procedure clicker dummy ; begin end ;
  3215.  
  3216. procedure i n s t a l l c l i c k ;
  3217.  
  3218.  
  3219.                                                 57
  3220.  
  3221.  
  3222.  
  3223.                               4.2. PROTECTED MODE MEMORY ORGANIZATION
  3224.  
  3225.  
  3226. begin clickproc := @clicker ;
  3227.          lock data ( c l i c k p r o c , s i z e o f ( c l i c k p r o c ) ) ;
  3228.          lock data ( dosmemselector , s i z e o f ( dosmemselector ) ) ;
  3229.  
  3230.          lock code ( @ c l i c k e r ,
  3231.                           l o n g i n t ( @clicker dummy )- l o n g i n t ( @ c l i c k e r ) ) ;
  3232.          lock code ( @int9 handler ,
  3233.                           l o n g i n t ( @int9 dummy )
  3234.                             - l o n g i n t ( @int9 handler ) ) ;
  3235.          newint9 handler . o f f s e t := @int9 handler ;
  3236.          newint9 handler . segment := get cs ;
  3237.          get pm interrupt ( kbdint , o l d i n t 9 h a n d l e r ) ;
  3238.          asmmovw %ds, %ax
  3239.              movw %ax , INT9 DS
  3240.               movl      OLDINT9 HANDLER, % eax
  3241.               movl %eax , OLDHANDLER
  3242.              movw 4+ OLDINT9 HANDLER, % ax
  3243.              movw %ax , 4+OLDHANDLER
  3244.          end ;
  3245.          set pm interrupt ( kbdint , newint9 handler ) ;
  3246. end ;
  3247.  
  3248. procedure remove click ;
  3249. begin set pm interrupt ( kbdint , oldint9 handler );
  3250.          unlock data ( dosmemselector , s i z e o f ( dosmemselector ) ) ;
  3251.          unlock data ( c l i c k p r o c , s i ze o f ( c l i c k p r o c ) ) ;
  3252.          unlock code ( @ c l i c k e r ,
  3253.                               l o n g i n t ( @clicker dummy )
  3254.                                - l o n g i n t ( @ c l i c k e r ) ) ;
  3255.          unlock code ( @int9 handler ,
  3256.                               l o n g i n t ( @int9 dummy )
  3257.                                - l o n g i n t ( @int9 handler ) ) ;
  3258. end ;
  3259.  
  3260. var ch : char ;
  3261.  
  3262. begin install click ;
  3263.          Writeln ( ' Enter any message . ' ,
  3264.                        ' Press r e t u r n when f i n i s h e d ' ) ;
  3265.          while ( ch <> #13) do begin
  3266.                    ch := readkey ; write ( ch ) ;
  3267.          end ;
  3268.          remove click ;
  3269. end .
  3270.  
  3271.  
  3272. Software interrupts
  3273. Ordinarily, a handler installed with set pm interrupt (86) only services software in-
  3274. terrupts that are executed in protected mode; real mode software interrupts can be
  3275.  
  3276.  
  3277.                                                     58
  3278.  
  3279.  
  3280.  
  3281.                                  4.2. PROTECTED MODE MEMORY ORGANIZATION
  3282.  
  3283.  
  3284. redirected by set rm interrupt (88). See also set rm interrupt (88), get rm interrupt
  3285. (77), set pm interrupt (86), get pm interrupt (74), lock data (82), lock code (82),
  3286. enable (70), disable (67), outportb (83) Executing software interrupts Simply execute
  3287. a realintr() call with the desired interrupt number and the supplied register data
  3288. structure. But some of these interrupts require you to supply them a pointer to a
  3289. bu er where they can store data to or obtain data from in memory. These interrupts
  3290. are real mode functions and so they only can access the first Mb of linear address
  3291. space, not FPC's data segment. For this reason FPC supplies a pre-initialized dos
  3292. memory location within the GO32 unit. This bu er is internally used for dos func-
  3293. tions too and so it's contents may change when calling other procedures. It's size can
  3294. be obtained with tb size (89) and it's linear address via transfer bu er (89). An-
  3295. other way is to allocate a completely new dos memory area via the global dos alloc
  3296. (79) function for your use and supply its real mode address. See also: tb size (89),
  3297. transfer bu er (89). global dos alloc (79), global dos free (81), realintr (84) The
  3298. following examples illustrate the use of software interrupts.
  3299. Program s o f t i n t ;
  3300.  
  3301. uses go32 ;
  3302.  
  3303. var r : t r e a l r e g s ;
  3304.  
  3305. begin r . al := $01;
  3306.           r e a l i n t r ( $21 , r ) ;
  3307.           Writeln ( ' DOS v ' , r . al , ' . ' , r . ah , ' detected ' ) ;
  3308. end .
  3309. Program rmpm int ;
  3310.  
  3311. uses cr t , go32 ;
  3312.  
  3313. {$ASMMODE DIRECT}
  3314.  
  3315. var r : t r e a l r e g s ;
  3316.          axreg : Word ;
  3317.  
  3318.          o l d i n t 2 1 h : t s e g i n f o ;
  3319.          newint21h : t s e g i n f o ;
  3320.  
  3321. procedure int21h handler ; assembler ;
  3322. asmcmpw $0x3001, %ax
  3323.     jne CallOld
  3324.     movw $0x3112 , % ax
  3325.     i r e t
  3326.  
  3327. CallOld :
  3328.     ljmp %cs : OLDHANDLER
  3329.  
  3330. OLDHANDLER: . long 0
  3331.                        . word 0
  3332. end ;
  3333.  
  3334. procedure resume ;
  3335.  
  3336.  
  3337.                                                   59
  3338.  
  3339.  
  3340.  
  3341.                             4.2. PROTECTED MODE MEMORY ORGANIZATION
  3342.  
  3343.  
  3344. begin Writeln ;
  3345.          Write ( '-- p r e s s any key to resume --' ) ; readkey ;
  3346.          gotoxy ( 1 , wherey ) ; c l r e o l ;
  3347. end ;
  3348.  
  3349. begin clrscr ;
  3350.          Writeln ( ' Executing r e a l mode i n t e r r u p t ' ) ;
  3351.          resume ;
  3352.          r . ah := $30 ; r . al := $01 ;             r e a l i n t r ( $21 , r ) ;
  3353.          Writeln ( ' DOS v ' , r . al , ' . ' , r . ah , ' detected ' ) ;
  3354.          resume ;
  3355.          Writeln ( ' Executing p r o t e c t e d mode i n t e r r u p t ' ,
  3356.                       ' without our own handler ' ) ;
  3357.          Writeln ;
  3358.          asmmovb $0x30, %ah
  3359.              movb $0x01 , % al
  3360.              int $0x21
  3361.              movw %ax ,        AXREG
  3362.          end ;
  3363.          Writeln ( ' DOS v ' , r . al , ' . ' , r . ah , ' detected ' ) ;
  3364.          resume ;
  3365.          Writeln ( ' As you can see the DPMI hosts ' ,
  3366.                       ' d e f a u l t p r o t e c t e d mode handler ' ) ;
  3367.          Writeln ( ' simply r e d i r e c t s i t to the r e a l mode handler ' ) ;
  3368.          resume ;
  3369.          Writeln ( ' Now exchanging the p r o t e c t e d mode ' ,
  3370.                       ' i n t e r r u p t with our own handler ' ) ;
  3371.          resume ;
  3372.  
  3373.          newint21h . o f f s e t := @int21h handler ;
  3374.          newint21h . segment := get cs ;
  3375.          get pm interrupt ( $21 , o l d i n t 2 1 h ) ;
  3376.          asmmovl OLDINT21H, %eax
  3377.              movl %eax , OLDHANDLER
  3378.              movw 4+ OLDINT21H, % ax
  3379.              movw %ax , 4+OLDHANDLER
  3380.          end ;
  3381.          set pm interrupt ( $21 , newint21h ) ;
  3382.  
  3383.          Writeln ( ' Executing r e a l mode i n t e r r u p t again ' ) ;
  3384.          resume ;
  3385.          r . ah := $30 ; r . al := $01 ; r e a l i n t r ( $21 , r ) ;
  3386.          Writeln ( ' DOS v ' , r . al , ' . ' , r . ah , ' detected ' ) ;
  3387.          Writeln ;
  3388.          Writeln ( ' See , i t didn ' ' t change in any way . ' ) ;
  3389.          resume ;
  3390.          Writeln ( ' Now c a l l i n g p r o t e c t e d mode i n t e r r u p t ' ) ;
  3391.          resume ;
  3392.          asmmovb $0x30, %ah
  3393.  
  3394.                                                60
  3395.  
  3396.  
  3397.  
  3398.                                4.2. PROTECTED MODE MEMORY ORGANIZATION
  3399.  
  3400.  
  3401.                  movb $0x01 , % al
  3402.                  int $0x21
  3403.                  movw %ax ,       AXREG
  3404.           end ;
  3405.           Writeln ( ' DOS v ' , lo ( axreg ) , ' . ' , hi ( axreg ) , ' detected ' ) ;
  3406.           Writeln ;
  3407.           Writeln ( ' Now you can see that there ' ' s ' ,
  3408.                         ' a d i s t i n c t i o n between the two ways of ' ) ;
  3409.           Writeln ( ' c a l l i n g i n t e r r u p t s . . . ' ) ;
  3410.           set pm interrupt ( $21 , o l d i n t 2 1 h ) ;
  3411. end .
  3412.  
  3413.  
  3414. Real mode callbacks
  3415. The callback mechanism can be thought of as the converse of calling a real mode
  3416. procedure (i.e. interrupt), which allows your program to pass information to a real
  3417. mode program, or obtain services from it in a manner that's transparent to the real
  3418. mode program. In order to make a real mode callback available, you must first get
  3419. the real mode callback address of your procedure and the selector and o set of a
  3420. register data structure. This real mode callback address (this is a segment:o set
  3421. address) can be passed to a real mode program via a software interrupt, a dos
  3422. memory block or any other convenient mechanism. When the real mode program
  3423. calls the callback (via a far call), the DPMI host saves the registers contents in
  3424. the supplied register data structure, switches into protected mode, and enters the
  3425. callback routine with the following conditions:
  3426.  
  3427.    * interrupts disabled
  3428.  
  3429.    * %CS:%EIP = 48 bit pointer specified in the original call to get rm callback
  3430.          (74)
  3431.  
  3432.    * %DS:%ESI = 48 bit pointer to to real mode SS:SP
  3433.  
  3434.    * %ES:%EDI = 48 bit pointer of real mode register data structure.
  3435.  
  3436.    * %SS:%ESP = locked protected mode stack
  3437.  
  3438.    * All other registers undefined
  3439.  
  3440. The callback procedure can then extract its parameters from the real mode regis-
  3441. ter data structure and/or copy parameters from the real mode stack to the pro-
  3442. tected mode stack. Recall that the segment register fields of the real mode register
  3443. data structure contain segment or paragraph addresses that are not valid in pro-
  3444. tected mode. Far pointers passed in the real mode register data structure must
  3445. be translated to virtual addresses before they can be used with a protected mode
  3446. program. The callback procedure exits by executing an IRET with the address of
  3447. the real mode register data structure in %ES:%EDI, passing information back to the
  3448. real mode caller by modifying the contents of the real mode register data structure
  3449. and/or manipulating the contents of the real mode stack. The callback procedure is
  3450. responsible for setting the proper address for resumption of real mode execution into
  3451. the real mode register data structure; typically, this is accomplished by extracting
  3452. the return address from the real mode stack and placing it into the %CS:%EIP fields
  3453. of the real mode register data structure. After the IRET, the DPMI host switches
  3454. the CPU back into real mode, loads ALL registers with the contents of the real
  3455. mode register data structure, and finally returns control to the real mode program.
  3456.  
  3457.                                                     61
  3458.  
  3459.  
  3460.  
  3461.                                     4.3. TYPES, VARIABLES AND CONSTANTS
  3462.  
  3463.  
  3464. All variables and code touched by the callback procedure MUST be locked to pre-
  3465. vent page faults. See also: get rm callback (74), free rm callback (71), lock code
  3466. (82), lock data (82)
  3467.  
  3468.  
  3469. 4.3 Types, Variables and Constants
  3470.  
  3471. Constants
  3472. Constants returned by get run mode
  3473.  
  3474. Tells you under what memory environment (e.g. memory manager) the program
  3475. currently runs.
  3476.  
  3477. rm_unknown = 0; { unknown }
  3478. rm_raw        = 1; { raw (without HIMEM) }
  3479. rm_xms        = 2; { XMS (for example with HIMEM, without EMM386) }
  3480. rm_vcpi       = 3; { VCPI (for example HIMEM and EMM386) }
  3481. rm_dpmi       = 4; { DPMI (for example \dos box or 386Max) }
  3482.  
  3483. Note: GO32V2 always creates DPMI programs, so you need a suitable DPMI host
  3484. like CWSDPMI.EXE or a Windows dos box. So you don't need to check it, these
  3485. constants are only useful in GO32V1 mode.
  3486.  
  3487. Processor flags constants
  3488.  
  3489. They are provided for a simple check with the flags identifier in the trealregs type.
  3490. To check a single flag, simply do an AND operation with the flag you want to check.
  3491. It's set if the result is the same as the flag value.
  3492.  
  3493. const carryflag = $001;
  3494. parityflag          = $004;
  3495. auxcarryflag        = $010;
  3496. zeroflag            = $040;
  3497. signflag            = $080;
  3498. trapflag            = $100;
  3499. interruptflag       = $200;
  3500. directionflag       = $400;
  3501. overflowflag        = $800;
  3502.  
  3503.  
  3504. Predefined types
  3505. type tmeminfo = record
  3506.                 available_memory : Longint;
  3507.                 available_pages : Longint;
  3508.                 available_lockable_pages : Longint;
  3509.                 linear_space : Longint;
  3510.                 unlocked_pages : Longint;
  3511.                 available_physical_pages : Longint;
  3512.                 total_physical_pages : Longint;
  3513.                 free_linear_space : Longint;
  3514.                 max_pages_in_paging_file : Longint;
  3515.                 reserved : array[0..2] of Longint;
  3516.    end;
  3517.  
  3518.                                            62
  3519.  
  3520.  
  3521.  
  3522.                                   4.3. TYPES, VARIABLES AND CONSTANTS
  3523.  
  3524.  
  3525.  
  3526.                            Table 4.1: Record description
  3527.  
  3528.   Record entry                      Description
  3529.   available memory                  Largest available free block in bytes.
  3530.   available pages                   Maximum unlocked page allocation in pages
  3531.   available lockable pages          Maximum locked page allocation in pages.
  3532.   linear space                      Linear address space size in pages.
  3533.   unlocked pages                    Total number of unlocked pages.
  3534.   available physical pages          Total number of free pages.
  3535.   total physical pages              Total number of physical pages.
  3536.   free linear space                 Free linear address space in pages.
  3537.   max pages in paging file Size of paging file/partition in pages.
  3538.  
  3539.  
  3540. Holds information about the memory allocation, etc. NOTE: The value of a field is
  3541. -1 (0    h) if the value is unknown, it's only guaranteed, that available memory
  3542. contains a valid value. The size of the pages can be determined by the get page size()
  3543. function.
  3544.  
  3545. type
  3546. trealregs = record
  3547.   case Integer of
  3548.         1: { 32-bit }
  3549.           (EDI, ESI, EBP, Res, EBX, EDX, ECX, EAX: Longint;
  3550.            Flags, ES, DS, FS, GS, IP, CS, SP, SS: Word);
  3551.         2: { 16-bit }
  3552.           (DI, DI2, SI, SI2, BP, BP2, R1, R2: Word;
  3553.            BX, BX2, DX, DX2, CX, CX2, AX, AX2: Word);
  3554.         3: { 8-bit }
  3555.           (stuff: array[1..4] of Longint;
  3556.            BL, BH, BL2, BH2, DL, DH, DL2, DH2, CL,
  3557.            CH, CL2, CH2, AL, AH, AL2, AH2: Byte);
  3558.         4: { Compat }
  3559.           (RealEDI, RealESI, RealEBP, RealRES, RealEBX,
  3560.            RealEDX, RealECX, RealEAX: Longint;
  3561.            RealFlags, RealES, RealDS, RealFS, RealGS,
  3562.            RealIP, RealCS, RealSP, RealSS: Word);
  3563.         end;
  3564.         registers = trealregs;
  3565.  
  3566. These two types contain the data structure to pass register values to a interrupt
  3567. handler or real mode callback.
  3568.  
  3569. type tseginfo = record
  3570.                   offset : Pointer; segment : Word; end;
  3571.  
  3572. This record is used to store a full 48-bit pointer. This may be either a protected
  3573. mode selector:o set address or in real mode a segment:o set address, depending
  3574. on application. See also: Selectors and descriptors, dos memory access, Interrupt
  3575. redirection
  3576.  
  3577.  
  3578.  
  3579.  
  3580.                                          63
  3581.  
  3582.  
  3583.  
  3584.                                                           4.4. FUNCTIONS AND PROCEDURES
  3585.  
  3586.  
  3587.            Variables.
  3588.            var dosmemselector : Word;
  3589.  
  3590.            Selector to the dos memory. The whole dos memory is automatically mapped to
  3591.            this single descriptor at startup. This selector is the recommened way to access dos
  3592.            memory.
  3593.  
  3594.              var int31error : Word;
  3595.  
  3596.            This variable holds the result of a DPMI interrupt call. Any nonzero value must be
  3597.            treated as a critical failure.
  3598.  
  3599.  
  3600.            4.4 Functions and Procedures
  3601.  
  3602.            allocate ldt descriptors
  3603. Declaration: Function allocate ldt descriptors (count : Word) : Word;
  3604.  
  3605. Description: Allocates a number of new descriptors. Parameters:
  3606.  
  3607.            count: specifies the number of requested unique descriptors.
  3608.  
  3609.            Return value: The base selector. Notes: The descriptors allocated must be initial-
  3610.            ized by the application with other function calls. This function returns descriptors
  3611.            with a limit and size value set to zero. If more than one descriptor was requested,
  3612.            the function returns a base selector referencing the first of a contiguous array of
  3613.            descriptors. The selector values for subsequent descriptors in the array can be
  3614.            calculated by adding the value returned by the get next selector increment value
  3615.            (73) function.
  3616.  
  3617.     Errors: Check the int31error variable.
  3618.  
  3619.   See also: free ldt descriptor (70), get next selector increment value (73), segment to descriptor
  3620.            (85), create code segment alias descriptor (67), set segment limit (88), set segment base address
  3621.            (88)
  3622.  
  3623.            Program sel des ;
  3624.  
  3625.            uses c rt ,
  3626.                    go32 ;
  3627.  
  3628.            const maxx = 80;
  3629.                      maxy = 25;
  3630.                       b y t e s p e r c e l l = 2;
  3631.                       s c r e e n s i z e = maxx   maxy   b y t e s p e r c e l l ;
  3632.  
  3633.                      linB8000 = $B800   1 6 ;
  3634.  
  3635.            type s t r i n g 8 0 = st r in g [ 8 0 ] ;
  3636.  
  3637.            var text save : array [0.. screensize -1] of byte ;
  3638.                    text oldx , text oldy : Word ;
  3639.  
  3640.  
  3641.                                                          64
  3642.  
  3643.  
  3644.  
  3645.                                                           4.4. FUNCTIONS AND PROCEDURES
  3646.  
  3647.  
  3648.          t e x t s e l : Word ;
  3649.  
  3650. procedure s t a t u s ( s : s t r i n g 8 0 ) ;
  3651. begin
  3652.    gotoxy ( 1 , 1 ) ;
  3653.     c l r e o l ;
  3654.    write ( s ) ;
  3655.    readkey ;
  3656. end ;
  3657.  
  3658. procedure s e l i n f o ( s e l : Word ) ;
  3659. begin
  3660. gotoxy ( 1 , 2 4 ) ;
  3661. c l r e o l ;
  3662. writeln ( ' D e s c r i p t o r base address : $ ' ,
  3663.                   h e x s t r ( get segment base address ( s e l ) , 8 ) ) ;
  3664. c l r e o l ;
  3665. write ( ' D e s c r i p t o r l i m i t : ' ,
  3666.                  get segment limit ( s e l ) ) ;
  3667. end ;
  3668.  
  3669. function makechar ( ch : char ; c o l o r : byte ) : Word ;
  3670. begin result := byte (ch) or ( color shl 8);
  3671. end ;
  3672.  
  3673. begin
  3674. seg move ( dosmemselector , linB8000 ,
  3675.                      get ds , l o n g i n t ( @text save ) , s c r e e n s i z e ) ;
  3676. text oldx := wherex ; text oldy := wherey ;
  3677. s e g f i l l w o r d ( dosmemselector , linB8000 ,
  3678.                            s c r e e n s i z e div 2 ,
  3679.                            makechar ( ' ' , Black or ( Black shl 4 ) ) ) ;
  3680. s t a t u s ( ' Creating s e l e c t o r ' +
  3681.                   ' ' ' t e x t s e l ' ' to a part of text screen memory ' ) ;
  3682. t e x t s e l := a l l o c a t e l d t d e s c r i p t o r s ( 1 ) ;
  3683. set segment base address ( t e x t s e l , linB8000
  3684.                                                   + b y t e s p e r c e l l   maxx   1 ) ;
  3685. set segment limit ( t e x t s e l ,
  3686.                                      s c r e e n s i z e -1-b y t e s p e r c e l l  maxx  3);
  3687. s e l i n f o ( t e x t s e l ) ;
  3688.  
  3689. s t a t u s ( ' and c l e a r i n g e n t i r e memory ' +
  3690.                  ' s e l e c t e d by ' ' t e x t s e l ' ' d e s c r i p t o r ' ) ;
  3691. s e g f i l l w o r d ( t e x t s e l , 0 ,
  3692.                            ( get segment limit ( t e x t s e l )+1) div 2 ,
  3693.                            makechar ( ' ' , LightBlue shl 4 ) ) ;
  3694.  
  3695. s t a t u s ( ' Notice that only the memory d e s c r i b e d ' +
  3696.                  ' by the d e s c r i p t o r changed , nothing e l s e ' ) ;
  3697.  
  3698. s t a t u s ( ' Now reducing i t ' ' s l i m i t and base and ' +
  3699.                  ' s e t t i n g i t ' ' s d e s c r i b e d memory ' ) ;
  3700. set segment base address ( t e x t s e l ,
  3701.  
  3702.                                                         65
  3703.  
  3704.  
  3705.  
  3706.                                                                     4.4. FUNCTIONS AND PROCEDURES
  3707.  
  3708.  
  3709.                     get segment base address ( t e x t s e l )
  3710.                     + b y t e s p e r c e l l   maxx ) ;
  3711.            set segment limit ( t e x t s e l ,
  3712.                     get segment limit ( t e x t s e l )
  3713.                     - b y t e s p e r c e l l   maxx   2 ) ;
  3714.            s e l i n f o ( t e x t s e l ) ;
  3715.            s t a t u s ( ' Notice that the base addr i n c r e a s e d by ' +
  3716.                         ' one l i n e but the l i m i t decreased by 2 l i n e s ' ) ;
  3717.            s t a t u s ( ' This should give you the hint that the ' +
  3718.                         ' l i m i t i s r e l a t i v e to the base ' ) ;
  3719.            s e g f i l l w o r d ( t e x t s e l , 0 ,
  3720.                                    ( get segment limit ( t e x t s e l )+1) div 2 ,
  3721.                                    makechar (#176, LightMagenta or Brown shl 4 ) ) ;
  3722.  
  3723.            s t a t u s ( ' Now l e t ' ' s get crazy and copy 10 l i n e s ' +
  3724.                         ' of data from the p r e v i o u s l y saved screen ' ) ;
  3725.            seg move ( get ds , l o n g i n t ( @text save ) ,
  3726.                             t e x t s e l , maxx   b y t e s p e r c e l l   2 ,
  3727.                            maxx   b y t e s p e r c e l l   1 0 ) ;
  3728.  
  3729.            s t a t u s ( ' At l a s t f r e e i n g the d e s c r i p t o r and ' +
  3730.                         ' r e s t o r i n g the old screen contents . . ' ) ;
  3731.            s t a t u s ( ' I hope t h i s l i t t l e program may give ' +
  3732.                         ' you some h i n t s on working with d e s c r i p t o r s ' ) ;
  3733.            f r e e l d t d e s c r i p t o r ( t e x t s e l ) ;
  3734.            seg move ( get ds , l o n g i n t ( @text save ) ,
  3735.                             dosmemselector , linB8000 , s c r e e n s i z e ) ;
  3736.            gotoxy ( text oldx , text oldy ) ;
  3737.            end .
  3738.  
  3739.  
  3740.            allocate memory block
  3741. Declaration: Function allocate memory block (size:Longint) : Longint;
  3742.  
  3743. Description: Allocates a block of linear memory. Parameters:
  3744.  
  3745.            size: Size of requested linear memory block in bytes.
  3746.  
  3747.            Returned values: blockhandle - the memory handle to this memory block. Linear
  3748.            address of the requested memory. Notes: WARNING: According to my DPMI
  3749.            docs this function is not implemented correctly. Normally you should also get a
  3750.            blockhandle to this block after successful operation. This handle is used to free the
  3751.            memory block afterwards or use this handle for other purposes. So this block can't
  3752.            be deallocated and is henceforth unusuable ! This function doesn't allocate any
  3753.            descriptors for this block, it's the applications resposibility to allocate and initialize
  3754.            for accessing this memory.
  3755.  
  3756.      Errors: Check the int31error variable.
  3757.  
  3758.   See also: free memory block (71)
  3759.  
  3760.  
  3761.            copyfromdos
  3762. Declaration: Procedure copyfromdos (var addr; len : Longint);
  3763.  
  3764.  
  3765.                                                                66
  3766.  
  3767.  
  3768.  
  3769.                                                      4.4. FUNCTIONS AND PROCEDURES
  3770.  
  3771.  
  3772. Description: Copies data from the pre-allocated dos memory transfer bu er to the heap. Pa-
  3773.            rameters:
  3774.  
  3775.            addr: data to copy to.
  3776.            len: number of bytes to copy to heap.
  3777.  
  3778.            Notes: Can only be used in conjunction with the dos memory transfer bu er.
  3779.  
  3780.      Errors: Check the int31error variable.
  3781.  
  3782.    See also: tb size (89), transfer bu er (89), copytodos (67)
  3783.  
  3784.  
  3785.            copytodos
  3786. Declaration: Procedure copytodos (var addr; len : Longint);
  3787.  
  3788. Description: Copies data from heap to the pre-allocated dos memory bu er. Parameters:
  3789.  
  3790.            addr: data to copy from.
  3791.            len: number of bytes to copy to dos memory bu er.
  3792.  
  3793.            Notes: This function fails if you try to copy more bytes than the transfer bu er is
  3794.            in size. It can only be used in conjunction with the transfer bu er.
  3795.  
  3796.      Errors: Check the int31error variable.
  3797.  
  3798.    See also: tb size (89), transfer bu er (89), copyfromdos (66)
  3799.  
  3800.  
  3801.            create code segment alias descriptor
  3802. Declaration: Function create code segment alias descriptor (seg : Word) : Word;
  3803.  
  3804. Description: Creates a new descriptor that has the same base and limit as the specified descrip-
  3805.            tor. Parameters:
  3806.  
  3807.            seg: selector.
  3808.  
  3809.            Return values: The data selector (alias). Notes: In e ect, the function returns a
  3810.            copy of the descriptor. The descriptor alias returned by this function will not track
  3811.            changes to the original descriptor. In other words, if an alias is created with this
  3812.            function, and the base or limit of the original segment is then changed, the two
  3813.            descriptors will no longer map the same memory.
  3814.  
  3815.      Errors: Check the int31error variable.
  3816.  
  3817.    See also: allocate ldt descriptors (64), set segment limit (88), set segment base address
  3818.            (88)
  3819.  
  3820.  
  3821.            disable
  3822. Declaration: Procedure disable ;
  3823.  
  3824. Description: Disables all hardware interrupts by execution a CLI instruction. Parameters:
  3825.            None.
  3826.  
  3827.      Errors: None.
  3828.  
  3829.    See also: enable (70)
  3830.  
  3831.  
  3832.                                                     67
  3833.  
  3834.  
  3835.  
  3836.                                                                   4.4. FUNCTIONS AND PROCEDURES
  3837.  
  3838.  
  3839.            dosmemfillchar
  3840. Declaration: Procedure dosmemfillchar (seg, ofs : Word; count : Longint; c : char);
  3841.  
  3842. Description: Sets a region of dos memory to a specific byte value. Parameters:
  3843.  
  3844.            seg: real mode segment.
  3845.            ofs: real mode o set.
  3846.            count: number of bytes to set.
  3847.            c: value to set memory to.
  3848.  
  3849.            Notes: No range check is performed.
  3850.  
  3851.      Errors: None.
  3852.  
  3853.   See also: dosmemput (70), dosmemget (69), dosmemmove (69)dosmemmove, dosmemfillword
  3854.            (69), seg move (86), seg fillchar (84), seg fillword (85)
  3855.  
  3856.            Program textmess ;
  3857.  
  3858.            uses c r t , go32 ;
  3859.  
  3860.            const columns = 80;
  3861.                        rows = 25;
  3862.                        s c r e e n s i z e = rows   columns  2;
  3863.  
  3864.                        text = ' ! Hello world ! ' ;
  3865.  
  3866.            var t e x t o f s : Longint ;
  3867.                     save screen : array [ 0 . . s c r e e n s i z e -1] of byte ;
  3868.                     curx , cury : I n t e g e r ;
  3869.  
  3870.            begin randomize;
  3871.                       dosmemget ( $B800 , 0 , save screen , s c r e e n s i z e ) ;
  3872.                       curx := wherex ; cury := wherey ;
  3873.                       gotoxy ( 1 , 1 ) ; Write ( text ) ;
  3874.                       t e x t o f s := s c r e e n s i z e + length ( text ) 2;
  3875.                       dosmemmove ( $B800 , 0 , $B800 , t e x t o f s , length ( text )   2 ) ;
  3876.                       d o s m e m f i l l c h a r ( $B800 , 0 , s c r e e n s i z e , #0);
  3877.                       while ( not keypressed ) do
  3878.                          begin
  3879.                          d o s m e m f i l l c h a r ( $B800 ,
  3880.                                                     t e x t o f s + random( length ( text )) 2 + 1,
  3881.                                                     1 , char ( random ( 2 5 5 ) ) ) ;
  3882.                          dosmemmove ( $B800 , t e x t o f s , $B800 ,
  3883.                                             random( columns ) 2+random( rows )  columns  2,
  3884.                                             length ( text )   2 ) ;
  3885.                                 delay ( 1 ) ;
  3886.                       end ;
  3887.                       readkey ;
  3888.                       readkey ;
  3889.                       dosmemput ( $B800 , 0 , save screen , s c r e e n s i z e ) ;
  3890.                       gotoxy ( curx , cury ) ;
  3891.            end .
  3892.  
  3893.  
  3894.                                                                   68
  3895.  
  3896.  
  3897.  
  3898.                                                          4.4. FUNCTIONS AND PROCEDURES
  3899.  
  3900.  
  3901.            dosmemfillword
  3902. Declaration: Procedure dosmemfillword (seg,ofs : Word; count : Longint; w : Word);
  3903. Description: Sets a region of dos memory to a specific word value. Parameters:
  3904.            seg: real mode segment.
  3905.            ofs: real mode o set.
  3906.            count: number of words to set.
  3907.            w: value to set memory to.
  3908.            Notes: No range check is performed.
  3909.     Errors: None.
  3910.   See also: dosmemput (70), dosmemget (69), dosmemmove (69), dosmemfillchar (68), seg move
  3911.            (86), seg fillchar (84), seg fillword (85)
  3912.  
  3913.  
  3914.            dosmemget
  3915. Declaration: Procedure dosmemget (seg : Word; ofs : Word; var data; count : Longint);
  3916. Description: Copies data from the dos memory onto the heap. Parameters:
  3917.            seg: source real mode segment.
  3918.            ofs: source real mode o set.
  3919.            data: destination.
  3920.            count: number of bytes to copy.
  3921.            Notes: No range checking is performed.
  3922.     Errors: None.
  3923.   See also: dosmemput (70), dosmemmove (69), dosmemfillchar (68), dosmemfillword (69), seg move
  3924.            (86), seg fillchar (84), seg fillword (85)
  3925.  
  3926.            For an example, see global dos alloc (79).
  3927.  
  3928.  
  3929.            dosmemmove
  3930. Declaration: Procedure dosmemmove (sseg, sofs, dseg, dofs : Word; count : Longint);
  3931. Description: Copies count bytes of data between two dos real mode memory locations. Param-
  3932.            eters:
  3933.            sseg: source real mode segment.
  3934.            sofs: source real mode o set.
  3935.            dseg: destination real mode segment.
  3936.            dofs: destination real mode o set.
  3937.            count: number of bytes to copy.
  3938.            Notes: No range check is performed in any way.
  3939.     Errors: None.
  3940.   See also: dosmemput (70), dosmemget (69), dosmemfillchar (68), dosmemfillword (69) seg move
  3941.            (86), seg fillchar (84), seg fillword (85)
  3942.  
  3943.            For an example, see seg fillchar (84).
  3944.  
  3945.                                                          69
  3946.  
  3947.  
  3948.  
  3949.                                                           4.4. FUNCTIONS AND PROCEDURES
  3950.  
  3951.  
  3952.             dosmemput
  3953. Declaration: Procedure dosmemput (seg : Word; ofs : Word; var data; count : Longint);
  3954.  
  3955. Description: Copies heap data to dos real mode memory. Parameters:
  3956.  
  3957.             seg: destination real mode segment.
  3958.             ofs: destination real mode o set.
  3959.             data: source.
  3960.             count: number of bytes to copy.
  3961.  
  3962.             Notes: No range checking is performed.
  3963.  
  3964.      Errors: None.
  3965.  
  3966.    See also: dosmemget (69), dosmemmove (69), dosmemfillchar (68), dosmemfillword (69), seg move
  3967.             (86), seg fillchar (84), seg fillword (85)
  3968.  
  3969.             For an example, see global dos alloc (79).
  3970.  
  3971.  
  3972.             enable
  3973. Declaration: Procedure enable ;
  3974.  
  3975. Description: Enables all hardware interrupts by executing a STI instruction. Parameters: None.
  3976.  
  3977.      Errors: None.
  3978.  
  3979.    See also: disable (67)
  3980.  
  3981.  
  3982.             free ldt descriptor
  3983. Declaration: Function free ldt descriptor (des : Word) : boolean;
  3984.  
  3985. Description: Frees a previously allocated descriptor. Parameters:
  3986.  
  3987.             des: The descriptor to be freed.
  3988.  
  3989.             Return value: True if successful, False otherwise. Notes: After this call this selector
  3990.             is invalid and must not be used for any memory operations anymore. Each descriptor
  3991.             allocated with allocate ldt descriptors (64) must be freed individually with this
  3992.             function, even if it was previously allocated as a part of a contiguous array of
  3993.             descriptors.
  3994.  
  3995.      Errors: Check the int31error variable.
  3996.  
  3997.    See also: allocate ldt descriptors (64), get next selector increment value (73)
  3998.  
  3999.             For an example, see allocate ldt descriptors (64).
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.                                                           70
  4009.  
  4010.  
  4011.  
  4012.                                                      4.4. FUNCTIONS AND PROCEDURES
  4013.  
  4014.  
  4015.            free memory block
  4016. Declaration: Function free memory block (blockhandle : Longint) : boolean;
  4017.  
  4018. Description: Frees a previously allocated memory block. Parameters:
  4019.  
  4020.            blockhandle: the handle to the memory area to free.
  4021.  
  4022.            Return value: True if successful, false otherwise. Notes: Frees memory that was
  4023.            previously allocated with allocate memory block (66) . This function doesn't free
  4024.            any descriptors mapped to this block, it's the application's responsibility.
  4025.  
  4026.      Errors: Check int31error variable.
  4027.  
  4028.    See also: allocate memory block (66)
  4029.  
  4030.  
  4031.            free rm callback
  4032. Declaration: Function free rm callback (var intaddr : tseginfo) : boolean;
  4033.  
  4034. Description: Releases a real mode callback address that was previously allocated with the
  4035.            get rm callback (74) function. Parameters:
  4036.  
  4037.            intaddr: real mode address bu er returned by get rm callback (74) .
  4038.  
  4039.            Return values: True if successful, False if not
  4040.  
  4041.      Errors: Check the int31error variable.
  4042.  
  4043.    See also: set rm interrupt (88), get rm callback (74)
  4044.  
  4045.            For an example, see get rm callback (74).
  4046.  
  4047.  
  4048.            get cs
  4049. Declaration: Function get cs : Word;
  4050.  
  4051. Description: Returns the cs selector. Parameters: None. Return values: The content of the cs
  4052.            segment register.
  4053.  
  4054.      Errors: None.
  4055.  
  4056.    See also: get ds (72), get ss (79)
  4057.  
  4058.            For an example, see set pm interrupt (86).
  4059.  
  4060.  
  4061.            get descriptor access rights
  4062. Declaration: Function get descriptor access rights (d : Word) : Longint;
  4063.  
  4064. Description: Gets the access rights of a descriptor. Parameters:
  4065.  
  4066.            d selector to descriptor.
  4067.  
  4068.            Return value: Access rights bit field.
  4069.  
  4070.      Errors: Check the int31error variable.
  4071.  
  4072.    See also: set descriptor access rights (86)
  4073.  
  4074.  
  4075.                                                      71
  4076.  
  4077.  
  4078.  
  4079.                                                      4.4. FUNCTIONS AND PROCEDURES
  4080.  
  4081.  
  4082.            get ds
  4083. Declaration: Function get ds : Word;
  4084.  
  4085. Description: Returns the ds selector. Parameters: None. Return values: The content of the ds
  4086.            segment register.
  4087.  
  4088.      Errors: None.
  4089.  
  4090.    See also: get cs (71), get ss (79)
  4091.  
  4092.  
  4093.            get linear addr
  4094. Declaration: Function get linear addr (phys addr : Longint; size : Longint) : Longint;
  4095.  
  4096. Description: Converts a physical address into a linear address. Parameters:
  4097.  
  4098.            phys addr: physical address of device.
  4099.            size: Size of region to map in bytes.
  4100.  
  4101.            Return value: Linear address that can be used to access the physical memory. Notes:
  4102.            It's the applications resposibility to allocate and set up a descriptor for access to
  4103.            the memory. This function shouldn't be used to map real mode addresses.
  4104.  
  4105.      Errors: Check the int31error variable.
  4106.  
  4107.    See also: allocate ldt descriptors (64), set segment limit (88), set segment base address
  4108.            (88)
  4109.  
  4110.  
  4111.            get meminfo
  4112. Declaration: Function get meminfo (var meminfo : tmeminfo) : boolean;
  4113.  
  4114. Description: Returns information about the amount of available physical memory, linear address
  4115.            space, and disk space for page swapping. Parameters:
  4116.  
  4117.            meminfo: bu er to fill memory information into.
  4118.  
  4119.            Return values: Due to an implementation bug this function always returns False,
  4120.            but it always succeeds. Notes: Only the first field of the returned structure is
  4121.            guaranteed to contain a valid value. Any fields that are not supported by the DPMI
  4122.            host will be set by the host to -1 (0FFFFFFFFH) to indicate that the information
  4123.            is not available. The size of the pages used by the DPMI host can be obtained with
  4124.            the get page size (74) function.
  4125.  
  4126.      Errors: Check the int31error variable.
  4127.  
  4128.    See also: get page size (74)
  4129.  
  4130.            Program meminf ;
  4131.  
  4132.            uses go32 ;
  4133.  
  4134.            var meminfo : tmeminfo ;
  4135.  
  4136.            begin
  4137.            get meminfo ( meminfo ) ;
  4138.            i f ( i n t 3 1 e r r o r <> 0) then
  4139.  
  4140.                                                     72
  4141.  
  4142.  
  4143.  
  4144.                                                              4.4. FUNCTIONS AND PROCEDURES
  4145.  
  4146.  
  4147.              begin
  4148.              Writeln ( ' Error g e t t i n g DPMI memory i n f o r m a t i o n . . . Halting ' ) ;
  4149.              Writeln ( ' DPMI e r r o r number : ' , i n t 3 1 e r r o r ) ;
  4150.              end
  4151.             else
  4152.              with meminfo do
  4153.                 begin
  4154.                 Writeln ( ' Largest a v a i l a b l e f r e e block : ' ,
  4155.                             available memory div 1 0 2 4 , ' kbytes ' ) ;
  4156.                 i f ( a v a i l a b l e p a g e s <> -1) then
  4157.                     Writeln ( ' Maximum a v a i l a b l e unlocked pages : ' ,
  4158.                                 a v a i l a b l e p a g e s ) ;
  4159.                 i f ( a v a i l a b l e l o c k a b l e p a g e s <> -1) then
  4160.                     Writeln ( ' Maximum l o c k a b l e a v a i l a b l e pages : ' ,
  4161.                                 a v a i l a b l e l o c k a b l e p a g e s ) ;
  4162.                 i f ( l i n e a r s p a c e <> -1) then
  4163.                     Writeln ( ' Li near address space s i z e : ' ,
  4164.                                l i n e a r s p a c e   get page size div 1024,
  4165.                                ' kbytes ' ) ;
  4166.                 i f ( unlocked pages <> -1) then
  4167.                     Writeln ( ' Total number of unlocked pages : ' ,
  4168.                                unlocked pages ) ;
  4169.                 i f ( a v a i l a b l e p h y s i c a l p a g e s <> -1) then
  4170.                     Writeln ( ' Total number of f r e e pages : ' ,
  4171.                                a v a i l a b l e p h y s i c a l p a g e s ) ;
  4172.                 i f ( t o t a l p h y s i c a l p a g e s <> -1) then
  4173.                     Writeln ( ' Total number of p h y s i c a l pages : ' ,
  4174.                                t o t a l p h y s i c a l p a g e s ) ;
  4175.                 i f ( f r e e l i n e a r s p a c e <> -1) then
  4176.                     Writeln ( ' Free l i n e a r address space : ' ,
  4177.                                f r e e l i n e a r s p a c e   get page size div 1024,
  4178.                                ' kbytes ' ) ;
  4179.                 i f ( max pages in paging file <> -1) then
  4180.                     Writeln ( ' Maximum s i z e of paging f i l e : ' ,
  4181.                                 max pages in paging file   get page size div 1024,
  4182.                                 ' kbytes ' ) ;
  4183.               end ;
  4184.            end .
  4185.  
  4186.  
  4187.            get next selector increment value
  4188. Declaration: Function get next selector increment value : Word;
  4189.  
  4190. Description: Returns the selector increment value when allocating multiple subsequent descrip-
  4191.            tors via allocate ldt descriptors (64). Parameters: None. Return value: Selector
  4192.            increment value. Notes: Because allocate ldt descriptors (64) only returns the se-
  4193.            lector for the first descriptor and so the value returned by this function can be used
  4194.            to calculate the selectors for subsequent descriptors in the array.
  4195.  
  4196.      Errors: Check the int31error variable.
  4197.  
  4198.    See also: allocate ldt descriptors (64), free ldt descriptor (70)
  4199.  
  4200.  
  4201.  
  4202.                                                             73
  4203.  
  4204.  
  4205.  
  4206.                                                      4.4. FUNCTIONS AND PROCEDURES
  4207.  
  4208.  
  4209.            get page size
  4210. Declaration: Function get page size : Longint;
  4211.  
  4212. Description: Returns the size of a single memory page. Return value: Size of a single page in
  4213.            bytes. Notes: The returned size is typically 4096 bytes.
  4214.  
  4215.      Errors: Check the int31error variable.
  4216.  
  4217.    See also: get meminfo (72)
  4218.  
  4219.            For an example, see get meminfo (72).
  4220.  
  4221.  
  4222.            get pm interrupt
  4223. Declaration: Function get pm interrupt (vector : byte; var intaddr : tseginfo) :
  4224.            boolean;
  4225.  
  4226. Description: Returns the address of a current protected mode interrupt handler. Parameters:
  4227.  
  4228.            vector: interrupt handler number you want the address to.
  4229.            intaddr: bu er to store address.
  4230.  
  4231.            Return values: True if successful, False if not. Notes: The returned address is a
  4232.            protected mode selector:o set address.
  4233.  
  4234.      Errors: Check the int31error variable.
  4235.  
  4236.    See also: set pm interrupt (86), set rm interrupt (88), get rm interrupt (77)
  4237.  
  4238.            For an example, see set pm interrupt (86).
  4239.  
  4240.  
  4241.            get rm callback
  4242. Declaration: Function get rm callback (pm func : pointer; const reg : trealregs;
  4243.            var rmcb: tseginfo) : boolean;
  4244.  
  4245. Description: Returns a unique real mode segment:offset address, known as a "real mode
  4246.            callback," that will transfer control from real mode to a protected mode procedure.
  4247.            Parameters:
  4248.  
  4249.            pm func: pointer to the protected mode callback function.
  4250.            reg: supplied registers structure.
  4251.            rmcb: bu er to real mode address of callback function.
  4252.  
  4253.            Return values: True if successful, otherwise False. Notes: Callback addresses
  4254.            obtained with this function can be passed by a protected mode program for example
  4255.            to an interrupt handler, device driver, or TSR, so that the real mode program can
  4256.            call procedures within the protected mode program or notify the protected mode
  4257.            program of an event. The contents of the supplied regs structure is not valid after
  4258.            function call, but only at the time of the actual callback.
  4259.  
  4260.      Errors: Check the int31error variable.
  4261.  
  4262.    See also: free rm callback (71)
  4263.  
  4264.  
  4265.  
  4266.                                                      74
  4267.  
  4268.  
  4269.  
  4270.                                                   4.4. FUNCTIONS AND PROCEDURES
  4271.  
  4272.  
  4273. Program c a l l b a c k ;
  4274.  
  4275. uses c r t ,
  4276.           go32 ;
  4277.  
  4278. const mouseint = $33 ;
  4279.  
  4280. var mouse regs                : t r e a l r e g s ;
  4281.          mouse seginfo : t s e g i n f o ;
  4282.  
  4283. var mouse numbuttons : l o n g i n t ;
  4284.  
  4285.          mouse action : word ;
  4286.          mouse x , mouse y : Word ;
  4287.          mouse b : Word ;
  4288.  
  4289.          u s e r p r o c i n s t a l l e d : Longbool ;
  4290.          u s e r p r o c l en g th : Longint ;
  4291.          userproc proc : p o i n t e r ;
  4292.  
  4293. {$ASMMODE DIRECT}
  4294. procedure c a l l b a c k h a n d l e r ; assembler ;
  4295. asmpushw %es
  4296.     pushw %ds
  4297.     pushl % edi
  4298.     pushl % e s i
  4299.     cmpl $1 ,         USERPROC INSTALLED
  4300.     je . LNoCallback
  4301.     pushal
  4302.     movw %es , % ax
  4303.     movw %ax , % ds
  4304.     movw U GO32 DOSMEMSELECTOR, % ax
  4305.     movw %ax , % fs
  4306.     c a l l   USERPROC PROC
  4307.     popal
  4308. . LNoCallback :
  4309.  
  4310.     popl % e s i
  4311.     popl % edi
  4312.     popw %ds
  4313.     popw %es
  4314.  
  4315.     movl (% e s i ), % eax
  4316.     movl %eax , % es : 42(% edi )
  4317.     addw $4 , % es : 46(% edi )
  4318.     i r e t
  4319. end ;
  4320.  
  4321. procedure mouse dummy ; begin end ;
  4322.  
  4323. procedure t e x t u s e r p r o c ;
  4324. begin mouse b := mouse regs . bx;
  4325.  
  4326.                                                   75
  4327.  
  4328.  
  4329.  
  4330.                                                        4.4. FUNCTIONS AND PROCEDURES
  4331.  
  4332.  
  4333.          mouse x := ( mouse regs . cx shr 3 ) + 1 ;
  4334.          mouse y := ( mouse regs . dx shr 3 ) + 1 ;
  4335. end ;
  4336.  
  4337. procedure i n s t a l l m o u s e ( u s e r p r o c : p o i n t e r ;
  4338.                                               u s e r p r o c l e n : l o n g i n t ) ;
  4339. var r : t r e a l r e g s ;
  4340. begin r . eax := $0; realintr (mouseint , r );
  4341.          i f ( r . eax <> $FFFF ) then begin
  4342.               Writeln ( ' No M i r c o s o f t compatible mouse found ' ) ;
  4343.               Write ( ' A M i r c o s o f t compatible mouse d r i v e r i s ' ) ;
  4344.               writeln ( ' n e c e s s a r y to run t h i s example ' ) ;
  4345.               halt ;
  4346.          end ;
  4347.          i f ( r . bx = $ f f f f ) then mouse numbuttons := 2
  4348.          else mouse numbuttons := r . bx ;
  4349.          Writeln ( mouse numbuttons ,
  4350.                         ' button M i r c o s o f t compatible mouse found . ' ) ;
  4351.          i f ( u s e r p r o c <> n i l ) then begin
  4352.               userproc proc := u s e r p r o c ;
  4353.               u s e r p r o c i n s t a l l e d := true ;
  4354.               u se r p r o c l en g th := u s e r p r o c l e n ;
  4355.               lock code ( userproc proc , u s er p r o c l en g t h ) ;
  4356.          end else begin
  4357.                   userproc proc := n i l ;
  4358.                   u s e r p ro c l e n g th : = 0 ;
  4359.                   u s e r p r o c i n s t a l l e d := f a l s e ;
  4360.          end ;
  4361.          lock data ( mouse x , s i z e o f ( mouse x ) ) ;
  4362.          lock data ( mouse y , s i z e o f ( mouse y ) ) ;
  4363.          lock data ( mouse b , s i z e o f ( mouse b ) ) ;
  4364.          lock data ( mouse action , s i z e o f ( mouse action ) ) ;
  4365.  
  4366.          lock data ( u s e r p r o c i n s t a l l e d , s i z e o f ( u s e r p r o c i n s t a l l e d ) ) ;
  4367.          lock data ( @userproc proc , s i z e o f ( userproc proc ) ) ;
  4368.  
  4369.          lock data ( mouse regs , s i z e o f ( mouse regs ) ) ;
  4370.          lock data ( mouse seginfo , s i z e o f ( mouse seginfo ) ) ;
  4371.          lock code ( @callback handler ,
  4372.                             l o n g i n t ( @mouse dummy)
  4373.                              - l o n g i n t ( @callback handler ) ) ;
  4374.          get rm callback ( @callback handler , mouse regs , mouse seginfo ) ;
  4375.          r . eax := $0c ; r . ecx := $7f ; r . edx := l o n g i n t ( mouse seginfo . o f f s e t ) ;
  4376.          r . es := mouse seginfo . segment ;
  4377.          r e a l i n t r ( mouseint , r ) ;
  4378.          r . eax := $01 ;
  4379.          r e a l i n t r ( mouseint , r ) ;
  4380. end ;
  4381.  
  4382. procedure remove mouse ;
  4383. var r : t r e a l r e g s ;
  4384. begin r . eax := $02 ; realintr (mouseint , r );
  4385.  
  4386.                                                      76
  4387.  
  4388.  
  4389.  
  4390.                                                               4.4. FUNCTIONS AND PROCEDURES
  4391.  
  4392.  
  4393.                     r . eax := $0c ; r . ecx : = 0 ; r . edx : = 0 ; r . es : = 0 ;
  4394.                     r e a l i n t r ( mouseint , r ) ;
  4395.                     free rm callback ( mouse seginfo ) ;
  4396.                     i f ( u s e r p r o c i n s t a l l e d ) then begin
  4397.                         unlock code ( userproc proc , u s e r p r oc le n gt h ) ;
  4398.                         userproc proc := n i l ;
  4399.                         u s e r p ro c l en g th : = 0 ;
  4400.                         u s e r p r o c i n s t a l l e d := f a l s e ;
  4401.                     end ;
  4402.                     unlock data ( mouse x , s i z e o f ( mouse x ) ) ;
  4403.                     unlock data ( mouse y , s i z e o f ( mouse y ) ) ;
  4404.                     unlock data ( mouse b , s i z e o f ( mouse b ) ) ;
  4405.                     unlock data ( mouse action , s i z e o f ( mouse action ) ) ;
  4406.  
  4407.                     unlock data ( @userproc proc , s i ze o f ( userproc proc ) ) ;
  4408.                     unlock data ( u s e r p r o c i n s t a l l e d ,
  4409.                                        s iz e o f ( u s e r p r o c i n s t a l l e d ) ) ;
  4410.  
  4411.                     unlock data ( mouse regs , s i z e o f ( mouse regs ) ) ;
  4412.                     unlock data ( mouse seginfo , s i z e o f ( mouse seginfo ) ) ;
  4413.                     unlock code ( @callback handler ,
  4414.                                        l o n g i n t ( @mouse dummy)
  4415.                                          - l o n g i n t ( @callback handler ) ) ;
  4416.                     f i l l c h a r ( mouse seginfo , s i z e o f ( mouse seginfo ) , 0 ) ;
  4417.            end ;
  4418.  
  4419.  
  4420.            begin install mouse ( @textuserproc , 400);
  4421.                     Writeln ( ' Press any key to e x i t . . . ' ) ;
  4422.                     while ( not keypressed ) do begin
  4423.                              { w r i t e mouse s t a t e i n f o }
  4424.                              gotoxy ( 1 , wherey ) ;
  4425.                              write ( ' MouseX : ' , mouse x : 2 ,
  4426.                                        ' MouseY : ' , mouse y : 2 ,
  4427.                                        ' Buttons : ' , mouse b : 2 ) ;
  4428.                     end ;
  4429.                     remove mouse ;
  4430.            end .
  4431.  
  4432.  
  4433.            get rm interrupt
  4434. Declaration: Function get rm interrupt (vector : byte; var intaddr : tseginfo) :
  4435.            boolean;
  4436.  
  4437. Description: Returns the contents of the current machine's real mode interrupt vector for the
  4438.            specified interrupt. Parameters:
  4439.  
  4440.            vector: interrupt vector number.
  4441.            intaddr: bu er to store real mode segment:offset address.
  4442.  
  4443.            Return values: True if successful, False otherwise. Notes: The returned address is
  4444.            a real mode segment address, which isn't valid in protected mode.
  4445.  
  4446.  
  4447.                                                              77
  4448.  
  4449.  
  4450.  
  4451.                                                        4.4. FUNCTIONS AND PROCEDURES
  4452.  
  4453.  
  4454.      Errors: Check the int31error variable.
  4455.  
  4456.    See also: set rm interrupt (88), set pm interrupt (86), get pm interrupt (74)
  4457.  
  4458.  
  4459.            get run mode
  4460. Declaration: Function get run mode : Word;
  4461.  
  4462. Description: Returns the current mode your application runs with. Return values: One of the
  4463.            constants used by this function.
  4464.  
  4465.      Errors: None.
  4466.  
  4467.    See also: constants returned by get run mode (78)
  4468.  
  4469.            Program getrunmd ;
  4470.  
  4471.            uses go32 ;
  4472.  
  4473.            begin
  4474.            { depending on the detected environment ,
  4475.               we simply w r i t e another message
  4476.            }case ( get run mode) of
  4477.               rm unknown :
  4478.                     Writeln ( ' Unknown environment found ' ) ;
  4479.               rm raw            :
  4480.                     Writeln ( ' You are c u r r e n t l y running in raw mode ' ,
  4481.                                ' ( without HIMEM) ' ) ;
  4482.               rm xms            :
  4483.                     Writeln ( ' You are c u r r e n t l y using HIMEM. SYS only ' ) ;
  4484.               rm vcpi           :
  4485.                     Writeln ( ' VCPI s e r v e r detected . ' ,
  4486.                               ' You ' ' re using HIMEM and EMM386' ) ;
  4487.               rm dpmi           :
  4488.                     Writeln ( ' DPMI detected . ' ,
  4489.                               ' You ' ' re using a DPMI host l i k e ' ,
  4490.                               ' a windows DOS box or CWSDPMI' ) ;
  4491.            end ;
  4492.            end .
  4493.  
  4494.  
  4495.            get segment base address
  4496. Declaration: Function get segment base address (d : Word) : Longint;
  4497.  
  4498. Description: Returns the 32-bit linear base address from the descriptor table for the specified
  4499.            segment. Parameters:
  4500.  
  4501.            d: selector of the descriptor you want the base address.
  4502.  
  4503.            Return values: Linear base address of specified descriptor.
  4504.  
  4505.      Errors: Check the int31error variable.
  4506.  
  4507.  
  4508.  
  4509.                                                        78
  4510.  
  4511.  
  4512.  
  4513.                                                        4.4. FUNCTIONS AND PROCEDURES
  4514.  
  4515.  
  4516.   See also: allocate ldt descriptors (64), set segment base address (88), allocate ldt descriptors
  4517.            (64), set segment limit (88), get segment limit (79)
  4518.  
  4519.            For an example, see allocate ldt descriptors (64).
  4520.  
  4521.  
  4522.            get segment limit
  4523. Declaration: Function get segment limit (d : Word) : Longint;
  4524.  
  4525. Description: Returns a descriptors segment limit. Parameters:
  4526.  
  4527.            d: selector.
  4528.  
  4529.            Return value: Limit of the descriptor in bytes.
  4530.  
  4531.      Errors: Returns zero if descriptor is invalid.
  4532.  
  4533.   See also: allocate ldt descriptors (64), set segment limit (88), set segment base address
  4534.            (88), get segment base address (78),
  4535.  
  4536.  
  4537.            get ss
  4538. Declaration: Function get ss : Word;
  4539.  
  4540. Description: Returns the ss selector. Parameters: None. Return values: The content of the ss
  4541.            segment register.
  4542.  
  4543.      Errors: None.
  4544.  
  4545.   See also: get ds (72), get cs (71)
  4546.  
  4547.  
  4548.            global dos alloc
  4549. Declaration: Function global dos alloc (bytes : Longint) : Longint;
  4550.  
  4551. Description: Allocates a block of dos real mode memory. Parameters:
  4552.  
  4553.            bytes: size of requested real mode memory.
  4554.  
  4555.            Return values: The low word of the returned value contains the selector to the
  4556.            allocated dos memory block, the high word the corresponding real mode segment
  4557.            value. The o set value is always zero. This function allocates memory from dos
  4558.            memory pool, i.e. memory below the 1 MB boundary that is controlled by dos.
  4559.            Such memory blocks are typically used to exchange data with real mode programs,
  4560.            TSRs, or device drivers. The function returns both the real mode segment base
  4561.            address of the block and one descriptor that can be used by protected mode appli-
  4562.            cations to access the block. This function should only used for temporary bu ers to
  4563.            get real mode information (e.g. interrupts that need a data structure in ES:(E)DI),
  4564.            because every single block needs an unique selector. The returned selector should
  4565.            only be freed by a global dos free (81) call.
  4566.  
  4567.      Errors: Check the int31error variable.
  4568.  
  4569.   See also: global dos free (81)
  4570.  
  4571.  
  4572.  
  4573.  
  4574.                                                        79
  4575.  
  4576.  
  4577.  
  4578.                                                     4.4. FUNCTIONS AND PROCEDURES
  4579.  
  4580.  
  4581. Program b u f f e r ;
  4582.  
  4583. uses go32 ;
  4584.  
  4585. procedure d o s a l l o c ( var s e l e c t o r : word ; var segment : word ; s i z e : l o n g i n t ) ;
  4586. var res : l o n g i n t ;
  4587. begin res := global dos alloc ( size );
  4588.           s e l e c t o r := word ( res ) ;
  4589.           segment := word ( res shr 1 6 ) ;
  4590. end ;
  4591.  
  4592. procedure d o s f r e e ( s e l e c t o r : word ) ;
  4593. begin global dos free ( selector );
  4594. end ;
  4595.  
  4596. type VBEInfoBuf = record
  4597.                                 S i g n a t u r e : array [ 0 . . 3 ] of char ;
  4598.                                 Version : Word ;
  4599.                                 r e s e r v e d : array [ 0 . . 5 0 5 ] of byte ;
  4600.           end ;
  4601.  
  4602. var s e l e c t o r ,
  4603.          segment : Word ;
  4604.  
  4605.          r : t r e a l r e g s ;
  4606.          i n f o b u f : VBEInfoBuf ;
  4607.  
  4608. begin fillchar (r , sizeof (r ), 0);
  4609.           f i l l c h a r ( i n f o b u f , s i z e o f ( VBEInfoBuf ) , 0 ) ;
  4610.           d o s a l l o c ( s e l e c t o r , segment , s i ze o f ( VBEInfoBuf ) ) ;
  4611.           i f ( i n t 3 1 e r r o r <>0) then begin
  4612.                Writeln ( ' Error while a l l o c a t i n g r e a l mode memory , h a l t i n g ' ) ;
  4613.                halt ;
  4614.           end ;
  4615.           i n f o b u f . S i g n a t u r e := ' VBE2' ;
  4616.           dosmemput ( segment , 0 , i n f o b u f , s i z e o f ( i n f o b u f ) ) ;
  4617.           r . ax := $4f00 ; r . es := segment ;
  4618.           r e a l i n t r ( $10 , r ) ;
  4619.           dosmemget ( segment , 0 , i n f o b u f , s i z e o f ( i n f o b u f ) ) ;
  4620.           d o s f r e e ( s e l e c t o r ) ;
  4621.           i f ( r . ax <> $4f ) then begin
  4622.                Writeln ( ' VBE BIOS e x t e n s i o n not a v a i l a b l e , f u n c t i o n c a l l f a i l e d ' ) ;
  4623.                halt ;
  4624.           end ;
  4625.           i f ( i n f o b u f . s i g n a t u r e [ 0 ] = ' V' ) and ( i n f o b u f . s i g n a t u r e [ 1 ] = ' E' ) and
  4626.                ( i n f o b u f . s i g n a t u r e [ 2 ] = ' S ' ) and ( i n f o b u f . s i g n a t u r e [ 3 ] = ' A' ) then begin
  4627.                Writeln ( ' VBE v e r s i o n ' , hi ( i n f o b u f . v e r s i o n ) , ' . ' , lo ( i n f o b u f . v e r s i o n ) , ' detected ' ) ;
  4628.           end ;
  4629. end .
  4630.  
  4631.  
  4632.  
  4633.                                                    80
  4634.  
  4635.  
  4636.  
  4637.                                                          4.4. FUNCTIONS AND PROCEDURES
  4638.  
  4639.  
  4640.            global dos free
  4641. Declaration: Function global dos free (selector :Word) : boolean;
  4642.  
  4643. Description: Frees a previously allocated dos memory block. Parameters:
  4644.  
  4645.            selector: selector to the dos memory block.
  4646.  
  4647.            Return value: True if successful, False otherwise. Notes: The descriptor allocated
  4648.            for the memory block is automatically freed and hence invalid for further use. This
  4649.            function should only be used for memory allocated by global dos alloc (79).
  4650.  
  4651.      Errors: Check the int31error variable.
  4652.  
  4653.   See also: global dos alloc (79)
  4654.  
  4655.            For an example, see global dos alloc (79).
  4656.  
  4657.  
  4658.            inportb
  4659. Declaration: Function inportb (port : Word) : byte;
  4660.  
  4661. Description: Reads 1 byte from the selected I/O port. Parameters:
  4662.  
  4663.            port: the I/O port number which is read.
  4664.  
  4665.            Return values: Current I/O port value.
  4666.  
  4667.      Errors: None.
  4668.  
  4669.   See also: outportb (83), inportw (81), inportl (81)
  4670.  
  4671.  
  4672.            inportl
  4673. Declaration: Function inportl (port : Word) : Longint;
  4674.  
  4675. Description: Reads 1 longint from the selected I/O port. Parameters:
  4676.  
  4677.            port: the I/O port number which is read.
  4678.  
  4679.            Return values: Current I/O port value.
  4680.  
  4681.      Errors: None.
  4682.  
  4683.   See also: outportb (83), inportb (81), inportw (81)
  4684.  
  4685.  
  4686.            inportw
  4687. Declaration: Function inportw (port : Word) : Word;
  4688.  
  4689. Description: Reads 1 word from the selected I/O port. Parameters:
  4690.  
  4691.            port: the I/O port number which is read.
  4692.  
  4693.            Return values: Current I/O port value.
  4694.  
  4695.      Errors: None.
  4696.  
  4697.   See also: outportw (83) inportb (81), inportl (81)
  4698.  
  4699.  
  4700.                                                          81
  4701.  
  4702.  
  4703.  
  4704.                                                     4.4. FUNCTIONS AND PROCEDURES
  4705.  
  4706.  
  4707.            lock code
  4708. Declaration: Function lock code (functionaddr : pointer; size : Longint) : boolean;
  4709.  
  4710. Description: Locks a memory range which is in the code segment selector. Parameters:
  4711.  
  4712.            functionaddr: address of the function to be locked.
  4713.            size: size in bytes to be locked.
  4714.  
  4715.            Return values: True if successful, False otherwise.
  4716.  
  4717.     Errors: Check the int31error variable.
  4718.  
  4719.   See also: lock linear region (82), lock data (82), unlock linear region (90), unlock data
  4720.            (89), unlock code (89)
  4721.  
  4722.            For an example, see get rm callback (74).
  4723.  
  4724.  
  4725.            lock data
  4726. Declaration: Function lock data (var data; size : Longint) : boolean;
  4727.  
  4728. Description: Locks a memory range which resides in the data segment selector. Parameters:
  4729.  
  4730.            data: address of data to be locked.
  4731.            size: length of data to be locked.
  4732.  
  4733.            Return values: True if successful, False otherwise.
  4734.  
  4735.     Errors: Check the int31error variable.
  4736.  
  4737.   See also: lock linear region (82), lock code (82), unlock linear region (90), unlock data
  4738.            (89), unlock code (89)
  4739.  
  4740.            For an example, see get rm callback (74).
  4741.  
  4742.  
  4743.            lock linear region
  4744. Declaration: Function lock linear region (linearaddr, size : Longint) : boolean;
  4745.  
  4746. Description: Locks a memory region to prevent swapping of it. Parameters:
  4747.  
  4748.            linearaddr: the linear address of the memory are to be locked.
  4749.            size: size in bytes to be locked.
  4750.  
  4751.            Return value: True if successful, False otherwise.
  4752.  
  4753.     Errors: Check the int31error variable.
  4754.  
  4755.   See also: lock data (82), lock code (82), unlock linear region (90), unlock data (89), un-
  4756.            lock code (89)
  4757.  
  4758.  
  4759.  
  4760.  
  4761.  
  4762.  
  4763.  
  4764.                                                    82
  4765.  
  4766.  
  4767.  
  4768.                                                       4.4. FUNCTIONS AND PROCEDURES
  4769.  
  4770.  
  4771.            outportb
  4772. Declaration: Procedure outportb (port : Word; data : byte);
  4773. Description: Sends 1 byte of data to the specified I/O port. Parameters:
  4774.            port: the I/O port number to send data to.
  4775.            data: value sent to I/O port.
  4776.            Return values: None.
  4777.      Errors: None.
  4778.    See also: inportb (81), outportl (83), outportw (83)
  4779.  
  4780.            program outport ;
  4781.  
  4782.            uses c r t , go32 ;
  4783.  
  4784.            begin
  4785.              { turn on speaker }
  4786.              outportb ( $61 , $ f f ) ;
  4787.              { wait a l i t t l e b i t }
  4788.              delay ( 5 0 ) ;
  4789.              { turn i t o f f again }
  4790.              outportb ( $61 , $0 ) ;
  4791.            end .
  4792.  
  4793.  
  4794.            outportl
  4795. Declaration: Procedure outportl (port : Word; data : Longint);
  4796. Description: Sends 1 longint of data to the specified I/O port. Parameters:
  4797.            port: the I/O port number to send data to.
  4798.            data: value sent to I/O port.
  4799.            Return values: None.
  4800.      Errors: None.
  4801.    See also: inportl (81), outportw (83), outportb (83)
  4802.  
  4803.            For an example, see outportb (83).
  4804.  
  4805.  
  4806.            outportw
  4807. Declaration: Procedure outportw (port : Word; data : Word);
  4808. Description: Sends 1 word of data to the specified I/O port. Parameters:
  4809.            port: the I/O port number to send data to.
  4810.            data: value sent to I/O port.
  4811.            Return values: None.
  4812.      Errors: None.
  4813.    See also: inportw (81), outportl (83), outportb (83)
  4814.  
  4815.            For an example, see outportb (83).
  4816.  
  4817.                                                       83
  4818.  
  4819.  
  4820.  
  4821.                                                                 4.4. FUNCTIONS AND PROCEDURES
  4822.  
  4823.  
  4824.            realintr
  4825. Declaration: Function realintr (intnr: Word; var regs : trealregs) : boolean;
  4826.  
  4827. Description: Simulates an interrupt in real mode. Parameters:
  4828.  
  4829.            intnr: interrupt number to issue in real mode.
  4830.            regs: registers data structure.
  4831.  
  4832.            Return values: The supplied registers data structure contains the values that were
  4833.            returned by the real mode interrupt. True if successful, False if not. Notes: The
  4834.            function transfers control to the address specified by the real mode interrupt vector
  4835.            of intnr. The real mode handler must return by executing an IRET.
  4836.  
  4837.      Errors: Check the int31error variable.
  4838.  
  4839.    See also:
  4840.  
  4841.                 Program f l a g s ;
  4842.  
  4843.                 uses go32 ;
  4844.  
  4845.                 var r : t r e a l r e g s ;
  4846.  
  4847.                 begin r . ax := $5300;
  4848.                          r . bx : = 0 ;
  4849.                          r e a l i n t r ( $15 , r ) ;
  4850.                          { check i f c a r r y c l e a r and w r i t e a s u i t e d message }
  4851.                          i f ( ( r . f l a g s and c a r r y f l a g )=0) then begin
  4852.                               Writeln ( ' APM v ' , ( r . ah and $f ) ,
  4853.                                             ' . ' , ( r . al shr 4 ) , ( r . al and $f ) ,
  4854.                                             ' detected ' ) ;
  4855.                          end else
  4856.                                Writeln ( ' APM not p r e s e n t ' ) ;
  4857.                 end .
  4858.  
  4859.  
  4860.            seg fillchar
  4861. Declaration: Procedure seg fillchar (seg : Word; ofs : Longint; count : Longint;
  4862.            c : char);
  4863.  
  4864. Description: Sets a memory area to a specific value. Parameters:
  4865.  
  4866.            seg: selector to memory area.
  4867.            ofs: o set to memory.
  4868.            count: number of bytes to set.
  4869.            c: byte data which is set.
  4870.  
  4871.            Return values: None. Notes: No range check is done in any way.
  4872.  
  4873.      Errors: None.
  4874.  
  4875.    See also: seg move (86), seg fillword (85), dosmemfillchar (68), dosmemfillword (69), dos-
  4876.            memget (69), dosmemput (70), dosmemmove (69)
  4877.  
  4878.  
  4879.                                                                 84
  4880.  
  4881.  
  4882.  
  4883.                                                               4.4. FUNCTIONS AND PROCEDURES
  4884.  
  4885.  
  4886.            Program s v g a s e l ;
  4887.  
  4888.            uses go32 ;
  4889.  
  4890.            var v g a s e l : Word ;
  4891.                     r : t r e a l r e g s ;
  4892.  
  4893.            begin
  4894.               r . eax := $13 ; r e a l i n t r ( $10 , r ) ;
  4895.               v g a s e l := segment to descriptor ( $A000 ) ;
  4896.               { simply f i l l the screen memory with c o l o r 15 }
  4897.               s e g f i l l c h a r ( v g a s e l , 0 , 6 4 0 0 0 , # 1 5 ) ;
  4898.               readln ;
  4899.             { back to text mode }
  4900.               r . eax := $3 ;
  4901.               r e a l i n t r ( $10 , r ) ;
  4902.            end .
  4903.  
  4904.  
  4905.            seg fillword
  4906. Declaration: Procedure seg fillword (seg : Word; ofs : Longint; count : Longint;
  4907.            w :Word);
  4908.  
  4909. Description: Sets a memory area to a specific value. Parameters:
  4910.  
  4911.            seg: selector to memory area.
  4912.            ofs: o set to memory.
  4913.            count: number of words to set.
  4914.            w: word data which is set.
  4915.  
  4916.            Return values: None. Notes: No range check is done in any way.
  4917.  
  4918.      Errors: None.
  4919.  
  4920.    See also: seg move (86), seg fillchar (84), dosmemfillchar (68), dosmemfillword (69), dos-
  4921.            memget (69), dosmemput (70), dosmemmove (69)
  4922.  
  4923.            For an example, see allocate ldt descriptors (64).
  4924.  
  4925.  
  4926.            segment to descriptor
  4927. Declaration: Function segment to descriptor (seg : Word) : Word;
  4928.  
  4929. Description: Maps a real mode segment (paragraph) address onto an descriptor that can be
  4930.            used by a protected mode program to access the same memory. Parameters:
  4931.  
  4932.            seg: the real mode segment you want the descriptor to.
  4933.  
  4934.            Return values: Descriptor to real mode segment address. Notes: The returned
  4935.            descriptors limit will be set to 64 kB. Multiple calls to this function with the same
  4936.            segment address will return the same selector. Descriptors created by this function
  4937.            can never be modified or freed. Programs which need to examine various real mode
  4938.            addresses using the same selector should use the function allocate ldt descriptors
  4939.            (64) and change the base address as necessary.
  4940.  
  4941.  
  4942.                                                               85
  4943.  
  4944.  
  4945.  
  4946.                                                      4.4. FUNCTIONS AND PROCEDURES
  4947.  
  4948.  
  4949.      Errors: Check the int31error variable.
  4950.  
  4951.    See also: allocate ldt descriptors (64), free ldt descriptor (70), set segment base address
  4952.            (88)
  4953.  
  4954.            For an example, see seg fillchar (84).
  4955.  
  4956.  
  4957.            seg move
  4958. Declaration: Procedure seg move (sseg : Word; source : Longint; dseg : Word; dest
  4959.            : Longint; count : Longint);
  4960.  
  4961. Description: Copies data between two memory locations. Parameters:
  4962.  
  4963.            sseg: source selector.
  4964.            source: source o set.
  4965.            dseg: destination selector.
  4966.            dest: destination o set.
  4967.            count: size in bytes to copy.
  4968.  
  4969.            Return values: None. Notes: Overlapping is only checked if the source selector is
  4970.            equal to the destination selector. No range check is done.
  4971.  
  4972.      Errors: None.
  4973.  
  4974.    See also: seg fillchar (84), seg fillword (85), dosmemfillchar (68), dosmemfillword (69), dos-
  4975.            memget (69), dosmemput (70), dosmemmove (69)
  4976.  
  4977.            For an example, see allocate ldt descriptors (64).
  4978.  
  4979.  
  4980.            set descriptor access rights
  4981. Declaration: Function set descriptor access rights (d : Word; w : Word) : Longint;
  4982.  
  4983. Description: Sets the access rights of a descriptor. Parameters:
  4984.  
  4985.            d: selector.
  4986.            w: new descriptor access rights.
  4987.  
  4988.            Return values: This function doesn't return anything useful.
  4989.  
  4990.      Errors: Check the int31error variable.
  4991.  
  4992.    See also: get descriptor access rights (71)
  4993.  
  4994.  
  4995.            set pm interrupt
  4996. Declaration: Function set pm interrupt (vector : byte; const intaddr : tseginfo)
  4997.            : boolean;
  4998.  
  4999. Description: Sets the address of the protected mode handler for an interrupt. Parameters:
  5000.  
  5001.            vector: number of protected mode interrupt to set.
  5002.            intaddr: selector:o set address to the interrupt vector.
  5003.  
  5004.  
  5005.                                                      86
  5006.  
  5007.  
  5008.  
  5009.                                                         4.4. FUNCTIONS AND PROCEDURES
  5010.  
  5011.  
  5012.         Return values: True if successful, False otherwise. Notes: The address supplied
  5013.         must be a valid selector:offset protected mode address.
  5014.  
  5015.   Errors: Check the int31error variable.
  5016.  
  5017. See also: get pm interrupt (74), set rm interrupt (88), get rm interrupt (77)
  5018.  
  5019.         Program int pm ;
  5020.  
  5021.         uses cr t , go32 ;
  5022.  
  5023.         const i n t 1 c = $1c ;
  5024.  
  5025.         var o l d i n t 1 c : t s e g i n f o ;
  5026.                  newint1c : t s e g i n f o ;
  5027.                  int1c counter : Longint ;
  5028.  
  5029.         {$ASMMODE DIRECT}
  5030.         procedure i n t 1 c h an d l e r ; assembler ;
  5031.         asm cli
  5032.             pushw %ds
  5033.             pushw %ax
  5034.             movw %cs : INT1C DS, % ax
  5035.             movw %ax , % ds
  5036.              i n c l       INT1C COUNTER
  5037.             popw %ax
  5038.             popw %ds
  5039.              s t i
  5040.              i r e t
  5041.         INT1C DS : . word 0
  5042.         end ;
  5043.  
  5044.         var i : Longint ;
  5045.  
  5046.         begin newint1c . offset := @int1c handler ;
  5047.                   newint1c . segment := get cs ;
  5048.                   get pm interrupt ( i n t 1 c , o l d i n t 1 c ) ;
  5049.                   asmmovw %ds, %ax
  5050.                         movw %ax , INT1C DS
  5051.                   end ;
  5052.                   Writeln ( '-- Press any key to e x i t --' ) ;
  5053.                   set pm interrupt ( i n t 1 c , newint1c ) ;
  5054.                   while ( not keypressed ) do begin
  5055.                              gotoxy ( 1 , wherey ) ;
  5056.                              write ( ' Number of i n t e r r u p t s occured : ' ,
  5057.                                      int1c counter ) ;
  5058.                   end ;
  5059.                   set pm interrupt ( i n t 1 c , o l d i n t 1 c ) ;
  5060.         end .
  5061.  
  5062.  
  5063.  
  5064.  
  5065.                                                         87
  5066.  
  5067.  
  5068.  
  5069.                                                      4.4. FUNCTIONS AND PROCEDURES
  5070.  
  5071.  
  5072.            set rm interrupt
  5073. Declaration: Function set rm interrupt (vector : byte; const intaddr : tseginfo)
  5074.            : boolean;
  5075.  
  5076. Description: Sets a real mode interrupt handler. Parameters:
  5077.  
  5078.            vector: the interrupt vector number to set.
  5079.            intaddr: address of new interrupt vector.
  5080.  
  5081.            Return values: True if successful, otherwise False. Notes: The address supplied
  5082.            MUST be a real mode segment address, not a selector:offset address. So the
  5083.            interrupt handler must either reside in dos memory (below 1 Mb boundary) or the
  5084.            application must allocate a real mode callback address with get rm callback (74).
  5085.  
  5086.      Errors: Check the int31error variable.
  5087.  
  5088.    See also: get rm interrupt (77), set pm interrupt (86), get pm interrupt (74), get rm callback
  5089.            (74)
  5090.  
  5091.  
  5092.            set segment base address
  5093. Declaration: Function set segment base address (d : Word; s : Longint) : boolean;
  5094.  
  5095. Description: Sets the 32-bit linear base address of a descriptor. Parameters:
  5096.  
  5097.            d: selector.
  5098.            s: new base address of the descriptor.
  5099.  
  5100.      Errors: Check the int31error variable.
  5101.  
  5102.    See also: allocate ldt descriptors (64), get segment base address (78), allocate ldt descriptors
  5103.            (64), set segment limit (88), get segment base address (78), get segment limit
  5104.            (79)
  5105.  
  5106.  
  5107.            set segment limit
  5108. Declaration: Function set segment limit (d : Word; s : Longint) : boolean;
  5109.  
  5110. Description: Sets the limit of a descriptor. Parameters:
  5111.  
  5112.            d: selector.
  5113.            s: new limit of the descriptor.
  5114.  
  5115.            Return values: Returns True if successful, else False. Notes: The new limit speci-
  5116.            fied must be the byte length of the segment - 1. Segment limits bigger than or equal
  5117.            to 1MB must be page aligned, they must have the lower 12 bits set.
  5118.  
  5119.      Errors: Check the int31error variable.
  5120.  
  5121.    See also: allocate ldt descriptors (64), set segment base address (88), get segment limit
  5122.            (79), set segment limit (88)
  5123.  
  5124.            For an example, see allocate ldt descriptors (64).
  5125.  
  5126.  
  5127.  
  5128.  
  5129.                                                      88
  5130.  
  5131.  
  5132.  
  5133.                                                     4.4. FUNCTIONS AND PROCEDURES
  5134.  
  5135.  
  5136.            tb size
  5137. Declaration: Function tb size : Longint;
  5138.  
  5139. Description: Returns the size of the pre-allocated dos memory bu er. Parameters: None.
  5140.            Return values: The size of the pre-allocated dos memory bu er. Notes: This block
  5141.            always seems to be 16k in size, but don't rely on this.
  5142.  
  5143.     Errors: None.
  5144.  
  5145.   See also: transfer bu er (89), copyfromdos (66) copytodos (67)
  5146.  
  5147.  
  5148.            transfer bu er
  5149. Declaration: Function transfer buffer : Longint;
  5150.  
  5151. Description: transfer buffer returns the o set of the transfer bu er.
  5152.  
  5153.     Errors: None.
  5154.  
  5155.   See also: tb size (89)
  5156.  
  5157.  
  5158.            unlock code
  5159. Declaration: Function unlock code (functionaddr : pointer; size : Longint) : boolean;
  5160.  
  5161. Description: Unlocks a memory range which resides in the code segment selector. Parameters:
  5162.  
  5163.            functionaddr: address of function to be unlocked.
  5164.            size: size bytes to be unlocked.
  5165.  
  5166.            Return value: True if successful, False otherwise.
  5167.  
  5168.     Errors: Check the int31error variable.
  5169.  
  5170.   See also: unlock linear region (90), unlock data (89), lock linear region (82), lock data
  5171.            (82), lock code (82)
  5172.  
  5173.            For an example, see get rm callback (74).
  5174.  
  5175.  
  5176.            unlock data
  5177. Declaration: Function unlock data (var data; size : Longint) : boolean;
  5178.  
  5179. Description: Unlocks a memory range which resides in the data segment selector. Paramters:
  5180.  
  5181.            data: address of memory to be unlocked.
  5182.            size: size bytes to be unlocked.
  5183.  
  5184.            Return values: True if successful, False otherwise.
  5185.  
  5186.     Errors: Check the int31error variable.
  5187.  
  5188.   See also: unlock linear region (90), unlock code (89), lock linear region (82), lock data
  5189.            (82), lock code (82)
  5190.  
  5191.            For an example, see get rm callback (74).
  5192.  
  5193.  
  5194.                                                     89
  5195.  
  5196.  
  5197.  
  5198.                                                      4.4. FUNCTIONS AND PROCEDURES
  5199.  
  5200.  
  5201.            unlock linear region
  5202. Declaration: Function unlock linear region (linearaddr, size : Longint) : boolean;
  5203.  
  5204. Description: Unlocks a previously locked linear region range to allow it to be swapped out again
  5205.            if needed. Parameters:
  5206.  
  5207.            linearaddr: linear address of the memory to be unlocked.
  5208.            size: size bytes to be unlocked.
  5209.  
  5210.            Return values: True if successful, False otherwise.
  5211.  
  5212.      Errors: Check the int31error variable.
  5213.  
  5214.    See also: unlock data (89), unlock code (89), lock linear region (82), lock data (82), lock code
  5215.            (82)
  5216.  
  5217.  
  5218.  
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.  
  5231.  
  5232.  
  5233.  
  5234.  
  5235.  
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.  
  5247.  
  5248.  
  5249.  
  5250.  
  5251.  
  5252.  
  5253.  
  5254.                                                     90
  5255.  
  5256.  
  5257.  
  5258. Chapter 5
  5259.  
  5260. The GRAPH unit.
  5261.  
  5262. This document describes the GRAPH unit for Free Pascal, under dos. The unit was
  5263. first written for dos by Florian kl¿ampfl. This chapter is divided in three sections.
  5264.  
  5265.    * The first section gives an introduction to the graph unit.
  5266.  
  5267.    * The second section lists the pre-defined constants, types and variables.
  5268.  
  5269.    * The second section describes the functions which appear in the interface part
  5270.         of the GRAPH unit.
  5271.  
  5272.  
  5273. 5.1 Introduction
  5274.  
  5275. Requirements
  5276. The unit Graph exports functions and procedures for graphical output. It requires
  5277. at least a VESA compatible VGA-Card or a VGA-Card with software-driver (min.
  5278. 512Kb video memory). Before the graph unit can be used, be sure your graphics
  5279. adapter supports the VESA-Standard. Otherwise in the most cases you can try to
  5280. use a VESA-TSR to make your adapter VESA compatible (e.g. UNIVBE).
  5281.  
  5282.  
  5283. 5.2 Constants, Types and Variables
  5284.  
  5285. Types
  5286. ArcCoordsType = record
  5287.  X,Y,Xstart,Ystart,Xend,Yend : Integer;
  5288. end;
  5289. FillPatternType = Array [1..8] of Byte;
  5290. FillSettingsType = Record
  5291.  Pattern,Color : Word
  5292. end;
  5293. LineSettingsType = Record
  5294.   LineStyle,Pattern, Width : Word;
  5295. end;
  5296. PaletteType = Record
  5297.  Size : Byte;
  5298.  Colors : array[0..MAxColor] of shortint;
  5299.  
  5300.                                          91
  5301.  
  5302.  
  5303.  
  5304.                                                       5.3. FUNCTIONS AND PROCEDURES
  5305.  
  5306.  
  5307.            end;
  5308.            PointType = Record
  5309.               X,Y : Integer;
  5310.            end;
  5311.            TextSettingsType = Record
  5312.              Font,Direction, CharSize, Horiz, Vert : Word
  5313.            end;
  5314.            ViewPortType = Record
  5315.               X1,Y1,X2,Y2 : Integer;
  5316.               Clip : Boolean
  5317.            end;
  5318.  
  5319.  
  5320.            5.3 Functions and procedures
  5321.  
  5322.            Arc
  5323. Declaration: Procedure Arc (X,Y : Integer; start,stop, radius : Word);
  5324. Description: Arc draws part of a circle with center at (X,Y), radius radius, starting from angle
  5325.            start, stopping at angle stop. These angles are measured counterclockwise.
  5326.      Errors: None.
  5327.    See also: Circle (92),Ellipse (94) GetArcCoords (94),PieSlice (102), Sector (103)
  5328.  
  5329.  
  5330.            Bar
  5331. Declaration: Procedure Bar (X1,Y1,X2,Y2 : Integer);
  5332. Description: Draws a rectangle with corners at (X1,Y1) and (X2,Y2) and fills it with the current
  5333.            color and fill-style.
  5334.      Errors: None.
  5335.    See also: Bar3D (92), Rectangle (103)
  5336.  
  5337.  
  5338.            Bar3D
  5339. Declaration: Procedure Bar3D (X1,Y1,X2,Y2 : Integer; depth : Word; Top : Boolean);
  5340. Description: Draws a 3-dimensional Bar with corners at (X1,Y1) and (X2,Y2) and fills it with
  5341.            the current color and fill-style. Depth specifies the number of pixels used to show
  5342.            the depth of the bar. If Top is true; then a 3-dimensional top is drawn.
  5343.      Errors: None.
  5344.    See also: Bar (92), Rectangle (103)
  5345.  
  5346.  
  5347.            Circle
  5348. Declaration: Procedure Circle (X,Y : Integer; Radius : Word);
  5349. Description: Circle draws part of a circle with center at (X,Y), radius radius.
  5350.      Errors: None.
  5351.    See also: Ellipse (94),Arc (92) GetArcCoords (94),PieSlice (102), Sector (103)
  5352.  
  5353.  
  5354.                                                      92
  5355.  
  5356.  
  5357.  
  5358.                                                      5.3. FUNCTIONS AND PROCEDURES
  5359.  
  5360.  
  5361.            ClearDevice
  5362. Declaration: Procedure ClearDevice ;
  5363.  
  5364. Description: Clears the graphical screen (with the current background color), and sets the
  5365.            pointer at (0,0)
  5366.  
  5367.      Errors: None.
  5368.  
  5369.    See also: ClearViewPort (93), SetBkColor (104)
  5370.  
  5371.  
  5372.            ClearViewPort
  5373. Declaration: Procedure ClearViewPort ;
  5374.  
  5375. Description: Clears the current view-port. The current background color is used as filling color.
  5376.            The pointer is set at (0,0)
  5377.  
  5378.      Errors: None.
  5379.  
  5380.    See also: ClearDevice (93),SetViewPort (107), SetBkColor (104)
  5381.  
  5382.  
  5383.            CloseGraph
  5384. Declaration: Procedure CloseGraph ;
  5385.  
  5386. Description: Closes the graphical system, and restores the screen modus which was active before
  5387.            the graphical modus was activated.
  5388.  
  5389.      Errors: None.
  5390.  
  5391.    See also: InitGraph (100)
  5392.  
  5393.  
  5394.            DetectGraph
  5395. Declaration: Procedure DetectGraph (Var Driver, Modus : Integer);
  5396.  
  5397. Description: Checks the hardware in the PC and determines the driver and screen-modus to be
  5398.            used. These are returned in Driver and Modus, and can be fed to InitGraph. See
  5399.            the InitGraph for a list of drivers and modi.
  5400.  
  5401.      Errors: None.
  5402.  
  5403.    See also: InitGraph (100)
  5404.  
  5405.  
  5406.            DrawPoly
  5407. Declaration: Procedure DrawPoly (NumberOfPoints : Word; Var PolyPoints;
  5408.  
  5409. Description: Draws a polygone with NumberOfPoints corner points, using the current color and
  5410.            line-style. PolyPoints is an array of type PointType.
  5411.  
  5412.      Errors: None.
  5413.  
  5414.    See also: Bar (92), seepBar3D, Rectangle (103)
  5415.  
  5416.  
  5417.  
  5418.  
  5419.                                                      93
  5420.  
  5421.  
  5422.  
  5423.                                                        5.3. FUNCTIONS AND PROCEDURES
  5424.  
  5425.  
  5426.             Ellipse
  5427. Declaration: Procedure Ellipse (X,Y : Integer; Start,Stop,XRadius,YRadius : Word);
  5428.  
  5429. Description: Ellipse draws part of an ellipse with center at (X,Y). XRadius and Yradius are
  5430.             the horizontal and vertical radii of the ellipse. Start and Stop are the starting and
  5431.             stopping angles of the part of the ellipse. They are measured counterclockwise from
  5432.             the X-axis.
  5433.  
  5434.      Errors: None.
  5435.  
  5436.    See also: Arc (92) Circle (92), FillEllipse (94)
  5437.  
  5438.  
  5439.             FillEllipse
  5440. Declaration: Procedure FillEllipse (X,Y : Integer; Xradius,YRadius: Word);
  5441.  
  5442. Description: Ellipse draws an ellipse with center at (X,Y). XRadius and Yradius are the
  5443.             horizontal and vertical radii of the ellipse. The ellipse is filled with the current
  5444.             color and fill-style.
  5445.  
  5446.      Errors: None.
  5447.  
  5448.    See also: Arc (92) Circle (92), GetArcCoords (94),PieSlice (102), Sector (103)
  5449.  
  5450.  
  5451.             FillPoly
  5452. Declaration: Procedure FillPoly (NumberOfPoints : Word; Var PolyPoints);
  5453.  
  5454. Description: Draws a polygone with NumberOfPoints corner points and fills it using the current
  5455.             color and line-style. PolyPoints is an array of type PointType.
  5456.  
  5457.      Errors: None.
  5458.  
  5459.    See also: Bar (92), seepBar3D, Rectangle (103)
  5460.  
  5461.  
  5462.             FloodFill
  5463. Declaration: Procedure FloodFill (X,Y : Integer; BorderColor : Word);
  5464.  
  5465. Description: Fills the area containing the point (X,Y), bounded by the color BorderColor.
  5466.  
  5467.      Errors: None
  5468.  
  5469.    See also: SetColor (104), SetBkColor (104)
  5470.  
  5471.  
  5472.             GetArcCoords
  5473. Declaration: Procedure GetArcCoords (Var ArcCoords : ArcCoordsType);
  5474.  
  5475. Description: GetArcCoords returns the coordinates of the latest Arc or Ellipse call.
  5476.  
  5477.      Errors: None.
  5478.  
  5479.    See also: Arc (92), Ellipse (94)
  5480.  
  5481.  
  5482.  
  5483.  
  5484.                                                        94
  5485.  
  5486.  
  5487.  
  5488.                                                      5.3. FUNCTIONS AND PROCEDURES
  5489.  
  5490.  
  5491.            GetAspectRatio
  5492. Declaration: Procedure GetAspectRatio (Var Xasp,Yasp : Word);
  5493. Description: GetAspectRatio determines the e ective resolution of the screen. The aspect
  5494.            ration can the be calculated as Xasp/Yasp.
  5495.      Errors: None.
  5496.    See also: InitGraph (100),SetAspectRatio (104)
  5497.  
  5498.  
  5499.            GetBkColor
  5500. Declaration: Function GetBkColor : Word;
  5501. Description: GetBkColor returns the current background color (the palette entry).
  5502.      Errors: None.
  5503.    See also: GetColor (95),SetBkColor (104)
  5504.  
  5505.  
  5506.            GetColor
  5507. Declaration: Function GetColor : Word;
  5508. Description: GetColor returns the current drawing color (the palette entry).
  5509.      Errors: None.
  5510.    See also: GetColor (95),SetBkColor (104)
  5511.  
  5512.  
  5513.            GetDefaultPalette
  5514. Declaration: Procedure GetDefaultPalette (Var Palette : PaletteType);
  5515. Description: Returns the current palette in Palette.
  5516.      Errors: None.
  5517.    See also: GetColor (95), GetBkColor (95)
  5518.  
  5519.  
  5520.            GetDriverName
  5521. Declaration: Function GetDriverName : String;
  5522. Description: GetDriverName returns a string containing the name of the current driver.
  5523.      Errors: None.
  5524.    See also: GetModeName (97), InitGraph (100)
  5525.  
  5526.  
  5527.            GetFillPattern
  5528. Declaration: Procedure GetFillPattern (Var FillPattern : FillPatternType);
  5529. Description: GetFillPattern returns an array with the current fill-pattern in FillPattern
  5530.      Errors: None
  5531.    See also: SetFillPattern (105)
  5532.  
  5533.  
  5534.                                                      95
  5535.  
  5536.  
  5537.  
  5538.                                                    5.3. FUNCTIONS AND PROCEDURES
  5539.  
  5540.  
  5541.            GetFillSettings
  5542. Declaration: Procedure GetFillSettings (Var FillInfo : FillSettingsType);
  5543. Description: GetFillSettings returns the current fill-settings in FillInfo
  5544.      Errors: None.
  5545.   See also: SetFillPattern (105)
  5546.  
  5547.  
  5548.            GetGraphMode
  5549. Declaration: Function GetGraphMode : Integer;
  5550. Description: GetGraphMode returns the current graphical modus
  5551.      Errors: None.
  5552.   See also: InitGraph (100)
  5553.  
  5554.  
  5555.            GetImage
  5556. Declaration: Procedure GetImage (X1,Y1,X2,Y2 : Integer, Var Bitmap;
  5557. Description: GetImage Places a copy of the screen area (X1,Y1) to X2,Y2 in BitMap
  5558.      Errors: Bitmap must have enough room to contain the image.
  5559.   See also: ImageSize (99), PutImage (102)
  5560.  
  5561.  
  5562.            GetLineSettings
  5563. Declaration: Procedure GetLineSettings (Var LineInfo : LineSettingsType);
  5564. Description: GetLineSettings returns the current Line settings in LineInfo
  5565.      Errors: None.
  5566.   See also: SetLineStyle (106)
  5567.  
  5568.  
  5569.            GetMaxColor
  5570. Declaration: Function GetMaxColor : Word;
  5571. Description: GetMaxColor returns the maximum color-number which can be set with SetColor
  5572.      Errors: None.
  5573.   See also: SetColor (104), GetPaletteSize (97)
  5574.  
  5575.  
  5576.            GetMaxMode
  5577. Declaration: Function GetMaxMode : Word;
  5578. Description: GetMaxMode returns the highest modus for the current driver.
  5579.      Errors: None.
  5580.   See also: InitGraph (100)
  5581.  
  5582.  
  5583.                                                    96
  5584.  
  5585.  
  5586.  
  5587.                                                      5.3. FUNCTIONS AND PROCEDURES
  5588.  
  5589.  
  5590.            GetMaxX
  5591. Declaration: Function GetMaxX : Word;
  5592. Description: GetMaxX returns the maximum horizontal screen length
  5593.     Errors: None.
  5594.   See also: GetMaxY (97)
  5595.  
  5596.  
  5597.            GetMaxY
  5598. Declaration: Function GetMaxY : Word;
  5599. Description: GetMaxY returns the maximum number of screen lines
  5600.     Errors: None.
  5601.   See also: GetMaxY (97)
  5602.  
  5603.  
  5604.            GetModeName
  5605. Declaration: Function GetModeName (Var modus : Integer) : String;
  5606. Description: Returns a string with the name of modus Modus
  5607.     Errors: None.
  5608.   See also: GetDriverName (95), InitGraph (100)
  5609.  
  5610.  
  5611.            GetModeRange
  5612. Declaration: Procedure GetModeRange (Driver : Integer;
  5613.            LoModus, HiModus: Integer);
  5614. Description: GetModeRange returns the Lowest and Highest modus of the currently installed
  5615.            driver.
  5616.     Errors: None.
  5617.   See also: InitGraph (100)
  5618.  
  5619.  
  5620.            GetPalette
  5621. Declaration: Procedure GetPalette (Var Palette : PaletteType);
  5622. Description: GetPalette returns in Palette the current palette.
  5623.     Errors: None.
  5624.   See also: GetPaletteSize (97), SetPalette (106)
  5625.  
  5626.  
  5627.            GetPaletteSize
  5628. Declaration: Function GetPaletteSize : Word;
  5629. Description: GetPaletteSize returns the maximum number of entries in the current palette.
  5630.     Errors: None.
  5631.   See also: GetPalette (97), SetPalette (106)
  5632.  
  5633.  
  5634.                                                      97
  5635.  
  5636.  
  5637.  
  5638.                                                          5.3. FUNCTIONS AND PROCEDURES
  5639.  
  5640.  
  5641.            GetPixel
  5642. Declaration: Function GetPixel (X,Y : Integer) : Word;
  5643.  
  5644. Description: GetPixel returns the color of the point at (X,Y)
  5645.  
  5646.      Errors: None.
  5647.  
  5648.    See also:
  5649.  
  5650.  
  5651.            GetTextSettings
  5652. Declaration: Procedure GetTextSettings (Var TextInfo : TextSettingsType);
  5653.  
  5654. Description: GetTextSettings returns the current text style settings : The font, direction, size
  5655.            and placement as set with SetTextStyle and SetTextJustify
  5656.  
  5657.      Errors: None.
  5658.  
  5659.    See also: SetTextStyle (107), SetTextJustify (106)
  5660.  
  5661.  
  5662.            GetViewSettings
  5663. Declaration: Procedure GetViewSettings (Var ViewPort : ViewPortType);
  5664.  
  5665. Description: GetViewSettings returns the current view-port and clipping settings in ViewPort.
  5666.  
  5667.      Errors: None.
  5668.  
  5669.    See also: SetViewPort (107)
  5670.  
  5671.  
  5672.            GetX
  5673. Declaration: Function GetX : Integer;
  5674.  
  5675. Description: GetX returns the X-coordinate of the current position of the graphical pointer
  5676.  
  5677.      Errors: None.
  5678.  
  5679.    See also: GetY (98)
  5680.  
  5681.  
  5682.            GetY
  5683. Declaration: Function GetY : Integer;
  5684.  
  5685. Description: GetY returns the Y-coordinate of the current position of the graphical pointer
  5686.  
  5687.      Errors: None.
  5688.  
  5689.    See also: GetX (98)
  5690.  
  5691.  
  5692.  
  5693.  
  5694.  
  5695.  
  5696.  
  5697.  
  5698.                                                          98
  5699.  
  5700.  
  5701.  
  5702.                                                       5.3. FUNCTIONS AND PROCEDURES
  5703.  
  5704.  
  5705.            GraphDefaults
  5706. Declaration: Procedure GraphDefaults ;
  5707.  
  5708. Description: GraphDefaults resets all settings for view-port, palette, foreground and back-
  5709.            ground pattern, line-style and pattern, filling style, filling color and pattern, font,
  5710.            text-placement and text size.
  5711.  
  5712.      Errors: None.
  5713.  
  5714.    See also: SetViewPort (107), SetFillStyle (105), SetColor (104), SetBkColor (104), SetLineStyle
  5715.            (106)
  5716.  
  5717.  
  5718.            GraphErrorMsg
  5719. Declaration: Function GraphErrorMsg (ErrorCode : Integer) : String;
  5720.  
  5721. Description: GraphErrorMsg returns a string describing the error Errorcode. This string can
  5722.            be used to let the user know what went wrong.
  5723.  
  5724.      Errors: None.
  5725.  
  5726.    See also: GraphResult (99)
  5727.  
  5728.  
  5729.            GraphResult
  5730. Declaration: Function GraphResult : Integer;
  5731.  
  5732. Description: GraphResult returns an error-code for the last graphical operation. If the re-
  5733.            turned value is zero, all went well. A value di erent from zero means an error
  5734.            has occurred. Except for all operations which draw something on the screen, the
  5735.            following procedures also can produce a GraphResult di erent from zero:
  5736.  
  5737.                *InstallUserFont (100)
  5738.                *SetLineStyle (106)
  5739.                *SetWriteMode (108)
  5740.                *SetFillStyle (105)
  5741.                *SetTextJustify (106)
  5742.                *SetGraphMode (105)
  5743.                *SetTextStyle (107)
  5744.  
  5745.      Errors: None.
  5746.  
  5747.    See also: GraphErrorMsg (99)
  5748.  
  5749.  
  5750.            ImageSize
  5751. Declaration: Function ImageSize (X1,Y1,X2,Y2 : Integer) : Word;
  5752.  
  5753. Description: ImageSize returns the number of bytes needed to store the image in the rectangle
  5754.            defined by (X1,Y1) and (X2,Y2).
  5755.  
  5756.      Errors: None.
  5757.  
  5758.    See also: GetImage (96)
  5759.  
  5760.  
  5761.                                                      99
  5762.  
  5763.  
  5764.  
  5765.                                                          5.3. FUNCTIONS AND PROCEDURES
  5766.  
  5767.  
  5768.            InitGraph
  5769. Declaration: Procedure InitGraph (var GraphDriver,GraphModus : integer;
  5770.            const PathToDriver : string);
  5771.  
  5772. Description: InitGraph initializes the graph package. GraphDriver has two valid values:
  5773.            GraphDriver=0 which performs an auto detect and initializes the highest possible
  5774.            mode with the most colors. 1024x768x64K is the highest possible resolution sup-
  5775.            ported by the driver, if you need a higher resolution, you must edit MODES.PPI. If
  5776.            you need another mode, then set GraphDriver to a value di erent from zero and
  5777.            graphmode to the mode you wish (VESA modes where 640x480x256 is 101h etc.).
  5778.            PathToDriver is only needed, if you use the BGI fonts from Borland.
  5779.  
  5780.      Errors: None.
  5781.  
  5782.    See also: Introduction, (page 91), DetectGraph (93), CloseGraph (93), GraphResult (99)
  5783.  
  5784.            Example:
  5785.  
  5786.            vargd,gm : integer;
  5787.                PathToDriver : string;
  5788.            begin
  5789.                gd:=detect; { highest possible resolution }
  5790.                gm:=0; { not needed, auto detection }
  5791.                PathToDriver:='C:\PP\BGI'; { path to BGI fonts,
  5792.                                                        drivers aren't needed }
  5793.                InitGraph(gd,gm,PathToDriver);
  5794.                if GraphResult<>grok then
  5795.                     halt; ..... { whatever you need }
  5796.                CloseGraph; { restores the old graphics mode }
  5797.            end.
  5798.  
  5799.  
  5800.            InstallUserDriver
  5801. Declaration: Function InstallUserDriver (DriverPath : String;
  5802.            AutoDetectPtr: Pointer) : Integer;
  5803.  
  5804. Description: InstallUserDriver adds the device-driver DriverPath to the list of .BGI drivers.
  5805.            AutoDetectPtr is a pointer to a possible auto-detect function.
  5806.  
  5807.      Errors: None.
  5808.  
  5809.    See also: InitGraph (100), InstallUserFont (100)
  5810.  
  5811.  
  5812.            InstallUserFont
  5813. Declaration: Function InstallUserFont (FontPath : String) : Integer;
  5814.  
  5815. Description: InstallUserFont adds the font in FontPath to the list of fonts of the .BGI system.
  5816.  
  5817.      Errors: None.
  5818.  
  5819.    See also: InitGraph (100), InstallUserDriver (100)
  5820.  
  5821.  
  5822.  
  5823.  
  5824.                                                          100
  5825.  
  5826.  
  5827.  
  5828.                                                       5.3. FUNCTIONS AND PROCEDURES
  5829.  
  5830.  
  5831.            Line
  5832. Declaration: Procedure Line (X1,Y1,X2,Y2 : Integer);
  5833.  
  5834. Description: Line draws a line starting from (X1,Y1 to (X2,Y2), in the current line style and
  5835.            color. The current position is put to (X2,Y2)
  5836.  
  5837.      Errors: None.
  5838.  
  5839.    See also: LineRel (101),LineTo (101)
  5840.  
  5841.  
  5842.            LineRel
  5843. Declaration: Procedure LineRel (DX,DY : Integer);
  5844.  
  5845. Description: LineRel draws a line starting from the current pointer position to the point(DX,DY,
  5846.            relative to the current position, in the current line style and color. The Current
  5847.            Position is set to the endpoint of the line.
  5848.  
  5849.      Errors: None.
  5850.  
  5851.    See also: Line (101), LineTo (101)
  5852.  
  5853.  
  5854.            LineTo
  5855. Declaration: Procedure LineTo (DX,DY : Integer);
  5856.  
  5857. Description: LineTo draws a line starting from the current pointer position to the point(DX,DY,
  5858.            relative to the current position, in the current line style and color. The Current
  5859.            position is set to the end of the line.
  5860.  
  5861.      Errors: None.
  5862.  
  5863.    See also: LineRel (101),Line (101)
  5864.  
  5865.  
  5866.            MoveRel
  5867. Declaration: Procedure MoveRel (DX,DY : Integer;
  5868.  
  5869. Description: MoveRel moves the pointer to the point (DX,DY), relative to the current pointer
  5870.            position
  5871.  
  5872.      Errors: None.
  5873.  
  5874.    See also: MoveTo (101)
  5875.  
  5876.  
  5877.            MoveTo
  5878. Declaration: Procedure MoveTo (X,Y : Integer;
  5879.  
  5880. Description: MoveTo moves the pointer to the point (X,Y).
  5881.  
  5882.      Errors: None.
  5883.  
  5884.    See also: MoveRel (101)
  5885.  
  5886.  
  5887.  
  5888.  
  5889.                                                       101
  5890.  
  5891.  
  5892.  
  5893.                                                     5.3. FUNCTIONS AND PROCEDURES
  5894.  
  5895.  
  5896.            OutText
  5897. Declaration: Procedure OutText (Const TextString : String);
  5898. Description: OutText puts TextString on the screen, at the current pointer position, using the
  5899.            current font and text settings. The current position is moved to the end of the text.
  5900.      Errors: None.
  5901.    See also: OutTextXY (102)
  5902.  
  5903.  
  5904.            OutTextXY
  5905. Declaration: Procedure OutTextXY (X,Y : Integer; Const TextString : String);
  5906. Description: OutText puts TextString on the screen, at position (X,Y), using the current font
  5907.            and text settings. The current position is moved to the end of the text.
  5908.      Errors: None.
  5909.    See also: OutText (102)
  5910.  
  5911.  
  5912.            PieSlice
  5913. Declaration: Procedure PieSlice (X,Y : Integer;
  5914.            Start,Stop,Radius : Word);
  5915. Description: PieSlice draws and fills a sector of a circle with center (X,Y) and radius Radius,
  5916.            starting at angle Start and ending at angle Stop.
  5917.      Errors: None.
  5918.    See also: Arc (92), Circle (92), Sector (103)
  5919.  
  5920.  
  5921.            PutImage
  5922. Declaration: Procedure PutImage (X1,Y1 : Integer; Var Bitmap; How : word) ;
  5923. Description: PutImage Places the bitmap in Bitmap on the screen at (X1,Y1). How determines
  5924.            how the bitmap will be placed on the screen. Possible values are :
  5925.                 *CopyPut
  5926.                 *XORPut
  5927.                 *ORPut
  5928.                 *AndPut
  5929.                 *NotPut
  5930.      Errors: None
  5931.    See also: ImageSize (99),GetImage (96)
  5932.  
  5933.  
  5934.            PutPixel
  5935. Declaration: Procedure PutPixel (X,Y : Integer; Color : Word);
  5936. Description: Puts a point at (X,Y) using color Color
  5937.      Errors: None.
  5938.    See also: GetPixel (98)
  5939.  
  5940.  
  5941.                                                     102
  5942.  
  5943.  
  5944.  
  5945.                                                       5.3. FUNCTIONS AND PROCEDURES
  5946.  
  5947.  
  5948.             Rectangle
  5949. Declaration: Procedure Rectangle (X1,Y1,X2,Y2 : Integer);
  5950.  
  5951. Description: Draws a rectangle with corners at (X1,Y1) and (X2,Y2), using the current color
  5952.             and style.
  5953.  
  5954.      Errors: None.
  5955.  
  5956.    See also: Bar (92), Bar3D (92)
  5957.  
  5958.  
  5959.             RegisterBGIDriver
  5960. Declaration: Function RegisterBGIDriver (Driver : Pointer) : Integer;
  5961.  
  5962. Description: Registers a user-defined BGI driver
  5963.  
  5964.      Errors: None.
  5965.  
  5966.    See also: InstallUserDriver (100), RegisterBGIFont (103)
  5967.  
  5968.  
  5969.             RegisterBGIFont
  5970. Declaration: Function RegisterBGIFont (Font : Pointer) : Integer;
  5971.  
  5972. Description: Registers a user-defined BGI driver
  5973.  
  5974.      Errors: None.
  5975.  
  5976.    See also: InstallUserFont (100), RegisterBGIDriver (103)
  5977.  
  5978.  
  5979.             RestoreCRTMode
  5980. Declaration: Procedure RestoreCRTMode ;
  5981.  
  5982. Description: Restores the screen modus which was active before the graphical modus was
  5983.             started.
  5984.  
  5985.      Errors: None.
  5986.  
  5987.    See also: InitGraph (100)
  5988.  
  5989.  
  5990.             Sector
  5991. Declaration: Procedure Sector (X,Y : Integer;
  5992.             Start,Stop,XRadius,YRadius : Word);
  5993.  
  5994. Description: Sector draws and fills a sector of an ellipse with center (X,Y) and radii XRadius
  5995.             and YRadius, starting at angle Start and ending at angle Stop.
  5996.  
  5997.      Errors: None.
  5998.  
  5999.    See also: Arc (92), Circle (92), PieSlice (102)
  6000.  
  6001.  
  6002.  
  6003.  
  6004.  
  6005.  
  6006.                                                       103
  6007.  
  6008.  
  6009.  
  6010.                                                      5.3. FUNCTIONS AND PROCEDURES
  6011.  
  6012.  
  6013.            SetActivePage
  6014. Declaration: Procedure SetActivePage (Page : Word);
  6015.  
  6016. Description: Sets Page as the active page for all graphical output.
  6017.  
  6018.      Errors: None.
  6019.  
  6020.    See also:
  6021.  
  6022.  
  6023.            SetAllPallette
  6024. Declaration: Procedure SetAllPallette (Var Palette);
  6025.  
  6026. Description: Sets the current palette to Palette. Palette is an untyped variable, usually
  6027.            pointing to a record of type PaletteType
  6028.  
  6029.      Errors: None.
  6030.  
  6031.    See also: GetPalette (97)
  6032.  
  6033.  
  6034.            SetAspectRatio
  6035. Declaration: Procedure SetAspectRatio (Xasp,Yasp : Word);
  6036.  
  6037. Description: Sets the aspect ratio of the current screen to Xasp/Yasp.
  6038.  
  6039.      Errors: None
  6040.  
  6041.    See also: InitGraph (100), GetAspectRatio (95)
  6042.  
  6043.  
  6044.            SetBkColor
  6045. Declaration: Procedure SetBkColor (Color : Word);
  6046.  
  6047. Description: Sets the background color to Color.
  6048.  
  6049.      Errors: None.
  6050.  
  6051.    See also: GetBkColor (95), SetColor (104)
  6052.  
  6053.  
  6054.            SetColor
  6055. Declaration: Procedure SetColor (Color : Word);
  6056.  
  6057. Description: Sets the foreground color to Color.
  6058.  
  6059.      Errors: None.
  6060.  
  6061.    See also: GetColor (95), SetBkColor (104)
  6062.  
  6063.  
  6064.  
  6065.  
  6066.  
  6067.  
  6068.  
  6069.  
  6070.                                                      104
  6071.  
  6072.  
  6073.  
  6074.                                                         5.3. FUNCTIONS AND PROCEDURES
  6075.  
  6076.  
  6077.             SetFillPattern
  6078. Declaration: Procedure SetFillPattern (FillPattern : FillPatternType,
  6079.             Color : Word);
  6080. Description: SetFillPattern sets the current fill-pattern to FillPattern, and the filling color
  6081.             to Color The pattern is an 8x8 raster, corresponding to the 64 bits in FillPattern.
  6082.      Errors: None
  6083.    See also: GetFillPattern (95), SetFillStyle (105)
  6084.  
  6085.  
  6086.             SetFillStyle
  6087. Declaration: Procedure SetFillStyle (Pattern,Color : word);
  6088. Description: SetFillStyle sets the filling pattern and color to one of the predefined filling
  6089.             patterns. Pattern can be one of the following predefined constants :
  6090.                 *EmptyFill Uses backgroundcolor.
  6091.                 *SolidFill Uses filling color
  6092.                 *LineFill Fills with horizontal lines.
  6093.                 *ltSlashFill Fills with lines from left-under to top-right.
  6094.                 *SlashFill Idem as previous, thick lines.
  6095.                 *BkSlashFill Fills with thick lines from left-Top to bottom-right.
  6096.                 *LtBkSlashFill Idem as previous, normal lines.
  6097.                 *HatchFill Fills with a hatch-like pattern.
  6098.                 *XHatchFill Fills with a hatch pattern, rotated 45 degrees.
  6099.                 *InterLeaveFill
  6100.                 *WideDotFill Fills with dots, wide spacing.
  6101.                 *CloseDotFill Fills with dots, narrow spacing.
  6102.                 *UserFill Fills with a user-defined pattern.
  6103.      Errors: None.
  6104.    See also: SetFillPattern (105)
  6105.  
  6106.  
  6107.             SetGraphBufSize
  6108. Declaration: Procedure SetGraphBufSize (BufSize : Word);
  6109. Description: SetGraphBufSize sets the graphical bu er size. The default size is 4Kb
  6110.      Errors: None.
  6111.    See also:
  6112.  
  6113.  
  6114.             SetGraphMode
  6115. Declaration: Procedure SetGraphMode (Mode : Integer);
  6116. Description: SetGraphMode sets the graphical mode and clears the screen.
  6117.      Errors: None.
  6118.    See also: InitGraph (100)
  6119.  
  6120.  
  6121.                                                         105
  6122.  
  6123.  
  6124.  
  6125.                                                        5.3. FUNCTIONS AND PROCEDURES
  6126.  
  6127.  
  6128.            SetLineStyle
  6129. Declaration: Procedure SetLineStyle (LineStyle,Pattern,Width : Word);
  6130.  
  6131. Description: SetLineStyle sets the drawing style for lines. You can specify a LineStyle which
  6132.            is one of the following pre-defined constants:
  6133.  
  6134.                *Solidln=0; draws a solid line.
  6135.                *Dottedln=1; Draws a dotted line.
  6136.                *Centerln=2; draws a non-broken centered line.
  6137.                *Dashedln=3; draws a dashed line.
  6138.                *UserBitln=4; Draws a User-defined bit pattern.
  6139.  
  6140.            If UserBitln is specified then Pattern contains the bit pattern. In all another
  6141.            cases, Pattern is ignored. The parameter Width indicates how thick the line should
  6142.            be. You can specify one of the following pre-defined constants:
  6143.  
  6144.                *NormWidth=1
  6145.                *ThickWidth=3
  6146.  
  6147.      Errors: None.
  6148.  
  6149.    See also: GetLineSettings (96)
  6150.  
  6151.  
  6152.            SetPalette
  6153. Declaration: Procedure SetPalette (ColorNr : Word; NewColor : ShortInt);
  6154.  
  6155. Description: SetPalette changes the ColorNr-th entry in the palette to NewColor
  6156.  
  6157.      Errors: None.
  6158.  
  6159.    See also: SetAllPallette (104),SetRGBPalette (106)
  6160.  
  6161.  
  6162.            SetRGBPalette
  6163. Declaration: Procedure SetRGBPalette (ColorNr,Red,Green,Blue : Integer);
  6164.  
  6165. Description: SetRGBPalette sets the ColorNr-th entry in the palette to the color with RGB-
  6166.            values Red, Green Blue.
  6167.  
  6168.      Errors: None.
  6169.  
  6170.    See also: SetAllPallette (104), SetPalette (106)
  6171.  
  6172.  
  6173.            SetTextJustify
  6174. Declaration: Procedure SetTextJustify (Horizontal,Vertical : Word);
  6175.  
  6176. Description: SetTextJustify controls the placement of new text, relative to the (graphical)
  6177.            cursor position. Horizontal controls horizontal placement, and can be one of the
  6178.            following pre-defined constants:
  6179.  
  6180.                *LeftText=0; Text is set left of the pointer.
  6181.                *CenterText=1; Text is set centered horizontally on the pointer.
  6182.                *RightText=2; Text is set to the right of the pointer.
  6183.  
  6184.                                                        106
  6185.  
  6186.  
  6187.  
  6188.                                                       5.3. FUNCTIONS AND PROCEDURES
  6189.  
  6190.  
  6191.            Vertical controls the vertical placement of the text, relative to the (graphical)
  6192.            cursor position. Its value can be one of the following pre-defined constants :
  6193.  
  6194.                *BottomText=0; Text is placed under the pointer.
  6195.                *CenterText=1; Text is placed centered vertically on the pointer.
  6196.                *TopText=2;Text is placed above the pointer.
  6197.  
  6198.      Errors: None.
  6199.  
  6200.    See also: OutText (102), OutTextXY (102)
  6201.  
  6202.  
  6203.            SetTextStyle
  6204. Declaration: Procedure SetTextStyle (Font,Direction,Magnitude : Word);
  6205.  
  6206. Description: SetTextStyle controls the style of text to be put on the screen. pre-defined
  6207.            constants for Font are:
  6208.  
  6209.                *DefaultFont=0;
  6210.                *TriplexFont=2;
  6211.                *SmallFont=2;
  6212.                *SansSerifFont=3;
  6213.                *GothicFont=4;
  6214.  
  6215.            Pre-defined constants for Direction are :
  6216.  
  6217.                *HorizDir=0;
  6218.                *VertDir=1;
  6219.      Errors: None.
  6220.  
  6221.    See also: GetTextSettings (98)
  6222.  
  6223.  
  6224.            SetUserCharSize
  6225. Declaration: Procedure SetUserCharSize (Xasp1,Xasp2,Yasp1,Yasp2 : Word);
  6226.  
  6227. Description: Sets the width and height of vector-fonts. The horizontal size is given by Xasp1/Xasp2,
  6228.            and the vertical size by Yasp1/Yasp2.
  6229.  
  6230.      Errors: None.
  6231.  
  6232.    See also: SetTextStyle (107)
  6233.  
  6234.  
  6235.            SetViewPort
  6236. Declaration: Procedure SetViewPort (X1,Y1,X2,Y2 : Integer; Clip : Boolean);
  6237.  
  6238. Description: Sets the current graphical view-port (window) to the rectangle defined by the top-
  6239.            left corner (X1,Y1) and the bottom-right corner (X2,Y2). If Clip is true, anything
  6240.            drawn outside the view-port (window) will be clipped (i.e. not drawn). Coordinates
  6241.            specified after this call are relative to the top-left corner of the view-port.
  6242.  
  6243.      Errors: None.
  6244.  
  6245.    See also: GetViewSettings (98)
  6246.  
  6247.  
  6248.                                                      107
  6249.  
  6250.  
  6251.  
  6252.                                                     5.3. FUNCTIONS AND PROCEDURES
  6253.  
  6254.  
  6255.            SetVisualPage
  6256. Declaration: Procedure SetVisualPage (Page : Word);
  6257.  
  6258. Description: SetVisualPage sets the video page to page number Page.
  6259.  
  6260.      Errors: None
  6261.  
  6262.    See also: SetActivePage (104)
  6263.  
  6264.  
  6265.            SetWriteMode
  6266. Declaration: Procedure SetWriteMode (Mode : Integer);
  6267.  
  6268. Description: SetWriteMode controls the drawing of lines on the screen. It controls the binary
  6269.            operation used when drawing lines on the screen. Mode can be one of the following
  6270.            pre-defined constants:
  6271.  
  6272.                 *CopyPut=0;
  6273.                 *XORPut=1;
  6274.  
  6275.      Errors: None.
  6276.  
  6277.    See also:
  6278.  
  6279.  
  6280.            TextHeight
  6281. Declaration: Function TextHeight (S : String) : Word;
  6282.  
  6283. Description: TextHeight returns the height (in pixels) of the string S in the current font and
  6284.            text-size.
  6285.  
  6286.      Errors: None.
  6287.  
  6288.    See also: TextWidth (108)
  6289.  
  6290.  
  6291.            TextWidth
  6292. Declaration: Function TextWidth (S : String) : Word;
  6293.  
  6294. Description: TextHeight returns the width (in pixels) of the string S in the current font and
  6295.            text-size.
  6296.  
  6297.      Errors: None.
  6298.  
  6299.    See also: TextHeight (108)
  6300.  
  6301.  
  6302.  
  6303.  
  6304.  
  6305.  
  6306.  
  6307.  
  6308.  
  6309.  
  6310.  
  6311.  
  6312.                                                   108
  6313.  
  6314.  
  6315.  
  6316. Chapter 6
  6317.  
  6318. The HEAPTRC unit.
  6319.  
  6320. This chapter describes the HEAPTRC unit for Free Pascal. It was written by Pierre
  6321. Muller.
  6322.  
  6323.  
  6324. 6.1 Purpose
  6325.  
  6326. The HEAPTRC unit can be used to debug your memory allocation/deallocation.
  6327. It keeps track of the calls to getmem/freemem, and, implicitly, of New/Dispose
  6328. statements.
  6329. When the program exits, or when you request it explicitly. It displays the total
  6330. memory used, and then dumps a list of blocks that were allocated but not freed. It
  6331. also displays where the memory was allocated.
  6332. If there are any inconsistencies, such as memory blocks being allocated or freed
  6333. twice, or a memory block that is released but with wrong size, this will be displayed
  6334. also.
  6335. The information that is stored/displayed can be customized using some constants.
  6336.  
  6337.  
  6338. 6.2 Usage
  6339.  
  6340. All that you need to do is to include heaptrc in the uses clause of your program.
  6341. Make sure that it is the first unit in the clause, otherwise memory allocated in
  6342. initialization code of units that precede the heaptrc unit will not be accounted for,
  6343. causing an incorrect memory usage report.
  6344. The following example shows how to use the heaptrc unit.
  6345. Program heapex ;
  6346.  
  6347. { Program used to demonstrate the usage of heaptrc unit }
  6348.  
  6349. Uses heaptrc ;
  6350.  
  6351. Var P1 :   Longint ;
  6352.          P2 : Pointer ;
  6353.          I : l o n g i n t ;
  6354.  
  6355. begin
  6356.  
  6357.                                         109
  6358.  
  6359.  
  6360.  
  6361.                                                                          6.2. USAGE
  6362.  
  6363.  
  6364.   New( P1 ) ;
  6365.   // causes p r e v i o u s a l l o c a t i o n not to be de-a l l o c a t e d
  6366.   New( P1 ) ;
  6367.   Dispose ( P1 ) ;
  6368.   For I :=1 to 10 do
  6369.          begin
  6370.          GetMem ( P2 , 1 2 8 ) ;
  6371.          // When I is even , d e a l l o c a t e block . We l o o s e 5 times 128
  6372.          // bytes t h i s way .
  6373.          I f ( I mod 2 ) = 0 Then FreeMem( P2 , 1 2 8 ) ;
  6374.          end ;
  6375.   GetMem( P2 , 1 2 8 ) ;
  6376.   // This w i l l provoke an e r r o r and a memory dump
  6377.   Freemem ( P2 , 6 4 ) ;
  6378. end .
  6379. This is the memory dump shown when running this program:
  6380.  
  6381. Marked memory at 08052C48 invalid
  6382. Wrong size : 128 allocated 64 freed
  6383.   0x0804C29C
  6384.   0x080509E2
  6385.   0x080480A4
  6386.   0x00000000
  6387. Heap dump by heaptrc unit
  6388. 13 memory blocks allocated : 1416/1424
  6389. 6 memory blocks freed               : 708/712
  6390. 7 unfreed memory blocks : 708
  6391. True heap size : 2097152
  6392. True free heap : 2096040
  6393. Should be : 2096104
  6394. Call trace for block 0x08052C48 size 128
  6395.   0x080509D6
  6396.   0x080480A4
  6397. Call trace for block 0x08052B98 size 128
  6398.   0x08050992
  6399.   0x080480A4
  6400. Call trace for block 0x08052AE8 size 128
  6401.   0x08050992
  6402.   0x080480A4
  6403. Call trace for block 0x08052A38 size 128
  6404.   0x08050992
  6405.   0x080480A4
  6406. Call trace for block 0x08052988 size 128
  6407.   0x08050992
  6408.   0x080480A4
  6409. Call trace for block 0x080528D8 size 128
  6410.   0x08050992
  6411.   0x080480A4
  6412. Call trace for block 0x080528A0 size 4
  6413.   0x08050961
  6414.   0x080480A4
  6415.  
  6416.  
  6417.  
  6418.  
  6419.                                           110
  6420.  
  6421.  
  6422.  
  6423.                                                 6.3. CONSTANTS, TYPES AND VARIABLES
  6424.  
  6425.  
  6426.            6.3 Constants, Types and variables
  6427.  
  6428.            The FillExtraInfoType is a procedural type used in the SetExtraInfo (112) call.
  6429.            type FillExtraInfoType = procedure(p : pointer );
  6430.            The following typed constants allow to fine-tune the standard dump of the memory
  6431.            usage by DumpHeap (111):
  6432.            const
  6433.               t r a c e s i z e = 8;
  6434.               q u i c k t r a c e : boolean = true ;
  6435.               HaltOnError : boolean = true ;
  6436.               k e e p r e l e a s e d : boolean = f a l s e ;
  6437.            Tracesize specifies how many levels of calls are displayed of the call stack during
  6438.            the memory dump. If you specify keepreleased:=True then half the TraceSize
  6439.            is reserved for the GetMem call stack, and the other half is reserved for the FreeMem
  6440.            call stack. For example, the default value of 8 will cause eight levels of call frames
  6441.            to be dumped for the getmem call if keepreleased is False. If KeepReleased is
  6442.            true, then 4 levels of call frames will be dumped for the GetMem call and 4 frames
  6443.            wil be dumped for the FreeMem call. If you want to change this value, you must
  6444.            recode the heaptrc unit.
  6445.            Quicktrace determines whether the memory manager checks whether a block that
  6446.            is about to be released is allocated correctly. This is a rather time consuming search,
  6447.            and slows program execution significantly, so by default it is set to False.
  6448.            If HaltOnError is set to True then an illegal call to FreeMem will cause the memory
  6449.            manager to execute a halt(1) instruction, causing a memory dump. By Default it
  6450.            is set to True.
  6451.            If keepreleased is set to true, then a list of freed memory blocks is kept. This
  6452.            is useful if you suspect that the same memory block is released twice. However,
  6453.            this option is very memory intensive, so use it sparingly, and only when it's really
  6454.            necessary.
  6455.  
  6456.  
  6457.            6.4 Functions and procedures
  6458.  
  6459.            DumpHeap
  6460. Declaration: procedure DumpHeap;
  6461.  
  6462. Description: DumpHeap dumps to standard output a summary of memory usage. It is called
  6463.            automatically by the heaptrc unit when your program exits (by instaling an exit
  6464.            procedure), but it can be called at any time
  6465.  
  6466.     Errors: None.
  6467.  
  6468.   See also: MarkHeap (111)
  6469.  
  6470.  
  6471.            MarkHeap
  6472. Declaration: procedure MarkHeap;
  6473.  
  6474. Description: MarkHeap marks all memory blocks with a special signature. You can use this if
  6475.            you think that you corruped the memory.
  6476.  
  6477.                                                        111
  6478.  
  6479.  
  6480.  
  6481.                                                     6.4. FUNCTIONS AND PROCEDURES
  6482.  
  6483.  
  6484.      Errors: None.
  6485.  
  6486.    See also: DumpHeap (111)
  6487.  
  6488.  
  6489.            SetExtraInfo
  6490. Declaration: procedure SetExtraInfo( size : longint;func : FillExtraInfoType);
  6491.  
  6492. Description: You can use SetExtraInfo to store extra info in the blocks that the heaptrc unit
  6493.            reserves when tracing getmem calls. Size indicates the size (in bytes) that the trace
  6494.            mechanism should reserve for your extra information. For each call to getmem, func
  6495.            will be called, and passed a pointer to the memory reserved.
  6496.            When dumping the memory summary, the extra info is shown as Longint values.
  6497.  
  6498.      Errors: You can only call SetExtraInfo if no memroy has been allocated yet. If memory
  6499.            was already allocated prior to the call to SetExtraInfo, then an error will be
  6500.            displayed on standard error output, and a DumpHeap (111) is executed.
  6501.  
  6502.    See also: DumpHeap (111)
  6503.  
  6504.            Program heapex ;
  6505.  
  6506.            { Program used to demonstrate the usage of heaptrc unit }
  6507.  
  6508.            Uses heaptrc ;
  6509.  
  6510.            Var P1 :   Longint ;
  6511.                     P2 : Pointer ;
  6512.                     I : l o n g i n t ;
  6513.                     Marker : Longint ;
  6514.  
  6515.            Procedure SetMarker ( P : p o i n t e r ) ;
  6516.  
  6517.            Type PLongint =   Longint ;
  6518.  
  6519.            begin
  6520.               PLongint (P) := Marker ;
  6521.            end ;
  6522.  
  6523.            Procedure           Part1 ;
  6524.  
  6525.            begin
  6526.               // Blocks a l l o c a t e d here are marked with $FFAAFFAA = -5570646
  6527.               Marker := $FFAAFFAA;
  6528.               New( P1 ) ;
  6529.               New( P1 ) ;
  6530.               Dispose ( P1 ) ;
  6531.               For I :=1 to 10 do
  6532.                     begin
  6533.                     GetMem ( P2 , 1 2 8 ) ;
  6534.                     I f ( I mod 2) = 0 Then FreeMem( P2 , 1 2 8 ) ;
  6535.                     end ;
  6536.               GetMem( P2 , 1 2 8 ) ;
  6537.            end ;
  6538.  
  6539.  
  6540.                                                    112
  6541.  
  6542.  
  6543.  
  6544.                                             6.4. FUNCTIONS AND PROCEDURES
  6545.  
  6546.  
  6547.  
  6548. Procedure          Part2 ;
  6549.  
  6550. begin
  6551.   // Blocks a l l o c a t e d here are marked with $FAFAFAFA = -84215046
  6552.   Marker := $FAFAFAFA;
  6553.   New( P1 ) ;
  6554.   New( P1 ) ;
  6555.   Dispose ( P1 ) ;
  6556.   For I :=1 to 10 do
  6557.          begin
  6558.          GetMem ( P2 , 1 2 8 ) ;
  6559.          I f ( I mod 2 ) = 0 Then FreeMem( P2 , 1 2 8 ) ;
  6560.          end ;
  6561.   GetMem( P2 , 1 2 8 ) ;
  6562. end ;
  6563.  
  6564. begin
  6565.  S e t E x t r a I n f o ( SizeOf ( Marker ) , @SetMarker ) ;
  6566.  Writeln ( ' Part 1' ) ;
  6567.  part1 ;
  6568.  Writeln ( ' Part 2' ) ;
  6569.  part2 ;
  6570. end .
  6571.  
  6572.  
  6573.  
  6574.  
  6575.  
  6576.  
  6577.  
  6578.  
  6579.  
  6580.  
  6581.  
  6582.  
  6583.  
  6584.  
  6585.  
  6586.  
  6587.  
  6588.  
  6589.  
  6590.  
  6591.  
  6592.  
  6593.  
  6594.  
  6595.  
  6596.  
  6597.  
  6598.  
  6599.  
  6600.                                            113
  6601.  
  6602.  
  6603.  
  6604. Chapter 7
  6605.  
  6606. The IPC unit.
  6607.  
  6608. This chapter describes the IPC unit for Free Pascal. It was written for linux
  6609. by Micha¿el Van Canneyt. It gives all the functionality of system V Inter-Process
  6610. Communication: shared memory, semaphores and messages.
  6611. The chapter is divided in 2 sections:
  6612.  
  6613.    * The first section lists types, constants and variables from the interface part of
  6614.      the unit.
  6615.  
  6616.    * The second section describes the functions defined in the unit.
  6617.  
  6618.  
  6619. 7.1 Types, Constants and variables :
  6620.  
  6621. Variables
  6622. VarIPCerror : longint;
  6623. The IPCerror variable is used to report errors, by all calls.
  6624.  
  6625.  
  6626. Constants
  6627. Const
  6628.   IPC_CREAT = 1 shl 9; { create if key is nonexistent }
  6629.   IPC_EXCL        = 2 shl 9; { fail if key exists }
  6630.   IPC_NOWAIT = 4 shl 9; { return error on wait }
  6631.  
  6632. These constants are used in the various xxxget calls.
  6633.  
  6634.   IPC_RMID = 0;         { remove resource }
  6635.   IPC_SET = 1;          { set ipc_perm options }
  6636.   IPC_STAT = 2;         { get ipc_perm options }
  6637.   IPC_INFO = 3;         { see ipcs }
  6638.  
  6639. These constants can be passed to the various xxxctl calls.
  6640.  
  6641. const
  6642.   MSG_NOERROR = 1 shl 12;
  6643.  
  6644.                                          114
  6645.  
  6646.  
  6647.  
  6648.                                 7.1. TYPES, CONSTANTS AND VARIABLES :
  6649.  
  6650.  
  6651.   MSG_EXCEPT = 2 shl 12;
  6652.   MSGMNI = 128;
  6653.   MSGMAX = 4056;
  6654.   MSGMNB = 16384;
  6655.  
  6656. These constants are used in the messaging system, they are not for use by the
  6657. programmer.
  6658.  
  6659. const
  6660.   SEM_UNDO = $1000;
  6661.   GETPID = 11;
  6662.   GETVAL = 12;
  6663.   GETALL = 13;
  6664.   GETNCNT = 14;
  6665.   GETZCNT = 15;
  6666.   SETVAL = 16;
  6667.   SETALL = 17;
  6668.  
  6669. These constants call be specified in the semop (123) call.
  6670.  
  6671.   SEMMNI = 128;
  6672.   SEMMSL = 32;
  6673.   SEMMNS = (SEMMNI * SEMMSL);
  6674.   SEMOPM = 32;
  6675.   SEMVMX = 32767;
  6676.  
  6677. These constanst are used internally by the semaphore system, they should not be
  6678. used by the programmer.
  6679.  
  6680. const
  6681.   SHM_R         = 4 shl 6;
  6682.   SHM_W         = 2 shl 6;
  6683.   SHM_RDONLY = 1 shl 12;
  6684.   SHM_RND       = 2 shl 12;
  6685.   SHM_REMAP = 4 shl 12;
  6686.   SHM_LOCK      = 11;
  6687.   SHM_UNLOCK = 12;
  6688.  
  6689. These constants are used in the shmctl (130) call.
  6690.  
  6691.  
  6692. Types
  6693. TypeTKey = Longint;
  6694.  
  6695. TKey is the type returned by the ftok (119) key generating function.
  6696.  
  6697. type
  6698.   PIPC_Perm = ^TIPC_Perm;
  6699.   TIPC_Perm = record
  6700.         key : TKey;
  6701.         uid,
  6702.         gid,
  6703.  
  6704.  
  6705.                                         115
  6706.  
  6707.  
  6708.  
  6709.                                      7.1. TYPES, CONSTANTS AND VARIABLES :
  6710.  
  6711.  
  6712.         cuid,
  6713.         cgid,
  6714.         mode,
  6715.         seq : Word;
  6716.   end;
  6717.  
  6718. The TIPC Perm structure is used in all IPC systems to specify the permissions.
  6719.  
  6720. Type
  6721.   PSHMid_DS = ^TSHMid_ds;
  6722.   TSHMid_ds = record
  6723.         shm_perm : TIPC_Perm;
  6724.         shm_segsz : longint;
  6725.         shm_atime : longint;
  6726.         shm_dtime : longint;
  6727.         shm_ctime : longint;
  6728.         shm_cpid : word;
  6729.         shm_lpid : word;
  6730.         shm_nattch : integer;
  6731.         shm_npages : word;
  6732.         shm_pages : Pointer;
  6733.         attaches       : pointer;
  6734.   end;
  6735.  
  6736. The TSHMid ds strucure is used in the shmctl (130) call to set or retrieve settings
  6737. concerning shared memory.
  6738.  
  6739. type
  6740.   PSHMinfo = ^TSHMinfo;
  6741.   TSHMinfo = record
  6742.         shmmax : longint;
  6743.         shmmin : longint;
  6744.         shmmni : longint;
  6745.         shmseg : longint;
  6746.         shmall : longint;
  6747.   end;
  6748.  
  6749. The TSHMinfo record is used by the shared memory system, and should not be
  6750. accessed by the programer directly.
  6751.  
  6752. type
  6753.   PMSG = ^TMSG;
  6754.   TMSG = record
  6755.         msg_next : PMSG;
  6756.         msg_type : Longint;
  6757.         msg_spot : PChar;
  6758.         msg_stime : Longint;
  6759.         msg_ts      : Integer;
  6760.   end;
  6761.  
  6762. The TMSG record is used in the handling of message queues. There should be few
  6763. cases where the programmer needs to access this data.
  6764.  
  6765. type
  6766.  
  6767.                                           116
  6768.  
  6769.  
  6770.  
  6771.                                    7.1. TYPES, CONSTANTS AND VARIABLES :
  6772.  
  6773.  
  6774.   PMSQid_ds = ^TMSQid_ds;
  6775.   TMSQid_ds = record
  6776.         msg_perm     : TIPC_perm;
  6777.         msg_first : PMsg;
  6778.         msg_last     : PMsg;
  6779.         msg_stime : Longint;
  6780.         msg_rtime : Longint;
  6781.         msg_ctime : Longint;
  6782.         wwait        : Pointer;
  6783.         rwait        : pointer;
  6784.         msg_cbytes : word;
  6785.         msg_qnum     : word;
  6786.         msg_qbytes : word;
  6787.         msg_lspid : word;
  6788.         msg_lrpid : word;
  6789.   end;
  6790.  
  6791. The TMSQid ds record is returned by the msgctl (120) call, and contains all data
  6792. about a message queue.
  6793.  
  6794.   PMSGbuf = ^TMSGbuf;
  6795.   TMSGbuf = record
  6796.         mtype : longint;
  6797.         mtext : array[0..0] of char;
  6798.   end;
  6799.  
  6800. The TMSGbuf record is a record containing the data of a record. you should never
  6801. use this record directly, instead you should make your own record that follows
  6802. the structure of the TMSGbuf record, but that has a size that is big enough to
  6803. accomodate your messages. The mtype field should always be present, and should
  6804. always be filled.
  6805.  
  6806. Type
  6807.   PMSGinfo = ^TMSGinfo;
  6808.   TMSGinfo = record
  6809.         msgpool : Longint;
  6810.         msgmap : Longint;
  6811.         msgmax : Longint;
  6812.         msgmnb : Longint;
  6813.         msgmni : Longint;
  6814.         msgssz : Longint;
  6815.         msgtql : Longint;
  6816.         msgseg : Word;
  6817.   end;
  6818.  
  6819. The TMSGinfo record is used internally by the message queue system, and should
  6820. not be used by the programmer directly.
  6821.  
  6822. Type
  6823.   PSEMid_ds = ^PSEMid_ds;
  6824.   TSEMid_ds = record
  6825.         sem_perm : tipc_perm;
  6826.         sem_otime : longint;
  6827.         sem_ctime : longint;
  6828.  
  6829.                                         117
  6830.  
  6831.  
  6832.  
  6833.                                   7.1. TYPES, CONSTANTS AND VARIABLES :
  6834.  
  6835.  
  6836.         sem_base             : pointer;
  6837.         sem_pending          : pointer;
  6838.         sem_pending_last : pointer;
  6839.         undo                 : pointer;
  6840.         sem_nsems : word;
  6841.   end;
  6842.  
  6843. The TSEMid ds structure is returned by the semctl (124) call, and contains all data
  6844. concerning a semahore.
  6845.  
  6846. Type
  6847.   PSEMbuf = ^TSEMbuf;
  6848.   TSEMbuf = record
  6849.         sem_num : word;
  6850.         sem_op : integer;
  6851.         sem_flg : integer;
  6852.   end;
  6853.  
  6854. The TSEMbuf record us use in the semop (123) call, and is used to specify which
  6855. operations you want to do.
  6856.  
  6857. Type
  6858.   PSEMinfo = ^TSEMinfo;
  6859.   TSEMinfo = record
  6860.         semmap : longint;
  6861.         semmni : longint;
  6862.         semmns : longint;
  6863.         semmnu : longint;
  6864.         semmsl : longint;
  6865.         semopm : longint;
  6866.         semume : longint;
  6867.         semusz : longint;
  6868.         semvmx : longint;
  6869.         semaem : longint;
  6870.   end;
  6871.  
  6872. The TSEMinfo record is used internally by the semaphore system, and should not
  6873. be used diirectly.
  6874.  
  6875. Type
  6876.   PSEMun = ^TSEMun;
  6877.   TSEMun = record
  6878.    case longint of
  6879.           0 : ( val : longint );
  6880.           1 : ( buf : PSEMid_ds );
  6881.           2 : ( arr : PWord );
  6882.           3 : ( padbuf : PSeminfo );
  6883.           4 : ( padpad : pointer );
  6884.    end;
  6885.  
  6886. The TSEMun variant record (actually a C union) is used in the semctl (124) call.
  6887.  
  6888.  
  6889.  
  6890.  
  6891.                                            118
  6892.  
  6893.  
  6894.  
  6895.                                                          7.2. FUNCTIONS AND PROCEDURES
  6896.  
  6897.  
  6898.            7.2 Functions and procedures
  6899.  
  6900.            ftok
  6901. Declaration: Function ftok (Path : String; ID : char) : TKey;
  6902.  
  6903. Description: ftok returns a key that can be used in a semget (123),shmget (129) or msgget
  6904.            (119) call to access a new or existing IPC resource.
  6905.            Path is the name of a file in the file system, ID is a character of your choice. The
  6906.            ftok call does the same as it's C couterpart, so a pascal program and a C program
  6907.            will access the same resource if they use the same Path and ID
  6908.  
  6909.     Errors: ftok returns -1 if the file in Path doesn't exist.
  6910.  
  6911.   See also: semget (123),shmget (129),msgget (119)
  6912.  
  6913.            For an example, see msgctl (120), semctl (124), shmctl (130).
  6914.  
  6915.  
  6916.            msgget
  6917. Declaration: Function msgget(key: TKey; msgflg:longint):longint;
  6918.  
  6919. Description: msgget returns the ID of the message queue described by key. Depending on the
  6920.            flags in msgflg, a new queue is created.
  6921.            msgflg can have one or more of the following values (combined by ORs):
  6922.  
  6923.            IPC CREATThe queue is created if it doesn't already exist.
  6924.            IPC EXCLIf used in combination with IPC CREAT, causes the call to fail if the
  6925.                    queue already exists. It cannot be used by itself.
  6926.  
  6927.            Optionally, the flags can be ORed with a permission mode, which is the same mode
  6928.            that can be used in the file system.
  6929.  
  6930.     Errors: On error, -1 is returned, and IPCError is set.
  6931.  
  6932.   See also: ftok (119),msgsnd (119), msgrcv (120), msgctl (120), semget (2)
  6933.  
  6934.            For an example, see msgctl (120).
  6935.  
  6936.  
  6937.            msgsnd
  6938. Declaration: Function msgsnd(msqid:longint; msgp: PMSGBuf; msgsz: longint; msgflg:longint):
  6939.            Boolean;
  6940.  
  6941. Description: msgsend sends a message to a message queue with ID msqid. msgp is a pointer to
  6942.            a message bu er, that should be based on the TMsgBuf type. msgsiz is the size of
  6943.            the message (NOT of the message bu er record !)
  6944.            The msgflg can have a combination of the following values (ORed together):
  6945.  
  6946.            0No special meaning. The message will be written to the queue. If the queue is
  6947.                    full, then the process is blocked.
  6948.            IPC NOWAITIf the queue is full, then no message is written, and the call returns
  6949.                    immediatly.
  6950.  
  6951.            The function returns True if the message was sent successfully, False otherwise.
  6952.  
  6953.                                                          119
  6954.  
  6955.  
  6956.  
  6957.                                                       7.2. FUNCTIONS AND PROCEDURES
  6958.  
  6959.  
  6960.     Errors: In case of error, the call returns False, and IPCerror is set.
  6961.  
  6962.   See also: msgget (119), msgrcv (120), seefmsgctl
  6963.  
  6964.            For an example, see msgctl (120).
  6965.  
  6966.  
  6967.            msgrcv
  6968. Declaration: Function msgrcv(msqid:longint; msgp: PMSGBuf; msgsz: longint; msgtyp:longint;
  6969.            msgflg:longint): Boolean;
  6970.  
  6971. Description: msgrcv retrieves a message of type msgtyp from the message queue with ID msqid.
  6972.            msgtyp corresponds to the mtype field of the TMSGbuf record. The message is stored
  6973.            in the MSGbuf structure pointed to by msgp.
  6974.            The msgflg parameter can be used to control the behaviour of the msgrcv call. It
  6975.            consists of an ORed combination of the following flags:
  6976.  
  6977.            0No special meaning.
  6978.            IPC NOWAITif no messages are available, then the call returns immediatly, with
  6979.                 the ENOMSG error.
  6980.            MSG NOERRORIf the message size is wrong (too large), no error is generated,
  6981.                 instead the message is truncated. Normally, in such cases, the call returns an
  6982.                 error (E2BIG)
  6983.  
  6984.            The function returns True if the message was received correctly, False otherwise.
  6985.  
  6986.     Errors: In case of error, False is returned, and IPCerror is set.
  6987.  
  6988.   See also: msgget (119), msgsnd (119), msgctl (120)
  6989.  
  6990.            For an example, see msgctl (120).
  6991.  
  6992.  
  6993.            msgctl
  6994. Declaration: Function msgctl(msqid:longint; cmd: longint; buf: PMSQid ds): Boolean;
  6995.  
  6996. Description: msgctl performs various operations on the message queue with id ID. Which op-
  6997.            eration is performed, depends on the cmd parameter, which can have one of the
  6998.            following values:
  6999.  
  7000.            IPC STATIn this case, the msgctl call fills the TMSQid ds structure with infor-
  7001.                 mation about the message queue.
  7002.            IPC SETin this case, the msgctl call sets the permissions of the queue as specified
  7003.                 in the ipc perm record inside buf.
  7004.            IPC RMIDIf this is specified, the message queue will be removed from the system.
  7005.  
  7006.            buf contains the data that are needed by the call. It can be Nil in case the message
  7007.            queue should be removed.
  7008.            The function returns True if successfull, False otherwise.
  7009.  
  7010.     Errors: On error, False is returned, and IPCerror is set accordingly.
  7011.  
  7012.   See also: msgget (119), msgsnd (119), msgrcv (120)
  7013.  
  7014.  
  7015.  
  7016.                                                       120
  7017.  
  7018.  
  7019.  
  7020.                                               7.2. FUNCTIONS AND PROCEDURES
  7021.  
  7022.  
  7023. program msgtool ;
  7024.  
  7025. Uses ipc ;
  7026.  
  7027. Type
  7028.   PMyMsgBuf =   TMyMsgBuf ;
  7029.   TMyMsgBuf = record
  7030.          mtype : Longint ;
  7031.          mtext : str ing [ 2 5 5 ] ;
  7032.   end ;
  7033.  
  7034. Procedure DoError ( Const Msg : string ) ;
  7035.  
  7036. begin
  7037.   Writeln ( msg , ' r e t u r n e d an e r r o r : ' , i p c e r r o r ) ;
  7038.   halt ( 1 ) ;
  7039. end ;
  7040.  
  7041. Procedure SendMessage ( Id : Longint ;
  7042.                                      Var Buf : TMyMsgBuf ;
  7043.                                      MType : Longint ;
  7044.                                      Const MText : String ) ;
  7045.  
  7046. begin
  7047.   Writeln ( ' Sending message . ' ) ;
  7048.   Buf . mtype := mtype ;
  7049.   Buf . Mtext := mtext ;
  7050.    I f not msgsnd ( Id , PMsgBuf ( @Buf ) , 2 5 6 , 0 ) then
  7051.          DoError ( ' msgsnd ' ) ;
  7052. end ;
  7053.  
  7054. Procedure ReadMessage ( ID : Longint ;
  7055.                                      Var Buf : TMyMsgBuf ;
  7056.                                      MType : l o n g i n t ) ;
  7057.  
  7058. begin
  7059.   Writeln ( ' Reading message . ' ) ;
  7060.   Buf . MType:=MType;
  7061.    I f msgrcv ( ID , PMSGBuf( @Buf ) , 2 5 6 , mtype , 0 ) then
  7062.          Writeln ( ' Type : ' , buf . mtype , ' Text : ' , buf . mtext )
  7063.   else
  7064.          DoError ( ' msgrcv ' ) ;
  7065. end ;
  7066.  
  7067. Procedure RemoveQueue ( ID : Longint ) ;
  7068.  
  7069. begin
  7070.    I f msgctl ( id , IPC RMID, Nil ) then
  7071.          Writeln ( ' Removed Queue with id ' , Id ) ;
  7072. end ;
  7073.  
  7074. Procedure ChangeQueueMode ( ID , mode : l o n g i n t ) ;
  7075.  
  7076. Var QueueDS : TMSQid ds ;
  7077.  
  7078.                                              121
  7079.  
  7080.  
  7081.  
  7082.                                                7.2. FUNCTIONS AND PROCEDURES
  7083.  
  7084.  
  7085.  
  7086. begin
  7087.    I f Not msgctl ( Id , IPC STAT, @QueueDS ) then
  7088.          DoError ( ' msgctl : s t a t ' ) ;
  7089.    Writeln ( ' Old p e r m i s s i o n s : ' , QueueDS . msg perm . mode ) ;
  7090.   QueueDS . msg perm . mode:=Mode;
  7091.    i f msgctl ( ID , IPC SET, @QueueDS ) then
  7092.          Writeln ( ' New p e r m i s s i o n s : ' , QueueDS . msg perm . mode)
  7093.    else
  7094.     DoError ( ' msgctl : IPC SET' ) ;
  7095. end ;
  7096.  
  7097. procedure usage ;
  7098.  
  7099. begin
  7100.    Writeln ( ' Usage : msgtool s ( end )                      < type > <text > (max 255 c h a r a c t e r s ) ' ) ;
  7101.    Writeln ( '                               r ( e c e i v e ) < type >' ) ;
  7102.    Writeln ( '                               d( e l e t e ) ' ) ;
  7103.    Writeln ( '                              m( ode ) < decimal mode>' ) ;
  7104.    halt ( 1 ) ;
  7105. end ;
  7106.  
  7107. Function StrToInt ( S : String ) : l o n g i n t ;
  7108.  
  7109. Var M : l o n g i n t ;
  7110.          C : I n t e g e r ;
  7111.  
  7112. begin
  7113.    val ( S ,M, C) ;
  7114.    I f C<>0 Then DoError ( ' StrToInt : ' +S ) ;
  7115.    StrToInt :=M;
  7116. end ;
  7117.  
  7118. VarKey : TKey;
  7119.   ID        : l o n g i n t ;
  7120.    Buf : TMyMsgBuf ;
  7121.  
  7122. begin
  7123.    I f Paramcount<1 then Usage ;
  7124.    key := Ftok ( ' . ' , 'M' ) ;
  7125.   ID := msgget ( key , IPC CREAT or 4 3 8 ) ;
  7126.    I f ID <0 then DoError ( ' MsgGet ' ) ;
  7127.   Case upCase ( Paramstr ( 1 ) [ 1 ] ) of
  7128.     ' S ' : I f ParamCount<>3 then
  7129.                     Usage
  7130.                  else
  7131.                     SendMessage ( id , Buf , StrToInt ( Paramstr ( 2 ) ) , paramstr ( 3 ) ) ;
  7132.     ' R' : I f ParamCount<>2 then
  7133.                     Usage
  7134.                  else
  7135.                     ReadMessage ( id , buf , s t r t o i n t ( Paramstr ( 2 ) ) ) ;
  7136.     ' D' : I f ParamCount<>1 then
  7137.                     Usage
  7138.  
  7139.                                               122
  7140.  
  7141.  
  7142.  
  7143.                                                          7.2. FUNCTIONS AND PROCEDURES
  7144.  
  7145.  
  7146.                            else
  7147.                                RemoveQueue ( ID ) ;
  7148.                'M' : I f ParamCount<>2 then
  7149.                                Usage
  7150.                            else
  7151.                                ChangeQueueMode ( id , s t r t o i n t ( paramstr ( 2 ) ) ) ;
  7152.                else
  7153.                       Usage
  7154.                end ;
  7155.            end .
  7156.  
  7157.  
  7158.            semget
  7159. Declaration: Function semget(key:Tkey; nsems:longint; semflg:longint): longint;
  7160.  
  7161. Description: msgget returns the ID of the semaphore set described by key. Depending on the
  7162.            flags in semflg, a new queue is created.
  7163.            semflg can have one or more of the following values (combined by ORs):
  7164.  
  7165.            IPC CREATThe queue is created if it doesn't already exist.
  7166.            IPC EXCLIf used in combination with IPC CREAT, causes the call to fail if the
  7167.                     set already exists. It cannot be used by itself.
  7168.  
  7169.            Optionally, the flags can be ORed with a permission mode, which is the same mode
  7170.            that can be used in the file system.
  7171.            if a new set of semaphores is created, then there will be nsems semaphores in it.
  7172.  
  7173.     Errors: On error, -1 is returned, and IPCError is set.
  7174.  
  7175.   See also: ftok (119), semop (123), semctl (124)
  7176.  
  7177.  
  7178.            semop
  7179. Declaration: Function semop(semid:longint; sops: pointer; nsops: cardinal): Boolean;
  7180.  
  7181. Description: semop performs a set of operations on a message queue. sops points to an array
  7182.            of type TSEMbuf. The array should contain nsops elements.
  7183.            The fields of the TSEMbuf structure
  7184.  
  7185.              TSEMbuf = record
  7186.                 sem_num : word;
  7187.                 sem_op : integer;
  7188.                 sem_flg : integer;
  7189.  
  7190.            should be filled as follows:
  7191.  
  7192.            sem numThe number of the semaphore in the set on which the operation must
  7193.                     be performed.
  7194.            sem opThe operation to be performed. The operation depends on the sign of
  7195.                     sem op
  7196.                       1.A positive number is simply added to the current value of the semaphore.
  7197.                       2.If 0 (zero) is specified, then the process is suspended until the specified
  7198.                         semaphore reaches zero.
  7199.  
  7200.                                                         123
  7201.  
  7202.  
  7203.  
  7204.                                                        7.2. FUNCTIONS AND PROCEDURES
  7205.  
  7206.  
  7207.                     3.If a negative number is specified, it is substracted from the current value
  7208.                         of the semaphore. If the value would become negative then the process
  7209.                         is suspended until the value becomes big enough, unless IPC NOWAIT is
  7210.                         specified in the sem flg.
  7211.           sem flgOptional flags: if IPC NOWAIT is specified, then the calling process will
  7212.                   never be suspended.
  7213.  
  7214.           The function returns True if the operations were successful, False otherwise.
  7215.  
  7216.     Errors: In case of error, False is returned, and IPCerror is set.
  7217.  
  7218.   See also: semget (123), semctl (124)
  7219.  
  7220.  
  7221.           semctl
  7222. Declaration: Function semctl(semid:longint; semnum:longint; cmd:longint; var arg: tsemun):
  7223.           longint;
  7224.  
  7225. Description: semctl performs various operations on the semaphore semnum w ith semaphore
  7226.           set id ID.
  7227.           The arg parameter supplies the data needed for each call. This is a variant record
  7228.           that should be filled di erently, according to the command:
  7229.  
  7230.           Type
  7231.             TSEMun = record
  7232.               case longint of
  7233.                     0 : ( val : longint );
  7234.                     1 : ( buf : PSEMid_ds );
  7235.                     2 : ( arr : PWord );
  7236.                     3 : ( padbuf : PSeminfo );
  7237.                     4 : ( padpad : pointer );
  7238.               end;
  7239.  
  7240.           Which operation is performed, depends on the cmd parameter, which can have one
  7241.           of the following values:
  7242.  
  7243.           IPC STATIn this case, the arg record should have it's buf field set to the address
  7244.                   of a TSEMid ds record. The semctl call fills this TSEMid ds structure with
  7245.                   information about the semaphore set.
  7246.           IPC SETIn this case, the arg record should have it's buf field set to the address
  7247.                   of a TSEMid ds record. The semctl call sets the permissions of the queue as
  7248.                   specified in the ipc perm record.
  7249.           IPC RMIDIf this is specified, the semaphore set is removed from from the system.
  7250.           GETALLIn this case, the arr field of arg should point to a memory area where
  7251.                   the values of the semaphores will be stored. The size of this memory area is
  7252.                   SizeOf(Word)* Number of semaphores in the set. This call will then fill
  7253.                   the memory array with all the values of the semaphores.
  7254.           GETNCNTThis will fill the val field of the arg union with the bumber of processes
  7255.                   waiting for resources.
  7256.           GETPIDsemctl returns the process ID of the process that performed the last
  7257.                   semop (123) call.
  7258.           GETVALsemctl returns the value of the semaphore with number semnum.
  7259.  
  7260.  
  7261.                                                        124
  7262.  
  7263.  
  7264.  
  7265.                                                     7.2. FUNCTIONS AND PROCEDURES
  7266.  
  7267.  
  7268.         GETZCNTsemctl returns the number of processes waiting for semaphores that
  7269.                  reach value zero.
  7270.         SETALLIn this case, the arr field of arg should point to a memory area where the
  7271.                  values of the semaphores will be retrieved from. The size of this memory area
  7272.                  is SizeOf(Word)* Number of semaphores in the set. This call will then
  7273.                  set the values of the semaphores from the memory array.
  7274.         SETVALThis will set the value of semaphore semnum to the value in the val field
  7275.                  of the arg parameter.
  7276.  
  7277.         The function returns -1 on error.
  7278.  
  7279.   Errors: The function returns -1 on error, and IPCerror is set accordingly.
  7280.  
  7281. See also: semget (123), semop (123)
  7282.  
  7283.         Program semtool ;
  7284.  
  7285.         { Program to demonstrat the use of semaphores }
  7286.  
  7287.         Uses ipc ;
  7288.  
  7289.         Const MaxSemValue = 5;
  7290.  
  7291.         Procedure DoError ( Const Msg : String ) ;
  7292.  
  7293.         begin
  7294.            Writeln ( ' Error : ' , msg , ' Code : ' , IPCerror ) ;
  7295.            Halt ( 1 ) ;
  7296.         end ;
  7297.  
  7298.         Function getsemval ( ID , Member : l o n g i n t ) : l o n g i n t ;
  7299.  
  7300.         Var S : TSEMun;
  7301.  
  7302.         begin
  7303.            GetSemVal := SemCtl ( id , member , GETVAL, S ) ;
  7304.         end ;
  7305.  
  7306.         Procedure DispVal ( ID , member : l o n g i n t ) ;
  7307.  
  7308.         begin
  7309.            writeln ( ' Value fo r member ' , member , ' i s ' , GetSemVal ( ID , Member ) ) ;
  7310.         end ;
  7311.  
  7312.         Function GetMemberCount ( ID : Longint ) : l o n g i n t ;
  7313.  
  7314.         Var opts : TSEMun;
  7315.                  semds : TSEMid ds ;
  7316.  
  7317.         begin
  7318.            opts . buf :=@semds ;
  7319.            I f semctl ( Id , 0 , IPC STAT, opts )<>-1 then
  7320.                  GetMemberCount := semds . sem nsems
  7321.            else
  7322.  
  7323.  
  7324.                                                    125
  7325.  
  7326.  
  7327.  
  7328.                                               7.2. FUNCTIONS AND PROCEDURES
  7329.  
  7330.  
  7331.          GetMemberCount :=-1;
  7332. end ;
  7333.  
  7334. Function OpenSem ( Key : TKey ) : Longint ;
  7335.  
  7336. begin
  7337.   OpenSem:= semget ( Key , 0 , 4 3 8 ) ;
  7338.    I f OpenSem=-1 then
  7339.          DoError ( ' OpenSem ' ) ;
  7340. end ;
  7341.  
  7342. Function CreateSem ( Key : TKey ; Members : Longint ) : Longint ;
  7343.  
  7344. Var Count : Longint ;
  7345.          Semopts : TSemun ;
  7346.  
  7347. begin
  7348.    I f members>semmsl then
  7349.          DoError ( ' Sorry , maximum number of semaphores in set exceeded ' ) ;
  7350.   Writeln ( ' Trying to c r e a t e a new semaphore set with ' , members , ' members . ' ) ;
  7351.   CreateSem := semget ( key , members , IPC CREAT or IPC Excl or 4 3 8 ) ;
  7352.    I f CreateSem =-1 then
  7353.          DoError ( ' Semaphore set a l r e a d y e x i s t s . ' ) ;
  7354.   Semopts . val :=MaxSemValue ; { I n i t i a l value of semaphores }
  7355.   For Count :=0 to Members-1 do
  7356.          semctl ( CreateSem , count , s e t v a l , semopts ) ;
  7357. end ;
  7358.  
  7359. Procedure lockSem ( ID , Member : Longint ) ;
  7360.  
  7361. Var lock : TSEMbuf ;
  7362.  
  7363. begin
  7364.   With lock do
  7365.          begin
  7366.          sem num:=0;
  7367.          sem op:=-1;
  7368.          sem flg :=IPC NOWAIT;
  7369.          end ;
  7370.     i f ( member <0) or ( member>GetMemberCount ( ID )-1) then
  7371.           DoError ( ' semaphore member out of range ' ) ;
  7372.     i f getsemval ( ID , member )=0 then
  7373.           DoError ( ' Semaphore r e s o u r c e s exhausted ( no lock ) ' ) ;
  7374.     lock . sem num:=member ;
  7375.     Writeln ( ' Attempting to lock member ' , member , ' of semaphore ' , ID ) ;
  7376.     i f not semop ( Id , @lock , 1 ) then
  7377.           DoError ( ' Lock f a i l e d ' )
  7378.     else
  7379.           Writeln ( ' Semaphore r e s o u r c e s decremented by one ' ) ;
  7380.     d i s p v a l ( ID , Member ) ;
  7381. end ;
  7382.  
  7383. Procedure UnlockSem ( ID , Member : Longint ) ;
  7384.  
  7385.  
  7386.                                               126
  7387.  
  7388.  
  7389.  
  7390.                                                7.2. FUNCTIONS AND PROCEDURES
  7391.  
  7392.  
  7393. Var Unlock : TSEMbuf ;
  7394.  
  7395. begin
  7396.   With Unlock do
  7397.          begin
  7398.          sem num:=0;
  7399.          sem op :=1;
  7400.          sem flg :=IPC NOWAIT;
  7401.          end ;
  7402.     i f ( member <0) or ( member>GetMemberCount ( ID )-1) then
  7403.           DoError ( ' semaphore member out of range ' ) ;
  7404.     i f getsemval ( ID , member)=MaxSemValue then
  7405.           DoError ( ' Semaphore not locked ' ) ;
  7406.     Unlock . sem num:=member ;
  7407.     Writeln ( ' Attempting to unlock member ' , member , ' of semaphore ' , ID ) ;
  7408.     i f not semop ( Id , @unlock , 1 ) then
  7409.           DoError ( ' Unlock f a i l e d ' )
  7410.     else
  7411.           Writeln ( ' Semaphore r e s o u r c e s incremented by one ' ) ;
  7412.     d i s p v a l ( ID , Member ) ;
  7413. end ;
  7414.  
  7415. Procedure RemoveSem ( ID : l o n g i n t ) ;
  7416.  
  7417. var S : TSemun ;
  7418.  
  7419. begin
  7420.    I f semctl ( Id , 0 , IPC RMID, s )<>-1 then
  7421.          Writeln ( ' Semaphore removed ' )
  7422.    else
  7423.          DoError ( ' Couldn ' ' t remove semaphore ' ) ;
  7424. end ;
  7425.  
  7426.  
  7427. Procedure ChangeMode ( ID , Mode : l o n g i n t ) ;
  7428.  
  7429. Var rc : l o n g i n t ;
  7430.          opts : TSEMun;
  7431.          semds : TSEMid ds ;
  7432.  
  7433. begin
  7434.    opts . buf :=@semds ;
  7435.    I f not semctl ( Id , 0 , IPC STAT, opts )<>-1 then
  7436.          DoError ( ' Couldn ' ' t s t a t semaphore ' ) ;
  7437.    Writeln ( ' Old p e r m i s s i o n s were : ' , semds . sem perm . mode ) ;
  7438.   semds . sem perm . mode:=mode ;
  7439.    I f semctl ( id , 0 , IPC SET, opts )<>-1 then
  7440.          Writeln ( ' Set p e r m i s s i o n s to ' , mode)
  7441.    else
  7442.          DoError ( ' Couldn ' ' t set p e r m i s s i o n s ' ) ;
  7443. end ;
  7444.  
  7445. Procedure PrintSem ( ID : l o n g i n t ) ;
  7446.  
  7447.  
  7448.                                              127
  7449.  
  7450.  
  7451.  
  7452.                                                 7.2. FUNCTIONS AND PROCEDURES
  7453.  
  7454.  
  7455. Var I , cnt : l o n g i n t ;
  7456.  
  7457. begin
  7458.    cnt := getmembercount ( ID ) ;
  7459.    Writeln ( ' Semaphore ' , ID , ' has ' , cnt , ' Members ' ) ;
  7460.    For I :=0 to cnt -1 Do
  7461.          DispVal ( id , i ) ;
  7462. end ;
  7463.  
  7464. Procedure USage ;
  7465.  
  7466. begin
  7467.    Writeln ( ' Usage : semtool c ( r e a t e ) < count >' ) ;
  7468.    Writeln ( '                                l ( ock ) <member>' ) ;
  7469.    Writeln ( '                                u( nlock ) <member>' ) ;
  7470.    Writeln ( '                                d( e l e t e ) ' ) ;
  7471.    Writeln ( '                               m( ode ) <mode>' ) ;
  7472.    halt ( 1 ) ;
  7473. end ;
  7474.  
  7475. Function StrToInt ( S : String ) : l o n g i n t ;
  7476.  
  7477. Var M : l o n g i n t ;
  7478.          C : I n t e g e r ;
  7479.  
  7480. begin
  7481.    val ( S ,M, C) ;
  7482.    I f C<>0 Then DoError ( ' StrToInt : ' +S ) ;
  7483.    StrToInt :=M;
  7484. end ;
  7485.  
  7486. Var Key : TKey ;
  7487.          ID : Longint ;
  7488.  
  7489. begin
  7490.    I f ParamCount<1 then USage ;
  7491.    key := ftok ( ' . ' , ' s ' ) ;
  7492.   Case UpCase( Paramstr ( 1 ) [ 1 ] ) of
  7493.     ' C' : begin
  7494.                  i f paramcount<>2 then usage ;
  7495.                  CreateSem ( key , s t r t o i n t ( paramstr ( 2 ) ) ) ;
  7496.                  end ;
  7497.     ' L ' : begin
  7498.                  i f paramcount<>2 then usage ;
  7499.                  ID :=OpenSem ( key ) ;
  7500.                  LockSem ( ID , s t r t o i n t ( paramstr ( 2 ) ) ) ;
  7501.                  end ;
  7502.     ' U' : begin
  7503.                  i f paramcount<>2 then usage ;
  7504.                  ID :=OpenSem ( key ) ;
  7505.                  UnLockSem ( ID , s t r t o i n t ( paramstr ( 2 ) ) ) ;
  7506.                  end ;
  7507.     'M' : begin
  7508.                  i f paramcount<>2 then usage ;
  7509.  
  7510.                                                128
  7511.  
  7512.  
  7513.  
  7514.                                                                 7.2. FUNCTIONS AND PROCEDURES
  7515.  
  7516.  
  7517.                                   ID :=OpenSem ( key ) ;
  7518.                                   ChangeMode ( ID , s t r t o i n t ( paramstr ( 2 ) ) ) ;
  7519.                                   end ;
  7520.                     ' D' : Begin
  7521.                                   ID :=OpenSem( Key ) ;
  7522.                                   RemoveSem( Id ) ;
  7523.                                   end ;
  7524.                     ' P' : begin
  7525.                                   ID :=OpenSem( Key ) ;
  7526.                                   PrintSem ( Id ) ;
  7527.                                   end ;
  7528.                   else
  7529.                          Usage
  7530.                   end ;
  7531.                 end .
  7532.  
  7533.  
  7534.            shmget
  7535. Declaration: Function shmget(key: Tkey; Size:longint; flag:longint):longint;
  7536.  
  7537. Description: shmget returns the ID of a shared memory block, described by key. Depending
  7538.            on the flags in flag, a new memory block is created.
  7539.            flag can have one or more of the following values (combined by ORs):
  7540.  
  7541.            IPC CREATThe queue is created if it doesn't already exist.
  7542.            IPC EXCLIf used in combination with IPC CREAT, causes the call to fail if the
  7543.                          queue already exists. It cannot be used by itself.
  7544.  
  7545.            Optionally, the flags can be ORed with a permission mode, which is the same mode
  7546.            that can be used in the file system.
  7547.            if a new memory block is created, then it will have size Size semaphores in it.
  7548.  
  7549.      Errors: On error, -1 is returned, and IPCError is set.
  7550.  
  7551.    See also:
  7552.  
  7553.  
  7554.            shmat
  7555. Declaration: Function shmat (shmid:longint; shmaddr:pchar; shmflg:longint):pchar;
  7556.  
  7557. Description: shmat attaches a shared memory block with identified shmid to the current process.
  7558.            The function returns a pointer to the shared memory block.
  7559.            If shmaddr is Nil, then the system chooses a free unmapped memory region, as
  7560.            high up in memory space as possible.
  7561.            If shmaddr is non-nil, and SHM RND is in shmflg, then the returned address is
  7562.            shmaddr, rounded down to SHMLBA. If SHM RND is not specified, then shmaddr must
  7563.            be a page-aligned address.
  7564.            The parameter shmflg can be used to control the behaviour of the shmat call. It
  7565.            consists of a ORed combination of the following costants:
  7566.  
  7567.            SHM RNDThe suggested address in shmaddr is rounded down to SHMLBA.
  7568.  
  7569.  
  7570.  
  7571.                                                                129
  7572.  
  7573.  
  7574.  
  7575.                                                        7.2. FUNCTIONS AND PROCEDURES
  7576.  
  7577.  
  7578.           SHM RDONLYthe shared memory is attached for read access only. Otherwise
  7579.                 the memory is attached for read-write. The process then needs read-write
  7580.                 permissions to access the shared memory.
  7581.  
  7582.     Errors: If an error occurs, -1 is returned, and IPCerror is set.
  7583.  
  7584.   See also: shmget (129), shmdt (130), shmctl (130)
  7585.  
  7586.           For an example, see shmctl (130).
  7587.  
  7588.  
  7589.           shmdt
  7590. Declaration: Function shmdt (shmaddr:pchar):boolean;
  7591.  
  7592. Description: shmdt detaches the shared memory at address shmaddr. This shared memory block
  7593.           is unavailable to the current process, until it is attached again by a call to shmat
  7594.           (129).
  7595.           The function returns True if the memory block was detached successfully, False
  7596.           otherwise.
  7597.  
  7598.     Errors: On error, False is returned, and IPCerror is set.
  7599.  
  7600.   See also: shmget (129), shmat (129), shmctl (130)
  7601.  
  7602.  
  7603.           shmctl
  7604. Declaration: Function shmctl(shmid:longint; cmd:longint; buf: pshmid ds): Boolean;
  7605.  
  7606. Description: shmctl performs various operations on the shared memory block identified by
  7607.           identifier shmid.
  7608.           The buf parameter points to a TSHMid ds record. The cmd parameter is used to
  7609.           pass which operation is to be performed. It can have one of the following values :
  7610.  
  7611.           IPC STATshmctl fills the TSHMid ds record that buf points to with the available
  7612.                 information about the shared memory block.
  7613.           IPC SETapplies the values in the ipc perm record that buf points to, to the
  7614.                 shared memory block.
  7615.           IPC RMIDthe shared memory block is destroyed (after all processes to which
  7616.                 the block is attached, have detached from it).
  7617.  
  7618.           If successful, the function returns True, False otherwise.
  7619.  
  7620.     Errors: If an error occurs, the function returns False, and IPCerror is set.
  7621.  
  7622.   See also: shmget (129), shmat (129), shmdt (130)
  7623.  
  7624.           Program shmtool ;
  7625.  
  7626.            uses ipc , s t r i n g s ;
  7627.  
  7628.            Const SegSize = 100;
  7629.  
  7630.            var key : Tkey ;
  7631.                  shmid , cntr : l o n g i n t ;
  7632.                  s e g p t r : pchar ;
  7633.  
  7634.                                                    130
  7635.  
  7636.  
  7637.  
  7638.                                             7.2. FUNCTIONS AND PROCEDURES
  7639.  
  7640.  
  7641.  
  7642. Procedure USage ;
  7643.  
  7644. begin
  7645.  Writeln ( ' Usage : shmtool w( r i t e ) text ' ) ;
  7646.  writeln ( '                            r ( ead ) ' ) ;
  7647.  writeln ( '                            d( e l e t e ) ' ) ;
  7648.  writeln ( '                            m( ode change ) mode ' ) ;
  7649.  halt ( 1 ) ;
  7650. end ;
  7651.  
  7652. Procedure Writeshm ( ID : Longint ; ptr : pchar ; S : st ring ) ;
  7653.  
  7654. begin
  7655.   strpcopy ( ptr , s ) ;
  7656. end ;
  7657.  
  7658. Procedure Readshm ( ID : l o n g i n t ; ptr : pchar ) ;
  7659.  
  7660. begin
  7661.   Writeln ( ' Read : ' , ptr ) ;
  7662. end ;
  7663.  
  7664. Procedure removeshm ( ID : Longint ) ;
  7665.  
  7666. begin
  7667.   shmctl ( ID , IPC RMID, Nil ) ;
  7668.   writeln ( ' Shared memory marked f o r d e l e t i o n ' ) ;
  7669. end ;
  7670.  
  7671. Procedure CHangeMode ( ID : l o n g i n t ; mode : String ) ;
  7672.  
  7673. Var m : word ;
  7674.          code : i n t e g e r ;
  7675.          data : TSHMid ds ;
  7676.  
  7677. begin
  7678.   val ( mode , m, code ) ;
  7679.    i f code <>0 then
  7680.          usage ;
  7681.    I f Not shmctl ( shmid , IPC STAT, @data ) then
  7682.          begin
  7683.          writeln ( ' Error : shmctl : ' , i p c e r r o r ) ;
  7684.          halt ( 1 ) ;
  7685.          end ;
  7686.   writeln ( ' Old p e r m i s s i o n s : ' , data . shm perm . mode ) ;
  7687.   data . shm perm . mode:=m;
  7688.    I f Not shmctl ( shmid , IPC SET, @data ) then
  7689.          begin
  7690.          writeln ( ' Error : shmctl : ' , i p c e r r o r ) ;
  7691.          halt ( 1 ) ;
  7692.          end ;
  7693.   writeln ( ' New p e r m i s s i o n s : ' , data . shm perm . mode ) ;
  7694. end ;
  7695.  
  7696.                                            131
  7697.  
  7698.  
  7699.  
  7700.                                                    7.2. FUNCTIONS AND PROCEDURES
  7701.  
  7702.  
  7703.  
  7704. begin
  7705.    i f paramcount <1 then usage ;
  7706.   key := ftok ( ' . ' , ' S ' ) ;
  7707.   shmid := shmget ( key , s e g s i z e , IPC CREAT or IPC EXCL or 4 3 8 ) ;
  7708.    I f shmid =-1 then
  7709.          begin
  7710.          Writeln ( ' Shared memory e x i s t s . Opening as c l i e n t ' ) ;
  7711.          shmid := shmget ( key , s e g s i z e , 0 ) ;
  7712.          I f shmid = -1 then
  7713.             begin
  7714.             Writeln ( ' shmget : Error ! ' , i p c e r r o r ) ;
  7715.             halt ( 1 ) ;
  7716.             end
  7717.          end
  7718.   else
  7719.          Writeln ( ' Creating new shared memory segment . ' ) ;
  7720.    s e g p t r := shmat ( shmid , n i l , 0 ) ;
  7721.    i f l o n g i n t ( s e g p t r )=-1 then
  7722.          begin
  7723.          Writeln ( ' Shmat : e r r o r ! ' , i p c e r r o r ) ;
  7724.          halt ( 1 ) ;
  7725.          end ;
  7726.   case upcase ( paramstr ( 1 ) [ 1 ] ) of
  7727.          'W' : writeshm ( shmid , s e g p t r , paramstr ( 2 ) ) ;
  7728.          ' R' : readshm ( shmid , s e g p t r ) ;
  7729.          ' D' : removeshm ( shmid ) ;
  7730.          'M' : changemode ( shmid , paramstr ( 2 ) ) ;
  7731.   else
  7732.          begin
  7733.          writeln ( paramstr ( 1 ) ) ;
  7734.          usage ;
  7735.          end ;
  7736.   end ;
  7737. end .
  7738.  
  7739.  
  7740.  
  7741.  
  7742.  
  7743.  
  7744.  
  7745.  
  7746.  
  7747.  
  7748.  
  7749.  
  7750.  
  7751.  
  7752.  
  7753.  
  7754.  
  7755.  
  7756.  
  7757.                                                    132
  7758.  
  7759.  
  7760.  
  7761. Chapter 8
  7762.  
  7763. The LINUX unit.
  7764.  
  7765. This chapter describes the LINUX unit for Free Pascal. The unit was written by
  7766. Micha¿el van Canneyt. It works only on the Linux operating system. This chapter
  7767. is divided in 2 sections:
  7768.  
  7769.    * The first section lists all constants, types and variables, as listed in the inter-
  7770.         face section of the LINUX unit.
  7771.  
  7772.    * The second section describes all procedures and functions in the LINUX unit.
  7773.  
  7774.  
  7775. 8.1 Type, Variable and Constant declarations
  7776.  
  7777. Types
  7778. PGlob and TGlob are 2 types used in the Glob (167) function:
  7779.  
  7780. PGlob = ^TGlob;
  7781. TGlob = record
  7782.   Name : PChar;
  7783.   Next : PGlob;
  7784.   end;
  7785.  
  7786. The following types are used in the signal-processing procedures.
  7787.  
  7788. {$Packrecords 1}
  7789. SignalHandler        = Procedure ( Sig : Integer);cdecl;
  7790. PSignalHandler = SignalHandler;
  7791. SignalRestorer = Procedure;cdecl;
  7792. PSignalrestorer = SignalRestorer;
  7793. SigActionRec = Record
  7794.   Sa_Handler : Signalhandler;
  7795.   Sa_Mask         : Longint;
  7796.   Sa_flags        : Integer;
  7797.   Sa_Restorer : SignalRestorer;
  7798. end;
  7799. PSigActionRec = ^SigActionRec;
  7800.  
  7801. Stat is used to store information about a file. It is defined in the syscalls unit.
  7802.  
  7803.  
  7804.                                            133
  7805.  
  7806.  
  7807.  
  7808.                         8.1. TYPE, VARIABLE AND CONSTANT DECLARATIONS
  7809.  
  7810.  
  7811.   stat = record
  7812.           dev        : word;
  7813.           pad1       : word;
  7814.           ino        : longint;
  7815.           mode       : word;
  7816.           nlink : word;
  7817.           uid        : word;
  7818.           gid        : word;
  7819.           rdev       : word;
  7820.           pad2       : word;
  7821.           size       : longint;
  7822.           blksze : Longint;
  7823.           blocks : Longint;
  7824.           atime : Longint;
  7825.           unused1 : longint;
  7826.           mtime       : Longint;
  7827.           unused2 : longint;
  7828.           ctime       : Longint;
  7829.           unused3 : longint;
  7830.           unused4 : longint;
  7831.           unused5 : longint;
  7832.           end;
  7833.  
  7834.  
  7835. Statfs is used to store information about a filesystem. It is defined in the syscalls
  7836. unit.
  7837.  
  7838.    statfs = record
  7839.           fstype       : longint;
  7840.           bsize        : longint;
  7841.           blocks       : longint;
  7842.           bfree        : longint;
  7843.           bavail       : longint;
  7844.           files        : longint;
  7845.           ffree        : longint;
  7846.           fsid         : longint;
  7847.           namelen : longint;
  7848.           spare        : array [0..6] of longint;
  7849.           end
  7850.  
  7851. Dir and PDir are used in the OpenDir (176) and ReadDir (178) functions.
  7852.  
  7853.   TDir =record
  7854.          fd         : integer;
  7855.          loc        : longint;
  7856.          size       : integer;
  7857.          buf        : pdirent;
  7858.          nextoff: longint;
  7859.          dd_max : integer;
  7860.          lock       : pointer;
  7861.   end;
  7862.   PDir =^TDir;
  7863.  
  7864. Dirent, PDirent are used in the ReadDir (178) function to return files in a direc-
  7865. tory.
  7866.  
  7867.                                          134
  7868.  
  7869.  
  7870.  
  7871.                         8.1. TYPE, VARIABLE AND CONSTANT DECLARATIONS
  7872.  
  7873.  
  7874.  PDirent = ^Dirent;
  7875.  Dirent = Record
  7876.    ino,
  7877.    off         : longint;
  7878.    reclen : word;
  7879.    name        : string[255]
  7880.  end;
  7881.  
  7882. Termio and Termios are used with iotcl() calls for terminal handling.
  7883.  
  7884. Const NCCS = 19;
  7885.             NCC = 8;
  7886.  
  7887. Type termio = record
  7888. c_iflag,{ input mode flags }
  7889. c_oflag,{ output mode flags }
  7890. c_cflag,{ control mode flags }
  7891. c_lflag : Word; { local mode flags }
  7892. c_line : Word; { line discipline - careful, only High byte in use}
  7893. c_cc : array [0..NCC-1] of char; { control characters }
  7894. end;
  7895. termios = record
  7896.   c_iflag,                      { input mode flags }
  7897.   c_oflag,                      { output mode flags }
  7898.   c_cflag,                      { control mode flags }
  7899.   c_lflag : Cardinal; { local mode flags }
  7900.   c_line : char;                 { line discipline }
  7901.   c_cc : array [0..NCCS-1] of char;               { control characters }
  7902. end;
  7903.  
  7904. Utimbuf is used in the Utime (189) call to set access and modificaton time of a file.
  7905.  
  7906. utimbuf = record
  7907.   actime,modtime : Longint;
  7908.   end;
  7909.  
  7910. For the Select (178) call, the following 4 types are needed:
  7911.  
  7912. FDSet = Array [0..31] of longint;
  7913. PFDSet = ^FDSet;
  7914. TimeVal = Record
  7915.    sec,usec : Longint;
  7916. end;
  7917. PTimeVal = ^TimeVal;
  7918.  
  7919. The Uname (188) function uses the utsname to return information about the current
  7920. kernel :
  7921.  
  7922. utsname =record
  7923.   sysname,nodename,release,
  7924.   version,machine,domainname : Array[0..64] of char;
  7925. end;
  7926.  
  7927. Its elements are null-terminated C style strings, you cannot access them directly !
  7928.  
  7929.                                         135
  7930.  
  7931.  
  7932.  
  7933.                     8.1. TYPE, VARIABLE AND CONSTANT DECLARATIONS
  7934.  
  7935.  
  7936. Variables
  7937. Linuxerror is the variable in which the procedures in the linux unit report errors.
  7938.  
  7939. LinuxError : Longint;
  7940.  
  7941. StdErr Is a Text variable, corresponding to Standard Error or diagnostic output.
  7942. It is connected to file descriptor 2. It can be freely used, and will be closed on exit.
  7943.  
  7944. StdErr : Text;
  7945.  
  7946.  
  7947. Constants
  7948. Constants for setting/getting process priorities :
  7949.  
  7950.        Prio_Process = 0;
  7951.        Prio_PGrp        = 1;
  7952.        Prio_User        = 2;
  7953.  
  7954. For testing access rights:
  7955.  
  7956.        R_OK = 4;
  7957.        W_OK = 2;
  7958.        X_OK = 1;
  7959.        F_OK = 0;
  7960.  
  7961. For signal handling functions :
  7962.  
  7963.        SA_NOCLDSTOP = 1;
  7964.        SA_SHIRQ        = $04000000;
  7965.        SA_STACK        = $08000000;
  7966.        SA_RESTART       = $10000000;
  7967.        SA_INTERRUPT = $20000000;
  7968.        SA_NOMASK        = $40000000;
  7969.        SA_ONESHOT       = $80000000;
  7970.  
  7971.        SIG_BLOCK       = 0;
  7972.        SIG_UNBLOCK = 1;
  7973.        SIG_SETMASK = 2;
  7974.        SIG_DFL = 0 ;
  7975.        SIG_IGN = 1 ;
  7976.        SIG_ERR = -1;
  7977.  
  7978.        SIGHUP = 1;
  7979.        SIGINT = 2;
  7980.        SIGQUIT = 3;
  7981.        SIGILL = 4;
  7982.        SIGTRAP = 5;
  7983.        SIGABRT = 6;
  7984.        SIGIOT = 6;
  7985.        SIGBUS = 7;
  7986.        SIGFPE = 8;
  7987.        SIGKILL = 9;
  7988.        SIGUSR1 = 10;
  7989.  
  7990.                                           136
  7991.  
  7992.  
  7993.  
  7994.                   8.1. TYPE, VARIABLE AND CONSTANT DECLARATIONS
  7995.  
  7996.  
  7997.        SIGSEGV = 11;
  7998.        SIGUSR2 = 12;
  7999.        SIGPIPE = 13;
  8000.        SIGALRM = 14;
  8001.        SIGTERM = 15;
  8002.        SIGSTKFLT = 16;
  8003.        SIGCHLD = 17;
  8004.        SIGCONT = 18;
  8005.        SIGSTOP = 19;
  8006.        SIGTSTP = 20;
  8007.        SIGTTIN = 21;
  8008.        SIGTTOU = 22;
  8009.        SIGURG = 23;
  8010.        SIGXCPU = 24;
  8011.        SIGXFSZ = 25;
  8012.        SIGVTALRM = 26;
  8013.        SIGPROF = 27;
  8014.        SIGWINCH = 28;
  8015.        SIGIO = 29;
  8016.        SIGPOLL = SIGIO;
  8017.        SIGPWR = 30;
  8018.        SIGUNUSED = 31;
  8019.  
  8020. For file control mechanism :
  8021.  
  8022.        F_GetFd = 1;
  8023.        F_SetFd = 2;
  8024.        F_GetFl = 3;
  8025.        F_SetFl = 4;
  8026.        F_GetLk = 5;
  8027.        F_SetLk = 6;
  8028.        F_SetLkW = 7;
  8029.        F_GetOwn = 8;
  8030.        F_SetOwn = 9;
  8031.  
  8032. For Terminal handling :
  8033.  
  8034.    TCGETS = $5401 ;
  8035.    TCSETS = $5402 ;
  8036.    TCSETSW = $5403 ;
  8037.    TCSETSF = $5404 ;
  8038.    TCGETA = $5405 ;
  8039.    TCSETA = $5406 ;
  8040.    TCSETAW = $5407 ;
  8041.    TCSETAF = $5408 ;
  8042.    TCSBRK = $5409 ;
  8043.    TCXONC = $540A ;
  8044.    TCFLSH = $540B ;
  8045.    TIOCEXCL = $540C ;
  8046.    TIOCNXCL = $540D ;
  8047.    TIOCSCTTY = $540E ;
  8048.    TIOCGPGRP = $540F ;
  8049.    TIOCSPGRP = $5410 ;
  8050.    TIOCOUTQ = $5411 ;
  8051.  
  8052.                                 137
  8053.  
  8054.  
  8055.  
  8056.                   8.1. TYPE, VARIABLE AND CONSTANT DECLARATIONS
  8057.  
  8058.  
  8059.    TIOCSTI = $5412 ;
  8060.    TIOCGWINSZ = $5413 ;
  8061.    TIOCSWINSZ = $5414 ;
  8062.    TIOCMGET = $5415 ;
  8063.    TIOCMBIS = $5416 ;
  8064.    TIOCMBIC = $5417 ;
  8065.    TIOCMSET = $5418 ;
  8066.    TIOCGSOFTCAR = $5419 ;
  8067.    TIOCSSOFTCAR = $541A ;
  8068.    FIONREAD = $541B ;
  8069.    TIOCINQ = FIONREAD;
  8070.    TIOCLINUX = $541C ;
  8071.    TIOCCONS = $541D ;
  8072.    TIOCGSERIAL = $541E ;
  8073.    TIOCSSERIAL = $541F ;
  8074.    TIOCPKT = $5420 ;
  8075.    FIONBIO = $5421 ;
  8076.    TIOCNOTTY = $5422 ;
  8077.    TIOCSETD = $5423 ;
  8078.    TIOCGETD = $5424 ;
  8079.    TCSBRKP = $5425 ;
  8080.    TIOCTTYGSTRUCT = $5426 ;
  8081.    FIONCLEX = $5450 ;
  8082.    FIOCLEX = $5451 ;
  8083.    FIOASYNC = $5452 ;
  8084.    TIOCSERCONFIG = $5453 ;
  8085.    TIOCSERGWILD = $5454 ;
  8086.    TIOCSERSWILD = $5455 ;
  8087.    TIOCGLCKTRMIOS = $5456 ;
  8088.    TIOCSLCKTRMIOS = $5457 ;
  8089.    TIOCSERGSTRUCT = $5458 ;
  8090.    TIOCSERGETLSR       = $5459 ;
  8091.    TIOCSERGETMULTI = $545A ;
  8092.    TIOCSERSETMULTI = $545B ;
  8093.    TIOCMIWAIT = $545C ;
  8094.    TIOCGICOUNT = $545D ;
  8095.    TIOCPKT_DATA = 0;
  8096.    TIOCPKT_FLUSHREAD = 1;
  8097.    TIOCPKT_FLUSHWRITE = 2;
  8098.    TIOCPKT_STOP = 4;
  8099.    TIOCPKT_START = 8;
  8100.    TIOCPKT_NOSTOP = 16;
  8101.    TIOCPKT_DOSTOP = 32;
  8102.  
  8103. Other than that, all constants for setting the speed and control flags of a terminal
  8104. line, as described in the termios (2) man page, are defined in the linux unit. It
  8105. would take too much place to list them here. To check the mode field of a stat
  8106. record, you ca use the following constants :
  8107.  
  8108.   { Constants to check stat.mode }
  8109.   STAT_IFMT      = $f000; {00170000}
  8110.   STAT_IFSOCK = $c000; {0140000}
  8111.   STAT_IFLNK = $a000; {0120000}
  8112.   STAT_IFREG = $8000; {0100000}
  8113.  
  8114.                                         138
  8115.  
  8116.  
  8117.  
  8118.                                                      8.2. FUNCTIONS AND PROCEDURES
  8119.  
  8120.  
  8121.               STAT_IFBLK = $6000; {0060000}
  8122.               STAT_IFDIR = $4000; {0040000}
  8123.               STAT_IFCHR = $2000; {0020000}
  8124.               STAT_IFIFO = $1000; {0010000}
  8125.               STAT_ISUID = $0800; {0004000}
  8126.               STAT_ISGID = $0400; {0002000}
  8127.               STAT_ISVTX = $0200; {0001000}
  8128.               { Constants to check permissions }
  8129.               STAT_IRWXO = $7;
  8130.               STAT_IROTH = $4;
  8131.               STAT_IWOTH = $2;
  8132.               STAT_IXOTH = $1;
  8133.               STAT_IRWXG = STAT_IRWXO shl 3;
  8134.               STAT_IRGRP = STAT_IROTH shl 3;
  8135.               STAT_IWGRP = STAT_IWOTH shl 3;
  8136.               STAT_IXGRP = STAT_IXOTH shl 3;
  8137.               STAT_IRWXU = STAT_IRWXO shl 6;
  8138.               STAT_IRUSR = STAT_IROTH shl 6;
  8139.               STAT_IWUSR = STAT_IWOTH shl 6;
  8140.               STAT_IXUSR = STAT_IXOTH shl 6;
  8141.  
  8142.            You can test the type of a filesystem returned by a FSStat (158) call with the
  8143.            following constants:
  8144.  
  8145.               fs_old_ext2 = $ef51;
  8146.               fs_ext2         = $ef53;
  8147.               fs_ext          = $137d;
  8148.               fs_iso          = $9660;
  8149.               fs_minix        = $137f;
  8150.               fs_minix_30 = $138f;
  8151.               fs_minux_V2 = $2468;
  8152.               fs_msdos        = $4d44;
  8153.               fs_nfs          = $6969;
  8154.               fs_proc         = $9fa0;
  8155.               fs_xia          = $012FD16D;
  8156.  
  8157.            the FLock (157) call uses the following mode constants :
  8158.  
  8159.               LOCK_SH = 1;
  8160.               LOCK_EX = 2;
  8161.               LOCK_UN = 8;
  8162.               LOCK_NB = 4;
  8163.  
  8164.  
  8165.            8.2 Functions and procedures
  8166.  
  8167.            Access
  8168. Declaration: Function Access (Path : Pathstr; Mode : integer) : Boolean;
  8169. Description: Tests user's access rights on the specified file. Mode is a mask existing of one or
  8170.            more of
  8171.            R OKUser has read rights.
  8172.            W OKUser has write rights.
  8173.  
  8174.                                                     139
  8175.  
  8176.  
  8177.  
  8178.                                                        8.2. FUNCTIONS AND PROCEDURES
  8179.  
  8180.  
  8181.            X OKUser has execute rights.
  8182.            F OKUser has search rights in the directory where the file is.
  8183.  
  8184.            The test is done with the real user ID, instead of the e ective user ID. If access is
  8185.            denied, or an error occurred, false is returned.
  8186.  
  8187.      Errors: LinuxError is used to report errors:
  8188.  
  8189.            sys eaccessThe requested access is denied, either to the file or one of the directo-
  8190.                     ries in its path.
  8191.            sys einvalMode was incorrect.
  8192.            sys enoentA directory component in Path doesn't exist or is a dangling symbolic
  8193.                     link.
  8194.            sys enotdirA directory component in Path is not a directory.
  8195.            sys enomemInsu cient kernel memory.
  8196.            sys eloopPath has a circular symbolic link.
  8197.  
  8198.    See also: Chown (143), Chmod (144), Access (2)
  8199.  
  8200.            Program Example26 ;
  8201.  
  8202.            { Program to demonstrate the Access f u n c t i o n . }
  8203.  
  8204.            Uses l i n u x ;
  8205.  
  8206.            begin
  8207.               i f Access ( '/ etc / passwd ' ,W OK) then
  8208.                     begin
  8209.                     Writeln ( ' Better check your system . ' ) ;
  8210.                     Writeln ( ' I can w r i t e to the / etc / passwd f i l e ! ' ) ;
  8211.                     end ;
  8212.            end .
  8213.  
  8214.  
  8215.            AssignPipe
  8216. Declaration: Procedure AssignPipe (Pipe in, Pipe out : Text);
  8217.  
  8218. Description: AssignePipe creates a pipe, i.e. two file objects, one for input, one for output.
  8219.            What is written to Pipe out, can be read from Pipe in. Reading and writing
  8220.            happens through the usual Readln(Pipe in,...) and Writeln (Pipe out,...)
  8221.            procedures.
  8222.  
  8223.      Errors: LinuxError is used to report errors:
  8224.  
  8225.            sys emfileToo many file descriptors for this process.
  8226.            sys enfileThe system file table is full.
  8227.  
  8228.    See also: POpen (177), MkFifo (175), pipe (2)
  8229.  
  8230.            Program Example36 ;
  8231.  
  8232.            { Program to demonstrate the AssignPipe f u n c t i o n . }
  8233.  
  8234.            Uses l i n u x ;
  8235.  
  8236.                                                        140
  8237.  
  8238.  
  8239.  
  8240.                                                            8.2. FUNCTIONS AND PROCEDURES
  8241.  
  8242.  
  8243.  
  8244.            Var p i p i , pipo : Text ;
  8245.                     s : String ;
  8246.  
  8247.             begin
  8248.               Writeln ( ' A s s i g n i n g Pipes . ' ) ;
  8249.                a s s i g n p i p e ( p i p i , pipo ) ;
  8250.                i f l i n u x e r r o r <>0 then
  8251.                     Writeln ( ' Error a s s i g n i n g pipes ! ' ) ;
  8252.               Writeln ( ' Writing to pipe , and f l u s h i n g . ' ) ;
  8253.               Writeln ( pipo , ' This i s a t e x t s t r i n g ' ) ; c l o s e ( pipo ) ;
  8254.               Writeln ( ' Reading from pipe . ' ) ;
  8255.               While not eof ( p i p i ) do
  8256.                     begin
  8257.                     Readln ( p i p i , s ) ;
  8258.                     Writeln ( ' Read from pipe : ' , s ) ;
  8259.                     end ;
  8260.                c l o s e ( p i p i ) ;
  8261.                writeln ( ' Closed pipes . ' ) ;
  8262.                writeln
  8263.            end .
  8264.  
  8265.  
  8266.            AssignStream
  8267. Declaration: Procedure AssignStream (StreamIn,StreamOut : Text; Const prog : String);
  8268.  
  8269. Description: AssignStream creates a 2 pipes, i.e. two file objects, one for input, one for output,
  8270.            the other ends of these pipes are connected to standard input and and output of
  8271.            Prog. Prog is the name of a program (including path) with options, which will be
  8272.            executed. What is written to StreamOut, will go to the standard input of Prog.
  8273.            Whatever is written by Prog to it's standard output be read from StreamIn. Read-
  8274.            ing and writing happens through the usual Readln(StreamIn,...) and Writeln
  8275.            (StreamOut,...) procedures.
  8276.            Remark: You should not use Reset or Rewrite on a file opened with POpen. This
  8277.            will close the file before re-opening it again, thereby closing the connection with the
  8278.            program.
  8279.  
  8280.      Errors: LinuxError is used to report errors:
  8281.  
  8282.            sys emfileToo many file descriptors for this process.
  8283.            sys enfileThe system file table is full.
  8284.  
  8285.            Other errors include the ones by the fork and exec programs
  8286.  
  8287.    See also: AssignPipe (140), POpen (177),pipe (2)
  8288.  
  8289.            Program Example38 ;
  8290.  
  8291.             { Program to demonstrate the AssignStream f u n c t i o n . }
  8292.  
  8293.            Uses l i n u x ;
  8294.  
  8295.            Var Si , So : Text ;
  8296.                     S : String ;
  8297.  
  8298.                                                            141
  8299.  
  8300.  
  8301.  
  8302.                                                            8.2. FUNCTIONS AND PROCEDURES
  8303.  
  8304.  
  8305.                     i : l o n g i n t ;
  8306.  
  8307.            begin
  8308.               i f not ( paramstr (1)= '- son ' ) then
  8309.                     begin
  8310.                     Writeln ( ' C a l l i n g son ' ) ;
  8311.                     Assignstream ( Si , So , ' . / ex38 -son ' ) ;
  8312.                     i f l i n u x e r r o r <>0 then
  8313.                        begin
  8314.                        writeln ( ' AssignStream f a i l e d ! ' ) ;
  8315.                        halt ( 1 ) ;
  8316.                        end ;
  8317.                     Writeln ( ' Speaking to son ' ) ;
  8318.                     For i :=1 to 10 do
  8319.                        begin
  8320.                        writeln ( so , ' Hello son ! ' ) ;
  8321.                        i f i o r e s u l t <>0 then writeln ( ' Can ' ' t speak to son . . . ' ) ;
  8322.                        end ;
  8323.                     For i :=1 to 3 do writeln ( so , ' Hello chap ! ' ) ;
  8324.                     c l o s e ( so ) ;
  8325.                     while not eof ( s i ) do
  8326.                        begin
  8327.                        readln ( s i , s ) ;
  8328.                        writeln ( ' Father : Son s aid : ' , S ) ;
  8329.                        end ;
  8330.                     Writeln ( ' Stopped c o n v e r s a t i o n ' ) ;
  8331.                     Close ( Si ) ;
  8332.                     Writeln ( ' Put down phone ' ) ;
  8333.                     end
  8334.               Else
  8335.                     begin
  8336.                     Writeln ( ' This i s the son ' ) ;
  8337.                     While not eof ( input ) do
  8338.                        begin
  8339.                        readln ( s ) ;
  8340.                        i f pos ( ' Hello son ! ' , S)<>0 then
  8341.                              Writeln ( ' Hello Dad ! ' )
  8342.                        elsewriteln ( 'Who are you ?' );
  8343.                        end ;
  8344.                     c l o s e ( output ) ;
  8345.                     end
  8346.            end .
  8347.  
  8348.  
  8349.            BaseName
  8350. Declaration: Function BaseName (Const Path;Suf : Pathstr) : Pathstr;
  8351.  
  8352. Description: Returns the filename part of Path, stripping o  Suf if it exists. The filename
  8353.            part is the whole name if Path contains no slash, or the part of Path after the last
  8354.            slash. The last character of the result is not a slash, unless the directory is the root
  8355.            directory.
  8356.  
  8357.     Errors: None.
  8358.  
  8359.                                                            142
  8360.  
  8361.  
  8362.  
  8363.                                                       8.2. FUNCTIONS AND PROCEDURES
  8364.  
  8365.  
  8366.   See also: DirName (146), FExpand (157), Basename (1)
  8367.  
  8368.            Program Example48 ;
  8369.  
  8370.            { Program to demonstrate the BaseName f u n c t i o n . }
  8371.  
  8372.            Uses l i n u x ;
  8373.  
  8374.            Var S : String ;
  8375.  
  8376.            begin
  8377.              S:= FExpand ( Paramstr ( 0 ) ) ;
  8378.               Writeln ( ' This program i s c a l l e d : ' , Basename ( S , ' ' ) ) ;
  8379.            end .
  8380.  
  8381.  
  8382.            CFMakeRaw
  8383. Declaration: Procedure CFMakeRaw (var Tios:TermIOS);
  8384.  
  8385. Description: CFMakeRaw Sets the flags in the Termios structure Tios to a state so that the
  8386.            terminal will function in Raw Mode.
  8387.  
  8388.     Errors: None.
  8389.  
  8390.   See also: CFSetOSpeed (143), CFSetISpeed (143), termios (2)
  8391.  
  8392.            For an example, see TCGetAttr (186).
  8393.  
  8394.  
  8395.            CFSetISpeed
  8396. Declaration: Procedure CFSetISpeed (var Tios:TermIOS;Speed:Longint);
  8397.  
  8398. Description: CFSetISpeed Sets the input baudrate in the TermIOS structure Tios to Speed.
  8399.  
  8400.     Errors: None.
  8401.  
  8402.   See also: CFSetOSpeed (143), CFMakeRaw (143), termios (2)
  8403.  
  8404.  
  8405.            CFSetOSpeed
  8406. Declaration: Procedure CFSetOSpeed (var Tios:TermIOS;Speed:Longint);
  8407.  
  8408. Description: CFSetOSpeed Sets the output baudrate in the Termios structure Tios to Speed.
  8409.  
  8410.     Errors: None.
  8411.  
  8412.   See also: CFSetISpeed (143), CFMakeRaw (143), termios (2)
  8413.  
  8414.  
  8415.            Chown
  8416. Declaration: Function Chown (Path : Pathstr;NewUid,NewGid : Longint) : Boolean;
  8417.  
  8418. Description: Chown sets the User ID and Group ID of the file in Path to NewUid, NewGid. The
  8419.            function returns True if the call was succesfull, False if the call failed.
  8420.  
  8421.  
  8422.                                                     143
  8423.  
  8424.  
  8425.  
  8426.                                                          8.2. FUNCTIONS AND PROCEDURES
  8427.  
  8428.  
  8429.      Errors: Errors are returned in LinuxError.
  8430.  
  8431.            sys epermThe e ective UID doesn't match the ownership of the file, and is not
  8432.                     zero. Owner or group were not specified correctly.
  8433.            sys eaccessOne of the directories in Path has no search (=execute) permission.
  8434.            sys enoentA directory entry in Path does not exist or is a symbolic link pointing
  8435.                     to a non-existent directory.
  8436.            sys enotdirA directory entry in OldPath or NewPath is nor a directory.
  8437.            sys enomemInsu cient kernel memory.
  8438.            sys erofsThe file is on a read-only filesystem.
  8439.            sys eloopPath has a reference to a circular symbolic link, i.e. a symbolic link,
  8440.                     whose expansion points to itself.
  8441.  
  8442.    See also: Chmod (144), Access (139), Chown (() 2)
  8443.  
  8444.            Program Example24 ;
  8445.  
  8446.            { Program to demonstrate the Chown f u n c t i o n . }
  8447.  
  8448.            Uses l i n u x ;
  8449.  
  8450.            Var UID , GID : Longint ;
  8451.                     F : Text ;
  8452.  
  8453.            begin
  8454.  
  8455.               Writeln ( ' This w i l l only work i f you are root . ' ) ;
  8456.               Write ( ' Enter a UID : ' ) ; readln ( UID ) ;
  8457.               Write ( ' Enter a GID : ' ) ; readln ( GID ) ;
  8458.               Assign ( f , ' t e s t . txt ' ) ;
  8459.               Rewrite ( f ) ;
  8460.               Writeln ( f , ' The owner of t h i s f i l e should become : ' ) ;
  8461.               Writeln ( f , ' UID : ' , UID ) ;
  8462.               Writeln ( f , ' GID : ' , GID ) ;
  8463.               Close ( F ) ;
  8464.               i f not Chown ( ' t e s t . txt ' , UID , GID ) then
  8465.                     i f L i n u x E r r o r =Sys EPERM then
  8466.                        Writeln ( ' You are not root ! ' )
  8467.                     else
  8468.                        Writeln ( ' Chmod f a i l e d with e x i t code : ' , L i n u x E r r o r )
  8469.               else
  8470.                     Writeln ( ' Changed owner s u c c e s s f u l l y ! ' ) ;
  8471.            end .
  8472.  
  8473.  
  8474.            Chmod
  8475. Declaration: Function Chmod (Path : Pathstr;NewMode : Longint) : Boolean;
  8476.  
  8477. Description: Chmod Sets the Mode bits of the file in Path to NewMode. Newmode can be specified
  8478.            by 'or'-ing the following:
  8479.  
  8480.            S ISUIDSet user ID on execution.
  8481.  
  8482.  
  8483.                                                          144
  8484.  
  8485.  
  8486.  
  8487.                                                              8.2. FUNCTIONS AND PROCEDURES
  8488.  
  8489.  
  8490.         S ISGIDSet Group ID on execution.
  8491.         S ISVTXSet sticky bit.
  8492.         S IRUSRRead by owner.
  8493.         S IWUSRWrite by owner.
  8494.         S IXUSRExecute by owner.
  8495.         S IRGRPRead by group.
  8496.         S IWGRPWrite by group.
  8497.         S IXGRPExecute by group.
  8498.         S IROTHRead by others.
  8499.         S IWOTHWrite by others.
  8500.         S IXOTHExecute by others.
  8501.         S IRWXORead, write, execute by others.
  8502.         S IRWXGRead, write, execute by groups.
  8503.         S IRWXURead, write, execute by user.
  8504.   Errors: Errors are returned in LinuxError.
  8505.         sys epermThe e ective UID doesn't match the ownership of the file, and is not
  8506.                  zero. Owner or group were not specified correctly.
  8507.         sys eaccessOne of the directories in Path has no search (=execute) permission.
  8508.         sys enoentA directory entry in Path does not exist or is a symbolic link pointing
  8509.                  to a non-existent directory.
  8510.         sys enotdirA directory entry in OldPath or NewPath is nor a directory.
  8511.         sys enomemInsu cient kernel memory.
  8512.         sys erofsThe file is on a read-only filesystem.
  8513.         sys eloopPath has a reference to a circular symbolic link, i.e. a symbolic link,
  8514.                  whose expansion points to itself.
  8515. See also: Chown (143), Access (139), Chmod (() 2)
  8516.  
  8517.         Program Example23 ;
  8518.  
  8519.         { Program to demonstrate the Chmod f u n c t i o n . }
  8520.  
  8521.         Uses l i n u x ;
  8522.  
  8523.         Var F : Text ;
  8524.  
  8525.         begin
  8526.            { Create a f i l e }
  8527.            Assign ( f , ' t e s t e x 2 1 ' ) ;
  8528.            Rewrite ( F ) ;
  8529.            Writeln ( f , '#!/ bin / sh ' ) ;
  8530.            Writeln ( f , ' echo Some text f o r t h i s f i l e ' ) ;
  8531.            Close ( F ) ;
  8532.            { Octal ( ) makes the c o r r e c t number from a
  8533.                  number that LOOKS o c t a l }
  8534.            Chmod ( ' t e s t e x 2 1 ' , o c t a l ( 7 7 7 ) ) ;
  8535.            { F i l e i s now e x e c u t a b l e        }
  8536.            e x e c l ( ' . / t e s t e x 2 1 ' ) ;
  8537.         end .
  8538.  
  8539.                                                          145
  8540.  
  8541.  
  8542.  
  8543.                                                       8.2. FUNCTIONS AND PROCEDURES
  8544.  
  8545.  
  8546.            CloseDir
  8547. Declaration: Function CloseDir (p:pdir) : integer;
  8548.  
  8549. Description: CloseDir closes the directory pointed to by p. It returns zero if the directory was
  8550.            closed succesfully, -1 otherwise.
  8551.  
  8552.      Errors: Errors are returned in LinuxError.
  8553.  
  8554.    See also: OpenDir (176), ReadDir (178), SeekDir (178), TellDir (188), closedir (3)
  8555.  
  8556.            For an example, see OpenDir (176).
  8557.  
  8558.  
  8559.            DirName
  8560. Declaration: Function DirName (Const Path : Pathstr) : Pathstr;
  8561.  
  8562. Description: Returns the directory part of Path. The directory is the part of Path before the
  8563.            last slash, or empty if there is no slash. The last character of the result is not a
  8564.            slash, unless the directory is the root directory.
  8565.  
  8566.      Errors: None.
  8567.  
  8568.    See also: BaseName (142), FExpand (157), Dirname (1)
  8569.  
  8570.            Program Example47 ;
  8571.  
  8572.            { Program to demonstrate the DirName f u n c t i o n . }
  8573.  
  8574.            Uses l i n u x ;
  8575.  
  8576.            Var S : String ;
  8577.  
  8578.            begin
  8579.               S:= FExpand ( Paramstr ( 0 ) ) ;
  8580.               Writeln ( ' This program i s in d i r e c t o r y : ' , Dirname ( S ) ) ;
  8581.            end .
  8582.  
  8583.  
  8584.            Dup
  8585. Declaration: Procedure Dup (Var OldFile, NewFile : Text);
  8586.  
  8587. Description: Makes NewFile an exact copy of OldFile, after having flushed the bu er of
  8588.            OldFile. Due to the bu ering mechanism of Pascal, this has not the same func-
  8589.            tionality as the dup (2) call in C. The internal Pascal bu ers are not the same after
  8590.            this call, but when the bu ers are flushed (e.g. after output), the output is sent to
  8591.            the same file. Doing an lseek will, however, work as in C, i.e. doing a lseek will
  8592.            change the fileposition in both files.
  8593.  
  8594.      Errors: Linuxerror is used to report errors.
  8595.  
  8596.            sys ebadfOldFile hasn't been assigned.
  8597.            sys emfileMaximum number of open files for the process is reached.
  8598.  
  8599.    See also: Dup2 (147), Dup (2)
  8600.  
  8601.  
  8602.                                                      146
  8603.  
  8604.  
  8605.  
  8606.                                                            8.2. FUNCTIONS AND PROCEDURES
  8607.  
  8608.  
  8609.           program Example31 ;
  8610.  
  8611.           { Program to demonstrate the Dup f u n c t i o n . }
  8612.  
  8613.           uses l i n u x ;
  8614.  
  8615.           var f : text ;
  8616.  
  8617.           begin
  8618.              i f not dup ( output , f ) then
  8619.                    Writeln ( ' Dup F a i l e d ! ' ) ;
  8620.              writeln ( ' This i s w r i t t e n to stdout . ' ) ;
  8621.              writeln ( f , ' This i s w r i t t e n to the dup f i l e , and f l u s h e d ' ) ; flush ( f ) ;
  8622.              writeln
  8623.           end .
  8624.  
  8625.  
  8626.           Dup2
  8627. Declaration: Procedure Dup2 (Var OldFile, NewFile : Text);
  8628.  
  8629. Description: Makes NewFile an exact copy of OldFile, after having flushed the bu er of
  8630.           OldFile. NewFile can be an assigned file. If newfile was open, it is closed first.
  8631.           Due to the bu ering mechanism of Pascal, this has not the same functionality as
  8632.           the dup2 (2) call in C. The internal Pascal bu ers are not the same after this call,
  8633.           but when the bu ers are flushed (e.g. after output), the output is sent to the same
  8634.           file. Doing an lseek will, however, work as in C, i.e. doing a lseek will change the
  8635.           fileposition in both files.
  8636.  
  8637.     Errors: Linuxerror is used to report errors.
  8638.  
  8639.           sys ebadfOldFile hasn't been assigned.
  8640.           sys emfileMaximum number of open files for the process is reached.
  8641.  
  8642.   See also: Dup (146), Dup2 (2)
  8643.  
  8644.           program Example31 ;
  8645.  
  8646.           { Program to demonstrate the Dup f u n c t i o n . }
  8647.  
  8648.           uses l i n u x ;
  8649.  
  8650.           var f : text ;
  8651.                    i : l o n g i n t ;
  8652.  
  8653.           begin
  8654.              Assign ( f , ' text . txt ' ) ;
  8655.              Rewrite ( F ) ;
  8656.              For i :=1 to 10 do writeln ( F, ' Line : ' , i ) ;
  8657.              i f not dup2 ( output , f ) then
  8658.                    Writeln ( ' Dup2 F a i l e d ! ' ) ;
  8659.              writeln ( ' This i s w r i t t e n to stdout . ' ) ;
  8660.              writeln ( f , ' This i s w r i t t e n to the dup f i l e , and f l u s h e d ' ) ;
  8661.              flush ( f ) ;
  8662.              writeln ;
  8663.  
  8664.                                                           147
  8665.  
  8666.  
  8667.  
  8668.                                                        8.2. FUNCTIONS AND PROCEDURES
  8669.  
  8670.  
  8671.               { Remove f i l e . Comment t h i s i f you want to check f l u s h i n g .}
  8672.               Unlink ( ' text . txt ' ) ;
  8673.            end .
  8674.  
  8675.  
  8676.            EpochToLocal
  8677. Declaration: Procedure EpochToLocal (Epoch : Longint; var Year,Month,Day,Hour,Minute,Second
  8678.            : Word);
  8679.  
  8680. Description: Converts the epoch time (=Number of seconds since 00:00:00 , January 1, 1970,
  8681.            corrected for your time zone ) to local date and time.
  8682.  
  8683.      Errors: None
  8684.  
  8685.    See also: GetEpochTime (163), LocalToEpoch (174), GetTime (166),GetDate (161)
  8686.  
  8687.            Program Example3 ;
  8688.  
  8689.            { Program to demonstrate the EpochToLocal f u n c t i o n . }
  8690.  
  8691.            Uses l i n u x ;
  8692.  
  8693.            Var Year , month , day , hour , minute , seconds : Word ;
  8694.  
  8695.            begin
  8696.               EpochToLocal ( GetEpochTime , Year , month , day , hour , minute , seconds ) ;
  8697.               Writeln ( ' Current date : ' , Day : 2 , ' / ' , Month : 2 , ' / ' , Year : 4 ) ;
  8698.               Writeln ( ' Current time : ' , Hour : 2 , ' : ' , minute : 2 , ' : ' , seconds : 2 ) ;
  8699.            end .
  8700.  
  8701.  
  8702.            Execl
  8703. Declaration: Procedure Execl (Path : pathstr);
  8704.  
  8705. Description: Replaces the currently running program with the program, specified in path. Path
  8706.            is split into a command and it's options. The executable in path is NOT searched
  8707.            in the path. The current environment is passed to the program. On success, execl
  8708.            does not return.
  8709.  
  8710.      Errors: Errors are reported in LinuxError:
  8711.  
  8712.            sys eaccesFile is not a regular file, or has no execute permission. A compononent
  8713.                     of the path has no search permission.
  8714.            sys epermThe file system is mounted noexec.
  8715.            sys e2bigArgument list too big.
  8716.            sys enoexecThe magic number in the file is incorrect.
  8717.            sys enoentThe file does not exist.
  8718.            sys enomemNot enough memory for kernel, or to split command line.
  8719.            sys enotdirA component of the path is not a directory.
  8720.            sys eloopThe path contains a circular reference (via symlinks).
  8721.  
  8722.    See also: Execve (151), Execv (150), Execvp (152), Execle (149), Execlp (150), Fork (161),
  8723.            execvp (3)
  8724.  
  8725.                                                       148
  8726.  
  8727.  
  8728.  
  8729.                                                        8.2. FUNCTIONS AND PROCEDURES
  8730.  
  8731.  
  8732.            Program Example10 ;
  8733.  
  8734.            { Program to demonstrate the Execl f u n c t i o n . }
  8735.  
  8736.            Uses l i n u x , s t r i n g s ;
  8737.  
  8738.            begin
  8739.               { Execute ' l s - l ' , with c u r r e n t environment . }
  8740.               { ' l s ' i s NOT looked f or in PATH environment v a r i a b l e .}
  8741.               Execl ( '/ bin / l s -l ' ) ;
  8742.            end .
  8743.  
  8744.  
  8745.            Execle
  8746. Declaration: Procedure Execle (Path : pathstr, Ep : ppchar);
  8747.  
  8748. Description: Replaces the currently running program with the program, specified in path. Path
  8749.            is split into a command and it's options. The executable in path is searched in the
  8750.            path, if it isn't an absolute filename. The environment in ep is passed to the
  8751.            program. On success, execle does not return.
  8752.  
  8753.      Errors: Errors are reported in LinuxError:
  8754.  
  8755.            sys eaccesFile is not a regular file, or has no execute permission. A compononent
  8756.                     of the path has no search permission.
  8757.            sys epermThe file system is mounted noexec.
  8758.            sys e2bigArgument list too big.
  8759.            sys enoexecThe magic number in the file is incorrect.
  8760.            sys enoentThe file does not exist.
  8761.            sys enomemNot enough memory for kernel, or to split command line.
  8762.            sys enotdirA component of the path is not a directory.
  8763.            sys eloopThe path contains a circular reference (via symlinks).
  8764.  
  8765.    See also: Execve (151), Execv (150), Execvp (152), Execl (148), Execlp (150), Fork (161),
  8766.            execvp (3)
  8767.  
  8768.            Program Example11 ;
  8769.  
  8770.            { Program to demonstrate the Execle f u n c t i o n . }
  8771.  
  8772.            Uses l i n u x , s t r i n g s ;
  8773.  
  8774.            begin
  8775.               { Execute ' l s - l ' , with c u r r e n t environment . }
  8776.               { ' l s ' i s NOT looked f o r in PATH environment v a r i a b l e .}
  8777.               { envp i s d e f i n e d in the system unit .}
  8778.               Execle ( '/ bin / l s -l ' , envp ) ;
  8779.            end .
  8780.  
  8781.  
  8782.  
  8783.  
  8784.  
  8785.                                                        149
  8786.  
  8787.  
  8788.  
  8789.                                                        8.2. FUNCTIONS AND PROCEDURES
  8790.  
  8791.  
  8792.            Execlp
  8793. Declaration: Procedure Execlp (Path : pathstr);
  8794.  
  8795. Description: Replaces the currently running program with the program, specified in path. Path
  8796.            is split into a command and it's options. The executable in path is searched in the
  8797.            path, if it isn't an absolute filename. The current environment is passed to the
  8798.            program. On success, execlp does not return.
  8799.  
  8800.      Errors: Errors are reported in LinuxError:
  8801.  
  8802.            sys eaccesFile is not a regular file, or has no execute permission. A compononent
  8803.                     of the path has no search permission.
  8804.            sys epermThe file system is mounted noexec.
  8805.            sys e2bigArgument list too big.
  8806.            sys enoexecThe magic number in the file is incorrect.
  8807.            sys enoentThe file does not exist.
  8808.            sys enomemNot enough memory for kernel, or to split command line.
  8809.            sys enotdirA component of the path is not a directory.
  8810.            sys eloopThe path contains a circular reference (via symlinks).
  8811.  
  8812.    See also: Execve (151), Execv (150), Execvp (152), Execle (149), Execl (148), Fork (161),
  8813.            execvp (3)
  8814.  
  8815.            Program Example12 ;
  8816.  
  8817.            { Program to demonstrate the Execlp f u n c t i o n . }
  8818.  
  8819.            Uses l i n u x , s t r i n g s ;
  8820.  
  8821.            begin
  8822.               { Execute ' l s - l ' , with c u r r e n t environment . }
  8823.               { ' l s ' i s looked fo r in PATH environment v a r i a b l e .}
  8824.               { envp i s d e f i n e d in the system unit .}
  8825.               Execlp ( ' l s -l ' , envp ) ;
  8826.            end .
  8827.  
  8828.  
  8829.            Execv
  8830. Declaration: Procedure Execv (Path : pathstr; args : ppchar);
  8831.  
  8832. Description: Replaces the currently running program with the program, specified in path. It
  8833.            gives the program the options in args. This is a pointer to an array of pointers to
  8834.            null-terminated strings. The last pointer in this array should be nil. The current
  8835.            environment is passed to the program. On success, execv does not return.
  8836.  
  8837.      Errors: Errors are reported in LinuxError:
  8838.  
  8839.            sys eaccesFile is not a regular file, or has no execute permission. A compononent
  8840.                     of the path has no search permission.
  8841.            sys epermThe file system is mounted noexec.
  8842.            sys e2bigArgument list too big.
  8843.            sys enoexecThe magic number in the file is incorrect.
  8844.  
  8845.                                                       150
  8846.  
  8847.  
  8848.  
  8849.                                                           8.2. FUNCTIONS AND PROCEDURES
  8850.  
  8851.  
  8852.            sys enoentThe file does not exist.
  8853.            sys enomemNot enough memory for kernel.
  8854.            sys enotdirA component of the path is not a directory.
  8855.            sys eloopThe path contains a circular reference (via symlinks).
  8856.  
  8857.   See also: Execve (151), Execvp (152), Execle (149), Execl (148), Execlp (150), Fork (161),
  8858.            execv (3)
  8859.  
  8860.            Program Example8 ;
  8861.  
  8862.            { Program to demonstrate the Execv f u n c t i o n . }
  8863.  
  8864.            Uses l i n u x , s t r i n g s ;
  8865.  
  8866.            Const Arg0 : PChar = '/ bin / l s ' ;
  8867.                        Arg1 : Pchar = '- l ' ;
  8868.  
  8869.            Var PP : PPchar ;
  8870.  
  8871.  
  8872.            begin
  8873.               GetMem ( PP,3  SizeOf ( Pchar ) ) ;
  8874.               PP[0]:= Arg0 ;
  8875.               PP[1]:= Arg1 ;
  8876.               PP[3]:= Nil ;
  8877.               { Execute '/ bin / l s - l ' , with c u r r e n t environment }
  8878.               Execv ( '/ bin / l s ' , pp ) ;
  8879.            end .
  8880.  
  8881.  
  8882.            Execve
  8883. Declaration: Procedure Execve (Path : pathstr; args,ep : ppchar);
  8884.  
  8885. Description: Replaces the currently running program with the program, specified in path. It
  8886.            gives the program the options in args, and the environment in ep. They are pointers
  8887.            to an array of pointers to null-terminated strings. The last pointer in this array
  8888.            should be nil. On success, execve does not return.
  8889.  
  8890.     Errors: Errors are reported in LinuxError:
  8891.  
  8892.            eaccesFile is not a regular file, or has no execute permission. A compononent of
  8893.                     the path has no search permission.
  8894.            sys epermThe file system is mounted noexec.
  8895.            sys e2bigArgument list too big.
  8896.            sys enoexecThe magic number in the file is incorrect.
  8897.            sys enoentThe file does not exist.
  8898.            sys enomemNot enough memory for kernel.
  8899.            sys enotdirA component of the path is not a directory.
  8900.            sys eloopThe path contains a circular reference (via symlinks).
  8901.  
  8902.   See also: Execve (151), Execv (150), Execvp (152) Execle (149), Execl (148), Execlp (150), Fork
  8903.            (161), execve (2)
  8904.  
  8905.                                                      151
  8906.  
  8907.  
  8908.  
  8909.                                                          8.2. FUNCTIONS AND PROCEDURES
  8910.  
  8911.  
  8912.            Program Example7 ;
  8913.  
  8914.            { Program to demonstrate the Execve f u n c t i o n . }
  8915.  
  8916.            Uses l i n u x , s t r i n g s ;
  8917.  
  8918.            Const Arg0 : PChar = '/ bin / l s ' ;
  8919.                        Arg1 : Pchar = '- l ' ;
  8920.  
  8921.            Var PP : PPchar ;
  8922.  
  8923.  
  8924.            begin
  8925.               GetMem ( PP,3  SizeOf ( Pchar ) ) ;
  8926.               PP[0]:= Arg0 ;
  8927.               PP[1]:= Arg1 ;
  8928.               PP[3]:= Nil ;
  8929.               { Execute '/ bin / l s - l ' , with c u r r e n t environment }
  8930.               { Envp i s d e f i n e d in system . inc }
  8931.               ExecVe ( '/ bin / l s ' , pp , envp ) ;
  8932.            end .
  8933.  
  8934.  
  8935.            Execvp
  8936. Declaration: Procedure Execvp (Path : pathstr; args : ppchar);
  8937.  
  8938. Description: Replaces the currently running program with the program, specified in path. The
  8939.            executable in path is searched in the path, if it isn't an absolute filename. It gives
  8940.            the program the options in args. This is a pointer to an array of pointers to
  8941.            null-terminated strings. The last pointer in this array should be nil. The current
  8942.            environment is passed to the program. On success, execvp does not return.
  8943.  
  8944.     Errors: Errors are reported in LinuxError:
  8945.  
  8946.            sys eaccesFile is not a regular file, or has no execute permission. A compononent
  8947.                     of the path has no search permission.
  8948.            sys epermThe file system is mounted noexec.
  8949.            sys e2bigArgument list too big.
  8950.            sys enoexecThe magic number in the file is incorrect.
  8951.            sys enoentThe file does not exist.
  8952.            sys enomemNot enough memory for kernel.
  8953.            sys enotdirA component of the path is not a directory.
  8954.            sys eloopThe path contains a circular reference (via symlinks).
  8955.  
  8956.   See also: Execve (151), Execv (150), Execle (149), Execl (148), Execlp (150), Fork (161),
  8957.            execvp (3)
  8958.  
  8959.            Program Example9 ;
  8960.  
  8961.            { Program to demonstrate the Execvp f u n c t i o n . }
  8962.  
  8963.            Uses l i n u x , s t r i n g s ;
  8964.  
  8965.                                                          152
  8966.  
  8967.  
  8968.  
  8969.                                                       8.2. FUNCTIONS AND PROCEDURES
  8970.  
  8971.  
  8972.  
  8973.             Const Arg0 : PChar = ' l s ' ;
  8974.                       Arg1 : Pchar = '- l ' ;
  8975.  
  8976.             Var PP : PPchar ;
  8977.  
  8978.  
  8979.             begin
  8980.               GetMem ( PP,3  SizeOf ( Pchar ) ) ;
  8981.               PP[0]:= Arg0 ;
  8982.               PP[1]:= Arg1 ;
  8983.               PP[3]:= Nil ;
  8984.                { Execute ' l s - l ' , with c u r r e n t environment . }
  8985.                { ' l s ' i s looked fo r in PATH environment v a r i a b l e .}
  8986.                { Envp i s d e f i n e d in the system unit . }
  8987.                Execvp ( ' l s ' , pp , envp ) ;
  8988.             end .
  8989.  
  8990.  
  8991.            FD ZERO
  8992. Declaration: Procedure FD ZERO (var fds:fdSet);
  8993. Description: FD ZERO clears all the filedescriptors in the file descriptor set fds.
  8994.      Errors: None.
  8995.    See also: Select (178), SelectText (180), GetFS (164), FD Clr (153), FD Set (154), FD IsSet
  8996.            (153)
  8997.  
  8998.            For an example, see Select (178).
  8999.  
  9000.  
  9001.            FD Clr
  9002. Declaration: Procedure FD Clr (fd:longint;var fds:fdSet);
  9003. Description: FD Clr clears file descriptor fd in filedescriptor s et fds.
  9004.      Errors: None.
  9005.    See also: Select (178), SelectText (180), GetFS (164), FD ZERO (153), FD Set (154), FD IsSet
  9006.            (153)
  9007.  
  9008.            For an example, see Select (178).
  9009.  
  9010.  
  9011.            FD IsSet
  9012. Declaration: Function FD IsSet (fd:longint;var fds:fdSet) : boolean;
  9013. Description: FD Set Checks whether file descriptor fd in filedescriptor set fds is set.
  9014.      Errors: None.
  9015.    See also: Select (178), SelectText (180), GetFS (164), FD ZERO (153), FD Clr (153), FD Set
  9016.            (154)
  9017.  
  9018.            For an example, see Select (178).
  9019.  
  9020.                                                      153
  9021.  
  9022.  
  9023.  
  9024.                                                       8.2. FUNCTIONS AND PROCEDURES
  9025.  
  9026.  
  9027.            FD Set
  9028. Declaration: Procedure FD Set (fd:longint;var fds:fdSet);
  9029.  
  9030. Description: FD Set sets file descriptor fd in filedescriptor set fds.
  9031.  
  9032.      Errors: None.
  9033.  
  9034.    See also: Select (178), SelectText (180), GetFS (164),FD ZERO (153), FD Clr (153), FD IsSet
  9035.            (153)
  9036.  
  9037.            For an example, see Select (178).
  9038.  
  9039.  
  9040.            fdClose
  9041. Declaration: Function fdClose (fd:longint) : boolean;
  9042.  
  9043. Description: fdClose closes a file with file descriptor Fd. The function returns True if the file
  9044.            was closed successfully, False otherwise.
  9045.  
  9046.      Errors: Errors are returned in LinuxError
  9047.  
  9048.    See also: fdOpen (154), fdRead (155), fdWrite (157),fdTruncate (156), fdFlush (154), seefFd-
  9049.            Seek
  9050.  
  9051.            For an example, see fdOpen (154).
  9052.  
  9053.  
  9054.            fdFlush
  9055. Declaration: Function fdFlush (fd:Longint) : boolean;
  9056.  
  9057. Description: fdflush flushes the Linux kernel file bu er, so the file is actually written to disk.
  9058.            This is NOT the same as the internal bu er, maintained by Free Pascal. The
  9059.            function returns True if the call was successful, false if an error occurred.
  9060.  
  9061.      Errors: Errors are returned in LinuxError.
  9062.  
  9063.    See also: fdOpen (154), fdClose (154), fdRead (155),fdWrite (157), fdTruncate (156), fdSeek
  9064.            (156)
  9065.  
  9066.            For an example, see fdRead (155).
  9067.  
  9068.  
  9069.            fdOpen
  9070. Declaration: Function fdOpen (Var PathName;flags:longint[; Mode: longint]) : longint;
  9071.  
  9072. Description: fdOpen opens a file in pathname with flags flags a ORed combination of Open Accmode,
  9073.            Open RdOnly, Open WrOnly, Open RdWr, Open Creat, Open Excl, Open NoCtty,
  9074.            Open Trunc, Open Append, Open NonBlock, Open NDelay, Open Sync PathName
  9075.            can be of type PChar or String The optional mode argument specifies the permis-
  9076.            sions to set when opening the file. This is modified by the umask setting. The
  9077.            real permissions are Mode and not umask. The return value of the function is the
  9078.            filedescriptor, or a negative value if there was an error.
  9079.  
  9080.      Errors: Errors are returned in LinuxError
  9081.  
  9082.  
  9083.                                                      154
  9084.  
  9085.  
  9086.  
  9087.                                                       8.2. FUNCTIONS AND PROCEDURES
  9088.  
  9089.  
  9090.   See also: fdClose (154), fdRead (155), fdWrite (157),fdTruncate (156), fdFlush (154), fdSeek
  9091.           (156)
  9092.  
  9093.           Program Example19 ;
  9094.  
  9095.           { Program to demonstrate the fdOpen , f d w r i t e and fdCLose f u n c t i o n s . }
  9096.  
  9097.           Uses l i n u x ;
  9098.  
  9099.           Const Line : String [ 8 0 ] = ' This i s easy w r i t i n g ! ' ;
  9100.  
  9101.           Var FD : Longint ;
  9102.  
  9103.           begin
  9104.              FD:= fdOpen ( ' Test . dat ' , Open WrOnly or Open Creat ) ;
  9105.              i f FD>0 then
  9106.                    begin
  9107.                    i f length ( Line )<>f d w r i t e ( FD, Line [ 1 ] , Length ( Line ) ) then
  9108.                       Writeln ( ' Error when w r i t i n g to f i l e ! ' ) ;
  9109.                    f d C l o s e (FD) ;
  9110.                    end ;
  9111.           end .
  9112.  
  9113.  
  9114.           fdRead
  9115. Declaration: Function fdRead (fd:longint;var buf;size:longint : longint;
  9116.  
  9117. Description: fdRead reads at most size bytes from the file descriptor fd, and stores them
  9118.           in buf. The function returns the number of bytes actually read, or -1 if an error
  9119.           occurred. No checking on the length of buf is done.
  9120.  
  9121.     Errors: Errors are returned in LinuxError.
  9122.  
  9123.   See also: fdOpen (154), fdClose (154), fdWrite (157),fdTruncate (156), fdFlush (154), fdSeek
  9124.           (156)
  9125.  
  9126.           Program Example20 ;
  9127.  
  9128.           { Program to demonstrate the fdRead and fdTruncate f u n c t i o n s . }
  9129.  
  9130.           Uses l i n u x ;
  9131.  
  9132.           Const Data : st r ing [ 1 0 ] = '12345687890' ;
  9133.  
  9134.           Var FD : Longint ;
  9135.                    l : l o n g i n t ;
  9136.  
  9137.           begin
  9138.              FD:= fdOpen ( ' t e s t . dat ' , open wronly or open creat , o c t a l ( 6 6 6 ) ) ;
  9139.              i f fd >0 then
  9140.                    begin
  9141.                    { F i l l f i l e with data }
  9142.                    for l :=1 to 10 do
  9143.                       i f fdWrite ( FD, Data [1],10)<>10 then
  9144.  
  9145.                                                      155
  9146.  
  9147.  
  9148.  
  9149.                                                            8.2. FUNCTIONS AND PROCEDURES
  9150.  
  9151.  
  9152.                              begin
  9153.                              writeln ( ' Error when w r i t i n g ! ' ) ;
  9154.                              halt ( 1 ) ;
  9155.                              end ;
  9156.                     f d C l o s e (FD) ;
  9157.                     FD:= fdOpen ( ' t e s t . dat ' , open rdonly ) ;
  9158.                     { Read data again }
  9159.                     I f FD>0 then
  9160.                        begin
  9161.                        For l :=1 to 5 do
  9162.                              i f fdRead ( FD, Data [1],10)<>10 then
  9163.                                 begin
  9164.                                 Writeln ( ' Error when Reading ! ' ) ;
  9165.                                 Halt ( 2 ) ;
  9166.                                 end ;
  9167.                        fdCLose (FD) ;
  9168.                        { Truncating f i l e at 60 bytes }
  9169.                        { For t r u n c a t i n g , f i l e must be open or w r i t e }
  9170.                        FD:= fdOpen ( ' t e s t . dat ' , open wronly , o c t a l ( 6 6 6 ) ) ;
  9171.                        i f FD>0 then
  9172.                              begin
  9173.                              i f not fdTruncate (FD, 6 0 ) then
  9174.                                  Writeln ( ' Error when t r u n c a t i n g ! ' ) ;
  9175.                              f d C l o s e ( FD) ;
  9176.                              end ;
  9177.                        end ;
  9178.                     end ;
  9179.            end .
  9180.  
  9181.  
  9182.            fdSeek
  9183. Declaration: Function fdSeek (fd,Pos,SeekType:longint : longint;
  9184.  
  9185. Description: fdSeek sets the current fileposition of file fd to Pos, starting from SeekType, which
  9186.            can be one of the following:
  9187.  
  9188.            Seek Set Pos is the absolute position in the file.
  9189.            Seek Cur Pos is relative to the current position.
  9190.            Seek end Pos is relative to the end of the file.
  9191.  
  9192.            The function returns the new fileposition, or -1 of an error occurred.
  9193.  
  9194.      Errors: Errors are returned in LinuxError.
  9195.  
  9196.    See also: fdOpen (154), fdWrite (157), fdClose (154), fdRead (155),fdTruncate (156), fdFlush
  9197.            (154)
  9198.  
  9199.            For an example, see fdOpen (154).
  9200.  
  9201.  
  9202.            fdTruncate
  9203. Declaration: Function fdTruncate (fd,size:longint) : boolean;
  9204.  
  9205.  
  9206.  
  9207.                                                           156
  9208.  
  9209.  
  9210.  
  9211.                                                           8.2. FUNCTIONS AND PROCEDURES
  9212.  
  9213.  
  9214. Description: fdTruncate sets the length of a file in fd on size bytes, where size must be less
  9215.            than or equal to the current length of the file in fd. The function returns True if
  9216.            the call was successful, false if an error occurred.
  9217.      Errors: Errors are returned in LinuxError.
  9218.    See also: fdOpen (154), fdClose (154), fdRead (155),fdWrite (157),fdFlush (154), fdSeek (156)
  9219.  
  9220.  
  9221.            fdWrite
  9222. Declaration: Function fdWrite (fd:longint;var buf;size:longint : longint;
  9223. Description: fdWrite writes at most size bytes from buf to file descriptor fd. The function
  9224.            returns the number of bytes actually written, or -1 if an error occurred.
  9225.      Errors: Errors are returned in LinuxError.
  9226.    See also: fdOpen (154), fdClose (154), fdRead (155),fdTruncate (156), fdSeek (156), fdFlush
  9227.            (154)
  9228.  
  9229.  
  9230.            FExpand
  9231. Declaration: Function FExpand (Const Path: Pathstr) : pathstr;
  9232. Description: Expands Path to a full path, starting from root, eliminating directory references
  9233.            such as . and .. from the result.
  9234.      Errors: None
  9235.    See also: BaseName (142),DirName (146)
  9236.  
  9237.            Program Example45 ;
  9238.  
  9239.            { Program to demonstrate the FExpand f u n c t i o n . }
  9240.  
  9241.            Uses l i n u x ;
  9242.  
  9243.            begin
  9244.               Writeln ( ' This program i s in : ' , FExpand ( Paramstr ( 0 ) ) ) ;
  9245.            end .
  9246.  
  9247.  
  9248.            FLock
  9249. Declaration: Procedure FLock (Var F; Mode : longint);
  9250. Description: FLock implements file locking. it sets or removes a lock on the file F. F can be of
  9251.            type Text or File, or it can be a linux filedescriptor (a longint) Mode can be one
  9252.            of the following constants :
  9253.            LOCK SH sets a shared lock.
  9254.            LOCK EX sets an exclusive lock.
  9255.            LOCK UN unlocks the file.
  9256.            LOCK NB This can be OR-ed together with the other. If this is done the appli-
  9257.                     cation doesn't block when locking.
  9258.      Errors: Errors are reported in LinuxError.
  9259.    See also: Fcntl (160), flock (2)
  9260.  
  9261.  
  9262.                                                           157
  9263.  
  9264.  
  9265.  
  9266.                                                             8.2. FUNCTIONS AND PROCEDURES
  9267.  
  9268.  
  9269.            FSStat
  9270. Declaration: Function FSStat (Path : Pathstr; Var Info : statfs) : Boolean;
  9271.  
  9272. Description: Return in Info information about the filesystem on which the file Path resides.
  9273.            Info is of type statfs. The function returns True if the call was succesfull, False
  9274.            if the call failed.
  9275.  
  9276.     Errors: LinuxError is used to report errors.
  9277.  
  9278.            sys enotdirA component of Path is not a directory.
  9279.            sys einvalInvalid character in Path.
  9280.            sys enoentPath does not exist.
  9281.            sys eaccessSearch permission is denied for component in Path.
  9282.            sys eloopA circular symbolic link was encountered in Path.
  9283.            sys eioAn error occurred while reading from the filesystem.
  9284.  
  9285.   See also: FStat (159), LStat (172), statfs (2)
  9286.  
  9287.            program Example30 ;
  9288.  
  9289.            { Program to demonstrate the FSStat f u n c t i o n . }
  9290.  
  9291.            uses l i n u x ;
  9292.  
  9293.            var s : st r ing ;
  9294.                     i n f o : s t a t f s ;
  9295.  
  9296.            begin
  9297.               writeln ( ' I n f o about c u r r e n t p a r t i t i o n : ' ) ;
  9298.               s := ' . ' ;
  9299.               while s<>' q ' do
  9300.                     begin
  9301.                     i f not f s s t a t ( s , i n f o ) then
  9302.                         begin
  9303.                          writeln ( ' Fstat f a i l e d . Errno : ' , l i n u x e r r o r ) ;
  9304.                          halt ( 1 ) ;
  9305.                         end ;
  9306.                     writeln ;
  9307.                     writeln ( ' Result of f s s t a t on f i l e ' ' ' , s , ' ' ' . ' ) ;
  9308.                     writeln ( ' f s t y p e    : ' , i n f o . f s t y p e ) ;
  9309.                     writeln ( ' b s i z e      : ' , i n f o . b s i z e ) ;
  9310.                     writeln ( ' b f r e e      : ' , i n f o . b f r e e ) ;
  9311.                     writeln ( ' b a v a i l    : ' , i n f o . b a v a i l ) ;
  9312.                     writeln ( ' f i l e s      : ' , i n f o . f i l e s ) ;
  9313.                     writeln ( ' f f r e e      : ' , i n f o . f f r e e ) ;
  9314.                     writeln ( ' f s i d        : ' , i n f o . f s i d ) ;
  9315.                     writeln ( ' Namelen : ' , i n f o . namelen ) ;
  9316.                     write ( ' Type name of f i l e to do f s s t a t . ( q q u i t s ) : ' ) ;
  9317.                     readln ( s )
  9318.                     end ;
  9319.            end .
  9320.  
  9321.  
  9322.  
  9323.                                                            158
  9324.  
  9325.  
  9326.  
  9327.                                                             8.2. FUNCTIONS AND PROCEDURES
  9328.  
  9329.  
  9330.            FSearch
  9331. Declaration: Function FSearch (Path : pathstr;DirList : string) : Pathstr;
  9332.  
  9333. Description: Searches in DirList, a colon separated list of directories, for a file named Path.
  9334.            It then returns a path to the found file.
  9335.  
  9336.      Errors: An empty string if no such file was found.
  9337.  
  9338.    See also: BaseName (142), DirName (146), FExpand (157)
  9339.  
  9340.            Program Example46 ;
  9341.  
  9342.             { Program to demonstrate the FSearch f u n c t i o n . }
  9343.  
  9344.            Uses l i n u x , s t r i n g s ;
  9345.  
  9346.             begin
  9347.                Writeln ( ' l s i s in : ' , FSearch ( ' l s ' , strpas ( Getenv ( ' PATH' ) ) ) ) ;
  9348.            end .
  9349.  
  9350.  
  9351.            FStat
  9352. Declaration: Function FStat (Path : Pathstr; Var Info : stat) : Boolean;
  9353.  
  9354. Description: FStat gets information about the file specified in Path, and stores it in Info, which
  9355.            is of type stat. The function returns True if the call was succesfull, False if the
  9356.            call failed.
  9357.  
  9358.      Errors: LinuxError is used to report errors.
  9359.  
  9360.            sys enoentPath does not exist.
  9361.  
  9362.    See also: FSStat (158), LStat (172), stat (2)
  9363.  
  9364.            program example28 ;
  9365.  
  9366.             { Program to demonstrate the FStat f u n c t i o n . }
  9367.  
  9368.             uses l i n u x ;
  9369.  
  9370.             var f : text ;
  9371.                     i : byte ;
  9372.                     i n f o : s t a t ;
  9373.  
  9374.             begin
  9375.                { Make a f i l e }
  9376.                a s s i g n ( f , ' t e s t . f i l ' ) ;
  9377.                rewrite ( f ) ;
  9378.                for i :=1 to 10 do writeln ( f , ' T e s t l i n e # ' , i ) ;
  9379.                c l o s e ( f ) ;
  9380.                { Do the c a l l on made f i l e . }
  9381.                i f not f s t a t ( ' t e s t . f i l ' , i n f o ) then
  9382.                      begin
  9383.                      writeln ( ' Fstat f a i l e d . Errno : ' , l i n u x e r r o r ) ;
  9384.                      halt ( 1 ) ;
  9385.  
  9386.                                                             159
  9387.  
  9388.  
  9389.  
  9390.                                                             8.2. FUNCTIONS AND PROCEDURES
  9391.  
  9392.  
  9393.                      end ;
  9394.               writeln ;
  9395.               writeln ( ' Result of f s t a t on f i l e ' ' t e s t . f i l ' ' . ' ) ;
  9396.               writeln ( ' Inode            : ' , i n f o . ino ) ;
  9397.               writeln ( ' Mode             : ' , i n f o . mode ) ;
  9398.               writeln ( ' n l i n k        : ' , i n f o . n l i n k ) ;
  9399.               writeln ( ' uid              : ' , i n f o . uid ) ;
  9400.               writeln ( ' gid              : ' , i n f o . gid ) ;
  9401.               writeln ( ' rdev             : ' , i n f o . rdev ) ;
  9402.               writeln ( ' Size             : ' , i n f o . s i z e ) ;
  9403.               writeln ( ' B l k s i z e : ' , i n f o . b l k s z e ) ;
  9404.               writeln ( ' Blocks           : ' , i n f o . blocks ) ;
  9405.               writeln ( ' atime            : ' , i n f o . atime ) ;
  9406.               writeln ( ' mtime            : ' , i n f o . mtime ) ;
  9407.               writeln ( ' ctime            : ' , i n f o . ctime ) ;
  9408.               { Remove f i l e }
  9409.               erase ( f ) ;
  9410.            end .
  9411.  
  9412.  
  9413.            Fcntl
  9414. Declaration: Function Fcntl (Fd : text, Cmd : Integer) : Integer;
  9415.  
  9416. Description: Read a file's attributes. Fd is an assigned file. Cmd speciefies what to do, and is
  9417.            one of the following:
  9418.  
  9419.            F GetFdRead the close on exec flag. If the low-order bit is 0, then the file will
  9420.                     remain open across execve calls.
  9421.            F GetFlRead the descriptor's flags.
  9422.            F GetOwnGet the Process ID of the owner of a socket.
  9423.  
  9424.      Errors: LinuxError is used to report errors.
  9425.  
  9426.            sys ebadfFd has a bad file descriptor.
  9427.  
  9428.    See also: Fcntl (160), Fcntl (2)
  9429.  
  9430.  
  9431.            Fcntl
  9432. Declaration: Procedure Fcntl (Fd : text, Cmd : Integer; Arg : longint);
  9433.  
  9434. Description: Read or Set a file's attributes. Fd is an assigned file. Cmd speciefies what to do,
  9435.            and is one of the following:
  9436.  
  9437.            F SetFdSet the close on exec flag of Fd. (only the least siginificant bit is used).
  9438.            F GetLkReturn the flock record that prevents this process from obtaining the
  9439.                     lock, or set the l type field of the lock of there is no obstruction. Arg is a
  9440.                     pointer to a flock record.
  9441.            F SetLkSet the lock or clear it (depending on l type in the flock structure). if
  9442.                     the lock is held by another process, an error occurs.
  9443.            F GetLkwSame as for F Setlk, but wait until the lock is released.
  9444.            F SetOwnSet the Process or process group that owns a socket.
  9445.  
  9446.      Errors: LinuxError is used to report errors.
  9447.  
  9448.                                                            160
  9449.  
  9450.  
  9451.  
  9452.                                                          8.2. FUNCTIONS AND PROCEDURES
  9453.  
  9454.  
  9455.            sys ebadfFd has a bad file descriptor.
  9456.            sys eagain or sys eaccessFor F SetLk, if the lock is held by another process.
  9457.  
  9458.    See also: Fcntl (160), Fcntl (2)
  9459.  
  9460.  
  9461.            Fork
  9462. Declaration: Function Fork : Longint;
  9463.  
  9464. Description: Fork creates a child process which is a copy of the parent process. Fork returns
  9465.            the process ID in the parent process, and zero in the child's process. (you can get
  9466.            the parent's PID with GetPPid (166)).
  9467.  
  9468.      Errors: On error, -1 is returned to the parent, and no child is created.
  9469.  
  9470.            sys eagainNot enough memory to create child process.
  9471.  
  9472.    See also: Execve (151), fork (2)
  9473.  
  9474.            Program Example14 ;
  9475.  
  9476.            { Program to demonstrate the Fork and WaitPidfunction . }
  9477.  
  9478.            Uses l i n u x ;
  9479.  
  9480.            Var PID , E x i t S t a t u s : Longint ;
  9481.  
  9482.            begin
  9483.               Writeln ( ' Spawning a c h i l d ' ) ;
  9484.               PID:= Fork ;
  9485.               I f PID=0 then
  9486.                     begin
  9487.                     Writeln ( ' Hello From the Child ! ! ' ) ;
  9488.                     Writeln ( ' E x i t i n g with e x i t s t a t u s 1 ! ' ) ;
  9489.                     Halt ( 1 ) ;
  9490.                     end
  9491.               Else
  9492.                     begin
  9493.                     Writeln ( ' Spawned c h i l d with PID : ' , PID ) ;
  9494.                     WaitPid ( PID , @ExitStatus , 0 ) ;
  9495.                     Writeln ( ' Child e x i t e d with s t a t u s : ' , E x i t S t a t u s shr 8 ) ;
  9496.                     end ;
  9497.            end .
  9498.  
  9499.  
  9500.            GetDate
  9501. Declaration: Procedure GetDate (Var Year, Month, Day : Word) ;
  9502.  
  9503. Description: Returns the current day.
  9504.  
  9505.      Errors: None
  9506.  
  9507.    See also: GetEpochTime (163), GetTime (166), EpochToLocal (148)
  9508.  
  9509.  
  9510.  
  9511.                                                         161
  9512.  
  9513.  
  9514.  
  9515.                                                        8.2. FUNCTIONS AND PROCEDURES
  9516.  
  9517.  
  9518.            Program Example6 ;
  9519.  
  9520.            { Program to demonstrate the GetDate f u n c t i o n . }
  9521.  
  9522.            Uses l i n u x ;
  9523.  
  9524.            Var Year , Month , Day : Word ;
  9525.  
  9526.            begin
  9527.             GetDate ( Year , Month , Day ) ;
  9528.             Writeln ( ' Date : ' , Day : 2 , ' / ' , Month : 2 , ' / ' , Year : 4 ) ;
  9529.            end .
  9530.  
  9531.  
  9532.            GetDomainName
  9533. Declaration: Function GetDomainName : String;
  9534.  
  9535. Description: Get the domain name of the machine on which the process is running. An empty
  9536.            string is returned if the domain is not set.
  9537.  
  9538.      Errors: None.
  9539.  
  9540.    See also: GetHostName (165),seemGetdomainname2
  9541.  
  9542.            Program Example39 ;
  9543.  
  9544.            { Program to demonstrate the GetDomainName f u n c t i o n . }
  9545.  
  9546.            Uses l i n u x ;
  9547.  
  9548.            begin
  9549.               Writeln ( ' Domain name of t h i s machine i s : ' , GetDomainName ) ;
  9550.            end .
  9551.  
  9552.  
  9553.            GetEGid
  9554. Declaration: Function GetEGid : Longint;
  9555.  
  9556. Description: Get the e ective group ID of the currently running process.
  9557.  
  9558.      Errors: None.
  9559.  
  9560.    See also: GetGid (164), getegid (2)
  9561.  
  9562.            Program Example18 ;
  9563.  
  9564.            { Program to demonstrate the GetGid and GetEGid f u n c t i o n s . }
  9565.  
  9566.            Uses l i n u x ;
  9567.  
  9568.            begin
  9569.              writeln ( ' Group Id = ' , get gid , ' E f f e c t i v e group Id = ' , g e t e g i d ) ;
  9570.            end .
  9571.  
  9572.  
  9573.  
  9574.                                                      162
  9575.  
  9576.  
  9577.  
  9578.                                                       8.2. FUNCTIONS AND PROCEDURES
  9579.  
  9580.  
  9581.            GetEUid
  9582. Declaration: Function GetEUid : Longint;
  9583.  
  9584. Description: Get the e ective user ID of the currently running process.
  9585.  
  9586.      Errors: None.
  9587.  
  9588.    See also: GetEUid (163), geteuid (2)
  9589.  
  9590.            Program Example17 ;
  9591.  
  9592.             { Program to demonstrate the GetUid and GetEUid f u n c t i o n s . }
  9593.  
  9594.            Uses l i n u x ;
  9595.  
  9596.             begin
  9597.                writeln ( ' User Id = ' , getuid , ' E f f e c t i v e user Id = ' , g e t eu i d ) ;
  9598.            end .
  9599.  
  9600.  
  9601.            GetEnv
  9602. Declaration: Function GetEnv (P : String) : PChar;
  9603.  
  9604. Description: Returns the value of the environment variable in P. If the variable is not defined,
  9605.            nil is returned. The value of the environment variable may be the empty string. A
  9606.            PChar is returned to accomodate for strings longer than 255 bytes, TERMCAP and
  9607.            LS COLORS, for instance.
  9608.  
  9609.      Errors: None.
  9610.  
  9611.    See also: sh (1) , csh (1)
  9612.  
  9613.            Program Example41 ;
  9614.  
  9615.             { Program to demonstrate the GetEnv f u n c t i o n . }
  9616.  
  9617.            Uses l i n u x ;
  9618.  
  9619.             begin
  9620.               Writeln ( ' Path i s : ' , Getenv ( ' PATH' ) ) ;
  9621.            end .
  9622.  
  9623.  
  9624.            GetEpochTime
  9625. Declaration: Function GetEpochTime : longint;
  9626.  
  9627. Description: returns the number of seconds since 00:00:00 gmt, january 1, 1970. it is adjusted
  9628.            to the local time zone, but not to DST.
  9629.  
  9630.      Errors: no errors
  9631.  
  9632.    See also: EpochToLocal (148), GetTime (166), time (2)
  9633.  
  9634.  
  9635.  
  9636.  
  9637.                                                       163
  9638.  
  9639.  
  9640.  
  9641.                                                          8.2. FUNCTIONS AND PROCEDURES
  9642.  
  9643.  
  9644.            Program Example1 ;
  9645.  
  9646.             { Program to demonstrate the GetEpochTime f u n c t i o n . }
  9647.  
  9648.            Uses l i n u x ;
  9649.  
  9650.             begin
  9651.               Write ( ' Secs past the s t a r t of the Epoch ( 0 0 : 0 0 1 / 1 / 1 9 8 0 ) : ' ) ;
  9652.               Writeln ( GetEpochTime ) ;
  9653.            end .
  9654.  
  9655.  
  9656.            GetFS
  9657. Declaration: Function GetFS (Var F : Any File Type) : Longint;
  9658. Description: GetFS returns the file selector that the kernel provided for your file. In principle
  9659.            you don' need this file selector. Only for some calls it is needed, such as the Select
  9660.            (178) call or so.
  9661.      Errors: In case the file was not opened, then -1 is returned.
  9662.    See also: Select (178)
  9663.  
  9664.            Program Example33 ;
  9665.  
  9666.             { Program to demonstrate the S e le ct T ext f u n c t i o n . }
  9667.  
  9668.            Uses l i n u x ;
  9669.  
  9670.            Var tv : TimeVal ;
  9671.  
  9672.             begin
  9673.               Writeln ( ' Press the <ENTER> to continue the program . ' ) ;
  9674.               { Wait u n t i l F i l e d e s c r i p t o r 0 (= Input ) changes }
  9675.                S e l e ct T e x t ( Input , n i l ) ;
  9676.               { Get r i d of <ENTER> in b u f f e r }
  9677.                readln ;
  9678.               Writeln ( ' Press <ENTER> key in l e s s than 2 seconds . . . ' ) ;
  9679.               tv . sec :=2;
  9680.               tv . usec :=0;
  9681.                i f S e l e c t T e x t ( Input , @tv )>0 then
  9682.                     Writeln ( ' Thank you ! ' )
  9683.                else
  9684.                     Writeln ( ' Too l a t e ! ' ) ;
  9685.            end .
  9686.  
  9687.  
  9688.            GetGid
  9689. Declaration: Function GetGid : Longint;
  9690. Description: Get the real group ID of the currently running process.
  9691.      Errors: None.
  9692.    See also: GetEGid (162), getgid (2)
  9693.  
  9694.                                                          164
  9695.  
  9696.  
  9697.  
  9698.                                                          8.2. FUNCTIONS AND PROCEDURES
  9699.  
  9700.  
  9701.            Program Example18 ;
  9702.  
  9703.            { Program to demonstrate the GetGid and GetEGid f u n c t i o n s . }
  9704.  
  9705.            Uses l i n u x ;
  9706.  
  9707.            begin
  9708.              writeln ( ' Group Id = ' , g et gi d , ' E f f e c t i v e group Id = ' , g e t e g i d ) ;
  9709.            end .
  9710.  
  9711.  
  9712.            GetHostName
  9713. Declaration: Function GetHostName : String;
  9714.  
  9715. Description: Get the hostname of the machine on which the process is running. An empty
  9716.            string is returned if hostname is not set.
  9717.  
  9718.      Errors: None.
  9719.  
  9720.    See also: GetDomainName (162),seemGethostname2
  9721.  
  9722.            Program Example40 ;
  9723.  
  9724.            { Program to demonstrate the GetHostName f u n c t i o n . }
  9725.  
  9726.            Uses l i n u x ;
  9727.  
  9728.            begin
  9729.               Writeln ( ' Name of t h i s machine i s : ' , GetHostName ) ;
  9730.            end .
  9731.  
  9732.  
  9733.            GetPid
  9734. Declaration: Function GetPid : Longint;
  9735.  
  9736. Description: Get the Process ID of the currently running process.
  9737.  
  9738.      Errors: None.
  9739.  
  9740.    See also: GetPPid (166), getpid (2)
  9741.  
  9742.            Program Example16 ;
  9743.  
  9744.            { Program to demonstrate the GetPid , GetPPid f u n c t i o n . }
  9745.  
  9746.            Uses l i n u x ;
  9747.  
  9748.            begin
  9749.               Writeln ( ' Process Id = ' , getpid , ' Parent p r o c e s s Id = ' , getppid ) ;
  9750.            end .
  9751.  
  9752.  
  9753.  
  9754.  
  9755.  
  9756.                                                     165
  9757.  
  9758.  
  9759.  
  9760.                                                      8.2. FUNCTIONS AND PROCEDURES
  9761.  
  9762.  
  9763.            GetPPid
  9764. Declaration: Function GetPPid : Longint;
  9765.  
  9766. Description: Get the Process ID of the parent process.
  9767.  
  9768.      Errors: None.
  9769.  
  9770.    See also: GetPid (165), getppid (2)
  9771.  
  9772.            Program Example16 ;
  9773.  
  9774.            { Program to demonstrate the GetPid , GetPPid f u n c t i o n . }
  9775.  
  9776.            Uses l i n u x ;
  9777.  
  9778.            begin
  9779.               Writeln ( ' Process Id = ' , getpid , ' Parent p r o c e s s Id = ' , getppid ) ;
  9780.            end .
  9781.  
  9782.  
  9783.            GetPriority
  9784. Declaration: Function GetPriority (Which,Who : Integer) : Integer;
  9785.  
  9786. Description: GetPriority returns the priority with which a process is running. Which process(es)
  9787.            is determined by the Which and Who variables. Which can be one of the pre-defined
  9788.            Prio Process, Prio PGrp, Prio User, in which case Who is the process ID,
  9789.            Process group ID or User ID, respectively.
  9790.  
  9791.      Errors: Error checking must be done on LinuxError, since a priority can be negative.
  9792.  
  9793.            sys esrchNo process found using which and who.
  9794.            sys einvalWhich was not one of Prio Process, Prio Grp or Prio User.
  9795.  
  9796.    See also: SetPriority (180), Nice (175), Getpriority (2)
  9797.  
  9798.            For an example, see Nice (175).
  9799.  
  9800.  
  9801.            GetTime
  9802. Declaration: Procedure GetTime (Var Hour,Minute, Second : Word) ;
  9803.  
  9804. Description: Returns the current time of the day.
  9805.  
  9806.      Errors: None
  9807.  
  9808.    See also: GetEpochTime (163), GetDate (161), EpochToLocal (148)
  9809.  
  9810.            Program Example5 ;
  9811.  
  9812.            { Program to demonstrate the GetTime f u n c t i o n . }
  9813.  
  9814.            Uses l i n u x ;
  9815.  
  9816.            Var Hour , Minute , Second : Word ;
  9817.  
  9818.  
  9819.                                                      166
  9820.  
  9821.  
  9822.  
  9823.                                                           8.2. FUNCTIONS AND PROCEDURES
  9824.  
  9825.  
  9826.            begin
  9827.               GetTime ( Hour , Minute , Second ) ;
  9828.               Writeln ( ' Time : ' , Hour : 2 , ' : ' , Minute : 2 , ' : ' , Second : 2 ) ;
  9829.            end .
  9830.  
  9831.  
  9832.            GetUid
  9833. Declaration: Function GetUid : Longint;
  9834.  
  9835. Description: Get the real user ID of the currently running process.
  9836.  
  9837.      Errors: None.
  9838.  
  9839.    See also: GetEUid (163), getuid (2)
  9840.  
  9841.            Program Example17 ;
  9842.  
  9843.            { Program to demonstrate the GetUid and GetEUid f u n c t i o n s . }
  9844.  
  9845.            Uses l i n u x ;
  9846.  
  9847.            begin
  9848.               writeln ( ' User Id = ' , getuid , ' E f f e c t i v e user Id = ' , g e t eu i d ) ;
  9849.            end .
  9850.  
  9851.  
  9852.            Glob
  9853. Declaration: Function Glob (Const Path : Pathstr) : PGlob;
  9854.  
  9855. Description: Glob returns a pointer to a glob structure which contains all filenames which exist
  9856.            and match the pattern in Path. The pattern can contain wildcard characters, which
  9857.            have their usual meaning.
  9858.  
  9859.      Errors: Returns nil on error, and LinuxError is set.
  9860.  
  9861.            sys enomemNo memory on heap for glob structure.
  9862.            othersAs returned by the opendir call, and sys readdir.
  9863.  
  9864.    See also: GlobFree (168), Glob (3)
  9865.  
  9866.            Program Example49 ;
  9867.  
  9868.            { Program to demonstrate the Glob and GlobFree f u n c t i o n s . }
  9869.  
  9870.            Uses l i n u x ;
  9871.  
  9872.            Var G1 , G2 : PGlob ;
  9873.  
  9874.            begin
  9875.               G1:= Glob ( '   ' ) ;
  9876.               i f L i n u x E r r o r =0 then
  9877.                     begin
  9878.                     G2:=G1 ;
  9879.                     Writeln ( ' F i l e s in t h i s d i r e c t o r y : ' ) ;
  9880.  
  9881.  
  9882.                                                          167
  9883.  
  9884.  
  9885.  
  9886.                                                         8.2. FUNCTIONS AND PROCEDURES
  9887.  
  9888.  
  9889.                     While g2<>Nil do
  9890.                       begin
  9891.                       Writeln ( g2  . name) ;
  9892.                       g2 :=g2  . next ;
  9893.                       end ;
  9894.                     GlobFree ( g1 ) ;
  9895.                     end ;
  9896.            end .
  9897.  
  9898.  
  9899.            GlobFree
  9900. Declaration: Procedure GlobFree (Var P : Pglob);
  9901.  
  9902. Description: Releases the memory, occupied by a pglob structure. P is set to nil.
  9903.  
  9904.      Errors: None
  9905.  
  9906.    See also: Glob (167)
  9907.  
  9908.            For an example, see Glob (167).
  9909.  
  9910.  
  9911.            IOCtl
  9912. Declaration: Procedure IOCtl (Handle,Ndx: Longint; Data: Pointer);
  9913.  
  9914. Description: This is a general interface to the Unix/ linux ioctl call. It performs various
  9915.            operations on the filedescriptor Handle. Ndx describes the operation to perform.
  9916.            Data points to data needed for the Ndx function. The structure of this data is
  9917.            function-dependent, so we don't elaborate on this here. For more information on
  9918.            this, see various manual pages under linux.
  9919.  
  9920.      Errors: Errors are reported in LinuxError. They are very dependent on the used function,
  9921.            that's why we don't list them here
  9922.  
  9923.    See also: ioctl (2)
  9924.  
  9925.            Program Example54 ;
  9926.  
  9927.            uses Linux ;
  9928.  
  9929.            { Program to demonstrate the IOCtl f u n c t i o n . }
  9930.  
  9931.            vartios : Termios ;
  9932.            begin
  9933.               IOCtl (1, TCGETS, @tios ) ;
  9934.               WriteLn ( ' Input Flags         : $ ' , h e x s t r ( t i o s . c i f l a g , 8 ) ) ;
  9935.               WriteLn ( ' Output Flags : $ ' , h e x s t r ( t i o s . c oflag , 8 ) ) ;
  9936.               WriteLn ( ' Line Flags          : $ ' , h e x s t r ( t i o s . c l f l a g , 8 ) ) ;
  9937.               WriteLn ( ' Control Flags : $ ' , h e x s t r ( t i o s . c cflag , 8 ) ) ;
  9938.            end .
  9939.  
  9940.  
  9941.  
  9942.  
  9943.  
  9944.                                                       168
  9945.  
  9946.  
  9947.  
  9948.                                                      8.2. FUNCTIONS AND PROCEDURES
  9949.  
  9950.  
  9951.            IOperm
  9952. Declaration: Function IOperm (From,Num : Cadinal; Value : Longint) : boolean;
  9953.  
  9954. Description: IOperm sets permissions on Num ports starting with port From to Value. The
  9955.            function returns True if the call was successfull, False otherwise. Remark:
  9956.  
  9957.                *This works ONLY as root.
  9958.                *Only the first 0x03ff ports can be set.
  9959.                *When doing a Fork (161), the permissions are reset. When doing a Execve
  9960.                 (151) they are kept.
  9961.  
  9962.      Errors: Errors are returned in LinuxError
  9963.  
  9964.    See also: ioperm (2)
  9965.  
  9966.  
  9967.            IsATTY
  9968. Declaration: Function IsATTY (var f) : Boolean;
  9969.  
  9970. Description: Check if the filehandle described by f is a terminal. f can be of type
  9971.  
  9972.                1.longint for file handles;
  9973.                2.Text for text variables such as input etc.
  9974.  
  9975.            Returns True if f is a terminal, False otherwise.
  9976.  
  9977.      Errors: No errors are reported
  9978.  
  9979.    See also: IOCtl (168),TTYName (187)
  9980.  
  9981.  
  9982.            S ISBLK
  9983. Declaration: Function S ISBLK (m:integer) : boolean;
  9984.  
  9985. Description: S ISBLK checks the file mode m to see whether the file is a block device file. If so
  9986.            it returns True.
  9987.  
  9988.      Errors: FStat (159), S ISLNK (170), S ISREG (171), S ISDIR (170), S ISCHR (169),
  9989.            S ISFIFO (170), S ISSOCK (171)
  9990.  
  9991.    See also: ISLNK.
  9992.  
  9993.  
  9994.            S ISCHR
  9995. Declaration: Function S ISCHR (m:integer) : boolean;
  9996.  
  9997. Description: S ISCHR checks the file mode m to see whether the file is a character device file.
  9998.            If so it returns True.
  9999.  
  10000.      Errors: FStat (159), S ISLNK (170), S ISREG (171), S ISDIR (170), S ISBLK (169),
  10001.            S ISFIFO (170), S ISSOCK (171)
  10002.  
  10003.    See also: ISLNK.
  10004.  
  10005.  
  10006.  
  10007.  
  10008.                                                     169
  10009.  
  10010.  
  10011.  
  10012.                                                             8.2. FUNCTIONS AND PROCEDURES
  10013.  
  10014.  
  10015.            S ISDIR
  10016. Declaration: Function S ISDIR (m:integer) : boolean;
  10017.  
  10018. Description: S ISDIR checks the file mode m to see whether the file is a directory. If so it
  10019.            returns True
  10020.  
  10021.      Errors: FStat (159), S ISLNK (170), S ISREG (171), S ISCHR (169), S ISBLK (169),
  10022.            S ISFIFO (170), S ISSOCK (171)
  10023.  
  10024.    See also: ISLNK.
  10025.  
  10026.  
  10027.            S ISFIFO
  10028. Declaration: Function S ISFIFO (m:integer) : boolean;
  10029.  
  10030. Description: S ISFIFO checks the file mode m to see whether the file is a fifo (a named pipe).
  10031.            If so it returns True.
  10032.  
  10033.      Errors: FStat (159), S ISLNK (170), S ISREG (171), S ISDIR (170), S ISCHR (169),
  10034.            S ISBLK (169), S ISSOCK (171)
  10035.  
  10036.    See also: ISLNK.
  10037.  
  10038.  
  10039.            S ISLNK
  10040. Declaration: Function S ISLNK (m:integer) : boolean;
  10041.  
  10042. Description: S ISLNK checks the file mode m to see whether the file is a symbolic link. If so it
  10043.            returns True
  10044.  
  10045.      Errors: FStat (159), S ISREG (171), S ISDIR (170), S ISCHR (169), S ISBLK (169),
  10046.            S ISFIFO (170), S ISSOCK (171)
  10047.            Program Example53 ;
  10048.  
  10049.            { Program to demonstrate the S ISLNK f u n c t i o n . }
  10050.  
  10051.            Uses l i n u x ;
  10052.  
  10053.            Var I n f o : Stat ;
  10054.  
  10055.            begin
  10056.               i f FStat ( paramstr ( 1 ) , i n f o ) then
  10057.                  begin
  10058.                  i f S ISLNK( i n f o . mode ) then
  10059.                        Writeln ( ' F i l e i s a l i n k ' ) ;
  10060.                  i f S ISREG( i n f o . mode ) then
  10061.                        Writeln ( ' F i l e i s a r e g u l a r f i l e ' ) ;
  10062.                  i f S ISDIR ( i n f o . mode ) then
  10063.                        Writeln ( ' F i l e i s a d i r e c t o r y ' ) ;
  10064.                  i f S ISCHR( i n f o . mode ) then
  10065.                        Writeln ( ' F i l e i s a c h a r a c t e r d e v i c e f i l e ' ) ;
  10066.                  i f S ISBLK( i n f o . mode ) then
  10067.                        Writeln ( ' F i l e i s a block d e v i c e f i l e ' ) ;
  10068.                  i f S ISFIFO ( i n f o . mode ) then
  10069.                        Writeln ( ' F i l e i s a named pipe ( FIFO ) ' ) ;
  10070.  
  10071.                                                            170
  10072.  
  10073.  
  10074.  
  10075.                                                            8.2. FUNCTIONS AND PROCEDURES
  10076.  
  10077.  
  10078.                          i f S ISSOCK( i n f o . mode ) then
  10079.                             Writeln ( ' F i l e i s a socket ' ) ;
  10080.                          end ;
  10081.                 end .
  10082.    See also:
  10083.  
  10084.  
  10085.            S ISREG
  10086. Declaration: Function S ISREG (m:integer) : boolean;
  10087.  
  10088. Description: S ISREG checks the file mode m to see whether the file is a regular file. If so it
  10089.            returns True
  10090.  
  10091.      Errors: FStat (159), S ISLNK (170), S ISDIR (170), S ISCHR (169), S ISBLK (169),
  10092.            S ISFIFO (170), S ISSOCK (171)
  10093.  
  10094.    See also: ISLNK.
  10095.  
  10096.  
  10097.            S ISSOCK
  10098. Declaration: Function S ISSOCK (m:integer) : boolean;
  10099.  
  10100. Description: S ISSOCK checks the file mode m to see whether the file is a socket. If so it returns
  10101.            True.
  10102.  
  10103.      Errors: FStat (159), S ISLNK (170), S ISREG (171), S ISDIR (170), S ISCHR (169),
  10104.            S ISBLK (169), S ISFIFO (170)
  10105.  
  10106.    See also: ISLNK.
  10107.  
  10108.  
  10109.            Kill
  10110. Declaration: Function Kill Pid : Longint; Sig : Integer) : Integer;
  10111.  
  10112. Description: Send a signal Sig to a process or process group. If Pid┐0 then the signal is sent
  10113.            to Pid, if it equals -1, then the signal is sent to all processes except process 1. If
  10114.            Pidí-1 then the signal is sent to process group -Pid. The return value is zero, except
  10115.            in case three, where the return value is the number of processes to which the signal
  10116.            was sent.
  10117.  
  10118.      Errors: LinuxError is used to report errors:
  10119.  
  10120.            sys einvalAn invalid signal is sent.
  10121.            sys esrchThe Pid or process group don't exist.
  10122.            sys epermThe e ective userid of the current process doesn't math the one of
  10123.                          process Pid.
  10124.  
  10125.    See also: SigAction (181), Signal (183), Kill (2)
  10126.  
  10127.  
  10128.  
  10129.  
  10130.  
  10131.  
  10132.  
  10133.                                                           171
  10134.  
  10135.  
  10136.  
  10137.                                                                  8.2. FUNCTIONS AND PROCEDURES
  10138.  
  10139.  
  10140.            LStat
  10141. Declaration: Function LStat (Path : Pathstr; Var Info : stat) : Boolean;
  10142.  
  10143. Description: LStat gets information about the link specified in Path, and stores it in Info,
  10144.            which is of type stat. Contrary to FStat, it stores information about the link, not
  10145.            about the file the link points to. The function returns True if the call was succesfull,
  10146.            False if the call failed.
  10147.  
  10148.     Errors: LinuxError is used to report errors.
  10149.  
  10150.            sys enoentPath does not exist.
  10151.  
  10152.   See also: FStat (159), FSStat (158), stat (2)
  10153.  
  10154.            program example29 ;
  10155.  
  10156.            { Program to demonstrate the LStat f u n c t i o n . }
  10157.  
  10158.            uses l i n u x ;
  10159.  
  10160.            var f : text ;
  10161.                  i : byte ;
  10162.                  i n f o : s t a t ;
  10163.  
  10164.            begin
  10165.               { Make a f i l e }
  10166.               a s s i g n ( f , ' t e s t . f i l ' ) ;
  10167.               rewrite ( f ) ;
  10168.               for i :=1 to 10 do writeln ( f , ' T e s t l i n e # ' , i ) ;
  10169.               c l o s e ( f ) ;
  10170.               { Do the c a l l on made f i l e . }
  10171.               i f not f s t a t ( ' t e s t . f i l ' , i n f o ) then
  10172.                     begin
  10173.                     writeln ( ' Fstat f a i l e d . Errno : ' , l i n u x e r r o r ) ;
  10174.                     halt ( 1 ) ;
  10175.                     end ;
  10176.               writeln ;
  10177.               writeln ( ' Result of f s t a t on f i l e ' ' t e s t . f i l ' ' . ' ) ;
  10178.               writeln ( ' Inode                 : ' , i n f o . ino ) ;
  10179.               writeln ( ' Mode                  : ' , i n f o . mode ) ;
  10180.               writeln ( ' n l i n k             : ' , i n f o . n l i n k ) ;
  10181.               writeln ( ' uid                   : ' , i n f o . uid ) ;
  10182.               writeln ( ' gid                   : ' , i n f o . gid ) ;
  10183.               writeln ( ' rdev                  : ' , i n f o . rdev ) ;
  10184.               writeln ( ' Size                  : ' , i n f o . s i z e ) ;
  10185.               writeln ( ' B l k s i z e : ' , i n f o . b l k s z e ) ;
  10186.               writeln ( ' Blocks                : ' , i n f o . blocks ) ;
  10187.               writeln ( ' atime                 : ' , i n f o . atime ) ;
  10188.               writeln ( ' mtime                 : ' , i n f o . mtime ) ;
  10189.               writeln ( ' ctime                 : ' , i n f o . ctime ) ;
  10190.  
  10191.               I f not SymLink ( ' t e s t . f i l ' , ' t e s t . lnk ' ) then
  10192.                  writeln ( ' Link f a i l e d ! Errno : ' , l i n u x e r r o r ) ;
  10193.  
  10194.               i f not l s t a t ( ' t e s t . lnk ' , i n f o ) then
  10195.  
  10196.                                                                 172
  10197.  
  10198.  
  10199.  
  10200.                                                                8.2. FUNCTIONS AND PROCEDURES
  10201.  
  10202.  
  10203.                       begin
  10204.                       writeln ( ' LStat f a i l e d . Errno : ' , l i n u x e r r o r ) ;
  10205.                       halt ( 1 ) ;
  10206.                       end ;
  10207.               writeln ;
  10208.               writeln ( ' Result of f s t a t on f i l e ' ' t e s t . lnk ' ' . ' ) ;
  10209.               writeln ( ' Inode               : ' , i n f o . ino ) ;
  10210.               writeln ( ' Mode                : ' , i n f o . mode ) ;
  10211.               writeln ( ' n l i n k           : ' , i n f o . n l i n k ) ;
  10212.               writeln ( ' uid                 : ' , i n f o . uid ) ;
  10213.               writeln ( ' gid                 : ' , i n f o . gid ) ;
  10214.               writeln ( ' rdev                : ' , i n f o . rdev ) ;
  10215.               writeln ( ' Size                : ' , i n f o . s i z e ) ;
  10216.               writeln ( ' B l k s i z e : ' , i n f o . b l k s z e ) ;
  10217.               writeln ( ' Blocks              : ' , i n f o . blocks ) ;
  10218.               writeln ( ' atime               : ' , i n f o . atime ) ;
  10219.               writeln ( ' mtime               : ' , i n f o . mtime ) ;
  10220.               writeln ( ' ctime               : ' , i n f o . ctime ) ;
  10221.               { Remove f i l e and l i n k }
  10222.               erase ( f ) ;
  10223.               u n l i n k ( ' t e s t . lnk ' ) ;
  10224.            end .
  10225.  
  10226.  
  10227.            Link
  10228. Declaration: Function Link (OldPath,NewPath : pathstr) : Boolean;
  10229.  
  10230. Description: Link makes NewPath point to the same file als OldPath. The two files then have
  10231.            the same inode number. This is known as a 'hard' link. The function returns True
  10232.            if the call was succesfull, False if the call failed.
  10233.  
  10234.     Errors: Errors are returned in LinuxError.
  10235.  
  10236.            sys exdevOldPath and NewPath are not on the same filesystem.
  10237.            sys epermThe filesystem containing oldpath and newpath doesn't support linking
  10238.                     files.
  10239.            sys eaccessWrite access for the directory containing Newpath is disallowed, or one
  10240.                     of the directories in OldPath or NewPath has no search (=execute) permission.
  10241.            sys enoentA directory entry in OldPath or NewPath does not exist or is a symbolic
  10242.                     link pointing to a non-existent directory.
  10243.            sys enotdirA directory entry in OldPath or NewPath is nor a directory.
  10244.            sys enomemInsu cient kernel memory.
  10245.            sys erofsThe files are on a read-only filesystem.
  10246.            sys eexistNewPath already exists.
  10247.            sys emlinkOldPath has reached maximal link count.
  10248.            sys eloopOldPath or NewPath has a reference to a circular symbolic link, i.e. a
  10249.                     symbolic link, whose expansion points to itself.
  10250.            sys enospcThe device containing NewPath has no room for anothe entry.
  10251.            sys epermOldPath points to . or .. of a directory.
  10252.  
  10253.   See also: SymLink (184), UnLink (188), Link (2)
  10254.  
  10255.                                                               173
  10256.  
  10257.  
  10258.  
  10259.                                                         8.2. FUNCTIONS AND PROCEDURES
  10260.  
  10261.  
  10262.           Program Example21 ;
  10263.  
  10264.           { Program to demonstrate the Link and UnLink f u n c t i o n s . }
  10265.  
  10266.           Uses l i n u x ;
  10267.  
  10268.           Var F : Text ;
  10269.                    S : String ;
  10270.           begin
  10271.              Assign ( F, ' t e s t . txt ' ) ;
  10272.              Rewrite ( F ) ;
  10273.              Writeln ( F, ' This i s w r i t t e n to t e s t . txt ' ) ;
  10274.              Close ( f ) ;
  10275.              { new . txt and t e s t . txt are now the same f i l e }
  10276.              i f not Link ( ' t e s t . txt ' , ' new . txt ' ) then
  10277.                    writeln ( ' Error when l i n k i n g ! ' ) ;
  10278.              { Removing t e s t . txt s t i l l l e a v e s new . txt }
  10279.              I f not Unlink ( ' t e s t . txt ' ) then
  10280.                    Writeln ( ' Error when u n l i n k i n g ! ' ) ;
  10281.              Assign ( f , ' new . txt ' ) ;
  10282.              Reset ( F ) ;
  10283.              While not EOF( f ) do
  10284.                    begin
  10285.                    Readln ( F, S ) ;
  10286.                    Writeln ( '> ' , s ) ;
  10287.                    end ;
  10288.             Close ( f ) ;
  10289.             { Remove new . txt a l s o }
  10290.             I f not Unlink ( ' new . txt ' ) then
  10291.               Writeln ( ' Error when u n l i n k i n g ! ' ) ;
  10292.           end .
  10293.  
  10294.  
  10295.           LocalToEpoch
  10296. Declaration: Function LocalToEpoch (Year,Month,Day,Hour,Minute,Second : Word) : longint;
  10297.  
  10298. Description: Converts the Local time to epoch time (=Number of seconds since 00:00:00 ,
  10299.           January 1, 1970 ).
  10300.  
  10301.     Errors: None
  10302.  
  10303.   See also: GetEpochTime (163), EpochToLocal (148), GetTime (166),GetDate (161)
  10304.  
  10305.           Program Example4 ;
  10306.  
  10307.           { Program to demonstrate the LocalToEpoch f u n c t i o n . }
  10308.  
  10309.           Uses l i n u x ;
  10310.  
  10311.           Var year , month , day , hour , minute , second : Word ;
  10312.  
  10313.           begin
  10314.              Write ( ' Year             : ' ) ; readln ( Year ) ;
  10315.              Write ( ' Month            : ' ) ; readln ( Month ) ;
  10316.  
  10317.                                                        174
  10318.  
  10319.  
  10320.  
  10321.                                                                8.2. FUNCTIONS AND PROCEDURES
  10322.  
  10323.  
  10324.               Write ( ' Day                : ' ) ; readln ( Day ) ;
  10325.               Write ( ' Hour               : ' ) ; readln ( Hour ) ;
  10326.               Write ( ' Minute             : ' ) ; readln ( Minute ) ;
  10327.               Write ( ' Seonds             : ' ) ; readln ( Second ) ;
  10328.               Write ( ' This i s : ' ) ;
  10329.               Write ( LocalToEpoch ( year , month , day , hour , minute , second ) ) ;
  10330.               Writeln ( ' seconds past 00:00 1/1/1980' ) ;
  10331.            end .
  10332.  
  10333.  
  10334.            MkFifo
  10335. Declaration: Function MkFifo (PathName: String; Mode : Longint) : Boolean;
  10336.  
  10337. Description: MkFifo creates named a named pipe in the filesystem, with name PathName and
  10338.            mode Mode.
  10339.  
  10340.      Errors: LinuxError is used to report errors:
  10341.  
  10342.            sys emfileToo many file descriptors for this process.
  10343.            sys enfileThe system file table is full.
  10344.  
  10345.    See also: POpen (177), MkFifo (175), mkfifo (4)
  10346.  
  10347.  
  10348.            Nice
  10349. Declaration: Procedure Nice ( N : Integer);
  10350.  
  10351. Description: Nice adds -N to the priority of the running process. The lower the priority numer-
  10352.            ically, the less the process is favored. Only the superuser can specify a negative N,
  10353.            i.e. increase the rate at which the process is run.
  10354.  
  10355.      Errors: Errors are returned in LinuxError
  10356.  
  10357.            sys epermA non-superuser tried to specify a negative N, i.e. do a priority increase.
  10358.  
  10359.    See also: GetPriority (166), SetPriority (180), Nice (2)
  10360.  
  10361.            Program Example15 ;
  10362.  
  10363.             { Program to demonstrate the Nice and Get / S e t P r i o r i t y f u n c t i o n s . }
  10364.  
  10365.            Uses l i n u x ;
  10366.  
  10367.             begin
  10368.                writeln ( ' S e t t i n g p r i o r i t y to 5' ) ;
  10369.                s e t p r i o r i t y ( p r i o p r o c e s s , getpid , 5 ) ;
  10370.                writeln ( ' New p r i o r i t y = ' , g e t p r i o r i t y ( p r i o p r o c e s s , getpid ) ) ;
  10371.                writeln ( ' Doing nice 10' ) ;
  10372.                nice ( 1 0 ) ;
  10373.                writeln ( ' New P r i o r i t y = ' , g e t p r i o r i t y ( p r i o p r o c e s s , getpid ) ) ;
  10374.            end .
  10375.  
  10376.  
  10377.  
  10378.  
  10379.  
  10380.                                                              175
  10381.  
  10382.  
  10383.  
  10384.                                                             8.2. FUNCTIONS AND PROCEDURES
  10385.  
  10386.  
  10387.            OpenDir
  10388. Declaration: Function OpenDir (f:pchar) : pdir;
  10389.  
  10390. Description: OpenDir opens the directory f, and returns a pdir pointer to a Dir record, which
  10391.            can be used to read the directory structure. If the directory cannot be opened, nil
  10392.            is returned.
  10393.  
  10394.      Errors: Errors are returned in LinuxError.
  10395.  
  10396.    See also: CloseDir (146), ReadDir (178), SeekDir (178), TellDir (188), opendir (3)
  10397.  
  10398.            Program Example35 ;
  10399.  
  10400.            { Program to demonstrate the
  10401.               OpenDir , ReadDir , SeekDir and T e l l D i r f u n c t i o n s . }
  10402.  
  10403.            Uses l i n u x ;
  10404.  
  10405.            Var TheDir : PDir ;
  10406.                  ADirent : PDirent ;
  10407.                  Entry : Longint ;
  10408.  
  10409.            begin
  10410.               TheDir := OpenDir ( ' . / . ' ) ;
  10411.               Repeat
  10412.                  Entry := T e l l D i r ( TheDir ) ;
  10413.                  ADirent := ReadDir ( TheDir ) ;
  10414.                  I f ADirent<>Nil then
  10415.                     With ADirent   do
  10416.                           begin
  10417.                           Writeln ( ' Entry No : ' , Entry ) ;
  10418.                           Writeln ( ' Inode             : ' , ino ) ;
  10419.                           Writeln ( ' O f f s e t       : ' , o f f ) ;
  10420.                           Writeln ( ' Reclen            : ' , r e c l e n ) ;
  10421.                           Writeln ( ' Name              : ' , pchar ( @name [ 0 ] ) ) ;
  10422.                           end ;
  10423.               Until ADirent =Nil ;
  10424.               Repeat
  10425.                  Write ( ' Entry No. you would l i k e to see again (-1 to stop ) : ' ) ;
  10426.                  ReadLn ( Entry ) ;
  10427.                  I f Entry <>-1 then
  10428.                     begin
  10429.                     SeekDir ( TheDir , Entry ) ;
  10430.                     ADirent := ReadDir ( TheDir ) ;
  10431.                     I f ADirent<>Nil then
  10432.                           With ADirent   do
  10433.                             begin
  10434.                             Writeln ( ' Entry No : ' , Entry ) ;
  10435.                             Writeln ( ' Inode              : ' , ino ) ;
  10436.                             Writeln ( ' O f f s e t        : ' , o f f ) ;
  10437.                             Writeln ( ' Reclen             : ' , r e c l e n ) ;
  10438.                             Writeln ( ' Name               : ' , pchar ( @name [ 0 ] ) ) ;
  10439.                             end ;
  10440.                  end ;
  10441.  
  10442.  
  10443.                                                           176
  10444.  
  10445.  
  10446.  
  10447.                                                        8.2. FUNCTIONS AND PROCEDURES
  10448.  
  10449.  
  10450.               Until Entry =-1;
  10451.               Cl oseDir ( TheDir ) ;
  10452.            end .
  10453.  
  10454.  
  10455.            PClose
  10456. Declaration: Function PClose (Var F : FileType) : longint;
  10457.  
  10458. Description: PClose closes a file opened with POpen. It waits for the command to complete,
  10459.            and then returns the exit status of the command.
  10460.  
  10461.      Errors: LinuxError is used to report errors. If it is di erent from zero, the exit status is
  10462.            not valid.
  10463.  
  10464.    See also: POpen (177)
  10465.  
  10466.            For an example, see POpen (177)
  10467.  
  10468.  
  10469.            POpen
  10470. Declaration: Procedure POpen (Var F : FileType; Cmd : pathstr; rw : char);
  10471.  
  10472. Description: Popen runs the command specified in Cmd, and redirects the standard in or output
  10473.            of the command to the other end of the pipe F. The parameter rw indicates the
  10474.            direction of the pipe. If it is set to 'W', then F can be used to write data, which will
  10475.            then be read by the command from stdinput. If it is set to 'R', then the standard
  10476.            output of the command can be read from F. F should be reset or rewritten prior to
  10477.            using it. F can be of type Text or File. A file opened with POpen can be closed
  10478.            with Close, but also with PClose (177). The result is the same, but PClose returns
  10479.            the exit status of the command Cmd.
  10480.  
  10481.      Errors: Errors are reported in LinuxError and are essentially those of the Execve, Dup
  10482.            and AssignPipe commands.
  10483.  
  10484.    See also: AssignPipe (140), popen (3) , PClose (177)
  10485.  
  10486.            Program Example37 ;
  10487.  
  10488.            { Program to demonstrate the Popen f u n c t i o n . }
  10489.  
  10490.            uses l i n u x ;
  10491.  
  10492.            var f : text ;
  10493.                     i : l o n g i n t ;
  10494.  
  10495.            begin
  10496.               writeln ( ' Creating a s h e l l s c r i p t to which echoes i t s arguments ' ) ;
  10497.               writeln ( ' and input back to stdout ' ) ;
  10498.               a s s i g n ( f , ' t es t 21 a ' ) ;
  10499.               rewrite ( f ) ;
  10500.               writeln ( f , '#!/ bin / sh ' ) ;
  10501.               writeln ( f , ' echo t h i s i s the c h i l d speaking . . . . ' ) ;
  10502.               writeln ( f , ' echo got arguments \ " $  "\ ' ) ;
  10503.               writeln ( f , ' cat ' ) ;
  10504.  
  10505.  
  10506.                                                        177
  10507.  
  10508.  
  10509.  
  10510.                                                           8.2. FUNCTIONS AND PROCEDURES
  10511.  
  10512.  
  10513.                writeln ( f , ' e x i t 2' ) ;
  10514.                writeln ( f ) ;
  10515.                c l o s e ( f ) ;
  10516.               chmod ( ' tes t2 1 a ' , o c t a l ( 7 5 5 ) ) ;
  10517.               popen ( f , ' . / t es t2 1 a arg1 arg2 ' , 'W' ) ;
  10518.                i f l i n u x e r r o r <>0 then
  10519.                      writeln ( ' e r r o r from POpen : L i n u x e r r o r : ' , L i n u x e r r o r ) ;
  10520.               for i :=1 to 10 do
  10521.                     writeln ( f , ' This i s w r i t t e n to the pipe , and should appear on stdout . ' ) ;
  10522.               Flush ( f ) ;
  10523.               Writeln ( ' The s c r i p t e x i t e d with s t a t u s : ' , PClose ( f ) ) ;
  10524.                writeln ;
  10525.                writeln ( ' Press <r e t u r n > to remove s h e l l s c r i p t . ' ) ;
  10526.               readln ;
  10527.                a s s i g n ( f , ' t es t 2 1 a ' ) ;
  10528.               erase ( f )
  10529.            end .
  10530.  
  10531.  
  10532.            ReadDir
  10533. Declaration: Function ReadDir (p:pdir) : pdirent;
  10534.  
  10535. Description: ReadDir reads the next entry in the directory pointed to by p. It returns a pdirent
  10536.            pointer to a structure describing the entry. If the next entry can't be read, Nil is
  10537.            returned.
  10538.  
  10539.      Errors: Errors are returned in LinuxError.
  10540.  
  10541.    See also: CloseDir (146), OpenDir (176), SeekDir (178), TellDir (188), readdir (3)
  10542.  
  10543.            For an example, see OpenDir (176).
  10544.  
  10545.  
  10546.            SeekDir
  10547. Declaration: Procedure SeekDir (p:pdir;off:longint);
  10548.  
  10549. Description: SeekDir sets the directory pointer to the off-th entry in the directory structure
  10550.            pointed to by p.
  10551.  
  10552.      Errors: Errors are returned in LinuxError.
  10553.  
  10554.    See also: CloseDir (146), ReadDir (178), OpenDir (176), TellDir (188), seekdir (3)
  10555.  
  10556.            For an example, see OpenDir (176).
  10557.  
  10558.  
  10559.            Select
  10560. Declaration: Function Select (N : Longint;
  10561.            var readfds,writefds,exceptfds : PFDset; Var Timeout) : Longint;
  10562.  
  10563. Description: Select checks one of the file descriptors in the FDSets to see if its status changed.
  10564.            readfds, writefds and exceptfds are pointers to arrays of 256 bits. If you want
  10565.            a file descriptor to be checked, you set the corresponding element in the array to 1.
  10566.            The other elements in the array must be set to zero. Three arrays are passed : The
  10567.  
  10568.  
  10569.                                                          178
  10570.  
  10571.  
  10572.  
  10573.                                                                8.2. FUNCTIONS AND PROCEDURES
  10574.  
  10575.  
  10576.        entries in readfds are checked to see if characters become available for reading.
  10577.        The entries in writefds are checked to see if it is OK to write to them, while
  10578.        entries in exceptfds are cheked to see if an exception occorred on them. You can
  10579.        use the functions FD ZERO (153), FD Clr (153), FD Set (154), FD IsSet (153)
  10580.        to manipulate the individual elements of a set. The pointers can be nil. N is the
  10581.        largest index of a nonzero entry plus 1. (= the largest file-descriptor + 1). TimeOut
  10582.        can be used to set a time limit. If TimeOut can be two types :
  10583.  
  10584.           1.TimeOut is of type PTime and contains a zero time, the call returns immediately.
  10585.                 If TimeOut is Nil, the kernel will wait forever, or until a status changed.
  10586.           2.TimeOut is of type Longint. If it is -1, this has the same e ect as a Timeout of
  10587.                 type PTime which is Nil. Otherwise, TimeOut contains a time in milliseconds.
  10588.  
  10589.        When the TimeOut is reached, or one of the file descriptors has changed, the Select
  10590.        call returns. On return, it will have modified the entries in the array which have
  10591.        actually changed, and it returns the number of entries that have been changed. If
  10592.        the timout was reached, and no decsriptor changed, zero is returned; The arrays of
  10593.        indexes are undefined after that. On error, -1 is returned.
  10594.  
  10595.  Errors: On error, the function returns -1, and Errors are reported in LinuxError :
  10596.  
  10597.        SYS EBADF An invalid descriptot was specified in one of the sets.
  10598.        SYS EINTR A non blocked signal was caught.
  10599.        SYS EINVAL N is negative or too big.
  10600.        SYS ENOMEM Select was unable to allocate memory for its internal tables.
  10601.  
  10602. See also: SelectText (180), GetFS (164), FD ZERO (153), FD Clr (153), FD Set (154),
  10603.        FD IsSet (153)
  10604.  
  10605.        Program Example33 ;
  10606.  
  10607.        { Program to demonstrate the S e l e c t f u n c t i o n . }
  10608.  
  10609.        Uses l i n u x ;
  10610.  
  10611.        Var FDS : FDSet ;
  10612.  
  10613.        begin
  10614.           FD Zero ( FDS) ;
  10615.           FD Set ( 0 , FDS) ;
  10616.           Writeln ( ' Press the <ENTER> to continue the program . ' ) ;
  10617.           { Wait u n t i l F i l e d e s c r i p t o r 0 (= Input ) changes }
  10618.           S e l e c t ( 1 , @FDS, n i l , n i l , n i l ) ;
  10619.           { Get r i d of <ENTER> in b u f f e r }
  10620.           readln ;
  10621.           Writeln ( ' Press <ENTER> key in l e s s than 2 seconds . . . ' ) ;
  10622.           FD Zero ( FDS) ;
  10623.           FD Set ( 0 , FDS) ;
  10624.           i f S e l e c t ( 1 , @FDS, n i l , n i l ,2000)>0 then
  10625.                 Writeln ( ' Thank you ! ' )
  10626.                 { FD ISSET (0, FDS) would be true here . }
  10627.           else
  10628.                 Writeln ( ' Too l a t e ! ' ) ;
  10629.        end .
  10630.  
  10631.  
  10632.                                                          179
  10633.  
  10634.  
  10635.  
  10636.                                                      8.2. FUNCTIONS AND PROCEDURES
  10637.  
  10638.  
  10639.            SelectText
  10640. Declaration: Function SelectText ( var T : Text; TimeOut :PTime) : Longint;
  10641.  
  10642. Description: SelectText executes the Select (178) call on a file of type Text. You can specify a
  10643.            timeout in TimeOut. The SelectText call determines itself whether it should check
  10644.            for read or write, depending on how the file was opened : With Reset it is checked
  10645.            for reading, with Rewrite and Append it is checked for writing.
  10646.  
  10647.      Errors: See Select (178). SYS EBADF can also mean that the file wasn't opened.
  10648.  
  10649.    See also: Select (178), GetFS (164)
  10650.  
  10651.  
  10652.            SetPriority
  10653. Declaration: Function SetPriority (Which,Who,Prio : Integer) : Integer;
  10654.  
  10655. Description: SetPriority sets the priority with which a process is running. Which process(es)
  10656.            is determined by the Which and Who variables. Which can be one of the pre-defined
  10657.            Prio Process, Prio PGrp, Prio User, in which case Who is the process ID,
  10658.            Process group ID or User ID, respectively. Prio is a value in the range -20 to 20.
  10659.  
  10660.      Errors: Error checking must be done on LinuxError, since a priority can be negative.
  10661.  
  10662.            sys esrchNo process found using which and who.
  10663.            sys einvalWhich was not one of Prio Process, Prio Grp or Prio User.
  10664.            sys epermA process was found, but neither its e ective or real user ID match the
  10665.                 e ective user ID of the caller.
  10666.            sys eaccesA non-superuser tried to a priority increase.
  10667.  
  10668.    See also: GetPriority (166), Nice (175), Setpriority (2)
  10669.  
  10670.            For an example, see Nice (175).
  10671.  
  10672.  
  10673.            Shell
  10674. Declaration: Function Shell (Command : String) : Longint;
  10675.  
  10676. Description: Shell invokes the bash shell (/bin/sh), and feeds it the command Command (using
  10677.            the -c option). The function then waits for the command to complete, and then
  10678.            returns the exit status of the command, or 127 if it could not complete the Fork
  10679.            (161) or Execve (151) calls.
  10680.  
  10681.      Errors: Errors are reported in LinuxError.
  10682.  
  10683.    See also: POpen (177), Fork (161), Execve (151), system (3)
  10684.  
  10685.            program example56 ;
  10686.  
  10687.            uses l i n u x ;
  10688.  
  10689.            { Program to demonstrate the S h e l l f u n c t i o n }
  10690.  
  10691.            Var S : Longint ;
  10692.  
  10693.            begin
  10694.  
  10695.                                                     180
  10696.  
  10697.  
  10698.  
  10699.                                                               8.2. FUNCTIONS AND PROCEDURES
  10700.  
  10701.  
  10702.                 Writeln ( ' Output of l s -l  . pp ' ) ;
  10703.                 S:= S h e l l ( ' l s -l  . pp ' ) ;
  10704.                 Writeln ( ' Command e x i t e d wwith s t a t u s : ' , S ) ;
  10705.            end .
  10706.  
  10707.  
  10708.            SigAction
  10709. Declaration: Procedure SigAction (Signum : Integer; Var Act,OldAct : PSigActionRec);
  10710.  
  10711. Description: Changes the action to take upon receipt of a signal. Act and Oldact are pointers
  10712.            to a SigActionRec record. SigNum specifies the signal, and can be any signal except
  10713.            SIGKILL or SIGSTOP. If Act is non-nil, then the new action for signal SigNum
  10714.            is taken from it. If OldAct is non-nil, the old action is stored there. Sa Handler
  10715.            may be SIG DFL for the default action or SIG IGN to ignore the signal. Sa Mask
  10716.            Specifies which signals should be ignord during the execution of the signal handler.
  10717.            Sa Flags Speciefies a series of flags which modify the behaviour of the signal
  10718.            handler. You can 'or' none or more of the following :
  10719.  
  10720.            SA NOCLDSTOPIf signum is SIGCHLD do not receive notification when child
  10721.                     processes stop.
  10722.            SA ONESHOT or SA RESETHANDRestore the signal action to the default
  10723.                     state once the signal handler has been called.
  10724.            SA RESTARTFor compatibility with BSD signals.
  10725.            SA NOMASK or SA NODEFERDo not prevent the signal from being re-
  10726.                     ceived from within its own signal handler.
  10727.  
  10728.      Errors: LinuxError is used to report errors.
  10729.  
  10730.            sys einvalan invalid signal was specified, or it was SIGKILL or SIGSTOP.
  10731.            sys efaultAct,OldAct point outside this process address space
  10732.            sys eintrSystem call was interrupted.
  10733.  
  10734.    See also: SigProcMask (182), SigPending (182), SigSuspend (183), Kill (171), Sigaction (2)
  10735.  
  10736.            Program example57 ;
  10737.  
  10738.            { Program to demonstrate the SigAction f u n c t i o n .}
  10739.  
  10740.            {do a kill -USR1 pid from another terminal to see what happens .
  10741.            r e p l a c e pid with the r e a l pid of t h i s program .
  10742.            You can get t h i s pid by running ' ps ' .
  10743.            }
  10744.  
  10745.            uses Linux ;
  10746.  
  10747.            Varoa, na : PSigActionRec ;
  10748.            Procedure DoSig ( s i g : Longint ) ; cdecl ;
  10749.  
  10750.            begin
  10751.                  writeln ( ' R e c e i v i n g s i g n a l : ' , s i g ) ;
  10752.  
  10753.                                                             181
  10754.  
  10755.  
  10756.  
  10757.                                                               8.2. FUNCTIONS AND PROCEDURES
  10758.  
  10759.  
  10760.            end ;
  10761.  
  10762.            begin
  10763.                new( na ) ;
  10764.                new( oa ) ;
  10765.                na  . Sa Handler :=@DoSig ;
  10766.                na  . Sa Mask :=0;
  10767.                na  . Sa Flags :=0;
  10768.                na  . Sa Restorer := Nil ;
  10769.                SigAction ( SigUsr1 , na , oa ) ;
  10770.                i f L i n u x E r r o r <>0 then
  10771.                       begin
  10772.                       writeln ( ' Error : ' , l i n u x e r r o r , ' . ' ) ;
  10773.                       halt ( 1 ) ;
  10774.                       end ;
  10775.                Writeln ( ' Send USR1 s i g n a l or p r e s s <ENTER> to e x i t ' ) ;
  10776.                readln ;
  10777.            end .
  10778.  
  10779.  
  10780.            SigPending
  10781. Declaration: Function SigPending : SigSet;
  10782.  
  10783. Description: Sigpending allows the examination of pending signals (which have been raised
  10784.            while blocked.) The signal mask of pending signals is returned.
  10785.  
  10786.      Errors: None
  10787.  
  10788.    See also: SigAction (181), SigProcMask (182), SigSuspend (183), Signal (183), Kill (171),
  10789.            Sigpending (2)
  10790.  
  10791.  
  10792.            SigProcMask
  10793. Declaration: Procedure SigProcMask (How : Integer; SSet,OldSSet : PSigSet);
  10794.  
  10795. Description: Changes the list of currently blocked signals. The behaviour of the call depends
  10796.            on How :
  10797.  
  10798.            SIG BLOCKThe set of blocked signals is the union of the current set and the
  10799.                     SSet argument.
  10800.            SIG UNBLOCKThe signals in SSet are removed from the set of currently blocked
  10801.                     signals.
  10802.            SIG SETMASKThe list of blocked signals is set so SSet.
  10803.  
  10804.            If OldSSet is non-nil, then the old set is stored in it.
  10805.  
  10806.      Errors: LinuxError is used to report errors.
  10807.  
  10808.            sys efaultSSet or OldSSet point to an adress outside the range of the process.
  10809.            sys eintrSystem call was interrupted.
  10810.  
  10811.    See also: SigAction (181), SigPending (182), SigSuspend (183), Kill (171), Sigprocmask (2)
  10812.  
  10813.  
  10814.  
  10815.  
  10816.                                                              182
  10817.  
  10818.  
  10819.  
  10820.                                                              8.2. FUNCTIONS AND PROCEDURES
  10821.  
  10822.  
  10823.            SigSuspend
  10824. Declaration: Procedure SigSuspend (Mask : SigSet);
  10825.  
  10826. Description: SigSuspend temporarily replaces the signal mask for the process with the one given
  10827.            in Mask, and then suspends the process until a signal is received.
  10828.  
  10829.      Errors: None
  10830.  
  10831.    See also: SigAction (181), SigProcMask (182), SigPending (182), Signal (183), Kill (171),
  10832.            SigSuspend (2)
  10833.  
  10834.  
  10835.            Signal
  10836. Declaration: Function Signal (SigNum : Integer; Handler : SignalHandler) : SignalHandler;
  10837.  
  10838. Description: Signal installs a new signal handler for signal SigNum. This call has the same
  10839.            functionality as the SigAction call. The return value for Signal is the old signal
  10840.            handler, or nil on error.
  10841.  
  10842.      Errors: LinuxError is used to report errors :
  10843.  
  10844.            SIG ERRAn error occurred.
  10845.  
  10846.    See also: SigAction (181),Kill (171), Signal (2)
  10847.  
  10848.            Program example58 ;
  10849.  
  10850.            { Program to demonstrate the S i g n a l f u n c t i o n .}
  10851.  
  10852.            {do a kill -USR1 pid from another terminal to see what happens .
  10853.            r e p l a c e pid with the r e a l pid of t h i s program .
  10854.            You can get t h i s pid by running ' ps ' .
  10855.            }
  10856.  
  10857.            uses Linux ;
  10858.  
  10859.            Procedure DoSig ( s i g : Longint ) ; cdecl ;
  10860.  
  10861.            begin
  10862.                 writeln ( ' R e c e i v i n g s i g n a l : ' , s i g ) ;
  10863.            end ;
  10864.  
  10865.            begin
  10866.                 SigNal ( SigUsr1 , @DoSig ) ;
  10867.                 i f L i n u x E r r o r <>0 then
  10868.                      begin
  10869.                      writeln ( ' Error : ' , l i n u x e r r o r , ' . ' ) ;
  10870.                      halt ( 1 ) ;
  10871.                      end ;
  10872.                 Writeln ( ' Send USR1 s i g n a l or p r e s s <ENTER> to e x i t ' ) ;
  10873.                 readln ;
  10874.            end .
  10875.  
  10876.  
  10877.  
  10878.                                                             183
  10879.  
  10880.  
  10881.  
  10882.                                                        8.2. FUNCTIONS AND PROCEDURES
  10883.  
  10884.  
  10885.           SymLink
  10886. Declaration: Function SymLink (OldPath,NewPath : pathstr) : Boolean;
  10887.  
  10888. Description: SymLink makes Newpath point to the file in OldPath, which doesn't necessarily
  10889.           exist. The two files DO NOT have the same inode number. This is known as a
  10890.           'soft' link. The permissions of the link are irrelevant, as they are not used when
  10891.           following the link. Ownership of the file is only checked in case of removal or
  10892.           renaming of the link. The function returns True if the call was succesfull, False if
  10893.           the call failed.
  10894.  
  10895.     Errors: Errors are returned in LinuxError.
  10896.  
  10897.           sys epermThe filesystem containing oldpath and newpath doesn't support linking
  10898.                 files.
  10899.           sys eaccessWrite access for the directory containing Newpath is disallowed, or one
  10900.                 of the directories in OldPath or NewPath has no search (=execute) permission.
  10901.           sys enoentA directory entry in OldPath or NewPath does not exist or is a symbolic
  10902.                 link pointing to a non-existent directory.
  10903.           sys enotdirA directory entry in OldPath or NewPath is nor a directory.
  10904.           sys enomemInsu cient kernel memory.
  10905.           sys erofsThe files are on a read-only filesystem.
  10906.           sys eexistNewPath already exists.
  10907.           sys eloopOldPath or NewPath has a reference to a circular symbolic link, i.e. a
  10908.                 symbolic link, whose expansion points to itself.
  10909.           sys enospcThe device containing NewPath has no room for anothe entry.
  10910.  
  10911.   See also: Link (173), UnLink (188), Symlink (2)
  10912.  
  10913.           Program Example22 ;
  10914.  
  10915.            { Program to demonstrate the SymLink and UnLink f u n c t i o n s . }
  10916.  
  10917.            Uses l i n u x ;
  10918.  
  10919.           Var F : Text ;
  10920.                 S : String ;
  10921.  
  10922.            begin
  10923.               Assign ( F, ' t e s t . txt ' ) ;
  10924.               Rewrite ( F ) ;
  10925.               Writeln ( F, ' This i s w r i t t e n to t e s t . txt ' ) ;
  10926.               Close ( f ) ;
  10927.               { new . txt and t e s t . txt are now the same f i l e }
  10928.               i f not SymLink ( ' t e s t . txt ' , ' new . txt ' ) then
  10929.                  writeln ( ' Error when s y m l i n k i n g ! ' ) ;
  10930.               { Removing t e s t . txt s t i l l l e a v e s new . txt
  10931.                  Pointing now to a non-e x i s t e n t f i l e ! }
  10932.               I f not Unlink ( ' t e s t . txt ' ) then
  10933.                  Writeln ( ' Error when u n l i n k i n g ! ' ) ;
  10934.               Assign ( f , ' new . txt ' ) ;
  10935.               { This should f a i l , s i n c e the symbolic l i n k
  10936.                  p o i n t s to a non-e x i s t e n t f i l e ! }
  10937.  
  10938.                                                       184
  10939.  
  10940.  
  10941.  
  10942.                                                       8.2. FUNCTIONS AND PROCEDURES
  10943.  
  10944.  
  10945.               { $i -}
  10946.               Reset ( F ) ;
  10947.               { $i +}
  10948.                I f IOResult =0 then
  10949.                     Writeln ( ' This shouldn ' ' t happen ' ) ;
  10950.              { Now remove new . txt a l s o }
  10951.              I f not Unlink ( ' new . txt ' ) then
  10952.                 Writeln ( ' Error when u n l i n k i n g ! ' ) ;
  10953.            end .
  10954.  
  10955.  
  10956.            TCDrain
  10957. Declaration: Function TCDrain (Fd:longint) : Boolean;
  10958. Description: TCDrain waits until all data to file descriptor Fd is transmitted.
  10959.            The function returns True if the call was succesfull, False otherwise.
  10960.      Errors: Errors are reported in LinuxError
  10961.    See also: termios (2)
  10962.  
  10963.  
  10964.            TCFlow
  10965. Declaration: Function TCFlow (Fd,Act:longint) : Boolean;
  10966. Description: TCFlow suspends/resumes transmission or reception of data to or from the file
  10967.            descriptor Fd, depending on the action Act. This can be one of the following pre-
  10968.            defined values:
  10969.            TCOOFF suspend reception/transmission,
  10970.            TCOON resume reception/transmission,
  10971.            TCIOFF transmit a stop character to stop input from the terminal,
  10972.            TCION transmit start to resume input from the terminal.
  10973.            The function returns True if the call was succesfull, False otherwise.
  10974.      Errors: Errors are reported in LinuxError.
  10975.    See also: termios (2)
  10976.  
  10977.  
  10978.            TCFlush
  10979. Declaration: Function TCFlush (Fd,QSel:longint) : Boolean;
  10980. Description: TCFlush discards all data sent or received to/from file descriptor fd. QSel indicates
  10981.            which queue should be discard. It can be one of the following pre-defined values :
  10982.            TCIFLUSH input,
  10983.            TCOFLUSH output,
  10984.            TCIOFLUSH both input and output.
  10985.            The function returns True if the call was succesfull, False otherwise.
  10986.      Errors: Errors are reported in LinuxError.
  10987.    See also: termios (2)
  10988.  
  10989.  
  10990.                                                      185
  10991.  
  10992.  
  10993.  
  10994.                                                              8.2. FUNCTIONS AND PROCEDURES
  10995.  
  10996.  
  10997.            TCGetAttr
  10998. Declaration: Function TCGetAttr (fd:longint;var tios:TermIOS) : Boolean;
  10999.  
  11000. Description: TCGetAttr gets the terminal parameters from the terminal referred to by the file
  11001.            descriptor fd and returns them in a TermIOS structure tios. The function returns
  11002.            True if the call was succesfull, False otherwise.
  11003.  
  11004.      Errors: Errors are reported in LinuxError
  11005.  
  11006.    See also: TCSetAttr (187), termios (2)
  11007.  
  11008.            Program Example55 ;
  11009.  
  11010.            uses Linux ;
  11011.  
  11012.            { Program to demonstrate the TCGetAttr / TCSetAttr /CFMakeRaw f u n c t i o n s . }
  11013.  
  11014.            procedure ShowTermios ( var t i o s : Termios ) ;
  11015.            begin
  11016.               WriteLn ( ' Input Flags            : $ ' , h e x s t r ( t i o s . c i f l a g ,8)+#13);
  11017.               WriteLn ( ' Output Flags : $ ' , h e x s t r ( t i o s . c oflag , 8 ) ) ;
  11018.               WriteLn ( ' Line Flags             : $ ' , h e x s t r ( t i o s . c l f l a g , 8 ) ) ;
  11019.               WriteLn ( ' Control Flags : $ ' , h e x s t r ( t i o s . c cflag , 8 ) ) ;
  11020.            end ;
  11021.  
  11022.            varoldios ,
  11023.               t i o s : Termios ;
  11024.            begin
  11025.               WriteLn ( ' Old a t t r i b u t e s : ' ) ;
  11026.               TCGetAttr (1, t i o s ) ;
  11027.               ShowTermios ( t i o s ) ;
  11028.               o l d i o s := t i o s ;
  11029.               Writeln ( ' S e t t i n g raw t e r m i n a l mode ' ) ;
  11030.               CFMakeRaw( t i o s ) ;
  11031.               TCSetAttr (1, TCSANOW, t i o s ) ;
  11032.               WriteLn ( ' Current a t t r i b u t e s : ' ) ;
  11033.               TCGetAttr (1, t i o s ) ;
  11034.               ShowTermios ( t i o s ) ;
  11035.               TCSetAttr (1, TCSANOW, o l d i o s ) ;
  11036.            end .
  11037.  
  11038.  
  11039.            TCGetPGrp
  11040. Declaration: Function TCGetPGrp (Fd:longint;var Id:longint) : boolean;
  11041.  
  11042. Description: TCGetPGrp returns the process group ID of a foreground process group in Id The
  11043.            function returns True if the call was succesfull, False otherwise
  11044.  
  11045.      Errors: Errors are reported in LinuxError
  11046.  
  11047.    See also: termios (2)
  11048.  
  11049.  
  11050.  
  11051.  
  11052.                                                              186
  11053.  
  11054.  
  11055.  
  11056.                                                     8.2. FUNCTIONS AND PROCEDURES
  11057.  
  11058.  
  11059.            TCSendBreak
  11060. Declaration: Function TCSendBreak (Fd,Duration:longint) : Boolean;
  11061. Description: TCSendBreak Sends zero-valued bits on an asynchrone serial connection decsribed
  11062.            by file-descriptor Fd, for duration Duration. The function returns True if the action
  11063.            was performed successfully, False otherwise.
  11064.      Errors: Errors are reported in LinuxError.
  11065.    See also: termios (2)
  11066.  
  11067.  
  11068.            TCSetAttr
  11069. Declaration: Function TCSetAttr (Fd:longint;OptAct:longint;var Tios:TermIOS) : Boolean;
  11070. Description: TCSetAttr Sets the terminal parameters you specify in a TermIOS structure Tios
  11071.            for the terminal referred to by the file descriptor Fd. OptAct specifies an optional
  11072.            action when the set need to be done, this could be one of the following pre-defined
  11073.            values:
  11074.            TCSANOW set immediately.
  11075.            TCSADRAIN wait for output.
  11076.            TCSAFLUSH wait for output and discard all input not yet read.
  11077.            The function Returns True if the call was succesfull, False otherwise.
  11078.      Errors: Errors are reported in LinuxError.
  11079.    See also: TCGetAttr (186), termios (2)
  11080.  
  11081.            For an example, see TCGetAttr (186).
  11082.  
  11083.  
  11084.            TCSetPGrp
  11085. Declaration: Function TCSetPGrp (Fd,Id:longint) : boolean;
  11086. Description: TCSetPGrp Sets the Process Group Id to Id. The function returns True if the call
  11087.            was successful, False otherwise.
  11088.      Errors: Errors are returned in LinuxError.
  11089.    See also: TCGetPGrp (186), termios (2)
  11090.  
  11091.            For an example, see TCGetPGrp (186).
  11092.  
  11093.  
  11094.            TTYName
  11095. Declaration: Function TTYName (var f) : String;
  11096. Description: Returns the name of the terminal pointed to by f. f must be a terminal. f can
  11097.            be of type:
  11098.               1.longint for file handles;
  11099.               2.Text for text variables such as input etc.
  11100.      Errors: Returns an empty string in case of an error. Linuxerror may be set to indicate
  11101.            what error occurred, but this is uncertain.
  11102.    See also: IsATTY (169),IOCtl (168)
  11103.  
  11104.  
  11105.                                                    187
  11106.  
  11107.  
  11108.  
  11109.                                                         8.2. FUNCTIONS AND PROCEDURES
  11110.  
  11111.  
  11112.            TellDir
  11113. Declaration: Function TellDir (p:pdir) : longint;
  11114.  
  11115. Description: TellDir returns the current location in the directory structure pointed to by p.
  11116.            It returns -1 on failure.
  11117.  
  11118.      Errors: Errors are returned in LinuxError.
  11119.  
  11120.    See also: CloseDir (146), ReadDir (178), SeekDir (178), OpenDir (176), telldir (3)
  11121.  
  11122.            For an example, see OpenDir (176).
  11123.  
  11124.  
  11125.            Umask
  11126. Declaration: Function Umask (Mask : Integer) : Integer;
  11127.  
  11128. Description: Change the file creation mask for the current user to Mask. The current mask is
  11129.            returned.
  11130.  
  11131.      Errors: None
  11132.  
  11133.    See also: Chmod (144), Umask (2)
  11134.  
  11135.            Program Example27 ;
  11136.  
  11137.            { Program to demonstrate the Umask f u n c t i o n . }
  11138.  
  11139.            Uses l i n u x ;
  11140.  
  11141.            begin
  11142.               Writeln ( ' Old Umask was : ' , Umask( Octal ( 1 1 1 ) ) ) ;
  11143.               WRiteln ( ' New Umask i s            : ' , Octal ( 1 1 1 ) ) ;
  11144.            end .
  11145.  
  11146.  
  11147.            Uname
  11148. Declaration: Procedure Uname (var unamerec:utsname);
  11149.  
  11150. Description: Uname gets the name and configuration of the current linux kernel, and returns
  11151.            it in unamerec.
  11152.  
  11153.      Errors: LinuxError is used to report errors.
  11154.  
  11155.    See also: GetHostName (165), GetDomainName (162), uname (2)
  11156.  
  11157.  
  11158.            UnLink
  11159. Declaration: Function UnLink (Var Path) : Boolean;
  11160.  
  11161. Description: UnLink decreases the link count on file Path. Path can be of type PathStr or
  11162.            PChar. If the link count is zero, the file is removed from the disk. The function
  11163.            returns True if the call was succesfull, False if the call failed.
  11164.  
  11165.      Errors: Errors are returned in LinuxError.
  11166.  
  11167.  
  11168.  
  11169.                                                        188
  11170.  
  11171.  
  11172.  
  11173.                                                       8.2. FUNCTIONS AND PROCEDURES
  11174.  
  11175.  
  11176.            sys eaccessYou have no write access right in the directory containing Path, or
  11177.                 you have no search permission in one of the directory components of Path.
  11178.            sys epermThe directory containing pathname has the sticky-bit set and the pro-
  11179.                 cess's e ective uid is neither the uid of the file to be deleted nor that of the
  11180.                 directory containing it.
  11181.            sys enoentA component of the path doesn't exist.
  11182.            sys enotdirA directory component of the path is not a directory.
  11183.            sys eisdirPath refers to a directory.
  11184.            sys enomemInsu cient kernel memory.
  11185.            sys erofsPath is on a read-only filesystem.
  11186.  
  11187.   See also: Link (173), SymLink (184), Unlink (2)
  11188.  
  11189.            For an example, see Link (173).
  11190.  
  11191.  
  11192.            Utime
  11193. Declaration: Function Utime (path : pathstr; utim : utimbuf) : Boolean;
  11194.  
  11195. Description: Utime sets the access and modification times of a file. the utimbuf record con-
  11196.            tains 2 fields, actime, and modtime, both of type Longint. They should be filled
  11197.            with an epoch-like time, specifying, respectively, the last access time, and the last
  11198.            modification time. For some filesystem (most notably, FAT), these times are the
  11199.            same.
  11200.  
  11201.     Errors: Errors are returned in LinuxError.
  11202.  
  11203.            sys eaccessOne of the directories in Path has no search (=execute) permission.
  11204.            sys enoentA directory entry in Path does not exist or is a symbolic link pointing
  11205.                 to a non-existent directory.
  11206.  
  11207.            Other errors may occur, but aren't documented.
  11208.  
  11209.   See also: GetEpochTime (163), Chown (143), Access (139), utime (() 2)
  11210.  
  11211.            Program Example25 ;
  11212.  
  11213.            { Program to demonstrate the UTime f u n c t i o n . }
  11214.  
  11215.            Uses l i n u x ;
  11216.  
  11217.            Var utim : utimbuf ;
  11218.                     year , month , day , hour , minute , second : Word ;
  11219.  
  11220.            begin
  11221.               { Set access and m o d i f i c a t i o n time of e x e c u t a b l e source }
  11222.               GetTime ( hour , minute , second ) ;
  11223.               GetDate ( year , month , day ) ;
  11224.               utim . actime := LocalToEpoch ( year , month , day , hour , minute , second ) ;
  11225.               utim . modtime := utim . actime ;
  11226.               i f not Utime ( ' ex25 . pp ' , utim ) then
  11227.                     writeln ( ' C a l l to UTime f a i l e d ! ' )
  11228.               else
  11229.  
  11230.                                                      189
  11231.  
  11232.  
  11233.  
  11234.                                                            8.2. FUNCTIONS AND PROCEDURES
  11235.  
  11236.  
  11237.                     begin
  11238.                     Write ( ' Set access and m o d i f i c a t i o n times to : ' ) ;
  11239.                     Write ( Hour : 2 , ' : ' , minute : 2 , ' : ' , second , ' , ' ) ;
  11240.                     Writeln ( Day : 2 , ' / ' , month : 2 , ' / ' , year : 4 ) ;
  11241.                     end ;
  11242.            end .
  11243.  
  11244.  
  11245.            WaitPid
  11246. Declaration: Function WaitPid (Pid : longint; Status : pointer; Options : Integer)
  11247.            : Longint;
  11248.  
  11249. Description: WaitPid waits for a child process with process ID Pid to exit. The value of Pid
  11250.            can be one of the following:
  11251.  
  11252.            Pid í -1Causes WaitPid to wait for any child process whose process group ID equals
  11253.                     the absolute value of pid.
  11254.            Pid = -1Causes WaitPid to wait for any child process.
  11255.            Pid = 0Causes WaitPid to wait for any child process whose process group ID
  11256.                     equals the one of the calling process.
  11257.            Pid ┐ 0Causes WaitPid to wait for the child whose process ID equals the value of
  11258.                     Pid.
  11259.  
  11260.            The Options parameter can be used to specify further how WaitPid behaves:
  11261.  
  11262.            WNOHANGCauses Waitpid to return immediately if no child has exited.
  11263.            WUNTRACEDCauses WaitPid to return also for children which are stopped,
  11264.                     but whose status has not yet been reported.
  11265.  
  11266.            Upon return, it returns the exit status of the process, or -1 in case of failure.
  11267.  
  11268.     Errors: Errors are returned in LinuxError.
  11269.  
  11270.   See also: Fork (161), Execve (151), waitpid (2)
  11271.  
  11272.            for an example, see Fork (161).
  11273.  
  11274.  
  11275.  
  11276.  
  11277.  
  11278.  
  11279.  
  11280.  
  11281.  
  11282.  
  11283.  
  11284.  
  11285.  
  11286.  
  11287.  
  11288.  
  11289.  
  11290.  
  11291.                                                           190
  11292.  
  11293.  
  11294.  
  11295. Chapter 9
  11296.  
  11297. The MMX unit
  11298.  
  11299. This chapter describes the MMX unit. This unit allows you to use the MMX capabil-
  11300. ities of the Free Pascal compiler. It was written by Florian Kl¿ampfl for the I386
  11301. processor.
  11302.  
  11303.  
  11304. 9.1 Variables, Types and constants
  11305.  
  11306. The following types are defined in the MMX unit:
  11307.  
  11308. tmmxshortint = array[0..7] of shortint;
  11309. tmmxbyte = array[0..7] of byte;
  11310. tmmxword = array[0..3] of word;
  11311. tmmxinteger = array[0..3] of integer;
  11312. tmmxfixed = array[0..3] of fixed16;
  11313. tmmxlongint = array[0..1] of longint;
  11314. tmmxcardinal = array[0..1] of cardinal;
  11315. { for the AMD 3D }
  11316. tmmxsingle = array[0..1] of single;
  11317.  
  11318. And the following pointers to the above types:
  11319.  
  11320. pmmxshortint = ^tmmxshortint;
  11321. pmmxbyte = ^tmmxbyte;
  11322. pmmxword = ^tmmxword;
  11323. pmmxinteger = ^tmmxinteger;
  11324. pmmxfixed = ^tmmxfixed;
  11325. pmmxlongint = ^tmmxlongint;
  11326. pmmxcardinal = ^tmmxcardinal;
  11327. { for the AMD 3D }
  11328. pmmxsingle = ^tmmxsingle;
  11329.  
  11330. The following initialized constants allow you to determine if the computer has MMX
  11331. extensions. They are set correctly in the unit's initialization code.
  11332.  
  11333. is_mmx_cpu : boolean = false;
  11334. is_amd_3d_cpu : boolean = false;
  11335.  
  11336.  
  11337.  
  11338.                                          191
  11339.  
  11340.  
  11341.  
  11342.                                                      9.2. FUNCTIONS AND PROCEDURES
  11343.  
  11344.  
  11345.            9.2 Functions and Procedures
  11346.  
  11347.            Emms
  11348. Declaration: Procedure Emms ;
  11349.  
  11350. Description: Emms sets all floating point registers to empty. This procedure must be called after
  11351.            you have used any MMX instructions, if you want to use floating point arithmetic.
  11352.            If you just want to move floating point data around, it isn't necessary to call this
  11353.            function, the compiler doesn't use the FPU registers when moving data. Only when
  11354.            doing calculations, you should use this function.
  11355.  
  11356.      Errors: None.
  11357.  
  11358.    See also: Programmers' guide
  11359.  
  11360.   Example:: Program MMXDemo;
  11361.            uses mmx;
  11362.            vard1 : double;
  11363.                a : array[0..10000] of double;
  11364.                i : longint;
  11365.            begin
  11366.                d1:=1.0;
  11367.            {$mmx+}
  11368.                { floating point data is used, but we do _no_ arithmetic }
  11369.                for i:=0 to 10000 do
  11370.                     a[i]:=d2; { this is done with 64 bit moves }
  11371.            {$mmx-}
  11372.                emms;       { clear fpu }
  11373.                { now we can do floating point arithmetic again }
  11374.            end.
  11375.  
  11376.  
  11377.  
  11378.  
  11379.  
  11380.  
  11381.  
  11382.  
  11383.  
  11384.  
  11385.  
  11386.  
  11387.  
  11388.  
  11389.  
  11390.  
  11391.  
  11392.  
  11393.  
  11394.  
  11395.  
  11396.  
  11397.  
  11398.                                                     192
  11399.  
  11400.  
  11401.  
  11402. Chapter 10
  11403.  
  11404. The Mouse unit
  11405.  
  11406. The mouse unit provides basic Mouse handling under Dos (Go32v1 and Go32v2)
  11407. Some general remarks about the mouse unit:
  11408.  
  11409.     * The mouse driver does not know when the text screen scrolls. This results in
  11410.           unerased mouse cursors on the screen when the screen scrolls while the mouse
  11411.           cursor is visible. The solution is to hide the mouse cursor (using HideMouse)
  11412.           when you write something to the screen and to show it again afterwards (using
  11413.           ShowMouse).
  11414.     * All Functions/Procedures that return and/or accept coordinates of the mouse
  11415.           cursor, always do so in pixels and zero based (so the upper left corner of the
  11416.           screen is (0,0)). To get the (column, row) in standard text mode, divide both
  11417.           x and y by 8 (and add 1 if you want to have it 1 based).
  11418.     * The real resolution of graphic modes and the one the mouse driver uses can
  11419.           di er. For example, mode 13h (320*200 pixels) is handled by the mouse driver
  11420.           as 640*200, so you will have to multiply the X coordinates you give to the
  11421.           driver and divide the ones you get from it by 2 in that mode.
  11422.     * By default the mouse unit is compiled with the conditional define MouseCheck.
  11423.           This causes every procedure/function of the unit to check the MouseFound
  11424.           variable prior to doing anything. Of course this is not necessary, so if you are
  11425.           sure you are not calling any mouse unit procedures when no mouse is found,
  11426.           you can recompile the mouse unit without this conditional define.
  11427.     * You will notice that several procedures/functions have longint sized param-
  11428.           eters while only the lower 16 bits are used. This is because FPC is a 32 bit
  11429.           compiler and consequently 32 bit parameters result in faster code.
  11430.  
  11431.  
  11432. 10.1 Constants, types and variables
  11433.  
  11434. The following constants are defined (to be used in e.g. the GetLastButtonPress (194)
  11435. call).
  11436.  
  11437.  LButton = 1; {left button}
  11438.  RButton = 2; {right button}
  11439.  MButton = 4; {middle button}
  11440.  
  11441. The following variable exist:
  11442.  
  11443.                                              193
  11444.  
  11445.  
  11446.  
  11447.                                                             10.2. FUNCTIONS AND PROCEDURES
  11448.  
  11449.  
  11450.              MouseFound: Boolean;
  11451.  
  11452.           it is set to True or False in the unit's initialization code.
  11453.  
  11454.  
  11455.           10.2 Functions and procedures
  11456.  
  11457.           GetLastButtonPress
  11458. Declaration: Function GetLastButtonPress (Button: Longint; Var x,y:Longint) : Longint;
  11459.  
  11460. Description: GetLastButtonPress Stores the position where Button was last pressed in x and
  11461.           y and returns the number of times this button has been pressed since the last call
  11462.           to this function with Button as parameter. For Button you can use the LButton,
  11463.           RButton and MButton constants for resp. the left, right and middle button. For
  11464.           two-button mice, checking the status of the middle button seems to give and clear
  11465.           the stats of the right button.
  11466.  
  11467.     Errors: None.
  11468.  
  11469.   See also: GetLastButtonRelease (195)
  11470.  
  11471.           { example f o r GetLastButtonPress and GetLastButtonRelease }
  11472.  
  11473.            Uses Mouse , Crt ;
  11474.  
  11475.           Var x , y , times : Longint ;
  11476.                 c : Char ;
  11477.  
  11478.            Begin
  11479.              I f MouseFound Then
  11480.                 Begin
  11481.                      ClrScr ;
  11482.                      ShowMouse ;
  11483.                      Writeln ( ' Move the mouse and c l i c k the buttons ( p r e s s escape to quit ) . ' ) ;
  11484.                      Writeln ( ' Press the L-key to see the s t a t s f o r the l e f t button . ' ) ;
  11485.                      Writeln ( ' Press the R-key to see the s t a t s f o r the r i g h t button . ' ) ;
  11486.                      Writeln ( ' Press the M-key to see the s t a t s f o r the middle button . ' ) ;
  11487.                      GotoXY( 1 , 1 9 ) ;
  11488.                      Write ( ' Since the l a s t c a l l to GetLastButtonPress with t h i s button as parameter , the ' ) ;
  11489.                      GotoXY( 1 , 2 2 ) ;
  11490.                      Write ( ' Since the l a s t c a l l to GetLastButtonRelease with t h i s button as parameter , the ' ) ;
  11491.                      Repeat
  11492.                         I f Keypressed Then
  11493.                            Begin
  11494.                                c := UpCase( Readkey ) ;
  11495.                                Case c Of
  11496.                                  ' L ' :
  11497.                                     Begin
  11498.                                             GotoXY ( 1 , 2 0 ) ;
  11499.                                             ClrEol ;
  11500.                                             times := GetLastButtonPress ( LButton , x , y ) ;
  11501.                                             Write ( ' l e f t button has been pr es se d ' , times ,
  11502.                                                         ' times , the l a s t time at ( ' , x , ' , ' , y , ' ) ' ) ;
  11503.                                             times := GetLastButtonRelease ( LButton , x , y ) ;
  11504.  
  11505.                                                             194
  11506.  
  11507.  
  11508.  
  11509.                                                              10.2. FUNCTIONS AND PROCEDURES
  11510.  
  11511.  
  11512.                                              GotoXY( 1 , 2 3 ) ;
  11513.                                              ClrEol ;
  11514.                                              Write ( ' l e f t button has been r e l e a s e d ' , times ,
  11515.                                                          ' times , the l a s t time at ( ' , x , ' , ' , y , ' ) ' )
  11516.                                       End;
  11517.                                    ' R' :
  11518.                                       Begin
  11519.                                              GotoXY ( 1 , 2 0 ) ;
  11520.                                              ClrEol ;
  11521.                                              times := GetLastButtonPress ( RButton , x , y ) ;
  11522.                                              Writeln ( ' r i g h t button has been p res s ed ' , times ,
  11523.                                                          ' times , the l a s t time at ( ' , x , ' , ' , y , ' ) ' ) ;
  11524.                                              times := GetLastButtonRelease ( RButton , x , y ) ;
  11525.                                              GotoXY( 1 , 2 3 ) ;
  11526.                                              ClrEol ;
  11527.                                              Write ( ' r i g h t button has been r e l e a s e d ' , times ,
  11528.                                                          ' times , the l a s t time at ( ' , x , ' , ' , y , ' ) ' )
  11529.                                       End;
  11530.                                    'M' :
  11531.                                       Begin
  11532.                                              GotoXY ( 1 , 2 0 ) ;
  11533.                                              ClrEol ;
  11534.                                              times := GetLastButtonPress ( MButton , x , y ) ;
  11535.                                              Writeln ( ' middle button has been pr es se d ' , times ,
  11536.                                                          ' times , the l a s t time at ( ' , x , ' , ' , y , ' ) ' ) ;
  11537.                                              times := GetLastButtonRelease ( MButton , x , y ) ;
  11538.                                              GotoXY( 1 , 2 3 ) ;
  11539.                                              ClrEol ;
  11540.                                              Write ( ' middle button has been r e l e a s e d ' , times ,
  11541.                                                          ' times , the l a s t time at ( ' , x , ' , ' , y , ' ) ' )
  11542.                                       End
  11543.                               End
  11544.                            End;
  11545.                      Until ( c = #27); { escape }
  11546.                      While KeyPressed do ReadKey ;
  11547.                      GotoXY( 1 , 2 4 ) ;
  11548.                      HideMouse
  11549.                   End
  11550.           End.
  11551.  
  11552.  
  11553.           GetLastButtonRelease
  11554. Declaration: Function GetLastButtonRelease (Button: Longint; Var x,y:Longint) : Longint;
  11555.  
  11556. Description: GetLastButtonRelease stores the position where Button was last released in x
  11557.           and y and returns the number of times this button has been released since the last
  11558.           call to this function with Button as parameter. For button you can use the LButton,
  11559.           RButton and MButton constants for resp. the left, right and middle button. For
  11560.           two-button mice, checking the stats of the middle button seems to give and clear
  11561.           the stats of the right button.
  11562.  
  11563.     Errors: None.
  11564.  
  11565.   See also: GetLastButtonPress (194)
  11566.  
  11567.  
  11568.                                                              195
  11569.  
  11570.  
  11571.  
  11572.                                                        10.2. FUNCTIONS AND PROCEDURES
  11573.  
  11574.  
  11575.           For an example, see GetLastButtonPress (194).
  11576.  
  11577.  
  11578.           GetMouseState
  11579. Declaration: Procedure GetMouseState (Var x, y, buttons: Longint);
  11580.  
  11581. Description: GetMouseState Returns information on the current mouse position and which
  11582.           buttons are currently pressed. x and y return the mouse cursor coordinates in
  11583.           pixels. Buttons is a bitmask. Check the example program to see how you can get
  11584.           the necessary information from it.
  11585.  
  11586.     Errors: None.
  11587.  
  11588.   See also: LPressed (198), MPressed (198), RPressed (198), SetMousePos (200)
  11589.  
  11590.           { example f or GetMouseState , I s L P r e s s e d , IsRPressed and IsMPressed }
  11591.  
  11592.           Uses Mouse , Crt ;
  11593.  
  11594.           Var X, Y, State : Longint ;
  11595.  
  11596.           Begin
  11597.              I f MouseFound Then
  11598.                  Begin
  11599.                      ClrScr ;
  11600.                      ShowMouse ;
  11601.                      GotoXY( 5 , 2 4 ) ;
  11602.                      Write ( ' Left button : ' ) ;
  11603.                      GotoXY( 3 0 , 2 4 ) ;
  11604.                      Write ( ' Right button : ' ) ;
  11605.                      GotoXY( 5 5 , 2 4 ) ;
  11606.                      Write ( ' Middle button : ' ) ;
  11607.                      While KeyPressed do Readkey ; { c l e a r keyboard b u f f e r }
  11608.                      Repeat
  11609.                           GetMouseState ( x , y , State ) ;
  11610.                           GotoXY ( 2 0 , 2 2 ) ;
  11611.                           Write ( ' X: ' , x : 5 , ' ( column : ' , ( x div 8 ) : 2 , ' )    Y: ' , y : 5 , ' ( row : ' , ( y div 8 ) : 2 , ' ) ' ) ;
  11612.                           GotoXY ( 1 8 , 2 4 ) ; { l e f t button }
  11613.                           I f ( State and LButton ) = LButton Then
  11614.           { or : " I f LPressed Then " . I f you use t h i s f u n c t i o n , no c a l l to GetMouseState
  11615.             i s n e c e s s a r y }
  11616.                              Write ( ' Down' )
  11617.                           Else
  11618.                              Write ( ' Up ' ) ;
  11619.                           GotoXY ( 4 4 , 2 4 ) ; { r i g h t button }
  11620.                           I f ( State and RButton ) = RButton Then
  11621.           { or : " I f RPressed Then "}
  11622.                              Write ( ' Down' )
  11623.                           Else
  11624.                              Write ( ' Up ' ) ;
  11625.                           GotoXY ( 7 0 , 2 4 ) ; { middle button }
  11626.                           I f ( State and MButton ) = MButton Then
  11627.           { or : " I f MPressed Then "}
  11628.                              Write ( ' Down' )
  11629.  
  11630.  
  11631.                                                        196
  11632.  
  11633.  
  11634.  
  11635.                                                            10.2. FUNCTIONS AND PROCEDURES
  11636.  
  11637.  
  11638.                             Else
  11639.                                Write ( ' Up ' )
  11640.                        Until KeyPressed ;
  11641.                        HideMouse ;
  11642.                        While KeyPressed Do Readkey
  11643.                    End
  11644.            End.
  11645.  
  11646.  
  11647.            HideMouse
  11648. Declaration: Procedure HideMouse ;
  11649.  
  11650. Description: HideMouse makes the mouse cursor invisible. Multiple calls to HideMouse will
  11651.            require just as many calls to ShowMouse to make the mouse cursor again visible.
  11652.  
  11653.      Errors: None.
  11654.  
  11655.    See also: ShowMouse (203), SetMouseHideWindow (199)
  11656.  
  11657.            For an example, see ShowMouse (203).
  11658.  
  11659.  
  11660.            InitMouse
  11661. Declaration: Procedure InitMouse ;
  11662.  
  11663. Description: InitMouse Initializes the mouse driver sets the variable MouseFound depending on
  11664.            whether or not a mouse is found. This is Automatically called at the start of your
  11665.            program. You should never have to call it, unless you want to reset everything to
  11666.            its default values.
  11667.  
  11668.      Errors: None.
  11669.  
  11670.    See also: MouseFound variable.
  11671.  
  11672.            Program Mouse1 ;
  11673.  
  11674.            { example fo r InitMouse and MouseFound }
  11675.  
  11676.            Uses Mouse ;
  11677.  
  11678.            Begin
  11679.               I f MouseFound Then
  11680.                    Begin
  11681.                       {go i n t o g r a p h i c s mode 13 h}
  11682.                        Asmmovl $0x013, %eax
  11683.                           pushl %ebp
  11684.                           int $0x010
  11685.                           popl %ebp
  11686.                        End;
  11687.                        InitMouse ;
  11688.                        ShowMouse ; { o t h e r w i s e i t s t a y s i n v i s i b l e }
  11689.                        Writeln ( ' Mouse Found ! ( p r e s s enter to quit ) ' ) ;
  11690.                        Readln ;
  11691.  
  11692.  
  11693.                                                            197
  11694.  
  11695.  
  11696.  
  11697.                                                    10.2. FUNCTIONS AND PROCEDURES
  11698.  
  11699.  
  11700.                       { back to text mode}
  11701.                       Asmmovl $3, %eax
  11702.                           pushl %ebp
  11703.                           int $0x010
  11704.                           popl %ebp
  11705.                        End
  11706.                    End
  11707.            End.
  11708.  
  11709.  
  11710.            LPressed
  11711. Declaration: Function LPressed : Boolean;
  11712.  
  11713. Description: LPressed returns True if the left mouse button is pressed. This is simply a wrapper
  11714.            for the GetMouseState procedure.
  11715.  
  11716.      Errors: None.
  11717.  
  11718.    See also: GetMouseState (196), MPressed (198), RPressed (198)
  11719.  
  11720.            For an example, see GetMouseState (196).
  11721.  
  11722.  
  11723.            MPressed
  11724. Declaration: Function MPressed : Boolean;
  11725.  
  11726. Description: MPressed returns True if the middle mouse button is pressed. This is simply a
  11727.            wrapper for the GetMouseState procedure.
  11728.  
  11729.      Errors: None.
  11730.  
  11731.    See also: GetMouseState (196), LPressed (198), RPressed (198)
  11732.  
  11733.            For an example, see GetMouseState (196).
  11734.  
  11735.  
  11736.            RPressed
  11737. Declaration: Function RPressed : Boolean;
  11738.  
  11739. Description: RPressed returns True if the right mouse button is pressed. This is simply a
  11740.            wrapper for the GetMouseState procedure.
  11741.  
  11742.      Errors: None.
  11743.  
  11744.    See also: GetMouseState (196), LPressed (198), MPressed (198)
  11745.  
  11746.            For an example, see GetMouseState (196).
  11747.  
  11748.  
  11749.            SetMouseAscii
  11750. Declaration: Procedure SetMouseAscii (Ascii: Byte);
  11751.  
  11752.  
  11753.  
  11754.                                                     198
  11755.  
  11756.  
  11757.  
  11758.                                                           10.2. FUNCTIONS AND PROCEDURES
  11759.  
  11760.  
  11761. Description: SetMouseAscii sets the Ascii value of the character that depicts the mouse cursor
  11762.            in text mode. The di erence between this one and SetMouseShape (200), is that
  11763.            the foreground and background colors stay the same and that the Ascii code you
  11764.            enter is the character that you will get on screen; there's no XOR'ing.
  11765.      Errors: None
  11766.    See also: SetMouseShape (200)
  11767.  
  11768.            { example f o r SetMouseAscii }
  11769.  
  11770.            { warning : no e r r o r checking i s performed on the input }
  11771.  
  11772.            Uses Mouse , Crt ;
  11773.  
  11774.            Var a s c i i : Byte ;
  11775.                    x , y : Longint ;
  11776.  
  11777.            Begin
  11778.               I f MouseFound Then
  11779.                    Begin
  11780.                       ClrScr ;
  11781.                       Writeln ( ' Press any mouse button to quit a f t e r you ' ' ve entered an A s c i i value . ' ) ;
  11782.                       Writeln ;
  11783.                       Writeln ( ' ASCII value of mouse c u r s o r : ' ) ;
  11784.                       ShowMouse ;
  11785.                       Repeat
  11786.                            GotoXY( 3 0 , 3 ) ;
  11787.                            ClrEol ;
  11788.                            Readln ( a s c i i ) ;
  11789.                            SetMouseAscii ( a s c i i )
  11790.                       Until ( GetLastButtonPress ( LButton , x , y ) <> 0) Or
  11791.                                  ( GetLastButtonPress ( RButton , x , y ) <> 0) Or
  11792.                                  ( GetLastButtonPress ( MButton , x , y ) <> 0);
  11793.                       HideMouse
  11794.                    End;
  11795.            End.
  11796.  
  11797.  
  11798.            SetMouseHideWindow
  11799. Declaration: Procedure SetMouseHideWindow (xmin,ymin,xmax,ymax: Longint);
  11800. Description: SetMouseHideWindow defines a rectangle on screen with top-left corner at (xmin,ymin)
  11801.            and botto-right corner at (xmax,ymax),which causes the mouse cursor to be turned
  11802.            o  when it is moved into it. When the mouse is moved into the specified region,
  11803.            it is turned o  until you call ShowMouse again. However, once you've called Show-
  11804.            Mouse (203), you'll have to call SetMouseHideWindow again to redefine the hide
  11805.            window... This may be annoying, but it's the way it's implemented in the mouse
  11806.            driver. While xmin, ymin, xmax and ymax are Longint parameters, only the lower
  11807.            16 bits are used.
  11808.      Errors: None.
  11809.    See also: ShowMouse (203), HideMouse (197)
  11810.  
  11811.            nputlistingmouseex/mouse9.pp
  11812.  
  11813.                                                           199
  11814.  
  11815.  
  11816.  
  11817.                                                        10.2. FUNCTIONS AND PROCEDURES
  11818.  
  11819.  
  11820.            SetMousePos
  11821. Declaration: Procedure SetMousePos (x,y:Longint);
  11822.  
  11823. Description: SetMosusePos sets the position of the mouse cursor on the screen. x is the hor-
  11824.            izontal position in pixels, y the vertical position in pixels. The upper-left hand
  11825.            corner of the screen is the origin. While x and y are longints, only the lower 16 bits
  11826.            are used.
  11827.  
  11828.     Errors: None.
  11829.  
  11830.   See also: GetMouseState (196)
  11831.  
  11832.            { example f o r SetMousePos }
  11833.  
  11834.            Uses Mouse , Crt ;
  11835.  
  11836.            Begin
  11837.               I f MouseFound Then
  11838.                    Begin
  11839.                       ShowMouse ;
  11840.                       While KeyPressed do ReadKey ;
  11841.                       Repeat
  11842.                            SetMousePos (Random( 8 0   8 ) , Random( 2 5   8 ) ) ;
  11843.                            delay ( 10 0 ) ;
  11844.                       Until Keypressed ;
  11845.                       HideMouse ;
  11846.                       While KeyPressed do ReadKey ;
  11847.                    End;
  11848.            End.
  11849.  
  11850.  
  11851.            SetMouseShape
  11852. Declaration: Procedure SetMouseShape (ForeColor,BackColor,Ascii: Byte);
  11853.  
  11854. Description: SetMouseShape defines how the mouse cursor looks in textmode The character
  11855.            and its attributes that are on the mouse cursor's position on screen are XOR'ed
  11856.            with resp. ForeColor, BackColor and Ascii. Set them all to 0 for a "transparent"
  11857.            cursor.
  11858.  
  11859.     Errors: None.
  11860.  
  11861.   See also: SetMouseAscii (198)
  11862.  
  11863.            { example fo r SetMouseShape }
  11864.  
  11865.            { warning : no e r r o r checking i s performed on the input }
  11866.  
  11867.            { the A s c i i value you enter i s XOR' ed with the A s c i i value of the c h a r a c t e r
  11868.             on the screen over which you move the c u r s o r . To get a " t r a n s p a r e n t " c u r s o r ,
  11869.             use the A s c i i value 0}
  11870.  
  11871.            Uses Mouse , Crt ;
  11872.  
  11873.            Var a s c i i , fc , bc : Byte ;
  11874.                    x , y : Longint ;
  11875.  
  11876.                                                        200
  11877.  
  11878.  
  11879.  
  11880.                                                           10.2. FUNCTIONS AND PROCEDURES
  11881.  
  11882.  
  11883.  
  11884.                Begin
  11885.                  I f MouseFound Then
  11886.                        Begin
  11887.                          ClrScr ;
  11888.                          Writeln ( ' Press any mouse button to quit a f t e r you ' ' ve entered a sequence of numbers . ' ) ;
  11889.                          Writeln ;
  11890.                          Writeln ( ' ASCII value of mouse c u r s o r : ' ) ;
  11891.                          Writeln ( ' Forground c o l o r : ' ) ;
  11892.                          Writeln ( ' Background c o l o r : ' ) ;
  11893.                          ShowMouse ;
  11894.                          Repeat
  11895.                                GotoXY( 3 0 , 3 ) ;
  11896.                                ClrEol ;
  11897.                                Readln ( a s c i i ) ;
  11898.                                GotoXY( 1 8 , 4 ) ;
  11899.                                ClrEol ;
  11900.                                Readln ( fc ) ;
  11901.                                GotoXY( 1 9 , 5 ) ;
  11902.                                ClrEol ;
  11903.                                Readln ( bc ) ;
  11904.                                SetMouseShape ( fc , bc , a s c i i )
  11905.                          Until ( GetLastButtonPress ( LButton , x , y ) <> 0) Or
  11906.                                      ( GetLastButtonPress ( RButton , x , y ) <> 0) Or
  11907.                                      ( GetLastButtonPress ( MButton , x , y ) <> 0);
  11908.                          HideMouse
  11909.                        End;
  11910.                End.
  11911.  
  11912.  
  11913.           SetMouseSpeed
  11914. Declaration: Procedure SetMouseSpeed (Horizontal, Vertical: Longint);
  11915.  
  11916. Description: SetMouseSpeed sets the mouse speed in mickeys per 8 pixels. A mickey is the
  11917.           smallest measurement unit handled by a mouse. With this procedure you can set
  11918.           how many mickeys the mouse should move to move the cursor 8 pixels horizontally
  11919.           of vertically. The default values are 8 for horizontal and 16 for vertical movement.
  11920.           While this procedure accepts longint parameters, only the low 16 bits are actually
  11921.           used.
  11922.  
  11923.     Errors: None.
  11924.  
  11925.   See also:
  11926.  
  11927.                Uses Mouse , Crt ;
  11928.  
  11929.                Var hor , v e r t : Longint ;
  11930.                        x , y : Longint ;
  11931.  
  11932.                Begin
  11933.                  I f MouseFound Then
  11934.                        Begin
  11935.                          ClrScr ;
  11936.                          Writeln ( ' C l i c k any button to quit a f t e r you ' ' ve entered a sequence of numbers . ' ) ;
  11937.  
  11938.                                                           201
  11939.  
  11940.  
  11941.  
  11942.                                                         10.2. FUNCTIONS AND PROCEDURES
  11943.  
  11944.  
  11945.                      Writeln ;
  11946.                      Writeln ( ' H o r i z o n t a l mickey ' ' s per p i x e l : ' ) ;
  11947.                      Writeln ( ' V e r t i c a l mickey ' ' s per p i x e l : ' ) ;
  11948.                      ShowMouse ;
  11949.                      Repeat
  11950.                           GotoXY( 3 2 , 3 ) ;
  11951.                           ClrEol ;
  11952.                           Readln ( hor ) ;
  11953.                           GotoXY( 3 0 , 4 ) ;
  11954.                           ClrEol ;
  11955.                           Readln ( v e r t ) ;
  11956.                           SetMouseSpeed ( hor , v e r t ) ;
  11957.                      Until ( GetLastButtonPress ( LButton , x , y ) <> 0) Or
  11958.                                 ( GetLastButtonPress ( RButton , x , y ) <> 0) Or
  11959.                                 ( GetLastButtonPress ( MButton , x , y ) <> 0);
  11960.                    End
  11961.            End.
  11962.  
  11963.  
  11964.            SetMouseWindow
  11965. Declaration: Procedure SetMouseWindow (xmin,ymin,xmax,ymax: Longint);
  11966.  
  11967. Description: SetMousWindow defines a rectangle on screen with top-left corner at (xmin,ymin)
  11968.            and botto-right corner at (xmax,ymax), out of which the mouse cursor can't move.
  11969.            This procedure is simply a wrapper for the SetMouseXRange (202) and SetMouseYRange
  11970.            (203) procedures. While xmin, ymin, xmax and ymax are Longint parameters, only
  11971.            the lower 16 bits are used.
  11972.  
  11973.     Errors: None.
  11974.  
  11975.   See also: SetMouseXRange (202), SetMouseYRange (203)
  11976.  
  11977.            For an example, see SetMouseXRange (202).
  11978.  
  11979.  
  11980.            SetMouseXRange
  11981. Declaration: Procedure SetMouseXRange (Min, Max: Longint);
  11982.  
  11983. Description: SetMouseXRange sets the minimum (Min) and maximum (Max) horizontal coordi-
  11984.            nates in between which the mouse cursor can move. While Min and Max are Longint
  11985.            parameters, only the lower 16 bits are used.
  11986.  
  11987.     Errors: None.
  11988.  
  11989.   See also: SetMouseYRange (203), SetMouseWindow (202)
  11990.  
  11991.            { example f o r SetMouseXRange , SetMouseYRange and SetMouseWindow }
  11992.  
  11993.            Uses Mouse , Crt ;
  11994.  
  11995.            Begin
  11996.               I f MouseFound Then
  11997.                    Begin
  11998.                      SetMouseXRange ( 2 0   8 , 5 0   8 ) ;     { c h a r r a c t e r width and height = 8 p i x e l s }
  11999.  
  12000.  
  12001.                                                         202
  12002.  
  12003.  
  12004.  
  12005.                                                        10.2. FUNCTIONS AND PROCEDURES
  12006.  
  12007.  
  12008.                       SetMouseYRange ( 1 0   8 , 1 5   8 ) ;
  12009.  
  12010.            { the two l i n e s of code have e x a c t l y the same e f f e c t as
  12011.             SetMouseWindow (20 8,10 8,50 8,15 8)}
  12012.  
  12013.                       Writeln ( ' Press any key to quit . ' ) ;
  12014.                       ShowMouse ;
  12015.                       While KeyPressed Do ReadKey ;
  12016.                       Readkey ;
  12017.                       While KeyPressed Do ReadKey ;
  12018.                       HideMouse
  12019.                    End
  12020.            End.
  12021.  
  12022.  
  12023.            SetMouseYRange
  12024. Declaration: Procedure SetMouseYRange (Min, Max: Longint);
  12025. Description: SetMouseYRange sets the minimum (Min) and maximum (Max) vertical coordinates
  12026.            in between which the mouse cursor can move. While Min and Max are Longint
  12027.            parameters, only the lower 16 bits are used.
  12028.      Errors: None.
  12029.    See also: SetMouseXRange (202), SetMouseWindow (202)
  12030.  
  12031.            For an example, see SetMouseXRange (202).
  12032.  
  12033.  
  12034.            ShowMouse
  12035. Declaration: Procedure ShowMouse ;
  12036. Description: ShowMouse makes the mouse cursor visible. At the start of your progam, the mouse
  12037.            is invisible.
  12038.      Errors: None.
  12039.    See also: HideMouse (197),SetMouseHideWindow (199)
  12040.  
  12041.            { example f o r ShowMouse and HideMouse }
  12042.  
  12043.            Uses Mouse ;
  12044.  
  12045.            Begin
  12046.               ClrScr ;
  12047.               I f MouseFound Then
  12048.                    Begin
  12049.                       Writeln ( ' Now you can see the mouse . . . ( p r e s s enter to continue ) ' ) ;
  12050.                       ShowMouse ;
  12051.                       Readln ;
  12052.                       HideMouse ;
  12053.                       Writeln ( ' And now you can ' ' t . . . ( p r e s s enter to quit ) ' ) ;
  12054.                       Readln
  12055.                    End
  12056.            End.
  12057.  
  12058.  
  12059.                                                        203
  12060.  
  12061.  
  12062.  
  12063. Chapter 11
  12064.  
  12065. The Objects unit.
  12066.  
  12067. This chapter documents the objects unit. The unit was implemented by many
  12068. people, and was mainly taken from the FreeVision sources.
  12069. The methods and fields that are in a Private part of an object declaration have
  12070. been left out of this documentation.
  12071.  
  12072.  
  12073. 11.1 Constants
  12074.  
  12075. The following constants are error codes, returned by the various stream objects.
  12076.  
  12077. CONST
  12078.    stOk            = 0; { No stream error }
  12079.    stError         = -1; { Access error }
  12080.    stInitError = -2; { Initialize error }
  12081.    stReadError = -3; { Stream read error }
  12082.    stWriteError = -4; { Stream write error }
  12083.    stGetError      = -5; { Get object error }
  12084.    stPutError      = -6; { Put object error }
  12085.    stSeekError = -7; { Seek error in stream }
  12086.    stOpenError = -8; { Error opening stream }
  12087.  
  12088. These constants can be passed to constructors of file streams:
  12089.  
  12090. CONST
  12091.    stCreate       = $3C00; { Create new file }
  12092.    stOpenRead = $3D00; { Read access only }
  12093.    stOpenWrite = $3D01; { Write access only }
  12094.    stOpen         = $3D02; { Read/write access }
  12095.  
  12096. The following constants are error codes, returned by the collection list objects:
  12097.  
  12098. CONST
  12099.    coIndexError = -1; { Index out of range }
  12100.    coOverflow      = -2; { Overflow }
  12101.  
  12102. Maximum data sizes (used in determining how many data can be used.
  12103.  
  12104.  
  12105.                                         204
  12106.  
  12107.  
  12108.  
  12109.                                                                       11.2. TYPES
  12110.  
  12111.  
  12112. CONST
  12113.    MaxBytes = 128*1024*1024;                                     { Maximum data size }
  12114.    MaxWords = MaxBytes DIV SizeOf(Word);                         { Max word data size }
  12115.    MaxPtrs = MaxBytes DIV SizeOf(Pointer);                       { Max ptr data size }
  12116.    MaxCollectionSize = MaxBytes DIV SizeOf(Pointer); { Max collection size }
  12117.  
  12118.  
  12119. 11.2 Types
  12120.  
  12121. The follwing auxiliary types are defined:
  12122.  
  12123. TYPE{ Character set }
  12124.    TCharSet = SET Of Char;
  12125.    PCharSet = ^TCharSet;
  12126.  
  12127.    { Byte array }
  12128.    TByteArray = ARRAY [0..MaxBytes-1] Of Byte;
  12129.    PByteArray = ^TByteArray;
  12130.  
  12131.    { Word array }
  12132.    TWordArray = ARRAY [0..MaxWords-1] Of Word;
  12133.    PWordArray = ^TWordArray;
  12134.  
  12135.    { Pointer array }
  12136.    TPointerArray = Array [0..MaxPtrs-1] Of Pointer;
  12137.    PPointerArray = ^TPointerArray;
  12138.  
  12139.    { String pointer }
  12140.    PString = ^String;
  12141.  
  12142.    { Filename array }
  12143.    AsciiZ = Array [0..255] Of Char;
  12144.  
  12145.    Sw_Word        = Cardinal;
  12146.    Sw_Integer = LongInt;
  12147.  
  12148. The following records are used internaly for easy type conversion:
  12149.  
  12150. TYPE{ Word to bytes}
  12151.    WordRec = packed RECORD
  12152.          Lo, Hi: Byte;
  12153.    END;
  12154.  
  12155.    { LongInt to words }
  12156.    LongRec = packed RECORD
  12157.          Lo, Hi: Word;
  12158.    END;
  12159.  
  12160.   { Pointer to words }
  12161.    PtrRec = packed RECORD
  12162.          Ofs, Seg: Word;
  12163.    END;
  12164.  
  12165.                                         205
  12166.  
  12167.  
  12168.  
  12169.                                                      11.3. PROCEDURES AND FUNCTIONS
  12170.  
  12171.  
  12172.            The following record is used when streaming objects:
  12173.  
  12174.            TYPEPStreamRec = ^TStreamRec;
  12175.               TStreamRec = Packed RECORD
  12176.                      ObjType: Sw_Word;
  12177.                      VmtLink: pointer;
  12178.                      Load : Pointer;
  12179.                      Store: Pointer;
  12180.                      Next : PStreamRec;
  12181.               END;
  12182.  
  12183.            The TPoint basic object is used in the TRect object (see section 11.4, page 209):
  12184.  
  12185.            TYPEPPoint = ^TPoint;
  12186.               TPoint = OBJECT
  12187.                      X, Y: Sw_Integer;
  12188.               END;
  12189.  
  12190.  
  12191.            11.3 Procedures and Functions
  12192.  
  12193.            NewStr
  12194. Declaration: Function NewStr (Const S: String): PString;
  12195. Description: NewStr makes a copy of the string S on the heap, and returns a pointer to this
  12196.            copy.
  12197.            The allocated memory is not based on the declared size of the string passed to
  12198.            NewStr, but is baed on the actual length of the string.
  12199.     Errors: If not enough memory is available, an 'out of memory' error will occur.
  12200.   See also: DisposeStr (207)
  12201.  
  12202.            Program ex40 ;
  12203.  
  12204.            { Program to demonstrate the NewStr f u n c t i o n }
  12205.  
  12206.            Uses Objects ;
  12207.  
  12208.            Var S : String ;
  12209.                     P : PString ;
  12210.  
  12211.            begin
  12212.              S:= ' Some r e a l l y cute s t r i n g ' ;
  12213.              Writeln ( ' Memavail : ' , Memavail ) ;
  12214.              P:=NewStr( S ) ;
  12215.               I f P <>S then
  12216.                     Writeln ( ' Oh-oh . . . Something i s wrong ! ! ' ) ;
  12217.              Writeln ( ' A l l o c a t e d s t r i n g . Memavail : ' , Memavail ) ;
  12218.              DisposeStr (P) ;
  12219.              Writeln ( ' D e a l l o c a t e d s t r i n g . Memavail : ' , Memavail ) ;
  12220.            end .
  12221.  
  12222.  
  12223.                                                      206
  12224.  
  12225.  
  12226.  
  12227.                                                     11.3. PROCEDURES AND FUNCTIONS
  12228.  
  12229.  
  12230.            DisposeStr
  12231. Declaration: Procedure DisposeStr (P: PString);
  12232.  
  12233. Description: DisposeStr removes a dynamically allocated string from the heap.
  12234.  
  12235.      Errors: None.
  12236.  
  12237.    See also: NewStr (206)
  12238.  
  12239.            For an example, see NewStr (206).
  12240.  
  12241.  
  12242.            Abstract
  12243. Declaration: Procedure Abstract;
  12244.  
  12245. Description: When implementing abstract methods, do not declare them as abstract. Instead,
  12246.            define them simply as virtual. In the implementation of such abstract methods,
  12247.            call the Abstract procedure. This allows explicit control of what happens when an
  12248.            abstract method is called.
  12249.            The current implementation of Abstract terminates the program with a run-time
  12250.            error 211.
  12251.  
  12252.      Errors: None.
  12253.  
  12254.    See also: Most abstract types.
  12255.  
  12256.  
  12257.            RegisterObjects
  12258. Declaration: Procedure RegisterObjects;
  12259.  
  12260. Description: RegisterObjects registers the following objects for streaming:
  12261.  
  12262.               1.TCollection, see section 11.10, page 234.
  12263.               2.TStringCollection, see section 11.12, page 254.
  12264.               3.TStrCollection, see section 11.13, page 255.
  12265.  
  12266.      Errors: None.
  12267.  
  12268.    See also: RegisterType (207)
  12269.  
  12270.  
  12271.            RegisterType
  12272. Declaration: Procedure RegisterType (Var S: TStreamRec);
  12273.  
  12274. Description: RegisterType registers a new type for streaming. An object cannot be streamed
  12275.            unless it has been registered first. The stream record S needs to have the following
  12276.            fields set:
  12277.  
  12278.            ObjType: Sw WordThis should be a unique identifier. Each possible type
  12279.                 should have it's own identifier.
  12280.            VmtLink: pointerThis should contain a pointer to the VMT (Virtual Method
  12281.                 Table) of the object you try to register. You can get it with the following
  12282.                 expression:
  12283.                           VmtLink: Ofs(TypeOf(MyType)^);
  12284.  
  12285.                                                     207
  12286.  
  12287.  
  12288.  
  12289.                                                       11.3. PROCEDURES AND FUNCTIONS
  12290.  
  12291.  
  12292.       Load : Pointeris a pointer to a method that initializes an instance of that object,
  12293.                and reads the initial values from a stream. This method should accept as it's
  12294.                sole argument a PStream type variable.
  12295.       Store: Pointeris a pointer to a method that stores an instance of the object to
  12296.                a stream. This method should accept as it's sole argument a PStream type
  12297.                variable.
  12298.  
  12299. Errors: In case of error (if a object with the same ObjType) is already registered), run-time
  12300.       error 212 occurs.
  12301.  
  12302.       Unit MyObject ;
  12303.  
  12304.  
  12305.       Interface
  12306.  
  12307.       Uses Objects ;
  12308.  
  12309.       Type PMyObject =  TMyObject;
  12310.                  TMyObject = Object ( TObject )
  12311.                     F i e l d : Longint ;
  12312.                     Constructor I n i t ;
  12313.                     Constructor Load ( Var Stream : TStream ) ;
  12314.                     Destructor Done ;
  12315.                     Procedure Store ( Var Stream : TStream ) ;
  12316.                     Function          G e t F i e l d : Longint ;
  12317.                     Procedure S e t F i e l d ( Value : Longint ) ;
  12318.                    end ;
  12319.  
  12320.       Implementation
  12321.  
  12322.       Constructor TMyobject . I n i t ;
  12323.  
  12324.       begin
  12325.          Inherited I n i t ;
  12326.          F i e l d :=-1;
  12327.       end ;
  12328.  
  12329.       Constructor TMyobject . Load ( Var Stream : TStream ) ;
  12330.  
  12331.       begin
  12332.          Stream . Read( F i e l d , Sizeof ( F i e l d ) ) ;
  12333.       end ;
  12334.  
  12335.       Destructor TMyObject . Done ;
  12336.  
  12337.       begin
  12338.       end ;
  12339.  
  12340.       Function TMyObject . G e t F i e l d : Longint ;
  12341.  
  12342.       begin
  12343.          G e t F i e l d := F i e l d ;
  12344.       end ;
  12345.  
  12346.                                                        208
  12347.  
  12348.  
  12349.  
  12350.                                                                                11.4. TRECT
  12351.  
  12352.  
  12353.  
  12354.            Function TMyObject . S e t F i e l d ( Value : Longint ) ;
  12355.  
  12356.            begin
  12357.               F i e l d := Value ;
  12358.            end ;
  12359.  
  12360.            Procedure TMyObject . Store ( Var Stream : TStream ) ;
  12361.  
  12362.            begin
  12363.               Stream . Write ( F i e l d , SizeOf ( F i e l d ) ) ;
  12364.            end ;
  12365.  
  12366.            Const MyObjectRec : TStreamRec = (
  12367.                          Objtype : 6 6 6 ;
  12368.                          vmtlink : Ofs ( TypeOf( TMyObject )   ) ;
  12369.                          Load : @TMyObject . Load ;
  12370.                          Store : @TMyObject . Store ;
  12371.                           ) ;
  12372.  
  12373.            begin
  12374.               R e g i s t e r O b j e c t s ;
  12375.               RegisterType ( MyObjectRec ) ;
  12376.            end .
  12377.  
  12378.  
  12379.            LongMul
  12380. Declaration: Function LongMul (X, Y: Integer): LongInt;
  12381.  
  12382. Description: LongMul multiplies X with Y. The result is of type Longint. This avoids possible
  12383.            overflow errors you would normally get when multiplying X and Y that are too big.
  12384.  
  12385.      Errors: None.
  12386.  
  12387.    See also: LongDiv (209)
  12388.  
  12389.  
  12390.            LongDiv
  12391. Declaration: Function LongDiv (X: Longint; Y: Integer): Integer;
  12392.  
  12393. Description: LongDiv divides X by Y. The result is of type Integer instead of type Longint, as
  12394.            you would get normally.
  12395.  
  12396.      Errors: If Y is zero, a run-time error will be generated.
  12397.  
  12398.    See also: LongMul (209)
  12399.  
  12400.  
  12401.            11.4 TRect
  12402.  
  12403.            The TRect object is declared as follows:
  12404.  
  12405.                TRect = OBJECT
  12406.                       A, B: TPoint;
  12407.  
  12408.  
  12409.                                                         209
  12410.  
  12411.  
  12412.  
  12413.                                                                                11.4. TRECT
  12414.  
  12415.  
  12416.                       FUNCTION Empty: Boolean;
  12417.                       FUNCTION Equals (R: TRect): Boolean;
  12418.                       FUNCTION Contains (P: TPoint): Boolean;
  12419.                       PROCEDURE Copy (R: TRect);
  12420.                       PROCEDURE Union (R: TRect);
  12421.                       PROCEDURE Intersect (R: TRect);
  12422.                       PROCEDURE Move (ADX, ADY: Sw_Integer);
  12423.                       PROCEDURE Grow (ADX, ADY: Sw_Integer);
  12424.                       PROCEDURE Assign (XA, YA, XB, YB: Sw_Integer);
  12425.                END;
  12426.  
  12427.  
  12428.            TRect.Empty
  12429. Declaration: Function TRect.Empty: Boolean;
  12430.  
  12431. Description: Empty returns True if the rectangle defined by the corner points A, B has zero or
  12432.            negative surface.
  12433.  
  12434.      Errors: None.
  12435.  
  12436.    See also: TRect.Equals (211), TRect.Contains (211)
  12437.  
  12438.            Program ex1 ;
  12439.  
  12440.            { Program to demonstrate TRect . Empty }
  12441.  
  12442.            Uses o b j e c t s ;
  12443.  
  12444.  
  12445.            Var ARect , BRect : TRect ;
  12446.                  P : TPoint ;
  12447.  
  12448.            begin
  12449.               With ARect . A do
  12450.                  begin
  12451.                  X:=10;
  12452.                  Y:=10;
  12453.                  end ;
  12454.               With ARect . B do
  12455.                  begin
  12456.                  X:=20;
  12457.                  Y:=20;
  12458.                  end ;
  12459.               { O f f s e t B by ( 5 , 5 ) }
  12460.               With BRect . A do
  12461.                  begin
  12462.                  X:=15;
  12463.                  Y:=15;
  12464.                  end ;
  12465.               With BRect . B do
  12466.                  begin
  12467.                  X:=25;
  12468.                  Y:=25;
  12469.                  end ;
  12470.  
  12471.  
  12472.                                                     210
  12473.  
  12474.  
  12475.  
  12476.                                                                                 11.4. TRECT
  12477.  
  12478.  
  12479.               { Point }
  12480.               With P do
  12481.                     begin
  12482.                     X:=15;
  12483.                     Y:=15;
  12484.                     end ;
  12485.               Writeln ( ' A empty : ' , ARect . Empty ) ;
  12486.               Writeln ( ' B empty : ' , BRect . Empty ) ;
  12487.               Writeln ( ' A Equals B : ' , ARect . Equals ( BRect ) ) ;
  12488.               Writeln ( ' A Contains ( 1 5 , 1 5 ) : ' , ARect . Contains (P) ) ;
  12489.            end .
  12490.  
  12491.  
  12492.            TRect.Equals
  12493. Declaration: Function TRect.Equals (R: TRect): Boolean;
  12494.  
  12495. Description: Equals returns True if the rectangle has the same corner points A,B as the rect-
  12496.            angle R, and False otherwise.
  12497.  
  12498.      Errors: None.
  12499.  
  12500.    See also: Empty (210), Contains (211)
  12501.  
  12502.            For an example, see TRect.Empty (210)
  12503.  
  12504.  
  12505.            TRect.Contains
  12506. Declaration: Function TRect.Contains (P: TPoint): Boolean;
  12507.  
  12508. Description: Contains returns True if the point P is contained in the rectangle (including
  12509.            borders), False otherwise.
  12510.  
  12511.      Errors: None.
  12512.  
  12513.    See also: Intersect (212), Equals (211)
  12514.  
  12515.  
  12516.            TRect.Copy
  12517. Declaration: Procedure TRect.Copy (R: TRect);
  12518.  
  12519. Description: Assigns the rectangle R to the object. After the call to Copy, the rectangle R has
  12520.            been copied to the object that invoked Copy.
  12521.  
  12522.      Errors: None.
  12523.  
  12524.    See also: Assign (214)
  12525.  
  12526.            Program ex2 ;
  12527.  
  12528.             { Program to demonstrate TRect . Copy }
  12529.  
  12530.            Uses o b j e c t s ;
  12531.  
  12532.            Var ARect , BRect , CRect : TRect ;
  12533.  
  12534.  
  12535.                                                     211
  12536.  
  12537.  
  12538.  
  12539.                                                                               11.4. TRECT
  12540.  
  12541.  
  12542.             begin
  12543.                ARect . Assign ( 1 0 , 1 0 , 2 0 , 2 0 ) ;
  12544.                BRect . Assign ( 1 5 , 1 5 , 2 5 , 2 5 ) ;
  12545.                CRect . Copy( ARect ) ;
  12546.                I f ARect . Equals ( CRect ) Then
  12547.                      Writeln ( ' ARect equals CRect ' )
  12548.                Else
  12549.                      Writeln ( ' ARect does not equal CRect ! ' ) ;
  12550.             end .
  12551.  
  12552.  
  12553.            TRect.Union
  12554. Declaration: Procedure TRect.Union (R: TRect);
  12555.  
  12556. Description: Union enlarges the current rectangle so that it becomes the union of the current
  12557.            rectangle with the rectangle R.
  12558.  
  12559.      Errors: None.
  12560.  
  12561.    See also: Intersect (212)
  12562.  
  12563.             Program ex3 ;
  12564.  
  12565.             { Program to demonstrate TRect . Union }
  12566.  
  12567.             Uses o b j e c t s ;
  12568.  
  12569.  
  12570.             Var ARect , BRect , CRect : TRect ;
  12571.  
  12572.             begin
  12573.                ARect . Assign ( 1 0 , 1 0 , 2 0 , 2 0 ) ;
  12574.                BRect . Assign ( 1 5 , 1 5 , 2 5 , 2 5 ) ;
  12575.                { CRect i s union of ARect and BRect }
  12576.                CRect . Assign ( 1 0 , 1 0 , 2 5 , 2 5 ) ;
  12577.                { C a l c u l a t e i t e x p l i c i t l y }
  12578.                ARect . Union ( BRect ) ;
  12579.                I f ARect . Equals ( CRect ) Then
  12580.                      Writeln ( ' ARect equals CRect ' )
  12581.                Else
  12582.                      Writeln ( ' ARect does not equal CRect ! ' ) ;
  12583.             end .
  12584.  
  12585.  
  12586.            TRect.Intersect
  12587. Declaration: Procedure TRect.Intersect (R: TRect);
  12588.  
  12589. Description: Intersect makes the intersection of the current rectangle with R. If the inter-
  12590.            section is empty, then the rectangle is set to the empty rectangle at coordinate
  12591.            (0,0).
  12592.  
  12593.      Errors: None.
  12594.  
  12595.    See also: Union (212)
  12596.  
  12597.  
  12598.                                                                 212
  12599.  
  12600.  
  12601.  
  12602.                                                                             11.4. TRECT
  12603.  
  12604.  
  12605.           Program ex4 ;
  12606.  
  12607.            { Program to demonstrate TRect . I n t e r s e c t }
  12608.  
  12609.            Uses o b j e c t s ;
  12610.  
  12611.  
  12612.           Var ARect , BRect , CRect : TRect ;
  12613.  
  12614.            begin
  12615.               ARect . Assign ( 1 0 , 1 0 , 2 0 , 2 0 ) ;
  12616.               BRect . Assign ( 1 5 , 1 5 , 2 5 , 2 5 ) ;
  12617.               { CRect i s i n t e r s e c t i o n of ARect and BRect }
  12618.               CRect . Assign ( 1 5 , 1 5 , 2 0 , 2 0 ) ;
  12619.               { C a l c u l a t e i t e x p l i c i t l y }
  12620.               ARect . I n t e r s e c t ( BRect ) ;
  12621.               I f ARect . Equals ( CRect ) Then
  12622.                    Writeln ( ' ARect equals CRect ' )
  12623.               Else
  12624.                    Writeln ( ' ARect does not equal CRect ! ' ) ;
  12625.               BRect . Assign ( 2 5 , 2 5 , 3 0 , 3 0 ) ;
  12626.               Arect . I n t e r s e c t ( BRect ) ;
  12627.               I f ARect . Empty Then
  12628.                    Writeln ( ' ARect i s empty ' ) ;
  12629.           end .
  12630.  
  12631.  
  12632.           TRect.Move
  12633. Declaration: Procedure TRect.Move (ADX, ADY: Sw Integer);
  12634.  
  12635. Description: Move moves the current rectangle along a vector with components (ADX,ADY). It
  12636.           adds ADX to the X-coordinate of both corner points, and ADY to both end points.
  12637.  
  12638.     Errors: None.
  12639.  
  12640.   See also: Grow (214)
  12641.  
  12642.           Program ex5 ;
  12643.  
  12644.            { Program to demonstrate TRect . Move }
  12645.  
  12646.            Uses o b j e c t s ;
  12647.  
  12648.  
  12649.           Var ARect , BRect : TRect ;
  12650.  
  12651.            begin
  12652.               ARect . Assign ( 1 0 , 1 0 , 2 0 , 2 0 ) ;
  12653.               ARect . Move( 5 , 5 ) ;
  12654.               // Brect should be where new ARect i s .
  12655.               BRect . Assign ( 1 5 , 1 5 , 2 5 , 2 5 ) ;
  12656.               I f ARect . Equals ( BRect ) Then
  12657.                    Writeln ( ' ARect equals BRect ' )
  12658.               Else
  12659.  
  12660.                                                                213
  12661.  
  12662.  
  12663.  
  12664.                                                                              11.5. TOBJECT
  12665.  
  12666.  
  12667.                     Writeln ( ' ARect does not equal BRect ! ' ) ;
  12668.            end .
  12669.  
  12670.  
  12671.            TRect.Grow
  12672. Declaration: Procedure TRect.Grow (ADX, ADY: Sw Integer);
  12673.  
  12674. Description: Grow expands the rectangle with an amount ADX in the X direction (both on the
  12675.            left and right side of the rectangle, thus adding a length 2*ADX to the width of the
  12676.            rectangle), and an amount ADY in the Y direction (both on the top and the bottom
  12677.            side of the rectangle, adding a length 2*ADY to the height of the rectangle.
  12678.            ADX and ADY can be negative. If the resulting rectangle is empty, it is set to the
  12679.            empty rectangle at (0,0).
  12680.  
  12681.      Errors: None.
  12682.  
  12683.   See also: Move (213).
  12684.  
  12685.            Program ex6 ;
  12686.  
  12687.            { Program to demonstrate TRect . Grow }
  12688.  
  12689.            Uses o b j e c t s ;
  12690.  
  12691.  
  12692.            Var ARect , BRect : TRect ;
  12693.  
  12694.            begin
  12695.               ARect . Assign ( 1 0 , 1 0 , 2 0 , 2 0 ) ;
  12696.               ARect . Grow ( 5 , 5 ) ;
  12697.               // Brect should be where new ARect i s .
  12698.               BRect . Assign ( 5 , 5 , 2 5 , 2 5 ) ;
  12699.               I f ARect . Equals ( BRect ) Then
  12700.                     Writeln ( ' ARect equals BRect ' )
  12701.               Else
  12702.                     Writeln ( ' ARect does not equal BRect ! ' ) ;
  12703.            end .
  12704.  
  12705.  
  12706.            TRect.Assign
  12707. Declaration: Procedure Trect.Assign (XA, YA, XB, YB: Sw Integer);
  12708.  
  12709. Description: Assign sets the corner points of the rectangle to (XA,YA) and (Xb,Yb).
  12710.  
  12711.      Errors: None.
  12712.  
  12713.   See also: Copy (211)
  12714.  
  12715.            For an example, see TRect.Copy (211).
  12716.  
  12717.  
  12718.            11.5 TObject
  12719.  
  12720.            The full declaration of the TObject type is:
  12721.  
  12722.                                                             214
  12723.  
  12724.  
  12725.  
  12726.                                                                               11.5. TOBJECT
  12727.  
  12728.  
  12729.            TYPETObject = OBJECT
  12730.                       CONSTRUCTOR Init;
  12731.                       PROCEDURE Free;
  12732.                       DESTRUCTOR Done;Virtual;
  12733.                END;
  12734.                PObject = ^TObject;
  12735.  
  12736.  
  12737.            TObject.Init
  12738. Declaration: Constructor TObject.Init;
  12739.  
  12740. Description: Instantiates a new object of type TObject. It fills the instance up with Zero bytes.
  12741.  
  12742.      Errors: None.
  12743.  
  12744.    See also: Free (215), Done (215)
  12745.  
  12746.            For an example, see Free (215)
  12747.  
  12748.  
  12749.            TObject.Free
  12750. Declaration: Procedure TObject.Free;
  12751.  
  12752. Description: Free calls the destructor of the object, and releases the memory occupied by the
  12753.            instance of the object.
  12754.  
  12755.      Errors: No checking is performed to see whether self is nil and whether the object is
  12756.            indeed allocated on the heap.
  12757.  
  12758.    See also: Init (215), Done (215)
  12759.  
  12760.            program ex7 ;
  12761.  
  12762.            { Program to demonstrate the TObject . Free c a l l }
  12763.  
  12764.            Uses Objects ;
  12765.  
  12766.            Var O : PObject ;
  12767.  
  12768.            begin
  12769.               Writeln ( ' Memavail : ' , Memavail ) ;
  12770.               // A l l o c a t e memory for object .
  12771.               O:=New( PObject , I n i t ) ;
  12772.               Writeln ( ' Memavail : ' , Memavail ) ;
  12773.               // Free memory of object .
  12774.               O . free ;
  12775.               Writeln ( ' Memavail : ' , Memavail ) ;
  12776.            end .
  12777.  
  12778.  
  12779.            TObject.Done
  12780. Declaration: Destructor TObject.Done;Virtual;
  12781.  
  12782.  
  12783.                                                     215
  12784.  
  12785.  
  12786.  
  12787.                                                                              11.6. TSTREAM
  12788.  
  12789.  
  12790. Description: Done, the destructor of TObject does nothing. It is mainly intended to be used in
  12791.             the TObject.Free (215) method.
  12792.             The destructore Done does not free the memory occupied by the object.
  12793.  
  12794.      Errors: None.
  12795.  
  12796.    See also: Free (215), Init (215)
  12797.  
  12798.             program ex8 ;
  12799.  
  12800.             { Program to demonstrate the TObject . Done c a l l }
  12801.  
  12802.             Uses Objects ;
  12803.  
  12804.             Var O : PObject ;
  12805.  
  12806.             begin
  12807.                Writeln ( ' Memavail : ' , Memavail ) ;
  12808.                // A l l o c a t e memory for object .
  12809.               O:=New( PObject , I n i t ) ;
  12810.                Writeln ( ' Memavail : ' , Memavail ) ;
  12811.               O . Done ;
  12812.                Writeln ( ' Memavail : ' , Memavail ) ;
  12813.             end .
  12814.  
  12815.  
  12816.             11.6 TStream
  12817.  
  12818.             The TStream object is the ancestor for all streaming objects, i.e. objects that have
  12819.             the capability to store and retrieve data.
  12820.             It defines a number of methods that are common to all objects that implement
  12821.             streaming, many of them are virtual, and are only implemented in the descendrnt
  12822.             types.
  12823.             Programs should not instantiate objects of type TStream directly, but instead in-
  12824.             stantiate a descendant type, such as TDosStream, TMemoryStream.
  12825.             This is the full declaration of the TStream object:
  12826.  
  12827.             TYPETStream = OBJECT (TObject)
  12828.                          Status        : Integer; { Stream status }
  12829.                          ErrorInfo : Integer; { Stream error info }
  12830.                          StreamSize: LongInt; { Stream current size }
  12831.                          Position : LongInt; { Current position }
  12832.                       FUNCTION Get: PObject;
  12833.                       FUNCTION StrRead: PChar;
  12834.                       FUNCTION GetPos: Longint; Virtual;
  12835.                       FUNCTION GetSize: Longint; Virtual;
  12836.                       FUNCTION ReadStr: PString;
  12837.                       PROCEDURE Open (OpenMode: Word); Virtual;
  12838.                       PROCEDURE Close; Virtual;
  12839.                       PROCEDURE Reset;
  12840.                       PROCEDURE Flush; Virtual;
  12841.                       PROCEDURE Truncate; Virtual;
  12842.  
  12843.                                                     216
  12844.  
  12845.  
  12846.  
  12847.                                                                                       11.6. TSTREAM
  12848.  
  12849.  
  12850.                      PROCEDURE Put (P: PObject);
  12851.                      PROCEDURE StrWrite (P: PChar);
  12852.                      PROCEDURE WriteStr (P: PString);
  12853.                      PROCEDURE Seek (Pos: LongInt); Virtual;
  12854.                      PROCEDURE Error (Code, Info: Integer); Virtual;
  12855.                      PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
  12856.                      PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
  12857.                      PROCEDURE CopyFrom (Var S: TStream; Count: Longint);
  12858.                END;
  12859.                PStream = ^TStream;
  12860.  
  12861.  
  12862.            TStream.Get
  12863. Declaration: Function TStream.Get : PObject;
  12864. Description: Get reads an object definition from a stream, and returns a pointer to an instance
  12865.            of this object.
  12866.      Errors: On error, TStream.Status is set, and NIL is returned.
  12867.    See also: Put (221)
  12868.  
  12869.            Program ex9 ;
  12870.  
  12871.            { Program to demonstrate TStream . Get and TStream . Put }
  12872.  
  12873.            Uses Objects , MyObject ;                { D e f i n i t i o n and r e g i s t r a t i o n of TMyObject }
  12874.  
  12875.            Var Obj : PMyObject ;
  12876.                     S : PStream ;
  12877.  
  12878.            begin
  12879.               Obj :=New( PMyObject , I n i t ) ;
  12880.               Obj  . S e t F i e l d ( $1111 ) ;
  12881.               Writeln ( ' F i e l d value : ' , Obj  . G e t F i e l d ) ;
  12882.               { Since Stream i s an a b s t r a c t type , we i n s t a n t i a t e a TMemoryStream }
  12883.               S:=New( PMemoryStream , I n i t ( 1 0 0 , 1 0 ) ) ;
  12884.               S  . Put ( Obj ) ;
  12885.               Writeln ( ' Disposing o b j e c t ' ) ;
  12886.               S  . Seek ( 0 ) ;
  12887.               Dispose ( Obj , Done ) ;
  12888.               Writeln ( ' Reading o b j e c t ' ) ;
  12889.               Obj := PMyObject ( S  . Get ) ;
  12890.               Writeln ( ' F i e l d Value : ' , Obj  . G e t F i e l d ) ;
  12891.               Dispose ( Obj , Done ) ;
  12892.            end .
  12893.  
  12894.  
  12895.            TStream.StrRead
  12896. Declaration: Function TStream.StrRead: PChar;
  12897. Description: StrRead reads a string from the stream, allocates memory for it, and returns a
  12898.            pointer to a null-terminated copy of the string on the heap.
  12899.      Errors: On error, Nil is returned.
  12900.  
  12901.                                                            217
  12902.  
  12903.  
  12904.  
  12905.                                                                                   11.6. TSTREAM
  12906.  
  12907.  
  12908.    See also: StrWrite (221), ReadStr (219)
  12909.  
  12910.            Program ex10 ;
  12911.  
  12912.            {Program to demonstrate the TStream. StrRead TStream. StrWrite functions
  12913.            }
  12914.  
  12915.            Uses o b j e c t s ;
  12916.  
  12917.            Var P : PChar ;
  12918.                     S : PStream ;
  12919.  
  12920.            begin
  12921.                 P:= ' Constant Pchar s t r i n g ' ;
  12922.                 Writeln ( ' Writing to stream : " ' , P, ' " ' ) ;
  12923.                 S:=New( PMemoryStream , I n i t ( 1 0 0 , 1 0 ) ) ;
  12924.                 S  . StrWrite (P) ;
  12925.                 S  . Seek ( 0 ) ;
  12926.                 P:= Nil ;
  12927.                 P:=S  . StrRead ;
  12928.                 DisPose ( S , Done ) ;
  12929.                 Writeln ( ' Read from stream : " ' , P, ' " ' ) ;
  12930.                 Freemem(P, Strlen (P)+1);
  12931.            end .
  12932.  
  12933.  
  12934.            TStream.GetPos
  12935. Declaration: TSTream.GetPos : Longint; Virtual;
  12936.  
  12937. Description: If the stream's status is stOk, GetPos returns the current position in the stream.
  12938.            Otherwise it returns -1
  12939.  
  12940.      Errors: -1 is returned if the status is an error condition.
  12941.  
  12942.    See also: Seek (222), GetSize (219)
  12943.  
  12944.            Program ex11 ;
  12945.  
  12946.            { Program to demonstrate the TStream . GetPos f u n c t i o n }
  12947.  
  12948.            Uses o b j e c t s ;
  12949.  
  12950.            Var L : String ;
  12951.                     S : PStream ;
  12952.  
  12953.            begin
  12954.                 L:= ' Some kind of s t r i n g ' ;
  12955.                 S:=New( PMemoryStream , I n i t ( 1 0 0 , 1 0 ) ) ;
  12956.                 Writeln ( ' Stream p o s i t i o n b e f o r e w r i t e : ' , S  . GetPos ) ;
  12957.                 S  . WriteStr ( @L) ;
  12958.                 Writeln ( ' Stream p o s i t i o n a f t e r w r i t e : ' , S  . GetPos ) ;
  12959.                 Dispose ( S , Done ) ;
  12960.            end .
  12961.  
  12962.  
  12963.                                                         218
  12964.  
  12965.  
  12966.  
  12967.                                                                                 11.6. TSTREAM
  12968.  
  12969.  
  12970.            TStream.GetSize
  12971. Declaration: Function TStream.GetSize: Longint; Virtual;
  12972.  
  12973. Description: If the stream's status is stOk then GetSize returns the size of the stream, otherwise
  12974.            it returns -1.
  12975.  
  12976.      Errors: -1 is returned if the status is an error condition.
  12977.  
  12978.    See also: Seek (222), GetPos (218)
  12979.  
  12980.            Program ex12 ;
  12981.  
  12982.             { Program to demonstrate the TStream . GetSize f u n c t i o n }
  12983.  
  12984.            Uses o b j e c t s ;
  12985.  
  12986.            Var L : String ;
  12987.                     S : PStream ;
  12988.  
  12989.             begin
  12990.                 L:= ' Some kind of s t r i n g ' ;
  12991.                 S:=New( PMemoryStream , I n i t ( 1 0 0 , 1 0 ) ) ;
  12992.                 Writeln ( ' Stream s i z e b e f o r e w r i t e : ' , S  . GetSize ) ;
  12993.                 S  . WriteStr ( @L) ;
  12994.                 Writeln ( ' Stream s i z e a f t e r w r i t e : ' , S  . GetSize ) ;
  12995.                 Dispose ( S , Done ) ;
  12996.            end .
  12997.  
  12998.  
  12999.            TStream.ReadStr
  13000. Declaration: Function TStream.ReadStr: PString;
  13001.  
  13002. Description: ReadStr reads a string from the stream, copies it to the heap and returns a pointer
  13003.            to this copy. The string is saved as a pascal string, and hence is NOT null termi-
  13004.            nated.
  13005.  
  13006.      Errors: On error (e.g. not enough memory), Nil is returned.
  13007.  
  13008.    See also: StrRead (217)
  13009.  
  13010.            Program ex13 ;
  13011.  
  13012.            {Program to demonstrate the TStream. ReadStr TStream. WriteStr functions
  13013.            }
  13014.  
  13015.            Uses o b j e c t s ;
  13016.  
  13017.            Var P : PString ;
  13018.                     L : String ;
  13019.                     S : PStream ;
  13020.  
  13021.             begin
  13022.                 L:= ' Constant s t r i n g l i n e ' ;
  13023.                 Writeln ( ' Writing to stream : " ' , L , ' " ' ) ;
  13024.  
  13025.                                                           219
  13026.  
  13027.  
  13028.  
  13029.                                                                               11.6. TSTREAM
  13030.  
  13031.  
  13032.               S:=New( PMemoryStream , I n i t ( 1 0 0 , 1 0 ) ) ;
  13033.               S  . WriteStr ( @L) ;
  13034.               S  . Seek ( 0 ) ;
  13035.               P:=S  . ReadStr ;
  13036.               L:=P ;
  13037.               DisposeStr (P) ;
  13038.               DisPose ( S , Done ) ;
  13039.               Writeln ( ' Read from stream : " ' , L , ' " ' ) ;
  13040.            end .
  13041.  
  13042.  
  13043.            TStream.Open
  13044. Declaration: Procedure TStream.Open (OpenMode: Word); Virtual;
  13045.  
  13046. Description: Open is an abstract method, that should be overridden by descendent objects.
  13047.            Since opening a stream depends on the stream's type this is not surprising.
  13048.  
  13049.      Errors: None.
  13050.  
  13051.    See also: Close (220), Reset (220)
  13052.  
  13053.            For an example, see TDosStream.Open (227).
  13054.  
  13055.  
  13056.            TStream.Close
  13057. Declaration: Procedure TStream.Close; Virtual;
  13058.  
  13059. Description: Close is an abstract method, that should be overridden by descendent objects.
  13060.            Since Closing a stream depends on the stream's type this is not surprising.
  13061.  
  13062.      Errors: None.
  13063.  
  13064.    See also: Open (220), Reset (220)
  13065.  
  13066.            for an example, see TDosStream.Open (227).
  13067.  
  13068.  
  13069.            TStream.Reset
  13070. Declaration: PROCEDURE TStream.Reset;
  13071.  
  13072. Description: Reset sets the stream's status to 0, as well as the ErrorInfo
  13073.  
  13074.      Errors: None.
  13075.  
  13076.    See also: Open (220), Close (220)
  13077.  
  13078.  
  13079.            TStream.Flush
  13080. Declaration: Procedure TStream.Flush; Virtual;
  13081.  
  13082. Description: Flush is an abstract method that should be overridden by descendent objects. It
  13083.            serves to enable the programmer to tell streams that implement a bu er to clear
  13084.            the bu er.
  13085.  
  13086.      Errors: None.
  13087.  
  13088.                                                      220
  13089.  
  13090.  
  13091.  
  13092.                                                                             11.6. TSTREAM
  13093.  
  13094.  
  13095.    See also: Truncate (221)
  13096.  
  13097.            for an example, see TBufStream.Flush (230).
  13098.  
  13099.  
  13100.            TStream.Truncate
  13101. Declaration: Procedure TStream.Truncate; Virtual;
  13102. Description: Truncate is an abstract procedure that should be overridden by descendent ob-
  13103.            jects. It serves to enable the programmer to truncate the size of the stream to the
  13104.            current file position.
  13105.      Errors: None.
  13106.    See also: Seek (222)
  13107.  
  13108.            For an example, see TDosStream.Truncate (225).
  13109.  
  13110.  
  13111.            TStream.Put
  13112. Declaration: Procedure TStream.Put (P: PObject);
  13113. Description: Put writes the object pointed to by P. P should be non-nil. The object type must
  13114.            have been registered with RegisterType (207).
  13115.            After the object has been written, it can be read again with Get (217).
  13116.      Errors: No check is done whether P is Nil or not. Passing Nil will cause a run-time error
  13117.            216 to be generated. If the object has not been registered, the status of the stream
  13118.            will be set to stPutError.
  13119.    See also: Get (217)
  13120.  
  13121.            For an example, see TStream.Get (217);
  13122.  
  13123.  
  13124.            TStream.StrWrite
  13125. Declaration: Procedure TStream.StrWrite (P: PChar);
  13126. Description: StrWrite writes the null-terminated string P to the stream. P can only be 65355
  13127.            bytes long.
  13128.      Errors: None.
  13129.    See also: WriteStr (221), StrRead (217), ReadStr (219)
  13130.  
  13131.            For an example, see TStream.StrRead (217).
  13132.  
  13133.  
  13134.            TStream.WriteStr
  13135. Declaration: Procedure TStream.WriteStr (P: PString);
  13136. Description: StrWrite writes the pascal string pointed to by P to the stream.
  13137.      Errors: None.
  13138.    See also: StrWrite (221), StrRead (217), ReadStr (219)
  13139.  
  13140.            For an example, see TStream.ReadStr (219).
  13141.  
  13142.                                                      221
  13143.  
  13144.  
  13145.  
  13146.                                                                              11.6. TSTREAM
  13147.  
  13148.  
  13149.            TStream.Seek
  13150. Declaration: PROCEDURE TStream.Seek (Pos: LongInt); Virtual;
  13151.  
  13152. Description: Seek sets the position to Pos. This position is counted from the beginning, and is
  13153.            zero based. (i.e. seeek(0) sets the position pointer on the first byte of the stream)
  13154.  
  13155.      Errors: If Pos is larger than the stream size, Status is set to StSeekError.
  13156.  
  13157.    See also: GetPos (218), GetSize (219)
  13158.  
  13159.            For an example, see TDosStream.Seek (226).
  13160.  
  13161.  
  13162.            TStream.Error
  13163. Declaration: Procedure TStream.Error (Code, Info: Integer); Virtual;
  13164.  
  13165. Description: Error sets the stream's status to Code and ErrorInfo to Info. If the StreamError
  13166.            procedural variable is set, Error executes it, passing Self as an argument.
  13167.            This method should not be called directly from a program. It is intended to be
  13168.            used in descendent objects.
  13169.  
  13170.      Errors: None.
  13171.  
  13172.    See also:
  13173.  
  13174.  
  13175.            TStream.Read
  13176. Declaration: Procedure TStream.Read (Var Buf; Count: Sw Word); Virtual;
  13177.  
  13178. Description: Read is an abstract method that should be overridden by descendent objects.
  13179.            Read reads Count bytes from the stream into Buf. It updates the position pointer,
  13180.            increasing it's value with Count. Buf must be large enough to contain Count bytes.
  13181.  
  13182.      Errors: No checking is done to see if Buf is large enough to contain Count bytes.
  13183.  
  13184.    See also: Write (223), ReadStr (219), StrRead (217)
  13185.  
  13186.                 program ex18 ;
  13187.  
  13188.                 { Program to demonstrate the TStream . Read method }
  13189.  
  13190.                 Uses Objects ;
  13191.  
  13192.                 Var Buf1 , Buf2 : Array [ 1 . . 1 0 0 0 ] of Byte ;
  13193.                      I : l o n g i n t ;
  13194.                      S : PMemorySTream ;
  13195.  
  13196.                 begin
  13197.                   For I :=1 to 1000 do
  13198.                      Buf1 [ I ]:= Random(1000);
  13199.                   Buf2 := Buf1 ;
  13200.                   S:=New( PMemoryStream , I n i t ( 1 0 0 , 1 0 ) ) ;
  13201.                   S  . Write ( Buf1 , SizeOf ( Buf1 ) ) ;
  13202.                   S  . Seek ( 0 ) ;
  13203.                   For I :=1 to 1000 do
  13204.  
  13205.                                                          222
  13206.  
  13207.  
  13208.  
  13209.                                                                                   11.6. TSTREAM
  13210.  
  13211.  
  13212.                     Buf1 [ I ]:=0;
  13213.               S  . Read( Buf1 , SizeOf ( Buf1 ) ) ;
  13214.               For I :=1 to 1000 do
  13215.                     I f Buf1 [ I ]<>buf2 [ i ] then
  13216.                       Writeln ( ' Buffer d i f f e r s at p o s i t i o n ' , I ) ;
  13217.               Dispose ( S , Done ) ;
  13218.            end .
  13219.  
  13220.  
  13221.            TStream.Write
  13222. Declaration: Procedure TStream.Write (Var Buf; Count: Sw Word); Virtual;
  13223.  
  13224. Description: Write is an abstract method that should be overridden by descendent objects.
  13225.            Write writes Count bytes to the stream from Buf. It updates the position pointer,
  13226.            increasing it's value with Count.
  13227.  
  13228.     Errors: No checking is done to see if Buf actually contains Count bytes.
  13229.  
  13230.   See also: Read (222), WriteStr (221), StrWrite (221)
  13231.  
  13232.            For an example, see TStream.Read (222).
  13233.  
  13234.  
  13235.            TStream.CopyFrom
  13236. Declaration: Procedure TStream.CopyFrom (Var S: TStream; Count: Longint);
  13237.  
  13238. Description: CopyFrom reads Count bytes from stream S and stores them in the current stream.
  13239.            It uses the Read (222) method to read the data, and the Write (223) method to
  13240.            write in the current stream.
  13241.  
  13242.     Errors: None.
  13243.  
  13244.   See also: Read (222), Write (223)
  13245.  
  13246.            Program ex19 ;
  13247.  
  13248.            { Program to demonstrate the TStream . CopyFrom f u n c t i o n }
  13249.  
  13250.            Uses o b j e c t s ;
  13251.  
  13252.            Var P : PString ;
  13253.                     L : String ;
  13254.                     S1 , S2 : PStream ;
  13255.  
  13256.            begin
  13257.               L:= ' Constant s t r i n g l i n e ' ;
  13258.               Writeln ( ' Writing to stream 1 : " ' , L , ' " ' ) ;
  13259.               S1:=New( PMemoryStream , I n i t ( 1 0 0 , 1 0 ) ) ;
  13260.               S2:=New( PMemoryStream , I n i t ( 1 0 0 , 1 0 ) ) ;
  13261.               S1  . WriteStr ( @L) ;
  13262.               S1  . Seek ( 0 ) ;
  13263.               Writeln ( ' Copying contents of stream 1 to stream 2' ) ;
  13264.               S2  . Copyfrom ( S1  , S1  . GetSize ) ;
  13265.               S2  . Seek ( 0 ) ;
  13266.  
  13267.                                                         223
  13268.  
  13269.  
  13270.  
  13271.                                                                         11.7. TDOSSTREAM
  13272.  
  13273.  
  13274.              P:=S2  . ReadStr ;
  13275.              L:=P ;
  13276.               DisposeStr (P) ;
  13277.               Dispose ( S1 , Done ) ;
  13278.               Dispose ( S2 , Done ) ;
  13279.               Writeln ( ' Read from stream 2 : " ' , L , ' " ' ) ;
  13280.            end .
  13281.  
  13282.  
  13283.            11.7 TDosStream
  13284.  
  13285.            TDosStream is a stream that stores it's contents in a file. it overrides a couple of
  13286.            methods of TSteam for this.
  13287.            In addition to the fields inherited from TStream (see section 11.6, page 216), there
  13288.            are some extra fields, that describe the file. (mainly the name and the OS file
  13289.            handle)
  13290.            No bu ering in memory is done when using TDosStream. All data are written
  13291.            directly to the file. For a stream that bu ers in memory, see section 11.8, page 228.
  13292.            Here is the full declaration of the TDosStream object:
  13293.  
  13294.            TYPETDosStream = OBJECT (TStream)
  13295.                        Handle: THandle; { DOS file handle }
  13296.                        FName : AsciiZ; { AsciiZ filename }
  13297.                     CONSTRUCTOR Init (FileName: FNameStr; Mode: Word);
  13298.                     DESTRUCTOR Done; Virtual;
  13299.                     PROCEDURE Close; Virtual;
  13300.                     PROCEDURE Truncate; Virtual;
  13301.                     PROCEDURE Seek (Pos: LongInt); Virtual;
  13302.                     PROCEDURE Open (OpenMode: Word); Virtual;
  13303.                     PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
  13304.                     PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
  13305.               END;
  13306.               PDosStream = ^TDosStream;
  13307.  
  13308.  
  13309.            TDosStream.Init
  13310. Declaration: Constructor Init (FileName: FNameStr; Mode: Word);
  13311.  
  13312. Description: Init instantiates an instance of TDosStream. The name of the file that contains
  13313.            (or will contain) the data of the stream is given in FileName. The Mode parameter
  13314.            determines whether a new file should be created and what access rights you have
  13315.            on the file. It can be one of the following constants:
  13316.  
  13317.            stCreateCreates a new file.
  13318.            stOpenReadRead access only.
  13319.            stOpenWriteWrite access only.
  13320.            stOpenRead and write access.
  13321.  
  13322.     Errors: On error, Status is set to stInitError, and ErrorInfo is set to the dos error
  13323.            code.
  13324.  
  13325.  
  13326.                                                     224
  13327.  
  13328.  
  13329.  
  13330.                                                                                  11.7. TDOSSTREAM
  13331.  
  13332.  
  13333.    See also: Done (225)
  13334.  
  13335.            For an example, see TDosStream.Truncate (225).
  13336.  
  13337.  
  13338.            TDosStream.Done
  13339. Declaration: Destructor TDosStream.Done; Virtual;
  13340.  
  13341. Description: Done closes the file if it was open and cleans up the instance of TDosStream.
  13342.  
  13343.      Errors: None.
  13344.  
  13345.    See also: Init (224), Close (225)
  13346.  
  13347.            for an example, see e.g. TDosStream.Truncate (225).
  13348.  
  13349.  
  13350.            TDosStream.Close
  13351. Declaration: Pocedure TDosStream.Close; Virtual;
  13352.  
  13353. Description: Close closes the file if it was open, and sets Handle to -1. Contrary to Done (225)
  13354.            it does not clean up the instance of TDosStream
  13355.  
  13356.      Errors: None.
  13357.  
  13358.    See also: TStream.Close (220), Init (224), Done (225)
  13359.  
  13360.            For an example, see TDosStream.Open (227).
  13361.  
  13362.  
  13363.            TDosStream.Truncate
  13364. Declaration: Procedure TDosStream.Truncate; Virtual;
  13365.  
  13366. Description: If the status of the stream is stOK, then Truncate tries to truncate the stream size
  13367.            to the current file position.
  13368.  
  13369.      Errors: If an error occurs, the stream's status is set to stError and ErrorInfo is set to
  13370.            the OS error code.
  13371.  
  13372.    See also: TStream.Truncate (221), GetSize (219)
  13373.  
  13374.             Program ex16 ;
  13375.  
  13376.             { Program to demonstrate the TStream . Truncate method }
  13377.  
  13378.             Uses Objects ;
  13379.  
  13380.             Var L : String ;
  13381.                  P : PString ;
  13382.                  S : PDosStream ; { Only one with Truncate implemented . }
  13383.  
  13384.             begin
  13385.               L:= ' Some constant s t r i n g ' ;
  13386.                { Buffer s i z e of 100 }
  13387.               S:=New( PDosStream , I n i t ( ' t e s t . dat ' , s t c r e a t e ) ) ;
  13388.  
  13389.                                                          225
  13390.  
  13391.  
  13392.  
  13393.                                                                                  11.7. TDOSSTREAM
  13394.  
  13395.  
  13396.               Writeln ( ' Writing "' , L , '" to stream with handle ' , S  . Handle ) ;
  13397.               S  . WriteStr ( @L) ;
  13398.               S  . WriteStr ( @L) ;
  13399.               { Close c a l l s f l u s h f i r s t }
  13400.               S  . Close ;
  13401.               S  . Open ( stOpen ) ;
  13402.               Writeln ( ' Size of stream i s : ' , S  . GetSize ) ;
  13403.               P:=S  . ReadStr ;
  13404.               L:=P ;
  13405.               DisposeStr (P) ;
  13406.               Writeln ( ' Read "' , L , '" from stream with handle ' , S  . Handle ) ;
  13407.               S  . Truncate ;
  13408.               Writeln ( ' Truncated stream . Size i s : ' , S  . GetSize ) ;
  13409.               S  . Close ;
  13410.               Dispose ( S , Done ) ;
  13411.            end .
  13412.  
  13413.  
  13414.            TDosStream.Seek
  13415. Declaration: Procedure TDosStream.Seek (Pos: LongInt); Virtual;
  13416.  
  13417. Description: If the stream's status is stOK, then Seek sets the file position to Pos. Pos is a
  13418.            zero-based o set, counted from the beginning of the file.
  13419.  
  13420.      Errors: In case an error occurs, the stream's status is set to stSeekError, and the OS
  13421.            error code is stored in ErrorInfo.
  13422.  
  13423.    See also: TStream.Seek (222), GetPos (218)
  13424.  
  13425.            Program ex17 ;
  13426.  
  13427.            { Program to demonstrate the TStream . Seek method }
  13428.  
  13429.            Uses Objects ;
  13430.  
  13431.            Var L : String ;
  13432.                     Marker : Word ;
  13433.                     P : PString ;
  13434.                     S : PDosStream ;
  13435.  
  13436.            begin
  13437.               L:= ' Some constant s t r i n g ' ;
  13438.               { Buffer s i z e of 100 }
  13439.               S:=New( PDosStream , I n i t ( ' t e s t . dat ' , s t c r e a t e ) ) ;
  13440.               Writeln ( ' Writing "' , L , '" to stream . ' ) ;
  13441.               S  . WriteStr ( @L) ;
  13442.               Marker :=S  . GetPos ;
  13443.               Writeln ( ' Set marker at ' , Marker ) ;
  13444.               L:= ' Some other constant S t r i n g ' ;
  13445.               Writeln ( ' Writing "' , L , '" to stream . ' ) ;
  13446.               S  . WriteStr ( @L) ;
  13447.               S  . Close ;
  13448.               S  . Open ( stOpenRead ) ;
  13449.               Writeln ( ' Size of stream i s : ' , S  . GetSize ) ;
  13450.  
  13451.                                                          226
  13452.  
  13453.  
  13454.  
  13455.                                                                                  11.7. TDOSSTREAM
  13456.  
  13457.  
  13458.               Writeln ( ' Seeking to marker ' ) ;
  13459.               S  . Seek ( Marker ) ;
  13460.               P:=S  . ReadStr ;
  13461.               L:=P ;
  13462.               DisposeStr (P) ;
  13463.               Writeln ( ' Read "' , L , '" from stream . ' ) ;
  13464.               S  . Close ;
  13465.               Dispose ( S , Done ) ;
  13466.            end .
  13467.  
  13468.  
  13469.            TDosStream.Open
  13470. Declaration: Procedure TDosStream.Open (OpenMode: Word); Virtual;
  13471.  
  13472. Description: If the stream's status is stOK, and the stream is closed then Open re-opens the file
  13473.            stream with mode OpenMode. This call can be used after a Close (225) call.
  13474.  
  13475.      Errors: If an error occurs when re-opening the file, then Status is set to stOpenError,
  13476.            and the OS error code is stored in ErrorInfo
  13477.  
  13478.    See also: TStream.Open (220), Close (225)
  13479.  
  13480.            Program ex14 ;
  13481.  
  13482.            { Program to demonstrate the TStream . Close method }
  13483.  
  13484.            Uses Objects ;
  13485.  
  13486.            Var L : String ;
  13487.                     P : PString ;
  13488.                     S : PDosStream ; { Only one with Close implemented . }
  13489.  
  13490.            begin
  13491.               L:= ' Some constant s t r i n g ' ;
  13492.               S:=New( PDosStream , I n i t ( ' t e s t . dat ' , s t c r e a t e ) ) ;
  13493.               Writeln ( ' Writing "' , L , '" to stream with handle ' , S  . Handle ) ;
  13494.               S  . WriteStr ( @L) ;
  13495.               S  . Close ;
  13496.               Writeln ( ' Closed stream . F i l e handle i s ' , S  . Handle ) ;
  13497.               S  . Open ( stOpenRead ) ;
  13498.               P:=S  . ReadStr ;
  13499.               L:=P ;
  13500.               DisposeStr (P) ;
  13501.               Writeln ( ' Read "' , L , '" from stream with handle ' , S  . Handle ) ;
  13502.               S  . Close ;
  13503.               Dispose ( S , Done ) ;
  13504.            end .
  13505.  
  13506.  
  13507.            TDosStream.Read
  13508. Declaration: Procedure TDosStream.Read (Var Buf; Count: Sw Word); Virtual;
  13509.  
  13510. Description: If the Stream is open and the stream status is stOK then Read will read Count
  13511.            bytes from the stream and place them in Buf.
  13512.  
  13513.                                                          227
  13514.  
  13515.  
  13516.  
  13517.                                                                             11.8. TBUFSTREAM
  13518.  
  13519.  
  13520.     Errors: In case of an error, Status is set to StReadError, and ErrorInfo gets the OS
  13521.            specific error, or 0 when an attempt was made to read beyond the end of the
  13522.            stream.
  13523.  
  13524.   See also: TStream.Read (222), Write (228)
  13525.  
  13526.            For an example, see TStream.Read (222).
  13527.  
  13528.  
  13529.            TDosStream.Write
  13530. Declaration: Procedure TDosStream.Write (Var Buf; Count: Sw Word); Virtual;
  13531.  
  13532. Description: If the Stream is open and the stream status is stOK then Write will write Count
  13533.            bytes from Buf and place them in the stream.
  13534.  
  13535.     Errors: In case of an error, Status is set to StWriteError, and ErrorInfo gets the OS
  13536.            specific error.
  13537.  
  13538.   See also: TStream.Write (223), Read (227)
  13539.  
  13540.            For an example, see TStream.Read (222).
  13541.  
  13542.  
  13543.            11.8 TBufStream
  13544.  
  13545.            Bufstream implements a bu ered file stream. That is, all data written to the stream
  13546.            is written to memory first. Only when the bu er is full, or on explicit request, the
  13547.            data is written to disk.
  13548.            Also, when reading from the stream, first the bu er is checked if there is any unread
  13549.            data in it. If so, this is read first. If not the bu er is filled again, and then the data
  13550.            is read from the bu er.
  13551.            The size of the bu er is fixed and is set when constructing the file.
  13552.            This is useful if you need heavy throughput for your stream, because it speeds up
  13553.            operations.
  13554.  
  13555.            TYPETBufStream = OBJECT (TDosStream)
  13556.                        LastMode: Byte;             { Last buffer mode }
  13557.                        BufSize : Sw_Word;          { Buffer size }
  13558.                        BufPtr : Sw_Word;           { Buffer start }
  13559.                        BufEnd : Sw_Word;           { Buffer end }
  13560.                        Buffer : PByteArray; { Buffer allocated }
  13561.                    CONSTRUCTOR Init (FileName: FNameStr; Mode, Size: Word);
  13562.                    DESTRUCTOR Done; Virtual;
  13563.                    PROCEDURE Close; Virtual;
  13564.                    PROCEDURE Flush; Virtual;
  13565.                    PROCEDURE Truncate; Virtual;
  13566.                    PROCEDURE Seek (Pos: LongInt); Virtual;
  13567.                    PROCEDURE Open (OpenMode: Word); Virtual;
  13568.                    PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
  13569.                    PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
  13570.                END;
  13571.                PBufStream = ^TBufStream;
  13572.  
  13573.                                                       228
  13574.  
  13575.  
  13576.  
  13577.                                                                        11.8. TBUFSTREAM
  13578.  
  13579.  
  13580.            TBufStream.Init
  13581. Declaration: Constructor Init (FileName: FNameStr; Mode,Size: Word);
  13582.  
  13583. Description: Init instantiates an instance of TBufStream. The name of the file that contains
  13584.            (or will contain) the data of the stream is given in FileName. The Mode parameter
  13585.            determines whether a new file should be created and what access rights you have
  13586.            on the file. It can be one of the following constants:
  13587.  
  13588.            stCreateCreates a new file.
  13589.            stOpenReadRead access only.
  13590.            stOpenWriteWrite access only.
  13591.            stOpenRead and write access.
  13592.  
  13593.            The Size parameter determines the size of the bu er that will be created. It should
  13594.            be di erent from zero.
  13595.  
  13596.      Errors: On error, Status is set to stInitError, and ErrorInfo is set to the dos error
  13597.            code.
  13598.  
  13599.    See also: TDosStream.Init (224), Done (229)
  13600.  
  13601.            For an example see TBufStream.Flush (230).
  13602.  
  13603.  
  13604.            TBufStream.Done
  13605. Declaration: Destructor TBufStream.Done; Virtual;
  13606.  
  13607. Description: Done flushes and closes the file if it was open and cleans up the instance of
  13608.            TBufStream.
  13609.  
  13610.      Errors: None.
  13611.  
  13612.    See also: TDosStream.Done (225), Init (229), Close (229)
  13613.  
  13614.            For an example see TBufStream.Flush (230).
  13615.  
  13616.  
  13617.            TBufStream.Close
  13618. Declaration: Pocedure TBufStream.Close; Virtual;
  13619.  
  13620. Description: Close flushes and closes the file if it was open, and sets Handle to -1. Contrary
  13621.            to Done (229) it does not clean up the instance of TBufStream
  13622.  
  13623.      Errors: None.
  13624.  
  13625.    See also: TStream.Close (220), Init (229), Done (229)
  13626.  
  13627.            For an example see TBufStream.Flush (230).
  13628.  
  13629.  
  13630.  
  13631.  
  13632.  
  13633.  
  13634.  
  13635.  
  13636.                                                     229
  13637.  
  13638.  
  13639.  
  13640.                                                                                   11.8. TBUFSTREAM
  13641.  
  13642.  
  13643.            TBufStream.Flush
  13644. Declaration: Pocedure TBufStream.Flush; Virtual;
  13645. Description: When the stream is in write mode, the contents of the bu er are written to disk,
  13646.            and the bu er position is set to zero.
  13647.            When the stream is in read mode, the bu er position is set to zero.
  13648.      Errors: Write errors may occur if the file was in write mode. see Write (231) for more info
  13649.            on the errors.
  13650.    See also: TStream.Close (220), Init (229), Done (229)
  13651.  
  13652.            Program ex15 ;
  13653.  
  13654.            { Program to demonstrate the TStream . Flush method }
  13655.  
  13656.            Uses Objects ;
  13657.  
  13658.            Var L : String ;
  13659.                     P : PString ;
  13660.                     S : PBufStream ; { Only one with Flush implemented . }
  13661.  
  13662.            begin
  13663.               L:= ' Some constant s t r i n g ' ;
  13664.               { Buffer s i z e of 100 }
  13665.               S:=New( PBufStream , I n i t ( ' t e s t . dat ' , s t c r e a t e , 1 0 0 ) ) ;
  13666.               Writeln ( ' Writing "' , L , '" to stream with handle ' , S  . Handle ) ;
  13667.               S  . WriteStr ( @L) ;
  13668.               { At t h i s moment , there i s no data on disk yet . }
  13669.               S  . Flush ;
  13670.               { Now there i s . }
  13671.               S  . WriteStr ( @L) ;
  13672.               { Close c a l l s f l u s h f i r s t }
  13673.               S  . Close ;
  13674.               Writeln ( ' Closed stream . F i l e handle i s ' , S  . Handle ) ;
  13675.               S  . Open ( stOpenRead ) ;
  13676.               P:=S  . ReadStr ;
  13677.               L:=P ;
  13678.               DisposeStr (P) ;
  13679.               Writeln ( ' Read "' , L , '" from stream with handle ' , S  . Handle ) ;
  13680.               S  . Close ;
  13681.               Dispose ( S , Done ) ;
  13682.            end .
  13683.  
  13684.  
  13685.            TBufStream.Truncate
  13686. Declaration: Procedure TBufStream.Truncate; Virtual;
  13687. Description: If the status of the stream is stOK, then Truncate tries to flush the bu er, and
  13688.            then truncates the stream size to the current file position.
  13689.      Errors: Errors can be those of Flush (230) or TDosStream.Truncate (225).
  13690.    See also: TStream.Truncate (221), TDosStream.Truncate (225), GetSize (219)
  13691.  
  13692.            For an example, see TDosStream.Truncate (225).
  13693.  
  13694.                                                           230
  13695.  
  13696.  
  13697.  
  13698.                                                                          11.8. TBUFSTREAM
  13699.  
  13700.  
  13701.            TBufStream.Seek
  13702. Declaration: Procedure TBufStream.Seek (Pos: LongInt); Virtual;
  13703.  
  13704. Description: If the stream's status is stOK, then Seek sets the file position to Pos. Pos is a
  13705.            zero-based o set, counted from the beginning of the file.
  13706.  
  13707.      Errors: In case an error occurs, the stream's status is set to stSeekError, and the OS
  13708.            error code is stored in ErrorInfo.
  13709.  
  13710.    See also: TStream.Seek (222), GetPos (218)
  13711.  
  13712.            For an example, see TStream.Seek (222);
  13713.  
  13714.  
  13715.            TBufStream.Open
  13716. Declaration: Procedure TBufStream.Open (OpenMode: Word); Virtual;
  13717.  
  13718. Description: If the stream's status is stOK, and the stream is closed then Open re-opens the file
  13719.            stream with mode OpenMode. This call can be used after a Close (229) call.
  13720.  
  13721.      Errors: If an error occurs when re-opening the file, then Status is set to stOpenError,
  13722.            and the OS error code is stored in ErrorInfo
  13723.  
  13724.    See also: TStream.Open (220), Close (229)
  13725.  
  13726.            For an example, see TDosStream.Open (227).
  13727.  
  13728.  
  13729.            TBufStream.Read
  13730. Declaration: Procedure TBufStream.Read (Var Buf; Count: Sw Word); Virtual;
  13731.  
  13732. Description: If the Stream is open and the stream status is stOK then Read will read Count
  13733.            bytes from the stream and place them in Buf.
  13734.            Read will first try to read the data from the stream's internal bu er. If insu cient
  13735.            data is available, the bu er will be filled before contiunuing to read. This process
  13736.            is repeated until all needed data has been read.
  13737.  
  13738.      Errors: In case of an error, Status is set to StReadError, and ErrorInfo gets the OS
  13739.            specific error, or 0 when an attempt was made to read beyond the end of the
  13740.            stream.
  13741.  
  13742.    See also: TStream.Read (222), Write (231)
  13743.  
  13744.            For an example, see TStream.Read (222).
  13745.  
  13746.  
  13747.            TBufStream.Write
  13748. Declaration: Procedure TBufStream.Write (Var Buf; Count: Sw Word); Virtual;
  13749.  
  13750. Description: If the Stream is open and the stream status is stOK then Write will write Count
  13751.            bytes from Buf and place them in the stream.
  13752.            Write will first try to write the data to the stream's internal bu er. When the
  13753.            internal bu er is full, then the contents will be written to disk. This process is
  13754.            repeated until all data has been written.
  13755.  
  13756.  
  13757.                                                     231
  13758.  
  13759.  
  13760.  
  13761.                                                                     11.9. TMEMORYSTREAM
  13762.  
  13763.  
  13764.     Errors: In case of an error, Status is set to StWriteError, and ErrorInfo gets the OS
  13765.            specific error.
  13766.   See also: TStream.Write (223), Read (231)
  13767.  
  13768.            For an example, see TStream.Read (222).
  13769.  
  13770.            11.9 TMemoryStream
  13771.  
  13772.            The TMemoryStream object implements a stream that stores it's data in memory.
  13773.            The data is stored on the heap, with the possibility to specify the maximum amout
  13774.            of data, and the the size of the memory blocks being used.
  13775.  
  13776.            TYPETMemoryStream = OBJECT (TStream)
  13777.                           BlkCount: Sw_Word;          { Number of segments }
  13778.                           BlkSize : Word;             { Memory block size }
  13779.                           MemSize : LongInt;          { Memory alloc size }
  13780.                           BlkList : PPointerArray; { Memory block list }
  13781.                      CONSTRUCTOR Init (ALimit: Longint; ABlockSize: Word);
  13782.                      DESTRUCTOR Done;                                                                  Virtual;
  13783.                      PROCEDURE Truncate;                                                               Virtual;
  13784.                      PROCEDURE Read (Var Buf; Count: Sw_Word);                                         Virtual;
  13785.                      PROCEDURE Write (Var Buf; Count: Sw_Word);                                        Virtual;
  13786.                END;
  13787.                PMemoryStream = ^TMemoryStream;
  13788.  
  13789.  
  13790.            TMemoryStream.Init
  13791. Declaration: Constructor TMemoryStream.Init (ALimit: Longint; ABlockSize: Word);
  13792. Description: Init instantiates a new TMemoryStream object. The memorystreamobject will
  13793.            initially allocate at least ALimit bytes memory, divided into memory blocks of size
  13794.            ABlockSize. The number of blocks needed to get to ALimit bytes is rounded up.
  13795.            By default, the number of blocks is 1, and the size of a block is 8192. This is selected
  13796.            if you specify 0 as the blocksize.
  13797.     Errors: If the stream cannot allocate the initial memory needed for the memory blocks,
  13798.            then the stream's status is set to stInitError.
  13799.   See also: Done (232)
  13800.  
  13801.            For an example, see e.g TStream.CopyFrom (223).
  13802.  
  13803.  
  13804.            TMemoryStream.Done
  13805. Declaration: Destructor TMemoryStream.Done; Virtual;
  13806. Description: Done releases the memory blocks used by the stream, and then cleans up the
  13807.            memory used by the stream object itself.
  13808.     Errors: None.
  13809.   See also: Init (232)
  13810.  
  13811.            For an example, see e.g TStream.CopyFrom (223).
  13812.  
  13813.                                                      232
  13814.  
  13815.  
  13816.  
  13817.                                                                         11.9. TMEMORYSTREAM
  13818.  
  13819.  
  13820.           TMemoryStream.Truncate
  13821. Declaration: Procedure TMemoryStream.Truncate; Virtual;
  13822.  
  13823. Description: Truncate sets the size of the memory stream equal to the current position. It
  13824.           de-allocates any memory-blocks that are no longer needed, so that the new size of
  13825.           the stream is the current position in the stream, rounded up to the first multiple of
  13826.           the stream blocksize.
  13827.  
  13828.     Errors: If an error occurs during memory de-allocation, the stream's status is set to
  13829.           stError
  13830.  
  13831.   See also: TStream.Truncate (221)
  13832.  
  13833.           Program ex20 ;
  13834.  
  13835.            { Program to demonstrate the TMemoryStream . Truncate method }
  13836.  
  13837.            Uses Objects ;
  13838.  
  13839.           Var L : String ;
  13840.                    P : PString ;
  13841.                    S : PMemoryStream ;
  13842.                    I , InitMem : Longint ;
  13843.  
  13844.            begin
  13845.              initMem :=Memavail ;
  13846.              L:= ' Some constant s t r i n g ' ;
  13847.              { Buffer s i z e of 100 }
  13848.              S:=New( PMemoryStream , I n i t ( 1 0 0 0 , 1 0 0 ) ) ;
  13849.              Writeln ( ' Free memory : ' , Memavail ) ;
  13850.              Writeln ( ' Writing 100 times "' , L , '" to stream . ' ) ;
  13851.              For I :=1 to 100 do
  13852.                    S  . WriteStr ( @L) ;
  13853.              Writeln ( ' F i n i s h e d . Free memory : ' , Memavail ) ;
  13854.              S  . Seek ( 1 0 0 ) ;
  13855.              S  . Truncate ;
  13856.              Writeln ( ' Truncated at byte 100. Free memory : ' , Memavail ) ;
  13857.              Dispose ( S , Done ) ;
  13858.              Writeln ( ' F i n i s h e d . Lost ' , InitMem-Memavail , ' Bytes . ' ) ;
  13859.           end .
  13860.  
  13861.  
  13862.           TMemoryStream.Read
  13863. Declaration: Procedure Read (Var Buf; Count: Sw Word); Virtual;
  13864.  
  13865. Description: Read reads Count bytes from the stream to Buf. It updates the position of the
  13866.           stream.
  13867.  
  13868.     Errors: If there is not enough data available, no data is read, and the stream's status is
  13869.           set to stReadError.
  13870.  
  13871.   See also: TStream.Read, Write (234)
  13872.  
  13873.           For an example, see TStream.Read (222).
  13874.  
  13875.  
  13876.                                                      233
  13877.  
  13878.  
  13879.  
  13880.                                                                       11.10. TCOLLECTION
  13881.  
  13882.  
  13883.            TMemoryStream.Write
  13884. Declaration: Procedure Write (Var Buf; Count: Sw Word); Virtual;
  13885.  
  13886. Description: Write copies Count bytes from Buf to the stream. It updates the position of the
  13887.            stream.
  13888.            If not enough memory is available to hold the extra Count bytes, then the stream
  13889.            will try to expand, by allocating as much blocks with size BlkSize (as specified in
  13890.            the constuctor call Init (232)) as needed.
  13891.  
  13892.     Errors: If the stream cannot allocate more memory, then the status is set to stWriteError
  13893.  
  13894.   See also: TStream.Write (223), Read (233)
  13895.  
  13896.            For an example, see TStream.Read (222).
  13897.  
  13898.  
  13899.            11.10 TCollection
  13900.  
  13901.            The TCollection object manages a collection of pointers or objects. It also provides
  13902.            a series of methods to manipulate these pointers or objects.
  13903.            Whether or not objects are used depends on the kind of calls you use. ALl kinds
  13904.            come in 2 flavors, one for objects, one for pointers.
  13905.            This is the full declaration of the TCollection object:
  13906.  
  13907.            TYPETItemList = Array [0..MaxCollectionSize - 1] Of Pointer;
  13908.               PItemList = ^TItemList;
  13909.  
  13910.               TCollection = OBJECT (TObject)
  13911.                       Items: PItemList; { Item list pointer }
  13912.                       Count: Sw_Integer; { Item count }
  13913.                       Limit: Sw_Integer; { Item limit count }
  13914.                       Delta: Sw_Integer; { Inc delta size }
  13915.                   Constructor Init (ALimit, ADelta: Sw_Integer);
  13916.                   Constructor Load (Var S: TStream);
  13917.                   Destructor Done; Virtual;
  13918.                   Function At (Index: Sw_Integer): Pointer;
  13919.                   Function IndexOf (Item: Pointer): Sw_Integer; Virtual;
  13920.                   Function GetItem (Var S: TStream): Pointer; Virtual;
  13921.                   Function LastThat (Test: Pointer): Pointer;
  13922.                   Function FirstThat (Test: Pointer): Pointer;
  13923.                   Procedure Pack;
  13924.                   Procedure FreeAll;
  13925.                   Procedure DeleteAll;
  13926.                   Procedure Free (Item: Pointer);
  13927.                   Procedure Insert (Item: Pointer); Virtual;
  13928.                   Procedure Delete (Item: Pointer);
  13929.                   Procedure AtFree (Index: Sw_Integer);
  13930.                   Procedure FreeItem (Item: Pointer); Virtual;
  13931.                   Procedure AtDelete (Index: Sw_Integer);
  13932.                   Procedure ForEach (Action: Pointer);
  13933.                   Procedure SetLimit (ALimit: Sw_Integer); Virtual;
  13934.                   Procedure Error (Code, Info: Integer); Virtual;
  13935.  
  13936.                                                     234
  13937.  
  13938.  
  13939.  
  13940.                                                                              11.10. TCOLLECTION
  13941.  
  13942.  
  13943.                       Procedure AtPut (Index: Sw_Integer; Item: Pointer);
  13944.                       Procedure AtInsert (Index: Sw_Integer; Item: Pointer);
  13945.                       Procedure Store (Var S: TStream);
  13946.                       Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
  13947.                END;
  13948.                PCollection = ^TCollection;
  13949.  
  13950.  
  13951.            TCollection.Init
  13952. Declaration: Constructor TCollection.Init (ALimit, ADelta: Sw Integer);
  13953.  
  13954. Description: Init initializes a new instance of a collection. It sets the (initial) maximum number
  13955.            of items in the collection to ALimit. ADelta is the increase size : The number of
  13956.            memory places that will be allocatiod in case ALimit is reached, and another element
  13957.            is added to the collection.
  13958.  
  13959.      Errors: None.
  13960.  
  13961.    See also: Load (235), Done (236)
  13962.  
  13963.            For an example, see TCollection.ForEach (245).
  13964.  
  13965.  
  13966.            TCollection.Load
  13967. Declaration: Constructor TCollection.Load (Var S: TStream);
  13968.  
  13969. Description: Load initializes a new instance of a collection. It reads from stream S the item
  13970.            count, the item limit count, and the increase size. After that, it reads the specified
  13971.            number of items from the stream.
  13972.  
  13973.      Errors: Errors returned can be those of GetItem (238).
  13974.  
  13975.    See also: Init (235), GetItem (238), Done (236).
  13976.  
  13977.            Program ex22 ;
  13978.  
  13979.             { Program to demonstrate the T C o l l e c t i o n . Load method }
  13980.  
  13981.            Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  13982.  
  13983.            Var C : P C o l l e c t i o n ;
  13984.                  M : PMyObject ;
  13985.                  I : Longint ;
  13986.                  S : PMemoryStream ;
  13987.  
  13988.             begin
  13989.               C:=New( P C o l l e c t i o n , I n i t ( 1 0 0 , 1 0 ) ) ;
  13990.               For I :=1 to 100 do
  13991.                  begin
  13992.                  M:=New( PMyObject , I n i t ) ;
  13993.                  M . S e t F i e l d (100- I ) ;
  13994.                  C . Insert (M) ;
  13995.                  end ;
  13996.               Writeln ( ' I n s e r t e d ' , C . Count , ' o b j e c t s ' ) ;
  13997.               S:=New( PMemorySTream , I n i t ( 1 0 0 0 , 1 0 ) ) ;
  13998.  
  13999.                                                               235
  14000.  
  14001.  
  14002.  
  14003.                                                                               11.10. TCOLLECTION
  14004.  
  14005.  
  14006.                C . Store ( S  );
  14007.                C . F r e e A l l ;
  14008.                Dispose (C, Done ) ;
  14009.                S  . Seek ( 0 ) ;
  14010.                C . Load ( S  );
  14011.                Writeln ( ' Read ' , C . Count , ' o b j e c t s from stream . ' ) ;
  14012.                Dispose ( S , Done ) ;
  14013.                Dispose (C, Done ) ;
  14014.             end .
  14015.  
  14016.  
  14017.             TCollection.Done
  14018. Declaration: Destructor TCollection.Done; Virtual;
  14019.  
  14020. Description: Done frees all objects in the collection, and then releases all memory occupied by
  14021.             the instance.
  14022.  
  14023.      Errors: None.
  14024.  
  14025.    See also: Init (235), FreeAll (240)
  14026.  
  14027.             For an example, see TCollection.ForEach (245).
  14028.  
  14029.  
  14030.             TCollection.At
  14031. Declaration: Function TCollection.At (Index: Sw Integer): Pointer;
  14032.  
  14033. Description: At returns the item at position Index.
  14034.  
  14035.      Errors: If Index is less than zero or larger than the number of items in the collection,
  14036.             seeplErrorTCollection.Error is called with coIndexError and Index as arguments,
  14037.             resulting in a run-time error.
  14038.  
  14039.    See also: Insert (243)
  14040.  
  14041.             Program ex23 ;
  14042.  
  14043.             { Program to demonstrate the T C o l l e c t i o n . At method }
  14044.  
  14045.             Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14046.  
  14047.             Var C : P C o l l e c t i o n ;
  14048.                      M : PMyObject ;
  14049.                      I : Longint ;
  14050.  
  14051.             begin
  14052.                C:=New( P C o l l e c t i o n , I n i t ( 1 0 0 , 1 0 ) ) ;
  14053.                For I :=1 to 100 do
  14054.                      begin
  14055.                      M:=New( PMyObject , I n i t ) ;
  14056.                      M . S e t F i e l d (100- I ) ;
  14057.                      C . Insert (M) ;
  14058.                      end ;
  14059.                For I :=0 to C . Count -1 do
  14060.  
  14061.  
  14062.                                                                236
  14063.  
  14064.  
  14065.  
  14066.                                                                                   11.10. TCOLLECTION
  14067.  
  14068.  
  14069.                          begin
  14070.                          M:=C . At( I ) ;
  14071.                          Writeln ( ' Object ' , i , ' has f i e l d : ' ,M . G e t F i e l d ) ;
  14072.                          end ;
  14073.                    C . F r e e A l l ;
  14074.                    Dispose (C, Done ) ;
  14075.                 end .
  14076.  
  14077.  
  14078.                 TCollection.IndexOf
  14079. Declaration: Function TCollection.IndexOf (Item: Pointer): Sw Integer; Virtual;
  14080.  
  14081. Description: IndexOf returns the index of Item in the collection. If Item isn't present in the
  14082.                 collection, -1 is returned.
  14083.  
  14084.      Errors:
  14085.  
  14086.    See also:
  14087.  
  14088.                 Program ex24 ;
  14089.  
  14090.                 { Program to demonstrate the T C o l l e c t i o n . IndexOf method }
  14091.  
  14092.                 Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14093.  
  14094.                 Var C : P C o l l e c t i o n ;
  14095.                          M, Keep : PMyObject ;
  14096.                          I : Longint ;
  14097.  
  14098.                 begin
  14099.                    Randomize ;
  14100.                    C:=New( P C o l l e c t i o n , I n i t ( 1 0 0 , 1 0 ) ) ;
  14101.                    Keep := Nil ;
  14102.                    For I :=1 to 100 do
  14103.                          begin
  14104.                          M:=New( PMyObject , I n i t ) ;
  14105.                          M . S e t F i e l d ( I -1);
  14106.                          I f Random<0.1 then
  14107.                            Keep :=M;
  14108.                          C . Insert (M) ;
  14109.                          end ;
  14110.                    I f Keep=Nil then
  14111.                          begin
  14112.                          Writeln ( ' Please run again . No o b j e c t s e l e c t e d ' ) ;
  14113.                          Halt ( 1 ) ;
  14114.                          end ;
  14115.                    Writeln ( ' S e l e c t e d o b j e c t has f i e l d : ' , Keep  . G e t F i e l d ) ;
  14116.                    Write ( ' S e l e c t e d o b j e c t has index : ' , C . IndexOf ( Keep ) ) ;
  14117.                    Writeln ( ' should match i t ' ' s f i e l d . ' ) ;
  14118.                    C . F r e e A l l ;
  14119.                    Dispose (C, Done ) ;
  14120.                 end .
  14121.  
  14122.  
  14123.  
  14124.                                                                    237
  14125.  
  14126.  
  14127.  
  14128.                                                                              11.10. TCOLLECTION
  14129.  
  14130.  
  14131.            TCollection.GetItem
  14132. Declaration: Function TCollection.GetItem (Var S: TStream): Pointer; Virtual;
  14133.  
  14134. Description: GetItem reads a single item o  the stream S, and returns a pointer to this item.
  14135.            This method is used internally by the Load method, and should not be used directly.
  14136.  
  14137.      Errors: Possible errors are the ones from TStream.Get (217).
  14138.  
  14139.    See also: TStream.Get (217), seeplStoreTCollection.Store
  14140.  
  14141.  
  14142.            TCollection.LastThat
  14143. Declaration: Function TCollection.LastThat (Test: Pointer): Pointer;
  14144.  
  14145. Description: This function returns the last item in the collection for which Test returns a non-
  14146.            nil result. Test is a function that accepts 1 argument: a pointer to an object, and
  14147.            that returns a pointer as a result.
  14148.  
  14149.      Errors: None.
  14150.  
  14151.    See also: FirstThat (239)
  14152.  
  14153.            Program ex21 ;
  14154.  
  14155.            { Program to demonstrate the T C o l l e c t i o n . Foreach method }
  14156.  
  14157.            Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14158.  
  14159.            Var C : P C o l l e c t i o n ;
  14160.                     M : PMyObject ;
  14161.                     I : Longint ;
  14162.  
  14163.            Function CheckField ( Dummy: Pointer ; P : PMyObject ) : Longint ;
  14164.  
  14165.            begin
  14166.               I f P . G e t F i e l d <56 then
  14167.                     C h e c k f i e l d :=1
  14168.               else
  14169.                     CheckField :=0;
  14170.            end ;
  14171.  
  14172.            begin
  14173.               C:=New( P C o l l e c t i o n , I n i t ( 1 0 0 , 1 0 ) ) ;
  14174.               For I :=1 to 100 do
  14175.                     begin
  14176.                     M:=New( PMyObject , I n i t ) ;
  14177.                     M . S e t F i e l d ( I ) ;
  14178.                     C . Insert (M) ;
  14179.                     end ;
  14180.               Writeln ( ' I n s e r t e d ' , C . Count , ' o b j e c t s ' ) ;
  14181.               Writeln ( ' Last one fo r which F i e l d <56 has index ( should be 5 4 ) : ' ,
  14182.                                   C . IndexOf (C . LastThat ( @CheckField ) ) ) ;
  14183.               C . F r e e A l l ;
  14184.               Dispose (C, Done ) ;
  14185.            end .
  14186.  
  14187.  
  14188.                                                               238
  14189.  
  14190.  
  14191.  
  14192.                                                                              11.10. TCOLLECTION
  14193.  
  14194.  
  14195.            TCollection.FirstThat
  14196. Declaration: Function TCollection.FirstThat (Test: Pointer): Pointer;
  14197.  
  14198. Description: This function returns the first item in the collection for which Test returns a non-
  14199.            nil result. Test is a function that accepts 1 argument: a pointer to an object, and
  14200.            that returns a pointer as a result.
  14201.  
  14202.      Errors: None.
  14203.  
  14204.    See also: LastThat (238)
  14205.  
  14206.            Program ex21 ;
  14207.  
  14208.            { Program to demonstrate the T C o l l e c t i o n . F i r s t T h a t method }
  14209.  
  14210.            Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14211.  
  14212.            Var C : P C o l l e c t i o n ;
  14213.                     M : PMyObject ;
  14214.                     I : Longint ;
  14215.  
  14216.            Function CheckField ( Dummy: Pointer ; P : PMyObject ) : Longint ;
  14217.  
  14218.            begin
  14219.               I f P . G e t F i e l d >56 then
  14220.                     C h e c k f i e l d :=1
  14221.               else
  14222.                     CheckField :=0;
  14223.            end ;
  14224.  
  14225.            begin
  14226.               C:=New( P C o l l e c t i o n , I n i t ( 1 0 0 , 1 0 ) ) ;
  14227.               For I :=1 to 100 do
  14228.                     begin
  14229.                     M:=New( PMyObject , I n i t ) ;
  14230.                     M . S e t F i e l d ( I ) ;
  14231.                     C . Insert (M) ;
  14232.                     end ;
  14233.               Writeln ( ' I n s e r t e d ' , C . Count , ' o b j e c t s ' ) ;
  14234.               Writeln ( ' f i r s t one fo r which F i e l d >56 has index ( should be 5 6 ) : ' ,
  14235.                                   C . IndexOf (C . F i r s t T h a t ( @CheckField ) ) ) ;
  14236.               C . F r e e A l l ;
  14237.               Dispose (C, Done ) ;
  14238.            end .
  14239.  
  14240.  
  14241.            TCollection.Pack
  14242. Declaration: Procedure TCollection.Pack;
  14243.  
  14244. Description: Pack removes all Nil pointers from the collection, and adjusts Count to reflect this
  14245.            change. No memory is freed as a result of this call. In order to free any memory,
  14246.            you can call SetLimit with an argument of Count after a call to Pack.
  14247.  
  14248.      Errors: None.
  14249.  
  14250.  
  14251.                                                               239
  14252.  
  14253.  
  14254.  
  14255.                                                                                   11.10. TCOLLECTION
  14256.  
  14257.  
  14258.    See also: SetLimit (246)
  14259.  
  14260.                 Program ex21 ;
  14261.  
  14262.                 { Program to demonstrate the T C o l l e c t i o n . F i r s t T h a t method }
  14263.  
  14264.                 Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14265.  
  14266.                 Var C : P C o l l e c t i o n ;
  14267.                          M : PMyObject ;
  14268.                          I : Longint ;
  14269.  
  14270.                 Function CheckField ( Dummy: Pointer ; P : PMyObject ) : Longint ;
  14271.  
  14272.                 begin
  14273.                    I f P . G e t F i e l d >56 then
  14274.                          C h e c k f i e l d :=1
  14275.                    else
  14276.                          CheckField :=0;
  14277.                 end ;
  14278.  
  14279.                 begin
  14280.                    C:=New( P C o l l e c t i o n , I n i t ( 1 0 0 , 1 0 ) ) ;
  14281.                    For I :=1 to 100 do
  14282.                          begin
  14283.                          M:=New( PMyObject , I n i t ) ;
  14284.                          M . S e t F i e l d ( I ) ;
  14285.                          C . Insert (M) ;
  14286.                          end ;
  14287.                    Writeln ( ' I n s e r t e d ' , C . Count , ' o b j e c t s ' ) ;
  14288.                    Writeln ( ' f i r s t one fo r which F i e l d >56 has index ( should be 5 6 ) : ' ,
  14289.                                        C . IndexOf (C . F i r s t T h a t ( @CheckField ) ) ) ;
  14290.                    C . F r e e A l l ;
  14291.                    Dispose (C, Done ) ;
  14292.                 end .
  14293.  
  14294.  
  14295.                 TCollection.FreeAll
  14296. Declaration: Procedure TCollection.FreeAll;
  14297.  
  14298. Description: FreeAll calls the destructor of each object in the collection. It doesn't release any
  14299.                 memory occumpied by the collection itself, but it does set Count to zero.
  14300.  
  14301.      Errors:
  14302.  
  14303.    See also: DeleteAll (241), FreeItem (244)
  14304.  
  14305.                 Program ex28 ;
  14306.  
  14307.                 { Program to demonstrate the T C o l l e c t i o n . F r e e A l l method }
  14308.  
  14309.                 Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14310.  
  14311.                 Var C : P C o l l e c t i o n ;
  14312.  
  14313.                                                                    240
  14314.  
  14315.  
  14316.  
  14317.                                                                                 11.10. TCOLLECTION
  14318.  
  14319.  
  14320.                     M : PMyObject ;
  14321.                     I , InitMem : Longint ;
  14322.  
  14323.            begin
  14324.                  Randomize ;
  14325.                  C:=New( P C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  14326.                  InitMem :=Memavail ;
  14327.                  Writeln ( ' I n i t i a l memory : ' , InitMem ) ;
  14328.                  For I :=1 to 100 do
  14329.                     begin
  14330.                     M:=New( PMyObject , I n i t ) ;
  14331.                     M . S e t F i e l d ( I -1);
  14332.                     C . Insert (M) ;
  14333.                     end ;
  14334.                  Writeln ( ' Added 100 Items . Memory a v a i l a b l e : ' , Memavail ) ;
  14335.                  Write ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14336.                  Write         ( ' ( Should be 100 ' , SizeOF ( TMyObject ) ) ;
  14337.                  Writeln ( '=' ,100  SizeOf ( TMyObject ) , ' ) ' ) ;
  14338.                  C . F r e e A l l ;
  14339.                  Writeln ( ' Freed a l l o b j e c t s . Memory a v a i l a b l e : ' , Memavail ) ;
  14340.                  Writeln ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14341.                  Dispose (C, Done ) ;
  14342.            end .
  14343.  
  14344.  
  14345.            TCollection.DeleteAll
  14346. Declaration: Procedure TCollection.DeleteAll;
  14347.  
  14348. Description: DeleteAll deletes all elements from the collection. It just sets the Count variable
  14349.            to zero. Contrary to FreeAll (240), DeletAll doesn't call the destructor of the
  14350.            objects.
  14351.  
  14352.      Errors: None.
  14353.  
  14354.    See also: FreeAll (240), Delete (243)
  14355.  
  14356.            Program ex29 ;
  14357.  
  14358.            { Program to demonstrate the TCollection . DeleteAll method
  14359.                 Compare with example 2 8 , where F r e e A l l i s used .
  14360.            }
  14361.  
  14362.            Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14363.  
  14364.            Var C : P C o l l e c t i o n ;
  14365.                     M : PMyObject ;
  14366.                     I , InitMem : Longint ;
  14367.  
  14368.            begin
  14369.                  Randomize ;
  14370.                  C:=New( P C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  14371.                  InitMem :=Memavail ;
  14372.                  Writeln ( ' I n i t i a l memory : ' , InitMem ) ;
  14373.  
  14374.                                                                  241
  14375.  
  14376.  
  14377.  
  14378.                                                                              11.10. TCOLLECTION
  14379.  
  14380.  
  14381.               For I :=1 to 100 do
  14382.                     begin
  14383.                     M:=New( PMyObject , I n i t ) ;
  14384.                     M . S e t F i e l d ( I -1);
  14385.                     C . Insert (M) ;
  14386.                     end ;
  14387.               Writeln ( ' Added 100 Items . Memory a v a i l a b l e : ' , Memavail ) ;
  14388.               Write ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14389.               Write           ( ' ( Should be 100 ' , SizeOF ( TMyObject ) ) ;
  14390.               Writeln ( '=' ,100  SizeOf ( TMyObject ) , ' ) ' ) ;
  14391.               C . D e l e t e A l l ;
  14392.               Writeln ( ' Deleted a l l o b j e c t s . Memory a v a i l a b l e : ' , Memavail ) ;
  14393.               Writeln ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14394.               Dispose (C, Done ) ;
  14395.            end .
  14396.  
  14397.  
  14398.            TCollection.Free
  14399. Declaration: Procedure TCollection.Free (Item: Pointer);
  14400.  
  14401. Description: Free Deletes Item from the collection, and calls the destructor Done of the object.
  14402.  
  14403.      Errors: If the Item is not in the collection, Error will be called with coIndexError.
  14404.  
  14405.    See also: FreeItem (244),
  14406.  
  14407.            Program ex30 ;
  14408.  
  14409.            { Program to demonstrate the T C o l l e c t i o n . Free method }
  14410.  
  14411.            Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14412.  
  14413.            Var C : P C o l l e c t i o n ;
  14414.                     M : PMyObject ;
  14415.                     I , InitMem : Longint ;
  14416.  
  14417.            begin
  14418.               Randomize ;
  14419.               C:=New( P C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  14420.               InitMem :=Memavail ;
  14421.               Writeln ( ' I n i t i a l memory : ' , InitMem ) ;
  14422.               For I :=1 to 100 do
  14423.                     begin
  14424.                     M:=New( PMyObject , I n i t ) ;
  14425.                     M . S e t F i e l d ( I -1);
  14426.                     C . Insert (M) ;
  14427.                     end ;
  14428.               Writeln ( ' Added 100 Items . Memory a v a i l a b l e : ' , Memavail ) ;
  14429.               Write ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14430.               Write           ( ' ( Should be 100 ' , SizeOF ( TMyObject ) ) ;
  14431.               Writeln ( '=' ,100  SizeOf ( TMyObject ) , ' ) ' ) ;
  14432.               With C  do
  14433.                     While Count >0 do Free ( At( Count -1));
  14434.               Writeln ( ' Freed a l l o b j e c t s . Memory a v a i l a b l e : ' , Memavail ) ;
  14435.  
  14436.                                                               242
  14437.  
  14438.  
  14439.  
  14440.                                                                              11.10. TCOLLECTION
  14441.  
  14442.  
  14443.               Writeln ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14444.               Dispose (C, Done ) ;
  14445.            end .
  14446.  
  14447.  
  14448.            TCollection.Insert
  14449. Declaration: Procedure TCollection.Insert (Item: Pointer); Virtual;
  14450.  
  14451. Description: Insert inserts Item in the collection. TCollection inserts this item at the end,
  14452.            but descendent objects may insert it at another place.
  14453.  
  14454.      Errors: None.
  14455.  
  14456.    See also: AtInsert (247), AtPut (247),
  14457.  
  14458.  
  14459.            TCollection.Delete
  14460. Declaration: Procedure TCollection.Delete (Item: Pointer);
  14461.  
  14462. Description: Delete deletes Item from the collection. It doesn't call the item's destructor,
  14463.            though. For this the Free (242) call is provided.
  14464.  
  14465.      Errors: If the Item is not in the collection, Error will be called with coIndexError.
  14466.  
  14467.    See also: AtDelete (245),Free (242)
  14468.  
  14469.            Program ex31 ;
  14470.  
  14471.            { Program to demonstrate the T C o l l e c t i o n . Delete method }
  14472.  
  14473.            Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14474.  
  14475.            Var C : P C o l l e c t i o n ;
  14476.                     M : PMyObject ;
  14477.                     I , InitMem : Longint ;
  14478.  
  14479.            begin
  14480.               Randomize ;
  14481.               C:=New( P C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  14482.               InitMem :=Memavail ;
  14483.               Writeln ( ' I n i t i a l memory : ' , InitMem ) ;
  14484.               For I :=1 to 100 do
  14485.                     begin
  14486.                     M:=New( PMyObject , I n i t ) ;
  14487.                     M . S e t F i e l d ( I -1);
  14488.                     C . Insert (M) ;
  14489.                     end ;
  14490.               Writeln ( ' Added 100 Items . Memory a v a i l a b l e : ' , Memavail ) ;
  14491.               Write ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14492.               Write           ( ' ( Should be 100 ' , SizeOF ( TMyObject ) ) ;
  14493.               Writeln ( '=' ,100  SizeOf ( TMyObject ) , ' ) ' ) ;
  14494.               With C  do
  14495.                     While Count >0 do Delete ( At( Count -1));
  14496.               Writeln ( ' Freed a l l o b j e c t s . Memory a v a i l a b l e : ' , Memavail ) ;
  14497.               Writeln ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14498.  
  14499.                                                               243
  14500.  
  14501.  
  14502.  
  14503.                                                                              11.10. TCOLLECTION
  14504.  
  14505.  
  14506.               Dispose (C, Done ) ;
  14507.            end .
  14508.  
  14509.  
  14510.            TCollection.AtFree
  14511. Declaration: Procedure TCollection.AtFree (Index: Sw Integer);
  14512.  
  14513. Description: AtFree deletes the item at position Index in the collection, and calls the item's
  14514.            destructor if it is not Nil.
  14515.  
  14516.      Errors: If Index isn't valid then Error (246) is called with CoIndexError.
  14517.  
  14518.    See also: Free (242), AtDelete (245)
  14519.  
  14520.            Program ex32 ;
  14521.  
  14522.             { Program to demonstrate the T C o l l e c t i o n . AtFree method }
  14523.  
  14524.            Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14525.  
  14526.            Var C : P C o l l e c t i o n ;
  14527.                     M : PMyObject ;
  14528.                     I , InitMem : Longint ;
  14529.  
  14530.             begin
  14531.               Randomize ;
  14532.               C:=New( P C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  14533.               InitMem :=Memavail ;
  14534.               Writeln ( ' I n i t i a l memory : ' , InitMem ) ;
  14535.               For I :=1 to 100 do
  14536.                     begin
  14537.                     M:=New( PMyObject , I n i t ) ;
  14538.                     M . S e t F i e l d ( I -1);
  14539.                     C . Insert (M) ;
  14540.                     end ;
  14541.               Writeln ( ' Added 100 Items . Memory a v a i l a b l e : ' , Memavail ) ;
  14542.               Write ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14543.               Write           ( ' ( Should be 100 ' , SizeOF ( TMyObject ) ) ;
  14544.               Writeln ( '=' ,100  SizeOf ( TMyObject ) , ' ) ' ) ;
  14545.               With C  do
  14546.                     While Count >0 do AtFree ( Count -1);
  14547.               Writeln ( ' Freed a l l o b j e c t s . Memory a v a i l a b l e : ' , Memavail ) ;
  14548.               Writeln ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14549.               Dispose (C, Done ) ;
  14550.            end .
  14551.  
  14552.  
  14553.            TCollection.FreeItem
  14554. Declaration: Procedure TCollection.FreeItem (Item: Pointer); Virtual;
  14555.  
  14556. Description: FreeItem calls the destructor of Item if it is not nil.
  14557.            This function is used internally by the TCollection object, and should not be called
  14558.            directly.
  14559.  
  14560.  
  14561.                                                               244
  14562.  
  14563.  
  14564.  
  14565.                                                                              11.10. TCOLLECTION
  14566.  
  14567.  
  14568.      Errors: None.
  14569.  
  14570.    See also: Free (244), seeplAtFreeTCollection.AtFree
  14571.  
  14572.  
  14573.            TCollection.AtDelete
  14574. Declaration: Procedure TCollection.AtDelete (Index: Sw Integer);
  14575.  
  14576. Description: AtDelete deletes the pointer at position Index in the collection. It doesn't call
  14577.            the object's destructor.
  14578.  
  14579.      Errors: If Index isn't valid then Error (246) is called with CoIndexError.
  14580.  
  14581.    See also: Delete (243)
  14582.  
  14583.            Program ex33 ;
  14584.  
  14585.            { Program to demonstrate the T C o l l e c t i o n . AtDelete method }
  14586.  
  14587.            Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14588.  
  14589.            Var C : P C o l l e c t i o n ;
  14590.                     M : PMyObject ;
  14591.                     I , InitMem : Longint ;
  14592.  
  14593.            begin
  14594.               Randomize ;
  14595.               C:=New( P C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  14596.               InitMem :=Memavail ;
  14597.               Writeln ( ' I n i t i a l memory : ' , InitMem ) ;
  14598.               For I :=1 to 100 do
  14599.                     begin
  14600.                     M:=New( PMyObject , I n i t ) ;
  14601.                     M . S e t F i e l d ( I -1);
  14602.                     C . Insert (M) ;
  14603.                     end ;
  14604.               Writeln ( ' Added 100 Items . Memory a v a i l a b l e : ' , Memavail ) ;
  14605.               Write ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14606.               Write           ( ' ( Should be 100 ' , SizeOF ( TMyObject ) ) ;
  14607.               Writeln ( '=' ,100  SizeOf ( TMyObject ) , ' ) ' ) ;
  14608.               With C  do
  14609.                     While Count >0 do AtDelete ( Count -1);
  14610.               Writeln ( ' Freed a l l o b j e c t s . Memory a v a i l a b l e : ' , Memavail ) ;
  14611.               Writeln ( ' Lost : ' , Initmem-Memavail , ' bytes . ' ) ;
  14612.               Dispose (C, Done ) ;
  14613.            end .
  14614.  
  14615.  
  14616.            TCollection.ForEach
  14617. Declaration: Procedure TCollection.ForEach (Action: Pointer);
  14618.  
  14619. Description: ForEach calls Action for each element in the collection, and passes the element as
  14620.            an argument to Action.
  14621.            Action is a procedural type variable that accepts a pointer as an argument.
  14622.  
  14623.                                                               245
  14624.  
  14625.  
  14626.  
  14627.                                                                               11.10. TCOLLECTION
  14628.  
  14629.  
  14630.      Errors: None.
  14631.    See also: FirstThat (239), LastThat (238)
  14632.  
  14633.             Program ex21 ;
  14634.  
  14635.             { Program to demonstrate the T C o l l e c t i o n . Foreach method }
  14636.  
  14637.             Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14638.  
  14639.             Var C : P C o l l e c t i o n ;
  14640.                      M : PMyObject ;
  14641.                      I : Longint ;
  14642.  
  14643.             Procedure P r i n t F i e l d ( Dummy: Pointer ; P : PMyObject ) ;
  14644.  
  14645.             begin
  14646.                Writeln ( ' F i e l d : ' , P . G e t F i e l d ) ;
  14647.             end ;
  14648.  
  14649.             begin
  14650.                C:=New( P C o l l e c t i o n , I n i t ( 1 0 0 , 1 0 ) ) ;
  14651.                For I :=1 to 100 do
  14652.                      begin
  14653.                      M:=New( PMyObject , I n i t ) ;
  14654.                      M . S e t F i e l d (100- I ) ;
  14655.                      C . Insert (M) ;
  14656.                      end ;
  14657.                Writeln ( ' I n s e r t e d ' , C . Count , ' o b j e c t s ' ) ;
  14658.                C . ForEach ( @ P r i n t F i e l d ) ;
  14659.                C . F r e e A l l ;
  14660.                Dispose (C, Done ) ;
  14661.             end .
  14662.  
  14663.  
  14664.             TCollection.SetLimit
  14665. Declaration: Procedure TCollection.SetLimit (ALimit: Sw Integer); Virtual;
  14666. Description: SetLimit sets the maximum number of elements in the collection. ALimit must
  14667.             not be less than Count, and should not be larger than MaxCollectionSize
  14668.      Errors: None.
  14669.    See also: Init (235)
  14670.  
  14671.             For an example, see Pack (239).
  14672.  
  14673.  
  14674.             TCollection.Error
  14675. Declaration: Procedure TCollection.Error (Code, Info: Integer); Virtual;
  14676. Description: Error is called by the various TCollection methods in case of an error condition.
  14677.             The default behaviour is to make a call to RunError with an error of 212-Code.
  14678.             This method can be overridden by descendent objects to implement a di erent
  14679.             error-handling.
  14680.  
  14681.                                                                246
  14682.  
  14683.  
  14684.  
  14685.                                                                                   11.10. TCOLLECTION
  14686.  
  14687.  
  14688.      Errors:
  14689.  
  14690.    See also: Abstract (207)
  14691.  
  14692.  
  14693.                 TCollection.AtPut
  14694. Declaration: Procedure TCollection.AtPut (Index: Sw Integer; Item: Pointer);
  14695.  
  14696. Description: AtPut sets the element at position Index in the collection to Item. Any previous
  14697.                 value is overwritten.
  14698.  
  14699.      Errors: If Index isn't valid then Error (246) is called with CoIndexError.
  14700.  
  14701.    See also:
  14702.  
  14703.                 For an example, see Pack (239).
  14704.  
  14705.  
  14706.                 TCollection.AtInsert
  14707. Declaration: Procedure TCollection.AtInsert (Index: Sw Integer; Item: Pointer);
  14708.  
  14709. Description: AtInsert inserts Item in the collection at position Index, shifting all elements by
  14710.                 one position. In case the current limit is reached, the collection will try to expand
  14711.                 with a call to SetLimit
  14712.  
  14713.      Errors: If Index isn't valid then Error (246) is called with CoIndexError. If the collection
  14714.                 fails to expand, then coOverFlow is passd to Error.
  14715.  
  14716.    See also: Insert (243)
  14717.  
  14718.                 Program ex34 ;
  14719.  
  14720.                 { Program to demonstrate the T C o l l e c t i o n . A t I n s e r t method }
  14721.  
  14722.                 Uses Objects , MyObject ; { For TMyObject d e f i n i t i o n and r e g i s t r a t i o n }
  14723.  
  14724.                 Var C : P C o l l e c t i o n ;
  14725.                          M : PMyObject ;
  14726.                          I : Longint ;
  14727.  
  14728.                 Procedure P r i n t F i e l d ( Dummy: Pointer ; P : PMyObject ) ;
  14729.  
  14730.                 begin
  14731.                    Writeln ( ' F i e l d : ' , P . G e t F i e l d ) ;
  14732.                 end ;
  14733.  
  14734.  
  14735.                 begin
  14736.                    Randomize ;
  14737.                    C:=New( P C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  14738.                    Writeln ( ' I n s e r t i n g 100 r e c o r d s at random p l a c e s . ' ) ;
  14739.                    For I :=1 to 100 do
  14740.                          begin
  14741.                          M:=New( PMyObject , I n i t ) ;
  14742.                          M . S e t F i e l d ( I -1);
  14743.  
  14744.                                                                    247
  14745.  
  14746.  
  14747.  
  14748.                                                                         11.11. TSORTEDCOLLECTION
  14749.  
  14750.  
  14751.                     I f I =1 then
  14752.                       C . Insert (M)
  14753.                     else
  14754.                       With C  do
  14755.                              A t I n s e r t (Random( Count ) , M) ;
  14756.                     end ;
  14757.               Writeln ( ' Values : ' ) ;
  14758.               C . Foreach ( @ P r i n t F i e l d ) ;
  14759.               Dispose (C, Done ) ;
  14760.            end .
  14761.  
  14762.  
  14763.            TCollection.Store
  14764. Declaration: Procedure TCollection.Store (Var S: TStream);
  14765.  
  14766. Description: Store writes the collection to the stream S. It does this by writeing the current
  14767.            Count, Limit and Delta to the stream, and then writing each item to the stream.
  14768.            The contents of the stream are then suitable for instantiating another collection
  14769.            with Load (235).
  14770.  
  14771.      Errors: Errors returned are those by TStream.Put (221).
  14772.  
  14773.    See also: Load (235), PutItem (248)
  14774.  
  14775.            For an example, see seeplLoadTCollection.Load.
  14776.  
  14777.  
  14778.            TCollection.PutItem
  14779. Declaration: Procedure TCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
  14780.  
  14781. Description: PutItem writes Item to stream S. This method is used internaly by the TCollection
  14782.            object, and should not be called directly.
  14783.  
  14784.      Errors: Errors are those returned by TStream.Put (221).
  14785.  
  14786.    See also: Store (248), GetItem (238).
  14787.  
  14788.  
  14789.            11.11 TSortedCollection
  14790.  
  14791.            TSortedCollection is an abstract class, implementing a sorted collection. You
  14792.            should never use an instance of TSortedCollection directly, instead you should
  14793.            declare a descendent type, and override the Compare (250) method.
  14794.            Because the collection is ordered, TSortedCollection overrides some TCollection
  14795.            methods, to provide faster routines for lookup.
  14796.            The Compare (250) method decides how elements in the collection should be ordered.
  14797.            Since TCollection has no way of knowing how to order pointers, you must override
  14798.            the compare method.
  14799.            Additionally, TCollection provides a means to filter out duplicates. if you set
  14800.            Duplicates to False (the default) then duplicates will not be allowed.
  14801.            Here is the complete declaration of TSortedCollection
  14802.  
  14803.  
  14804.  
  14805.                                                             248
  14806.  
  14807.  
  14808.  
  14809.                                                               11.11. TSORTEDCOLLECTION
  14810.  
  14811.  
  14812.            TYPETSortedCollection = OBJECT (TCollection)
  14813.                          Duplicates: Boolean; { Duplicates flag }
  14814.                       Constructor Init (ALimit, ADelta: Sw_Integer);
  14815.                       Constructor Load (Var S: TStream);
  14816.                       Function KeyOf (Item: Pointer): Pointer; Virtual;
  14817.                       Function IndexOf (Item: Pointer): Sw_Integer; Virtual;
  14818.                       Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
  14819.                       Function Search (Key: Pointer; Var Index: Sw_Integer): Boolean;Virtual;
  14820.                       Procedure Insert (Item: Pointer); Virtual;
  14821.                       Procedure Store (Var S: TStream);
  14822.                END;
  14823.                PSortedCollection = ^TSortedCollection;
  14824.  
  14825.            In the subsequent examples, the following descendent of TSortedCollection is
  14826.            used:
  14827.             Unit MySortC ;
  14828.  
  14829.             Interface
  14830.  
  14831.            Uses Objects ;
  14832.  
  14833.            Type
  14834.               PMySortedCollection =   TMySortedCollection ;
  14835.               TMySortedCollection = Object ( T S o r t e d C o l l e c t i o n )
  14836.                         Function Compare ( Key1 , Key2 : Pointer ) : Sw integer ; v i r t u a l ;
  14837.                         end ;
  14838.  
  14839.             Implementation
  14840.  
  14841.            Uses MyObject ;
  14842.  
  14843.             Function TMySortedCollection . Compare ( Key1 , Key2 : Pointer ) : sw integer ;
  14844.  
  14845.             begin
  14846.               Compare := PMyobject ( Key1 ) . G e t F i e l d - PMyObject ( Key2 ) . G e t F i e l d ;
  14847.            end ;
  14848.  
  14849.            end .
  14850.  
  14851.  
  14852.            TSortedCollection.Init
  14853. Declaration: Constructor TSortedCollection.Init (ALimit, ADelta: Sw Integer);
  14854. Description: Init calls the inherited constuctor (see TCollection.Init (235)) and sets the Duplicates
  14855.            flag to false.
  14856.            You should not call this method directly, since TSortedCollection is a abstract
  14857.            class. Instead, the descendent classes should call it via the inherited keyword.
  14858.      Errors: None.
  14859.    See also: Load (250), Done (236)
  14860.  
  14861.            For an example, see
  14862.  
  14863.                                                      249
  14864.  
  14865.  
  14866.  
  14867.                                                              11.11. TSORTEDCOLLECTION
  14868.  
  14869.  
  14870.            TSortedCollection.Load
  14871. Declaration: Constructor Load (Var S: TStream);
  14872.  
  14873. Description: Load calls the inherited constuctor (see TCollection.Load (235)) and reads the
  14874.            Duplicates flag from the stream..
  14875.            You should not call this method directly, since TSortedCollection is a abstract
  14876.            class. Instead, the descendent classes should call it via the inherited keyword.
  14877.  
  14878.      Errors: None.
  14879.  
  14880.    See also: Init (249), Done (236)
  14881.  
  14882.            For an example, see TCollection.Load (235).
  14883.  
  14884.  
  14885.            TSortedCollection.KeyOf
  14886. Declaration: Function TSortedCollection.KeyOf (Item: Pointer): Pointer; Virtual;
  14887.  
  14888. Description: KeyOf returns the key associated with Item. TSortedCollection returns the item
  14889.            itself as the key, descendent objects can override this method to calculate a (unique)
  14890.            key based on the item passed (such as hash values).
  14891.            Keys are used to sort the objects, they are used to search and sort the items in
  14892.            the collection. If descendent types override this method then it allows possibly for
  14893.            faster search/sort methods based on keys rather than on the objects themselves.
  14894.  
  14895.      Errors: None.
  14896.  
  14897.    See also: IndexOf (250), Compare (250).
  14898.  
  14899.  
  14900.            TSortedCollection.IndexOf
  14901. Declaration: Function TSortedCollection.IndexOf (Item: Pointer): Sw Integer; Virtual;
  14902.  
  14903. Description: IndexOf returns the index of Item in the collection. It searches for the object
  14904.            based on it's key. If duplicates are allowed, then it returns the index of last object
  14905.            that matches Item.
  14906.            In case Item is not found in the collection, -1 is returned.
  14907.  
  14908.      Errors: None.
  14909.  
  14910.    See also: Search (251), Compare (250).
  14911.  
  14912.            For an example, see TCollection.IndexOf (237)
  14913.  
  14914.  
  14915.            TSortedCollection.Compare
  14916. Declaration: Function TSortedCollection.Compare (Key1, Key2: Pointer): Sw Integer;
  14917.            Virtual;
  14918.  
  14919. Description: Compare is an abstract method that should be overridden by descendent objects in
  14920.            order to compare two items in the collection. This method is used in the Search (251)
  14921.            method and in the Insert (252) method to determine the ordering of the objects.
  14922.            The function should compare the two keys of items and return the following function
  14923.            results:
  14924.  
  14925.                                                     250
  14926.  
  14927.  
  14928.  
  14929.                                                             11.11. TSORTEDCOLLECTION
  14930.  
  14931.  
  14932.            Result í 0If Key1 is logically before Key2 (Key1<Key2)
  14933.            Result = 0If Key1 and Key2 are equal. (Key1=Key2)
  14934.            Result ┐ 0If Key1 is logically after Key2 (Key1>Key2)
  14935.  
  14936.     Errors: An 'abstract run-time error' will be generated if you call TSortedCollection.Compare
  14937.            directly.
  14938.  
  14939.   See also: IndexOf (250), Search (251)
  14940.  
  14941.            Unit MySortC ;
  14942.  
  14943.            Interface
  14944.  
  14945.            Uses Objects ;
  14946.  
  14947.            Type
  14948.               PMySortedCollection =   TMySortedCollection ;
  14949.               TMySortedCollection = Object ( T S o r t e d C o l l e c t i o n )
  14950.                         Function Compare ( Key1 , Key2 : Pointer ) : Sw integer ; v i r t u a l ;
  14951.                         end ;
  14952.  
  14953.            Implementation
  14954.  
  14955.            Uses MyObject ;
  14956.  
  14957.            Function TMySortedCollection . Compare ( Key1 , Key2 : Pointer ) : sw integer ;
  14958.  
  14959.            begin
  14960.               Compare := PMyobject ( Key1 ) . G e t F i e l d - PMyObject ( Key2 ) . G e t F i e l d ;
  14961.            end ;
  14962.  
  14963.            end .
  14964.  
  14965.  
  14966.            TSortedCollection.Search
  14967. Declaration: Function TSortedCollection.Search (Key: Pointer; Var Index: Sw Integer):
  14968.            Boolean;Virtual;
  14969.  
  14970. Description: Search looks for the item with key Key and returns the position of the item (if
  14971.            present) in the collection in Index.
  14972.            Instead of a linear search as TCollection does, TSortedCollection uses a binary
  14973.            search based on the keys of the objects. It uses the Compare (250) function to
  14974.            implement this search.
  14975.            If the item is found, Search returns True, otherwise False is returned.
  14976.  
  14977.     Errors: None.
  14978.  
  14979.   See also: IndexOf (237).
  14980.  
  14981.            Program ex36 ;
  14982.  
  14983.            { Program to demonstrate the T S o r t e d C o l l e c t i o n . I n s e r t method }
  14984.  
  14985.  
  14986.  
  14987.                                                    251
  14988.  
  14989.  
  14990.  
  14991.                                                                        11.11. TSORTEDCOLLECTION
  14992.  
  14993.  
  14994.            Uses Objects , MyObject , MySortC ;
  14995.             { For TMyObject , TMySortedCollection d e f i n i t i o n and r e g i s t r a t i o n }
  14996.  
  14997.            Var C : P S o r t e d C o l l e c t i o n ;
  14998.                     M : PMyObject ;
  14999.                     I : Longint ;
  15000.  
  15001.            Procedure P r i n t F i e l d ( Dummy: Pointer ; P : PMyObject ) ;
  15002.  
  15003.            begin
  15004.               Writeln ( ' F i e l d : ' , P . G e t F i e l d ) ;
  15005.            end ;
  15006.  
  15007.  
  15008.            begin
  15009.               Randomize ;
  15010.               C:=New( PMySortedCollection , I n i t ( 1 2 0 , 1 0 ) ) ;
  15011.               C . D u p l i c a t e s := True ;
  15012.               Writeln ( ' I n s e r t i n g 100 r e c o r d s at random p l a c e s . ' ) ;
  15013.               For I :=1 to 100 do
  15014.                     begin
  15015.                     M:=New( PMyObject , I n i t ) ;
  15016.                     M . S e t F i e l d (Random( 1 0 0 ) ) ;
  15017.                     C . Insert (M)
  15018.                     end ;
  15019.               M:=New( PMyObject , I n i t ) ;
  15020.               Repeat ;
  15021.                     Write ( ' Value to search f or (-1 stops ) : ' ) ;
  15022.                     read ( I ) ;
  15023.                     I f I <>-1 then
  15024.                        begin
  15025.                        M . S e t F i e l d ( i ) ;
  15026.                        I f Not C . Search ( M, I ) then
  15027.                              Writeln ( ' No such value found ' )
  15028.                        else
  15029.                              begin
  15030.                              Write ( ' Value ' , PMyObject (C . At( I ) )   . G e t F i e l d ) ;
  15031.                              Writeln ( ' p r e s e n t at p o s i t i o n ' , I ) ;
  15032.                              end ;
  15033.                        end ;
  15034.               Until I =-1;
  15035.               Dispose (M, Done ) ;
  15036.               Dispose (C, Done ) ;
  15037.            end .
  15038.  
  15039.  
  15040.            TSortedCollection.Insert
  15041. Declaration: Procedure TSortedCollection.Insert (Item: Pointer); Virtual;
  15042.  
  15043. Description: Insert inserts an item in the collection at the correct position, such that the
  15044.            collection is ordered at all times. You should never use Atinsert (247), since then
  15045.            the collection ordering is not guaranteed.
  15046.            If Item is already present in the collection, and Duplicates is False, the item will
  15047.  
  15048.  
  15049.                                                                 252
  15050.  
  15051.  
  15052.  
  15053.                                                                        11.11. TSORTEDCOLLECTION
  15054.  
  15055.  
  15056.            not be inserted.
  15057.  
  15058.      Errors: None.
  15059.  
  15060.    See also: AtInsert (247)
  15061.  
  15062.            Program ex35 ;
  15063.  
  15064.             { Program to demonstrate the T S o r t e d C o l l e c t i o n . I n s e r t method }
  15065.  
  15066.            Uses Objects , MyObject , MySortC ;
  15067.              { For TMyObject , TMySortedCollection d e f i n i t i o n and r e g i s t r a t i o n }
  15068.  
  15069.            Var C : P S o r t e d C o l l e c t i o n ;
  15070.                     M : PMyObject ;
  15071.                     I : Longint ;
  15072.  
  15073.             Procedure P r i n t F i e l d ( Dummy: Pointer ; P : PMyObject ) ;
  15074.  
  15075.             begin
  15076.               Writeln ( ' F i e l d : ' , P . G e t F i e l d ) ;
  15077.            end ;
  15078.  
  15079.  
  15080.             begin
  15081.               Randomize ;
  15082.               C:=New( PMySortedCollection , I n i t ( 1 2 0 , 1 0 ) ) ;
  15083.               Writeln ( ' I n s e r t i n g 100 r e c o r d s at random p l a c e s . ' ) ;
  15084.               For I :=1 to 100 do
  15085.                     begin
  15086.                     M:=New( PMyObject , I n i t ) ;
  15087.                     M . S e t F i e l d (Random( 1 0 0 ) ) ;
  15088.                     C . Insert (M)
  15089.                     end ;
  15090.               Writeln ( ' Values : ' ) ;
  15091.               C . Foreach ( @ P r i n t F i e l d ) ;
  15092.               Dispose (C, Done ) ;
  15093.            end .
  15094.  
  15095.  
  15096.            TSortedCollection.Store
  15097. Declaration: Procedure TSortedCollection.Store (Var S: TStream);
  15098.  
  15099. Description: Store writes the collection to the stream S. It does this by calling the inherited
  15100.            TCollection.Store (248), and then writing the Duplicates flag to the stream.
  15101.            After a Store, the collection can be loaded from the stream with the constructor
  15102.            Load (250)
  15103.  
  15104.      Errors: Errors can be those of TStream.Put (221).
  15105.  
  15106.    See also: Load (250)
  15107.  
  15108.            For an example, see TCollection.Load (235).
  15109.  
  15110.  
  15111.  
  15112.                                                                 253
  15113.  
  15114.  
  15115.  
  15116.                                                                  11.12. TSTRINGCOLLECTION
  15117.  
  15118.  
  15119.            11.12 TStringCollection
  15120.  
  15121.            The TStringCollection object manages a sorted collection of pascal strings. To
  15122.            this end, it overrides the Compare (250) method of TSortedCollection, and it
  15123.            introduces methods to read/write strings from a stream.
  15124.            Here is the full declaration of the TStringCollection object:
  15125.  
  15126.            TYPETStringCollection = OBJECT (TSortedCollection)
  15127.                       Function GetItem (Var S: TStream): Pointer; Virtual;
  15128.                       Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
  15129.                       Procedure FreeItem (Item: Pointer); Virtual;
  15130.                       Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
  15131.                END;
  15132.                PStringCollection = ^TStringCollection;
  15133.  
  15134.  
  15135.            TStringCollection.GetItem
  15136. Declaration: Function TStringCollection.GetItem (Var S: TStream): Pointer; Virtual;
  15137.  
  15138. Description: GetItem reads a string from the stream S and returns a pointer to it. It doesn't
  15139.            insert the string in the collection.
  15140.            This method is primarily introduced to be able to load and store the collection from
  15141.            and to a stream.
  15142.  
  15143.      Errors: The errors returned are those of TStream.ReadStr (219).
  15144.  
  15145.    See also: PutItem (255)
  15146.  
  15147.  
  15148.            TStringCollection.Compare
  15149. Declaration: Function TStringCollection.Compare (Key1, Key2: Pointer): Sw Integer;
  15150.            Virtual;
  15151.  
  15152. Description: TStringCollection overrides the Compare function so it compares the two keys
  15153.            as if they were pointers to strings. The compare is done case sensitive. It returns
  15154.            the following results:
  15155.  
  15156.            -1if the first string is alphabetically earlier than the second string.
  15157.            0if the two strings are equal.
  15158.            1if the first string is alphabetically later than the second string.
  15159.  
  15160.      Errors: None.
  15161.  
  15162.    See also: TSortedCollection.Compare (250)
  15163.  
  15164.            Program ex37 ;
  15165.  
  15166.            { Program to demonstrate the T S t r i n g C o l l e c t i o n . Compare method }
  15167.  
  15168.            Uses Objects ;
  15169.  
  15170.            Var C : P S t r i n g C o l l e c t i o n ;
  15171.                  S : String ;
  15172.  
  15173.                                                           254
  15174.  
  15175.  
  15176.  
  15177.                                                                                   11.13. TSTRCOLLECTION
  15178.  
  15179.  
  15180.                     I : l o n g i n t ;
  15181.  
  15182.            begin
  15183.               Randomize ;
  15184.               C:=New( P S t r i n g C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  15185.               C . D u p l i c a t e s := True ; { D u p l i c a t e s allowed }
  15186.               Writeln ( ' I n s e r t i n g 100 r e c o r d s at random p l a c e s . ' ) ;
  15187.               For I :=1 to 100 do
  15188.                     begin
  15189.                     Str (Random( 1 0 0 ) , S ) ;
  15190.                     S:= ' S t r i n g with value ' +S ;
  15191.                     C . Insert ( NewStr( S ) ) ;
  15192.                     end ;
  15193.               For I :=0 to 98 do
  15194.                     With C  do
  15195.                     I f Compare ( At( i ) , At( I +1))=0 then
  15196.                        Writeln ( ' D u p l i ca t e s t r i n g found at p o s i t i o n ' , i ) ;
  15197.               Dispose (C, Done ) ;
  15198.            end .
  15199.  
  15200.  
  15201.            TStringCollection.FreeItem
  15202. Declaration: Procedure TStringCollection.FreeItem (Item: Pointer); Virtual;
  15203.  
  15204. Description: TStringCollection overrides FreeItem so that the string pointed to by Item is
  15205.            disposed from memory.
  15206.  
  15207.      Errors: None.
  15208.  
  15209.   See also: TCollection.FreeItem (244)
  15210.  
  15211.  
  15212.            TStringCollection.PutItem
  15213. Declaration: Procedure TStringCollection.PutItem (Var S: TStream; Item: Pointer);
  15214.            Virtual;
  15215.  
  15216. Description: PutItem writes the string pointed to by Item to the stream S.
  15217.            This method is primarily used in the Load and Store methods, and should not be
  15218.            used directly.
  15219.  
  15220.      Errors: Errors are those of TStream.WriteStr (221).
  15221.  
  15222.   See also: GetItem (254)
  15223.  
  15224.  
  15225.            11.13 TStrCollection
  15226.  
  15227.            The TStrCollection object manages a sorted collection of null-terminated strings
  15228.            (pchar strings). To this end, it overrides the Compare (250) method of TSortedCollection,
  15229.            and it introduces methods to read/write strings from a stream.
  15230.            Here is the full declaration of the TStrCollection object:
  15231.  
  15232.            TYPETStrCollection = OBJECT (TSortedCollection)
  15233.  
  15234.                                                                255
  15235.  
  15236.  
  15237.  
  15238.                                                                                    11.13. TSTRCOLLECTION
  15239.  
  15240.  
  15241.                      Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
  15242.                      Function GetItem (Var S: TStream): Pointer; Virtual;
  15243.                      Procedure FreeItem (Item: Pointer); Virtual;
  15244.                      Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
  15245.                END;
  15246.                PStrCollection = ^TStrCollection;
  15247.  
  15248.  
  15249.            TStrCollection.GetItem
  15250. Declaration: Function TStrCollection.GetItem (Var S: TStream): Pointer; Virtual;
  15251.  
  15252. Description: GetItem reads a null-terminated string from the stream S and returns a pointer
  15253.            to it. It doesn't insert the string in the collection.
  15254.            This method is primarily introduced to be able to load and store the collection from
  15255.            and to a stream.
  15256.  
  15257.     Errors: The errors returned are those of TStream.StrRead (217).
  15258.  
  15259.   See also: PutItem (257)
  15260.  
  15261.  
  15262.            TStrCollection.Compare
  15263. Declaration: Function TStrCollection.Compare (Key1, Key2: Pointer): Sw Integer;
  15264.            Virtual;
  15265.  
  15266. Description: TStrCollection overrides the Compare function so it compares the two keys as if
  15267.            they were pointers to strings. The compare is done case sensitive. It returns
  15268.  
  15269.            -1if the first string is alphabetically earlier than the second string.
  15270.            0if the two strings are equal.
  15271.            1if the first string is alphabetically later than the second string.
  15272.  
  15273.     Errors: None.
  15274.  
  15275.   See also: TSortedCollection.Compare (250)
  15276.  
  15277.            Program ex38 ;
  15278.  
  15279.            { Program to demonstrate the T S t r C o l l e c t i o n . Compare method }
  15280.  
  15281.            Uses Objects , S t r i n g s ;
  15282.  
  15283.            Var C : P S t r C o l l e c t i o n ;
  15284.                  S : String ;
  15285.                   I : l o n g i n t ;
  15286.                  P : Pchar ;
  15287.  
  15288.            begin
  15289.               Randomize ;
  15290.               C:=New( P S t r C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  15291.               C . D u p l i c a t e s := True ; { D u p l i c a t e s allowed }
  15292.               Writeln ( ' I n s e r t i n g 100 r e c o r d s at random p l a c e s . ' ) ;
  15293.               For I :=1 to 100 do
  15294.                  begin
  15295.  
  15296.  
  15297.                                                                256
  15298.  
  15299.  
  15300.  
  15301.                                                              11.14. TUNSORTEDSTRCOLLECTION
  15302.  
  15303.  
  15304.                     Str (Random( 1 0 0 ) , S ) ;
  15305.                     S:= ' S t r i n g with value ' +S ;
  15306.                     P:= S t r A l l o c ( Length ( S)+1);
  15307.                     C . Insert ( StrPCopy (P, S ) ) ;
  15308.                     end ;
  15309.               For I :=0 to 98 do
  15310.                     With C  do
  15311.                        I f Compare ( At( I ) , At( I +1))=0 then
  15312.                              Writeln ( ' D u p l i c a t e s t r i n g found at p o s i t i o n ' , I ) ;
  15313.               Dispose (C, Done ) ;
  15314.            end .
  15315.  
  15316.  
  15317.            TStrCollection.FreeItem
  15318. Declaration: Procedure TStrCollection.FreeItem (Item: Pointer); Virtual;
  15319.  
  15320. Description: TStrCollection overrides FreeItem so that the string pointed to by Item is dis-
  15321.            posed from memory.
  15322.  
  15323.      Errors: None.
  15324.  
  15325.    See also: TCollection.FreeItem (244)
  15326.  
  15327.  
  15328.            TStrCollection.PutItem
  15329. Declaration: Procedure TStrCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
  15330.  
  15331. Description: PutItem writes the string pointed to by Item to the stream S.
  15332.            This method is primarily used in the Load and Store methods, and should not be
  15333.            used directly.
  15334.  
  15335.      Errors: Errors are those of TStream.StrWrite (221).
  15336.  
  15337.    See also: GetItem (256)
  15338.  
  15339.  
  15340.            11.14 TUnSortedStrCollection
  15341.  
  15342.            The TUnSortedStrCollection object manages an unsorted list of objects. To this
  15343.            end, it overrides the TSortedCollection.Insert (252) method to add strings at the end
  15344.            of the collection, rather than in the alphabetically correct position.
  15345.            Take care, the Search (251) and IndexOf (237) methods will not work on an unsorted
  15346.            string collection.
  15347.            Here is the full declaration of the TUnsortedStrCollection object:
  15348.  
  15349.            TYPETUnSortedStrCollection = OBJECT (TStringCollection)
  15350.                       Procedure Insert (Item: Pointer); Virtual;
  15351.                END;
  15352.                PUnSortedStrCollection = ^TUnSortedStrCollection;
  15353.  
  15354.  
  15355.  
  15356.  
  15357.  
  15358.                                                              257
  15359.  
  15360.  
  15361.  
  15362.                                                                             11.15. TRESOURCECOLLECTION
  15363.  
  15364.  
  15365.                 TUnSortedStrCollection.Insert
  15366. Declaration: Procedure TUnSortedStrCollection.Insert (Item: Pointer); Virtual;
  15367.  
  15368. Description: Insert inserts a string at the end of the collection, instead of on it's alphabetical
  15369.                 place, resulting in an unsorted collection of strings.
  15370.  
  15371.      Errors:
  15372.  
  15373.    See also:
  15374.  
  15375.                 Program ex39 ;
  15376.  
  15377.                 { Program to demonstrate the T U n s o r t e d S t r C o l l e c t i o n . I n s e r t method }
  15378.  
  15379.                 Uses Objects , S t r i n g s ;
  15380.  
  15381.                 Var C : P U n s o r t e d S t r C o l l e c t i o n ;
  15382.                          S : String ;
  15383.                          I : l o n g i n t ;
  15384.                          P : Pchar ;
  15385.  
  15386.                 begin
  15387.                    Randomize ;
  15388.                    C:=New( P U n s o r t e d S t r C o l l e c t i o n , I n i t ( 1 2 0 , 1 0 ) ) ;
  15389.                    Writeln ( ' I n s e r t i n g 100 r e c o r d s at random p l a c e s . ' ) ;
  15390.                    For I :=1 to 100 do
  15391.                          begin
  15392.                          Str (Random( 1 0 0 ) , S ) ;
  15393.                          S:= ' S t r i n g with value ' +S ;
  15394.                          P:= S t r A l l o c ( Length ( S)+1);
  15395.                          C . Insert ( StrPCopy (P, S ) ) ;
  15396.                          end ;
  15397.                    For I :=0 to 99 do
  15398.                          Writeln ( I : 2 , ' : ' , PChar (C . At( i ) ) ) ;
  15399.                    Dispose (C, Done ) ;
  15400.                 end .
  15401.  
  15402.  
  15403.                 11.15 TResourceCollection
  15404.  
  15405.                 A TResourceCollection manages a collection of resource names. It stores the
  15406.                 position and the size of a resource, as well as the name of the resource. It stores
  15407.                 these items in records that look like this:
  15408.  
  15409.                 TYPETResourceItem = packed RECORD
  15410.                           Posn: LongInt;
  15411.                           Size: LongInt;
  15412.                           Key : String;
  15413.                     End;
  15414.                     PResourceItem = ^TResourceItem;
  15415.  
  15416.                 It overrides some methods of TStringCollection in order to accomplish this.
  15417.  
  15418.  
  15419.                                                                      258
  15420.  
  15421.  
  15422.  
  15423.                                                            11.15. TRESOURCECOLLECTION
  15424.  
  15425.  
  15426.            Remark that the TResourceCollection manages the names of the resources and
  15427.            their assiciated positions and sizes, it doesn't manage the resources themselves.
  15428.            Here is the full declaration of the TResourceCollection object:
  15429.  
  15430.            TYPETResourceCollection = OBJECT (TStringCollection)
  15431.                       Function KeyOf (Item: Pointer): Pointer; Virtual;
  15432.                       Function GetItem (Var S: TStream): Pointer; Virtual;
  15433.                       Procedure FreeItem (Item: Pointer); Virtual;
  15434.                       Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
  15435.                END;
  15436.                PResourceCollection = ^TResourceCollection;
  15437.  
  15438.  
  15439.            TResourceCollection.KeyOf
  15440. Declaration: Function TResourceCollection.KeyOf (Item: Pointer): Pointer; Virtual;
  15441.  
  15442. Description: KeyOf returns the key of an item in the collection. For resources, the key is a
  15443.            pointer to the string with the resource name.
  15444.  
  15445.      Errors: None.
  15446.  
  15447.    See also: TStringCollection.Compare (254)
  15448.  
  15449.  
  15450.            TResourceCollection.GetItem
  15451. Declaration: Function TResourceCollection.GetItem (Var S: TStream): Pointer; Virtual;
  15452.  
  15453. Description: GetItem reads a resource item from the stream S. It reads the position, size and
  15454.            name from the stream, in that order. It DOES NOT read the resource itself from
  15455.            the stream.
  15456.            The resulting item is not inserted in the collection. This call is manly for internal
  15457.            use by the TCollection.Load (235) method.
  15458.  
  15459.      Errors: Errors returned are those by TStream.Read (222)
  15460.  
  15461.    See also: TCollection.Load (235), TStream.Read (222)
  15462.  
  15463.  
  15464.            TResourceCollection.FreeItem
  15465. Declaration: Procedure TResourceCollection.FreeItem (Item: Pointer); Virtual;
  15466.  
  15467. Description: FreeItem releases the memory occupied by Item. It de-allocates the name, and
  15468.            then the resourceitem record.
  15469.            It does NOT remove the item from the collection.
  15470.  
  15471.      Errors: None.
  15472.  
  15473.    See also: TCollection.FreeItem (244)
  15474.  
  15475.  
  15476.  
  15477.  
  15478.  
  15479.  
  15480.                                                    259
  15481.  
  15482.  
  15483.  
  15484.                                                                      11.16. TRESOURCEFILE
  15485.  
  15486.  
  15487.            TResourceCollection.PutItem
  15488. Declaration: Procedure TResourceCollection.PutItem (Var S: TStream; Item: Pointer);
  15489.            Virtual;
  15490.  
  15491. Description: PutItem writes Item to the stream S. It does this by writing the position and size
  15492.            and name of the resource item to the stream.
  15493.            This method is used primarily by the Store (248) method.
  15494.  
  15495.      Errors: Errors returned are those by TStream.Write (223).
  15496.  
  15497.    See also: Store (248)
  15498.  
  15499.  
  15500.            11.16 TResourceFile
  15501.  
  15502.            TYPETResourceFile = OBJECT (TObject)
  15503.                          Stream : PStream; { File as a stream }
  15504.                          Modified: Boolean; { Modified flag }
  15505.                       Constructor Init (AStream: PStream);
  15506.                       Destructor Done; Virtual;
  15507.                       Function Count: Sw_Integer;
  15508.                       Function KeyAt (I: Sw_Integer): String;
  15509.                       Function Get (Key: String): PObject;
  15510.                       Function SwitchTo (AStream: PStream; Pack: Boolean): PStream;
  15511.                       Procedure Flush;
  15512.                       Procedure Delete (Key: String);
  15513.                       Procedure Put (Item: PObject; Key: String);
  15514.                END;
  15515.                PResourceFile = ^TResourceFile;
  15516.  
  15517.  
  15518.            TResourceFile Fields
  15519.            TResourceFile has the following fields:
  15520.  
  15521.            Stream contains the (file) stream that has the executable image and the resources.
  15522.                  It can be initialized by the Init (260) constructor call.
  15523.  
  15524.            Modified is set to True if one of the resources has been changed. It is set by the
  15525.                  SwitchTo (260), Delete (262) and Put (262) methods. Calling Flush (262) will
  15526.                  clear the Modified flag.
  15527.  
  15528.  
  15529.            TResourceFile.Init
  15530. Declaration: Constructor TResourceFile.Init (AStream: PStream);
  15531.  
  15532. Description: Init instantiates a new instance of a TResourceFile object. If AStream is not nil
  15533.            then it is considered as a stream describing an executable image on disk.
  15534.            Init will try to position the stream on the start of the resources section, and read
  15535.            all resources from the stream.
  15536.  
  15537.      Errors: None.
  15538.  
  15539.    See also: Done (261)
  15540.  
  15541.  
  15542.                                                      260
  15543.  
  15544.  
  15545.  
  15546.                                                                         11.16. TRESOURCEFILE
  15547.  
  15548.  
  15549.             TResourceFile.Done
  15550. Declaration: Destructor TResourceFile.Done; Virtual;
  15551.  
  15552. Description: Done cleans up the instance of the TResourceFile Object. If Stream was specified
  15553.             at initialization, then Stream is disposed of too.
  15554.  
  15555.      Errors: None.
  15556.  
  15557.    See also: Init (260)
  15558.  
  15559.  
  15560.             TResourceFile.Count
  15561. Declaration: Function TResourceFile.Count: Sw Integer;
  15562.  
  15563. Description: Count returns the number of resources. If no resources were read, zero is returned.
  15564.  
  15565.      Errors: None.
  15566.  
  15567.    See also: Init (260)
  15568.  
  15569.  
  15570.             TResourceFile.KeyAt
  15571. Declaration: Function TResourceFile.KeyAt (I: Sw Integer): String;
  15572.  
  15573. Description: KeyAt returns the key (the name) of the I-th resource.
  15574.  
  15575.      Errors: In case I is invalid, TCollection.Error will be executed.
  15576.  
  15577.    See also: Get (261)
  15578.  
  15579.  
  15580.             TResourceFile.Get
  15581. Declaration: Function TResourceFile.Get (Key: String): PObject;
  15582.  
  15583. Description: Get returns a pointer to a instance of a resource identified by Key. If Key cannot
  15584.             be found in the list of resources, then Nil is returned.
  15585.  
  15586.      Errors: Errors returned may be those by TStream.Get
  15587.  
  15588.    See also:
  15589.  
  15590.  
  15591.             TResourceFile.SwitchTo
  15592. Declaration: Function TResourceFile.SwitchTo (AStream: PStream; Pack: Boolean): PStream;
  15593.  
  15594. Description: SwitchTo switches to a new stream to hold the resources in. AStream will be the
  15595.             new stream after the call to SwitchTo.
  15596.             If Pack is true, then all the known resources will be copied from the current stream
  15597.             to the new stream (AStream). If Pack is False, then only the current resource is
  15598.             copied.
  15599.             The return value is the value of the original stream: Stream.
  15600.             The Modified flag is set as a consequence of this call.
  15601.  
  15602.      Errors: Errors returned can be those of TStream.Read (222) and TStream.Write (223).
  15603.  
  15604.    See also: Flush (262)
  15605.  
  15606.  
  15607.                                                       261
  15608.  
  15609.  
  15610.  
  15611.                                                                         11.17. TSTRINGLIST
  15612.  
  15613.  
  15614.            TResourceFile.Flush
  15615. Declaration: Procedure TResourceFile.Flush;
  15616.  
  15617. Description: If the Modified flag is set to True, then Flush writes the resources to the stream
  15618.            Stream. It sets the Modified flag to true after that.
  15619.  
  15620.      Errors: Errors can be those by TStream.Seek (222) and TStream.Write (223).
  15621.  
  15622.    See also: SwitchTo (261)
  15623.  
  15624.  
  15625.            TResourceFile.Delete
  15626. Declaration: Procedure TResourceFile.Delete (Key: String);
  15627.  
  15628. Description: Delete deletes the resource identified by Key from the collection. It sets the
  15629.            Modified flag to true.
  15630.  
  15631.      Errors: None.
  15632.  
  15633.    See also: Flush (262)
  15634.  
  15635.  
  15636.            TResourceFile.Put
  15637. Declaration: Procedure TResourceFile.Put (Item: PObject; Key: String);
  15638.  
  15639. Description: Put sets the resource identified by Key to Item. If no such resource exists, a new
  15640.            one is created. The item is written to the stream.
  15641.  
  15642.      Errors: Errors returned may be those by TStream.Put (221) and TStream.Seek
  15643.  
  15644.    See also: Get (261)
  15645.  
  15646.  
  15647.            11.17 TStringList
  15648.  
  15649.            A TStringList object can be used to read a collection of strings stored in a stream.
  15650.            If you register this object with the RegisterType (207) function, you cannot register
  15651.            the TStrListMaker object.
  15652.            This is the public declaration of the TStringList object:
  15653.  
  15654.            TYPETStrIndexRec = Packed RECORD
  15655.                       Key, Count, Offset: Word;
  15656.                END;
  15657.  
  15658.                TStrIndex = Array [0..9999] Of TStrIndexRec;
  15659.                PStrIndex = ^TStrIndex;
  15660.  
  15661.                TStringList = OBJECT (TObject)
  15662.                       Constructor Load (Var S: TStream);
  15663.                       Destructor Done; Virtual;
  15664.                       Function Get (Key: Sw_Word): String;
  15665.                END;
  15666.                PStringList = ^TStringList;
  15667.  
  15668.  
  15669.                                                    262
  15670.  
  15671.  
  15672.  
  15673.                                                                     11.18. TSTRLISTMAKER
  15674.  
  15675.  
  15676.            TStringList.Load
  15677. Declaration: Constructor TstringList.Load (Var S: TStream);
  15678.  
  15679. Description: The Load constructor reads the TStringList object from the stream S. It also
  15680.            reads the descriptions of the strings from the stream. The string descriptions are
  15681.            stored as an array of TstrIndexrec records, where each record describes a string
  15682.            on the stream. These records are kept in memory.
  15683.  
  15684.      Errors: If an error occurs, a stream error is triggered.
  15685.  
  15686.    See also: Done (263)
  15687.  
  15688.  
  15689.            TStringList.Done
  15690. Declaration: Destructor TstringList.Done; Virtual;
  15691.  
  15692. Description: The Done destructor frees the memory occupied by the string descriptions, and
  15693.            destroys the object.
  15694.  
  15695.      Errors: None.
  15696.  
  15697.    See also: Load (263), TObject.Done (215)
  15698.  
  15699.  
  15700.            TStringList.Get
  15701. Declaration: Function TStringList.Get (Key: Sw Word): String;
  15702.  
  15703. Description: Get reads the string with key Key from the list of strings on the stream, and returns
  15704.            this string. If there is no string with such a key, an empty string is returned.
  15705.  
  15706.      Errors: If no string with key Key is found, an empty string is returned. A stream error
  15707.            may result if the stream doesn't contain the needed strings.
  15708.  
  15709.    See also: TStrListMaker.Put (264)
  15710.  
  15711.  
  15712.            11.18 TStrListMaker
  15713.  
  15714.            The TStrListMaker object can be used to generate a stream with strings, which
  15715.            can be read with the TStringList object. If you register this object with the
  15716.            RegisterType (207) function, you cannot register the TStringList object.
  15717.            This is the public declaration of the TStrListMaker object:
  15718.  
  15719.            TYPETStrListMaker = OBJECT (TObject)
  15720.                       Constructor Init (AStrSize, AIndexSize: Sw_Word);
  15721.                       Destructor Done; Virtual;
  15722.                       Procedure Put (Key: SwWord; S: String);
  15723.                       Procedure Store (Var S: TStream);
  15724.                END;
  15725.                PStrListMaker = ^TStrListMaker;
  15726.  
  15727.  
  15728.  
  15729.  
  15730.  
  15731.                                                      263
  15732.  
  15733.  
  15734.  
  15735.                                                                     11.18. TSTRLISTMAKER
  15736.  
  15737.  
  15738.            TStrListMaker.Init
  15739. Declaration: Constructor TStrListMaker.Init (AStrSize, AIndexSize: SwWord);
  15740.  
  15741. Description: The Init constructor creates a new instance of the TstrListMaker object. It
  15742.            allocates AStrSize bytes on the heap to hold all the strings you wish to store.
  15743.            It also allocates enough room for AIndexSize key description entries (of the type
  15744.            TStrIndexrec).
  15745.            AStrSize must be large enough to contain all the strings you wish to store. If not
  15746.            enough memory is allocated, other memory will be overwritten. The same is true
  15747.            for AIndexSize : maximally AIndexSize strings can be written to the stream.
  15748.  
  15749.      Errors: None.
  15750.  
  15751.    See also: TObject.Init (215), Done (264)
  15752.  
  15753.  
  15754.            TStrListMaker.Done
  15755. Declaration: Destructor TStrListMaker.Done; Virtual;
  15756.  
  15757. Description: The Done destructor de-allocates the memory for the index description records and
  15758.            the string data, and then destroys the object.
  15759.  
  15760.      Errors: None.
  15761.  
  15762.    See also: TObject.Done (215), Init (264)
  15763.  
  15764.  
  15765.            TStrListMaker.Put
  15766. Declaration: Procedure TStrListMaker.Put (Key: Sw Word; S: String);
  15767.  
  15768. Description: Put adds they string S with key Key to the collection of strings. This action doesn't
  15769.            write the string to a stream. To write the strings to the stream, see the Store (264)
  15770.            method.
  15771.  
  15772.      Errors: None.
  15773.  
  15774.    See also: Store (264).
  15775.  
  15776.  
  15777.            TStrListMaker.Store
  15778. Declaration: Procedure TStrListMaker.Store (Var S: TStream);
  15779.  
  15780. Description: Store writes the collection of strings to the stream S. The collection can then be
  15781.            read with the TStringList object.
  15782.  
  15783.      Errors: A stream error may occur when writing the strings to the stream.
  15784.  
  15785.    See also: TStringList.Load (263), Put (264).
  15786.  
  15787.  
  15788.  
  15789.  
  15790.  
  15791.  
  15792.  
  15793.  
  15794.  
  15795.                                                      264
  15796.  
  15797.  
  15798.  
  15799.            Chapter 12
  15800.  
  15801.            The PRINTER unit.
  15802.  
  15803.            This chapter describes the PRINTER unit for Free Pascal. It was written for dos
  15804.            by Florian kl¿ampfl, and it was written for linux by Micha¿el Van Canneyt. Its basic
  15805.            functionality is the same for both systems. The chapter is divided in 2 sections:
  15806.  
  15807.               * The first section lists types, constants and variables from the interface part of
  15808.                  the unit.
  15809.  
  15810.               * The second section describes the functions defined in the unit.
  15811.  
  15812.  
  15813.            12.1 Types, Constants and variables :
  15814.  
  15815.            varlst : text;
  15816.  
  15817.            Lst is the standard printing device.
  15818.            On linux, Lst is set up using AssignLst('/tmp/PID.lst'). You can change this
  15819.            behaviour at compile time, setting the DefFile constant.
  15820.  
  15821.  
  15822.            12.2 Procedures and functions
  15823.  
  15824.            AssignLst
  15825. Declaration: Procedure AssignLst ( Var F : text; ToFile : string[255]);
  15826.  
  15827. Description: linux only.
  15828.            Assigns to F a printing device. ToFile is a string with the following form:
  15829.  
  15830.                * '|filename options' : This sets up a pipe with the program filename, with
  15831.                 the given options, such as in the popen() call.
  15832.                * 'filename' : Prints to file filename. Filename can contain the string 'PID'
  15833.                 (No Quotes), which will be replaced by the PID of your program. When closing
  15834.                 lst, the file will be sent to lpr and deleted. (lpr should be in PATH)
  15835.                *'filename|' Idem as previous, only the file is NOT sent to lpr, nor is it
  15836.                 deleted. (useful for opening /dev/printer or for later printing)
  15837.  
  15838.      Errors: Errors are reported in Linuxerror.
  15839.  
  15840.  
  15841.                                                    265
  15842.  
  15843.  
  15844.  
  15845.                                                         12.2. PROCEDURES AND FUNCTIONS
  15846.  
  15847.  
  15848. See also: lpr (1)
  15849.  
  15850.         program t e s t p r n ;
  15851.  
  15852.         uses p r i n t e r ;
  15853.  
  15854.         var i : i n t e g e r ;
  15855.                  f : text ;
  15856.  
  15857.         begin
  15858.            writeln ( ' Test of p r i n t e r unit ' ) ;
  15859.            writeln ( ' Writing to l s t . . . ' ) ;
  15860.            for i :=1 to 80 do writeln ( l s t , ' This i s l i n e ' , i , ' . ' #13);
  15861.            c l o s e ( l s t ) ;
  15862.            writeln ( ' Done . ' ) ;
  15863.            { $ i f d e f l i n u x }
  15864.            writeln ( ' Writing to pipe . . . ' ) ;
  15865.            a s s i g n l s t ( f , ' | / usr / bin / l p r -m' ) ;
  15866.            rewrite ( f ) ;
  15867.            for i :=1 to 80 do writeln ( f , ' This i s l i n e ' , i , ' . ' #13);
  15868.            c l o s e ( f ) ;
  15869.            writeln ( ' Done . ' )
  15870.            { $ e n d i f }
  15871.         end .
  15872.  
  15873.  
  15874.  
  15875.  
  15876.  
  15877.  
  15878.  
  15879.  
  15880.  
  15881.  
  15882.  
  15883.  
  15884.  
  15885.  
  15886.  
  15887.  
  15888.  
  15889.  
  15890.  
  15891.  
  15892.  
  15893.  
  15894.  
  15895.  
  15896.  
  15897.  
  15898.  
  15899.  
  15900.  
  15901.                                                         266
  15902.  
  15903.  
  15904.  
  15905. Chapter 13
  15906.  
  15907. The SOCKETS unit.
  15908.  
  15909. This chapter describes the SOCKETS unit for Free Pascal. it was written for linux
  15910. by Micha¿el Van Canneyt. The chapter is divided in 2 sections:
  15911.  
  15912.    * The first section lists types, constants and variables from the interface part of
  15913.       the unit.
  15914.    * The second section describes the functions defined in the unit.
  15915.  
  15916.  
  15917. 13.1 Types, Constants and variables :
  15918.  
  15919. The following constants identify the di erent socket types, as needed in the Socket
  15920. (277) call.
  15921.  
  15922. SOCK_STREAM        = 1; { stream (connection) socket            }
  15923. SOCK_DGRAM         = 2; { datagram (conn.less) socket }
  15924. SOCK_RAW           = 3; { raw socket                            }
  15925. SOCK_RDM           = 4; { reliably-delivered message            }
  15926. SOCK_SEQPACKET = 5; { sequential packet socket                  }
  15927. SOCK_PACKET        =10;
  15928.  
  15929. The following constants determine the socket domain, they are used in the Socket
  15930. (277) call.
  15931.  
  15932. AF_UNSPEC          = 0;
  15933. AF_UNIX            = 1; { Unix domain sockets                   }
  15934. AF_INET            = 2; { Internet IP Protocol                  }
  15935. AF_AX25            = 3; { Amateur Radio AX.25                   }
  15936. AF_IPX             = 4; { Novell IPX                            }
  15937. AF_APPLETALK       = 5; { Appletalk DDP                         }
  15938. AF_NETROM          = 6; { Amateur radio NetROM                  }
  15939. AF_BRIDGE          = 7; { Multiprotocol bridge                  }
  15940. AF_AAL5            = 8; { Reserved for Werner's ATM             }
  15941. AF_X25             = 9; { Reserved for X.25 project             }
  15942. AF_INET6           = 10; { IP version 6                              }
  15943. AF_MAX             = 12;
  15944.  
  15945. The following constants determine the protocol family, they are used in the Socket
  15946. (277) call.
  15947.  
  15948.                                         267
  15949.  
  15950.  
  15951.  
  15952.                                                     13.2. FUNCTIONS AND PROCEDURES
  15953.  
  15954.  
  15955.            PF_UNSPEC             = AF_UNSPEC;
  15956.            PF_UNIX               = AF_UNIX;
  15957.            PF_INET               = AF_INET;
  15958.            PF_AX25               = AF_AX25;
  15959.            PF_IPX                = AF_IPX;
  15960.            PF_APPLETALK          = AF_APPLETALK;
  15961.            PF_NETROM             = AF_NETROM;
  15962.            PF_BRIDGE             = AF_BRIDGE;
  15963.            PF_AAL5               = AF_AAL5;
  15964.            PF_X25                = AF_X25;
  15965.            PF_INET6              = AF_INET6;
  15966.            PF_MAX                = AF_MAX;
  15967.  
  15968.            The following types are used to store di erent kinds of eddresses for the Bind (270),
  15969.            Recv (275) and Send (275) calls.
  15970.  
  15971.            TSockAddr = packed Record
  15972.              family:word;
  15973.              data :array [0..13] of char;
  15974.              end;
  15975.            TUnixSockAddr = packed Record
  15976.              family:word;
  15977.              path:array[0..108] of char;
  15978.              end;
  15979.            TInetSockAddr = packed Record
  15980.              family:Word;
  15981.              port :Word;
  15982.              addr :Cardinal;
  15983.              pad         :array [1..8] of byte;
  15984.              end;
  15985.  
  15986.            The following type is returned by the SocketPair (277) call.
  15987.  
  15988.            TSockArray = Array[1..2] of Longint;
  15989.  
  15990.  
  15991.            13.2 Functions and Procedures
  15992.  
  15993.            Accept
  15994. Declaration: Function Accept (Sock:Longint;Var Addr;Var Addrlen:Longint) : Longint;
  15995. Description: Accept accepts a connection from a socket Sock, which was listening for a con-
  15996.            nection. If a connection is accepted, a file descriptor is returned. On error -1 is
  15997.            returned. The returned socket may NOT be used to accept more connections. The
  15998.            original socket remains open.
  15999.            The Accept call fills the address of the connecting entity in Addr, and sets its length
  16000.            in Addrlen. Addr should be pointing to enough space, and Addrlen should be set
  16001.            to the amount of space available, prior to the call.
  16002.     Errors: On error, -1 is returned, and errors are reported in SocketError, and include the
  16003.            following:
  16004.            SYS EBADFThe socket descriptor is invalid.
  16005.            SYS ENOTSOCKThe descriptor is not a socket.
  16006.  
  16007.                                                     268
  16008.  
  16009.  
  16010.  
  16011.                                                       13.2. FUNCTIONS AND PROCEDURES
  16012.  
  16013.  
  16014.         SYS EOPNOTSUPPThe socket type doesn't support the Listen operation.
  16015.         SYS EFAULTAddr points outside your address space.
  16016.         SYS EWOULDBLOCKThe requested operation would block the process.
  16017. See also: Listen (274), Connect (271)
  16018.  
  16019.         Program s e r v e r ;
  16020.  
  16021.         { Program to test Sockets unit by Michael van Canneyt and Peter Vreman
  16022.              Server Version , F i r s t Run sock svr to l e t i t c r e a t e a socket and then
  16023.              s o c k c l i to connect to that socket
  16024.         }
  16025.  
  16026.         uses Linux , Sockets ;
  16027.         const
  16028.              SPath=' ServerSoc ' ;
  16029.  
  16030.         VarFromName : string ;
  16031.              Buffer         : st r ing [ 2 5 5 ] ;
  16032.              S              : Longint ;
  16033.              Sin , Sout : Text ;
  16034.  
  16035.         procedure p e r r o r ( const S : st ri ng ) ;
  16036.         begin
  16037.              writeln ( S , So cketE rr or ) ;
  16038.              halt ( 1 0 0 ) ;
  16039.         end ;
  16040.  
  16041.  
  16042.  
  16043.         begin
  16044.              S:= Socket ( AF UNIX, SOCK STREAM, 0 ) ;
  16045.              i f So cketE rr or <>0 then
  16046.                   Perror ( ' Server : Socket : ' ) ;
  16047.              UnLink ( SPath ) ;
  16048.              i f not Bind ( S , SPath ) then
  16049.                   PError ( ' Server : Bind : ' ) ;
  16050.              i f not L i s t e n ( S , 1 ) then
  16051.                   PError ( ' Server : L i s t e n : ' ) ;
  16052.              Writeln ( ' Waiting fo r Connect from C l i e n t , run now s o c k c l i in an other tty ' ) ;
  16053.              i f not Accept ( S , FromName , Sin , Sout ) then
  16054.                   PError ( ' Server : Accept : ' ) ;
  16055.              Reset ( Sin ) ;
  16056.              ReWrite ( Sout ) ;
  16057.              Writeln ( Sout , ' Message From Server ' ) ;
  16058.              Flush ( SOut ) ;
  16059.              while not eof ( sin ) do
  16060.                   begin
  16061.                     Readln ( Sin , Buffer ) ;
  16062.                     Writeln ( ' Server : read : ' , b u f f e r ) ;
  16063.                   end ;
  16064.              Unlink ( SPath ) ;
  16065.  
  16066.                                                       269
  16067.  
  16068.  
  16069.  
  16070.                                                       13.2. FUNCTIONS AND PROCEDURES
  16071.  
  16072.  
  16073.            end .
  16074.  
  16075.  
  16076.            Accept
  16077. Declaration: Function Accept (Sock:longint;var addr:string;var SockIn,SockOut:text)
  16078.            : Boolean;
  16079.  
  16080. Description: This is an alternate form of the Accept (268) command. It is equivalent to subse-
  16081.            quently calling the regular Accept (268) function and the Sock2Text (277) function.
  16082.            The function returns True if successfull, False otherwise.
  16083.  
  16084.      Errors: The errors are those of Accept (268).
  16085.  
  16086.    See also: Accept (268)
  16087.  
  16088.  
  16089.            Accept
  16090. Declaration: Function Accept (Sock:longint;var addr:string;var SockIn,SockOut:File)
  16091.            : Boolean;
  16092.  
  16093. Description: This is an alternate form of the Accept (268) command. It is equivalent to subse-
  16094.            quently calling the regular Accept (268) function and the Sock2File (276) function.
  16095.            The Addr parameter contains the name of the unix socket file to be opened. The
  16096.            function returns True if successfull, False otherwise.
  16097.  
  16098.      Errors: The errors are those of Accept (268).
  16099.  
  16100.    See also: Accept (268)
  16101.  
  16102.  
  16103.            Accept
  16104. Declaration: Function Accept (Sock:longint;var addr:TInetSockAddr;var SockIn,SockOut:File)
  16105.            : Boolean;
  16106.  
  16107. Description: This is an alternate form of the Accept (268) command. It is equivalent to subse-
  16108.            quently calling the regular Accept (268) function and the Sock2File (276) function.
  16109.            The Addr parameter contains the parameters of the internet socket that should be
  16110.            opened. The function returns True if successfull, False otherwise.
  16111.  
  16112.      Errors: The errors are those of Accept (268).
  16113.  
  16114.    See also: Accept (268)
  16115.  
  16116.  
  16117.            Bind
  16118. Declaration: Function Bind (Sock:Longint;Var Addr;AddrLen:Longint) : Boolean;
  16119.  
  16120. Description: Bind binds the socket Sock to address Addr. Addr has length Addrlen. The
  16121.            function returns True if the call was succesful, False if not.
  16122.  
  16123.      Errors: Errors are returned in SocketError and include the following:
  16124.  
  16125.            SYS EBADFThe socket descriptor is invalid.
  16126.            SYS EINVALThe socket is already bound to an address,
  16127.            SYS EACCESSAddress is protected and you don't have permission to open it.
  16128.  
  16129.                                                       270
  16130.  
  16131.  
  16132.  
  16133.                                                          13.2. FUNCTIONS AND PROCEDURES
  16134.  
  16135.  
  16136.            More arrors can be found in the Unix man pages.
  16137.  
  16138.    See also: Socket (277)
  16139.  
  16140.  
  16141.            Bind
  16142. Declaration: Function Bind (Sock:longint;const addr:string) : boolean;
  16143.  
  16144. Description: This is an alternate form of the Bind command. This form of the Bind command
  16145.            is equivalent to subsequently calling Str2UnixSockAddr (277) and the regular Bind
  16146.            (270) function. The function returns True if successfull, False otherwise.
  16147.  
  16148.      Errors: Errors are those of the regular Bind (270) command.
  16149.  
  16150.    See also: Bind (270)
  16151.  
  16152.  
  16153.            Connect
  16154. Declaration: Function Connect (Sock:Longint;Var Addr;Addrlen:Longint) : Longint;
  16155.  
  16156. Description: Connect opens a connection to a peer, whose address is described by Addr. AddrLen
  16157.            contains the length of the address. The type of Addr depends on the kind of connec-
  16158.            tion you're trying to make, but is generally one of TSockAddr or TUnixSockAddr.
  16159.            The Connect function returns a file descriptor if the call was successfull, -1 in case
  16160.            of error.
  16161.  
  16162.      Errors: On error, -1 is returned and errors are reported in SocketError.
  16163.  
  16164.    See also: Listen (274), Bind (270),Accept (268)
  16165.  
  16166.            Program C l i e n t ;
  16167.  
  16168.            { Program to test Sockets unit by Michael van Canneyt and Peter Vreman
  16169.                 C l i e n t Version , F i r s t Run sock svr to l e t i t c r e a t e a socket and then
  16170.                 s o c k c l i to connect to that socket
  16171.            }
  16172.  
  16173.            uses Sockets , Linux ;
  16174.  
  16175.            procedure PError ( const S : s tr in g ) ;
  16176.            begin
  16177.                 writeln ( S , Soc ket Erro r ) ;
  16178.                 halt ( 1 0 0 ) ;
  16179.            end ;
  16180.  
  16181.  
  16182.            VarSaddr            : String [ 2 5 ] ;
  16183.                 Buffer         : st r ing [ 2 5 5 ] ;
  16184.                 S              : Longint ;
  16185.                 Sin , Sout : Text ;
  16186.                 i              : i n t e g e r ;
  16187.            begin
  16188.                 S:= Socket ( AF UNIX, SOCK STREAM, 0 ) ;
  16189.  
  16190.                                                          271
  16191.  
  16192.  
  16193.  
  16194.                                                       13.2. FUNCTIONS AND PROCEDURES
  16195.  
  16196.  
  16197.              i f So cketE rr or <>0 then
  16198.                Perror ( ' C l i e n t : Socket : ' ) ;
  16199.              Saddr := ' ServerSoc ' ;
  16200.              i f not Connect ( S , SAddr , Sin , Sout ) then
  16201.                PError ( ' C l i e n t : Connect : ' ) ;
  16202.              Reset ( Sin ) ;
  16203.              ReWrite ( Sout ) ;
  16204.              Buffer := ' This i s a t e x t s t r i n g sent by the C l i e n t . ' ;
  16205.              for i :=1 to 10 do
  16206.                Writeln ( Sout , Buffer ) ;
  16207.              Flush ( Sout ) ;
  16208.              Readln ( SIn , Buffer ) ;
  16209.              WriteLn ( Buffer ) ;
  16210.              Close ( sout ) ;
  16211.           end .
  16212.  
  16213.  
  16214.           Connect
  16215. Declaration: Function Connect (Sock:longint;const addr:string;var SockIn,SockOut:text)
  16216.           : Boolean;
  16217.  
  16218. Description: This is an alternate form of the Connect (271) command. It is equivalent to
  16219.           subsequently calling the regular Connect (271) function and the Sock2Text (277)
  16220.           function. The function returns True if successfull, False otherwise.
  16221.  
  16222.     Errors: The errors are those of Connect (271).
  16223.  
  16224.   See also: Connect (271)
  16225.  
  16226.  
  16227.           Connect
  16228. Declaration: Function Connect (Sock:longint;const addr:string;var SockIn,SockOut:file)
  16229.           : Boolean;
  16230.  
  16231. Description: This is an alternate form of the Connect (271) command. The parameter addr
  16232.           contains the name of the unix socket file to be opened. It is equivalent to subse-
  16233.           quently calling the regular Connect (271) function and the Sock2File (276) function.
  16234.           The function returns True if successfull, False otherwise.
  16235.  
  16236.     Errors: The errors are those of Connect (271).
  16237.  
  16238.   See also: Connect (271)
  16239.  
  16240.  
  16241.           Connect
  16242. Declaration: Function Connect (Sock:longint;const addr: TInetSockAddr;var SockIn,SockOut:file)
  16243.           : Boolean;
  16244.  
  16245. Description: This is another alternate form of the Connect (271) command. It is equivalent
  16246.           to subsequently calling the regular Connect (271) function and the Sock2File (276)
  16247.           function. The Addr parameter contains the parameters of the internet socket to
  16248.           connect to. The function returns True if successfull, False otherwise.
  16249.  
  16250.     Errors: The errors are those of Connect (271).
  16251.  
  16252.  
  16253.                                                       272
  16254.  
  16255.  
  16256.  
  16257.                                                        13.2. FUNCTIONS AND PROCEDURES
  16258.  
  16259.  
  16260.   See also: Connect (271)
  16261.  
  16262.           program p f i n g e r ;
  16263.  
  16264.           uses s o c k e t s , e r r o r s ;
  16265.  
  16266.           Var Addr : TInetSockAddr ;
  16267.                    S : Longint ;
  16268.                    Sin , Sout : Text ;
  16269.                    Line : strin g ;
  16270.  
  16271.           begin
  16272.              Addr . f a m i l y :=AF INET;
  16273.              { port 79 in network order }
  16274.              Addr . port :=79 shl 8 ;
  16275.              { l o c a l h o s t : 1 2 7 . 0 . 0 . 1 in network order }
  16276.              Addr . addr :=((1 shl 2 4 ) or 1 2 7 ) ;
  16277.              S:= Socket ( AF INET, SOCK STREAM, 0 ) ;
  16278.              I f Not Connect ( S ,ADDR, SIN , SOUT) Then
  16279.                    begin
  16280.                    Writeln ( ' Couldn ' ' t connect to l o c a l h o s t ' ) ;
  16281.                    Writeln ( ' Socket e r r o r : ' , s t r e r r o r ( S ock et E rror ) ) ;
  16282.                    halt ( 1 ) ;
  16283.                    end ;
  16284.              rewrite ( sout ) ;
  16285.              reset ( sin ) ;
  16286.              writeln ( sout , paramstr ( 1 ) ) ;
  16287.              flush ( sout ) ;
  16288.              while not eof ( sin ) do
  16289.                    begin
  16290.                    readln ( Sin , l i n e ) ;
  16291.                    writeln ( l i n e ) ;
  16292.                    end ;
  16293.              c l o s e ( sin ) ;
  16294.              c l o s e ( sout ) ;
  16295.           end .
  16296.  
  16297.  
  16298.           GetPeerName
  16299. Declaration: Function GetPeerName (Sock:Longint;Var Addr;Var Addrlen:Longint) : Longint;
  16300.  
  16301. Description: GetPeerName returns the name of the entity connected to the specified socket
  16302.           Sock. The Socket must be connected for this call to work. Addr should point to
  16303.           enough space to store the name, the amount of space pointed to should be set in
  16304.           Addrlen. When the function returns succesfully, Addr will be filled with the name,
  16305.           and Addrlen will be set to the length of Addr.
  16306.  
  16307.     Errors: Errors are reported in SocketError, and include the following:
  16308.  
  16309.           SYS EBADFThe socket descriptor is invalid.
  16310.           SYS ENOBUFSThe system doesn't have enough bu ers to perform the opera-
  16311.                    tion.
  16312.           SYS ENOTSOCKThe descriptor is not a socket.
  16313.  
  16314.  
  16315.                                                         273
  16316.  
  16317.  
  16318.  
  16319.                                                   13.2. FUNCTIONS AND PROCEDURES
  16320.  
  16321.  
  16322.            SYS EFAULTAddr points outside your address space.
  16323.            SYS ENOTCONNThe socket isn't connected.
  16324.  
  16325.   See also: Connect (271), Socket (277), connect (2)
  16326.  
  16327.  
  16328.            GetSocketName
  16329. Declaration: Function GetSocketName (Sock:Longint;Var Addr;Var Addrlen:Longint) : Longint;
  16330.  
  16331. Description: GetSockName returns the current name of the specified socket Sock. Addr should
  16332.            point to enough space to store the name, the amount of space pointed to should be
  16333.            set in Addrlen. When the function returns succesfully, Addr will be filled with the
  16334.            name, and Addrlen will be set to the length of Addr.
  16335.  
  16336.     Errors: Errors are reported in SocketError, and include the following:
  16337.  
  16338.            SYS EBADFThe socket descriptor is invalid.
  16339.            SYS ENOBUFSThe system doesn't have enough bu ers to perform the opera-
  16340.                 tion.
  16341.            SYS ENOTSOCKThe descriptor is not a socket.
  16342.            SYS EFAULTAddr points outside your address space.
  16343.  
  16344.   See also: Bind (270)
  16345.  
  16346.  
  16347.            GetSocketOptions
  16348. Declaration: Function GetSocketOptions (Sock,Level,OptName:Longint;Var OptVal;optlen:longint)
  16349.            : Longint;
  16350.  
  16351. Description: GetSocketOptions gets the connection options for socket Sock. The socket may
  16352.            be obtained from di erent levels, indicated by Level, which can be one of the
  16353.            following:
  16354.  
  16355.            SOL SOCKETFrom the socket itself.
  16356.            XXXset Level to XXX, the protocol number of the protocol which should interprete
  16357.                 the option.
  16358.  
  16359.            For more information on this call, refer to the unix manual page getsockopt (2) .
  16360.  
  16361.     Errors: Errors are reported in SocketError, and include the following:
  16362.  
  16363.            SYS EBADFThe socket descriptor is invalid.
  16364.            SYS ENOTSOCKThe descriptor is not a socket.
  16365.            SYS EFAULTOptVal points outside your address space.
  16366.  
  16367.   See also: GetSocketOptions (274)
  16368.  
  16369.  
  16370.            Listen
  16371. Declaration: Function Listen (Sock,MaxConnect:Longint) : Boolean;
  16372.  
  16373. Description: Listen listens for up to MaxConnect connections from socket Sock. The socket
  16374.            Sock must be of type SOCK STREAM or Sock SEQPACKET. The function returns True
  16375.            if a connection was accepted, False if an error occurred.
  16376.  
  16377.  
  16378.                                                   274
  16379.  
  16380.  
  16381.  
  16382.                                                    13.2. FUNCTIONS AND PROCEDURES
  16383.  
  16384.  
  16385.     Errors: Errors are reported in SocketError, and include the following:
  16386.            SYS EBADFThe socket descriptor is invalid.
  16387.            SYS ENOTSOCKThe descriptor is not a socket.
  16388.            SYS EOPNOTSUPPThe socket type doesn't support the Listen operation.
  16389.   See also: Socket (277), Bind (270), Connect (271)
  16390.  
  16391.  
  16392.            Recv
  16393. Declaration: Function Recv (Sock:Longint;Var Addr;AddrLen,Flags:Longint) : Longint;
  16394. Description: Recv reads at most Addrlen bytes from socket Sock into address Addr. The socket
  16395.            must be in a connected state. Flags can be one of the following:
  16396.            1: Process out-of band data.
  16397.            4: Bypass routing, use a direct interface.
  16398.            ??: Wait for full request or report an error.
  16399.            The functions returns the number of bytes actually read from the socket, or -1 if a
  16400.            detectable error occurred.
  16401.     Errors: Errors are reported in SocketError, and include the following:
  16402.            SYS EBADFThe socket descriptor is invalid.
  16403.            SYS ENOTCONNThe socket isn't connected.
  16404.            SYS ENOTSOCKThe descriptor is not a socket.
  16405.            SYS EFAULTThe address is outside your address space.
  16406.            SYS EMSGSIZEThe message cannot be sent atomically.
  16407.            SYS EWOULDBLOCKThe requested operation would block the process.
  16408.            SYS ENOBUFSThe system doesn't have enough free bu ers available.
  16409.   See also: Send (275)
  16410.  
  16411.  
  16412.            Send
  16413. Declaration: Function Send (Sock:Longint;Var Addr;AddrLen,Flags:Longint) : Longint;
  16414. Description: Send sends AddrLen bytes starting from address Addr to socket Sock. Sock must
  16415.            be in a connected state. The function returns the number of bytes sent, or -1 if a
  16416.            detectable error occurred. Flags can be one of the following:
  16417.            1: Process out-of band data.
  16418.            4: Bypass routing, use a direct interface.
  16419.     Errors: Errors are reported in SocketError, and include the following:
  16420.            SYS EBADFThe socket descriptor is invalid.
  16421.            SYS ENOTSOCKThe descriptor is not a socket.
  16422.            SYS EFAULTThe address is outside your address space.
  16423.            SYS EMSGSIZEThe message cannot be sent atomically.
  16424.            SYS EWOULDBLOCKThe requested operation would block the process.
  16425.            SYS ENOBUFSThe system doesn't have enough free bu ers available.
  16426.   See also: Recv (275), send (2)
  16427.  
  16428.  
  16429.                                                    275
  16430.  
  16431.  
  16432.  
  16433.                                                     13.2. FUNCTIONS AND PROCEDURES
  16434.  
  16435.  
  16436.            SetSocketOptions
  16437. Declaration: Function SetSocketOptions (Sock,Level,OptName:Longint;Var OptVal;optlen:longint)
  16438.            : Longint;
  16439.  
  16440. Description: SetSocketOptions sets the connection options for socket Sock. The socket may
  16441.            be manipulated at di erent levels, indicated by Level, which can be one of the
  16442.            following:
  16443.  
  16444.            SOL SOCKETTo manipulate the socket itself.
  16445.            XXXset Level to XXX, the protocol number of the protocol which should interprete
  16446.                 the option.
  16447.  
  16448.            For more information on this call, refer to the unix manual page setsockopt (2) .
  16449.  
  16450.      Errors: Errors are reported in SocketError, and include the following:
  16451.  
  16452.            SYS EBADFThe socket descriptor is invalid.
  16453.            SYS ENOTSOCKThe descriptor is not a socket.
  16454.            SYS EFAULTOptVal points outside your address space.
  16455.  
  16456.    See also: GetSocketOptions (274)
  16457.  
  16458.  
  16459.            Shutdown
  16460. Declaration: Function Shutdown (Sock:Longint;How:Longint) : Longint;
  16461.  
  16462. Description: ShutDown closes one end of a full duplex socket connection, described by Sock. How
  16463.            determines how the connection will be shut down, and can be one of the following:
  16464.  
  16465.            0: Further receives are disallowed.
  16466.            1: Further sends are disallowed.
  16467.            2: Sending nor receiving are allowed.
  16468.  
  16469.            On succes, the function returns 0, on error -1 is returned.
  16470.  
  16471.      Errors: SocketError is used to report errors, and includes the following:
  16472.  
  16473.            SYS EBADFThe socket descriptor is invalid.
  16474.            SYS ENOTCONNThe socket isn't connected.
  16475.            SYS ENOTSOCKThe descriptor is not a socket.
  16476.  
  16477.    See also: Socket (277), Connect (271)
  16478.  
  16479.  
  16480.            Sock2File
  16481. Declaration: Procedure Sock2File (Sock:Longint;Var SockIn,SockOut:File);
  16482.  
  16483. Description: Sock2File transforms a socket Sock into 2 Pascal file descriptors of type File,
  16484.            one for reading from the socket (SockIn), one for writing to the socket (SockOut).
  16485.  
  16486.      Errors: None.
  16487.  
  16488.    See also: Socket (277), Sock2Text (277)
  16489.  
  16490.  
  16491.  
  16492.                                                     276
  16493.  
  16494.  
  16495.  
  16496.                                                     13.2. FUNCTIONS AND PROCEDURES
  16497.  
  16498.  
  16499.            Sock2Text
  16500. Declaration: Procedure Sock2Text (Sock:Longint;Var SockIn,SockOut: Text);
  16501.  
  16502. Description: Sock2Text transforms a socket Sock into 2 Pascal file descriptors of type Text,
  16503.            one for reading from the socket (SockIn), one for writing to the socket (SockOut).
  16504.  
  16505.     Errors: None.
  16506.  
  16507.   See also: Socket (277), Sock2File (276)
  16508.  
  16509.  
  16510.            Socket
  16511. Declaration: Function Socket (Domain,SocketType,Protocol:Longint) : Longint;
  16512.  
  16513. Description: Socket creates a new socket in domain Domain, from type SocketType using pro-
  16514.            tocol Protocol. The Domain, Socket type and Protocol can be specified using
  16515.            predefined constants (see the section on constants for available constants) If succes-
  16516.            full, the function returns a socket descriptor, which can be passed to a subsequent
  16517.            Bind (270) call. If unsuccesfull, the function returns -1.
  16518.  
  16519.     Errors: Errors are returned in SocketError, and include the follwing:
  16520.  
  16521.            SYS EPROTONOSUPPORTThe protocol type or the specified protocol is not
  16522.                 supported within this domain.
  16523.            SYS EMFILEThe per-process descriptor table is full.
  16524.            SYS ENFILEThe system file table is full.
  16525.            SYS EACCESSPermission to create a socket of the specified type and/or proto-
  16526.                 col is denied.
  16527.            SYS ENOBUFSInsu cient bu er space is available. The socket cannot be cre-
  16528.                 ated until su cient resources are freed.
  16529.  
  16530.   See also: SocketPair (277), socket (2)
  16531.  
  16532.            for an example, see Accept (268).
  16533.  
  16534.  
  16535.            SocketPair
  16536. Declaration: Function SocketPair (Domain,SocketType,Protocol:Longint;var Pair:TSockArray)
  16537.            : Longint;
  16538.  
  16539. Description: SocketPair creates 2 sockets in domain Domain, from type SocketType and using
  16540.            protocol Protocol. The pair is returned in Pair, and they are indistinguishable.
  16541.            The function returns -1 upon error and 0 upon success.
  16542.  
  16543.     Errors: Errors are reported in SocketError, and are the same as in Socket (277)
  16544.  
  16545.   See also: Str2UnixSockAddr (277)
  16546.  
  16547.  
  16548.            Str2UnixSockAddr
  16549. Declaration: Procedure Str2UnixSockAddr(const addr:string;var t:TUnixSockAddr;var len:longint)
  16550.  
  16551. Description: Str2UnixSockAddr transforms a Unix socket address in a string to a TUnixSockAddr
  16552.            structure which can be passed to the Bind (270) call.
  16553.  
  16554.  
  16555.                                                     277
  16556.  
  16557.  
  16558.  
  16559.                                       13.2. FUNCTIONS AND PROCEDURES
  16560.  
  16561.  
  16562.   Errors: None.
  16563.  
  16564. See also: Socket (277), Bind (270)
  16565.  
  16566.  
  16567.  
  16568.  
  16569.  
  16570.  
  16571.  
  16572.  
  16573.  
  16574.  
  16575.  
  16576.  
  16577.  
  16578.  
  16579.  
  16580.  
  16581.  
  16582.  
  16583.  
  16584.  
  16585.  
  16586.  
  16587.  
  16588.  
  16589.  
  16590.  
  16591.  
  16592.  
  16593.  
  16594.  
  16595.  
  16596.  
  16597.  
  16598.  
  16599.  
  16600.  
  16601.  
  16602.  
  16603.  
  16604.  
  16605.  
  16606.  
  16607.  
  16608.  
  16609.  
  16610.  
  16611.  
  16612.  
  16613.  
  16614.                                       278
  16615.  
  16616.  
  16617.  
  16618.            Chapter 14
  16619.  
  16620.            The STRINGS unit.
  16621.  
  16622.            This chapter describes the STRINGS unit for Free Pascal. Since the unit only pro-
  16623.            vides some procedures and functions, there is only one section, which gives the
  16624.            declarations of these functions, together with an explanation.
  16625.  
  16626.  
  16627.            14.1 Functions and procedures.
  16628.  
  16629.            StrAlloc
  16630. Declaration: Function StrAlloc (Len : Longint);PChar
  16631.  
  16632. Description: StrAlloc reserves memory on the heap for a string with length Len, terminating
  16633.            #0 included, and returns a pointer to it.
  16634.  
  16635.     Errors: If there is not enough memory, a run-time error occurs.
  16636.  
  16637.   See also: StrNew (286), StrPCopy (287).
  16638.  
  16639.  
  16640.            StrCat
  16641. Declaration: Function StrCat (Dest,Source : PChar) : PChar;
  16642.  
  16643. Description: Attaches Source to Dest and returns Dest.
  16644.  
  16645.     Errors: No length checking is performed.
  16646.  
  16647.   See also: Concat ()
  16648.  
  16649.            Program Example11 ;
  16650.  
  16651.            Uses s t r i n g s ;
  16652.  
  16653.            { Program to demonstrate the StrCat f u n c t i o n . }
  16654.  
  16655.            Const P1 : PChar = ' This i s a PChar S t r i n g . ' ;
  16656.  
  16657.            Var P2 : PChar ;
  16658.  
  16659.            begin
  16660.               P2:= S t r A l l o c ( StrLen ( P1) 2+1);
  16661.  
  16662.                                                    279
  16663.  
  16664.  
  16665.  
  16666.                                                        14.1. FUNCTIONS AND PROCEDURES.
  16667.  
  16668.  
  16669.               StrMove ( P2 , P1 , StrLen ( P1 )+1); { P2=P1 }
  16670.               StrCat ( P2 , P1 ) ;                            { Append P2 once more }
  16671.               Writeln ( ' P2 : ' , P2 ) ;
  16672.            end .
  16673.  
  16674.  
  16675.            StrComp
  16676. Declaration: Function StrComp (S1,S2 : PChar) : Longint;
  16677.  
  16678. Description: Compares the null-terminated strings S1 and S2. The result is
  16679.  
  16680.                *A negative Longint when S1<S2.
  16681.                *0 when S1=S2.
  16682.                *A positive Longint when S1>S2.
  16683.  
  16684.      Errors: None.
  16685.  
  16686.    See also: StrLComp (283), StrIComp (282), StrLIComp (285)
  16687.  
  16688.            For an example, see StrLComp (283).
  16689.  
  16690.  
  16691.            StrCopy
  16692. Declaration: Function StrCopy (Dest,Source : PChar) : PChar;
  16693.  
  16694. Description: Copy the null terminated string in Source to Dest, and returns a pointer to Dest.
  16695.            Dest needs enough room to contain Source, i.e. StrLen(Source)+1 bytes.
  16696.  
  16697.      Errors: No length checking is performed.
  16698.  
  16699.    See also: StrPCopy (287), StrLCopy (284), StrECopy (281)
  16700.  
  16701.            Program Example4 ;
  16702.  
  16703.            Uses s t r i n g s ;
  16704.  
  16705.            { Program to demonstrate the StrCopy f u n c t i o n . }
  16706.  
  16707.            Const P : PCHar = ' This i s a PCHAR s t r i n g . ' ;
  16708.  
  16709.            var PP : PChar ;
  16710.  
  16711.            begin
  16712.               PP:= S t r A l l o c ( Strlen (P)+1);
  16713.               STrCopy ( PP, P) ;
  16714.               I f StrComp ( PP, P)<>0 then
  16715.                     Writeln ( ' Oh-oh problems . . . ' )
  16716.               else
  16717.                     Writeln ( ' A l l i s w e l l : PP=' , PP) ;
  16718.            end .
  16719.  
  16720.  
  16721.  
  16722.  
  16723.  
  16724.                                                        280
  16725.  
  16726.  
  16727.  
  16728.                                                   14.1. FUNCTIONS AND PROCEDURES.
  16729.  
  16730.  
  16731.            StrDispose
  16732. Declaration: Procedure StrDispose (P : PChar);
  16733. Description: Removes the string in P from the heap and releases the memory.
  16734.      Errors: None.
  16735.    See also: Dispose () , StrNew (286)
  16736.  
  16737.            Program Example17 ;
  16738.  
  16739.            Uses s t r i n g s ;
  16740.  
  16741.            { Program to demonstrate the St rD is po s e f u n c t i o n . }
  16742.  
  16743.            Const P1 : PChar = ' This i s a PChar s t r i n g ' ;
  16744.  
  16745.            var P2 : PChar ;
  16746.  
  16747.            begin
  16748.               Writeln ( ' Before StnNew : Memory a v a i l a b l e : ' , MemAvail ) ;
  16749.               P2:=StrNew ( P1 ) ;
  16750.               Writeln ( ' After StrNew : Memory a v a i l a b l e : ' , MemAvail ) ;
  16751.               Writeln ( ' P2 : ' , P2 ) ;
  16752.               StrDispose ( P2 ) ;
  16753.               Writeln ( ' After Str Di s pose : Memory a v a i l a b l e : ' , MemAvail ) ;
  16754.            end .
  16755.  
  16756.  
  16757.            StrECopy
  16758. Declaration: Function StrECopy (Dest,Source : PChar) : PChar;
  16759. Description: Copies the Null-terminated string in Source to Dest, and returns a pointer to the
  16760.            end (i.e. the terminating Null-character) of the copied string.
  16761.      Errors: No length checking is performed.
  16762.    See also: StrLCopy (284), StrCopy (280)
  16763.  
  16764.            Program Example6 ;
  16765.  
  16766.            Uses s t r i n g s ;
  16767.  
  16768.            { Program to demonstrate the StrECopy f u n c t i o n . }
  16769.  
  16770.            Const P : PChar = ' This i s a PCHAR s t r i n g . ' ;
  16771.  
  16772.            Var PP : PChar ;
  16773.  
  16774.            begin
  16775.               PP:= S t r A l l o c ( StrLen (P)+1);
  16776.               I f Longint ( StrECopy (PP, P))- Longint (PP)<>StrLen (P) then
  16777.                     Writeln ( ' Something i s wrong here ! ' )
  16778.               else
  16779.                     Writeln ( ' PP= ' , PP) ;
  16780.            end .
  16781.  
  16782.                                                        281
  16783.  
  16784.  
  16785.  
  16786.                                                          14.1. FUNCTIONS AND PROCEDURES.
  16787.  
  16788.  
  16789.            StrEnd
  16790. Declaration: Function StrEnd (P : PChar) : PChar;
  16791.  
  16792. Description: Returns a pointer to the end of P. (i.e. to the terminating null-character.
  16793.  
  16794.      Errors: None.
  16795.  
  16796.    See also: StrLen (284)
  16797.  
  16798.            Program Example6 ;
  16799.  
  16800.            Uses s t r i n g s ;
  16801.  
  16802.            { Program to demonstrate the StrEnd f u n c t i o n . }
  16803.  
  16804.            Const P : PChar = ' This i s a PCHAR s t r i n g . ' ;
  16805.  
  16806.            begin
  16807.               I f Longint ( StrEnd (P))- Longint (P)<>StrLen (P) then
  16808.                     Writeln ( ' Something i s wrong here ! ' )
  16809.               else
  16810.                     Writeln ( ' A l l i s w e l l . . ' ) ;
  16811.            end .
  16812.  
  16813.  
  16814.            StrIComp
  16815. Declaration: Function StrIComp (S1,S2 : PChar) : Longint;
  16816.  
  16817. Description: Compares the null-terminated strings S1 and S2, ignoring case. The result is
  16818.  
  16819.                *A negative Longint when S1<S2.
  16820.                *0 when S1=S2.
  16821.                *A positive Longint when S1>S2.
  16822.  
  16823.      Errors: None.
  16824.  
  16825.    See also: StrLComp (283), StrComp (280), StrLIComp (285)
  16826.  
  16827.            Program Example8 ;
  16828.  
  16829.            Uses s t r i n g s ;
  16830.  
  16831.            { Program to demonstrate the StrLComp f u n c t i o n . }
  16832.  
  16833.            Const P1 : PChar = ' This i s the f i r s t s t r i n g . ' ;
  16834.                       P2 : PCHar = ' This i s the second s t r i n g . ' ;
  16835.  
  16836.            Var L : Longint ;
  16837.  
  16838.            begin
  16839.               Write ( ' P1 and P2 are ' ) ;
  16840.               I f StrComp ( P1 , P2)<>0 then write ( ' NOT ' ) ;
  16841.               write ( ' equal . The f i r s t ' ) ;
  16842.               L :=1;
  16843.  
  16844.  
  16845.                                                          282
  16846.  
  16847.  
  16848.  
  16849.                                                    14.1. FUNCTIONS AND PROCEDURES.
  16850.  
  16851.  
  16852.               While StrLComp( P1 , P2 , L)=0 do inc ( L ) ;
  16853.               dec ( l ) ;
  16854.               Writeln ( l , ' c h a r a c t e r s are the same . ' ) ;
  16855.            end .
  16856.  
  16857.  
  16858.            StrLCat
  16859. Declaration: Function StrLCat (Dest,Source : PChar; MaxLen : Longint) : PChar;
  16860.  
  16861. Description: Adds MaxLen characters from Source to Dest, and adds a terminating null-character.
  16862.            Returns Dest.
  16863.  
  16864.      Errors: None.
  16865.  
  16866.    See also: StrCat (279)
  16867.  
  16868.            Program Example12 ;
  16869.  
  16870.            Uses s t r i n g s ;
  16871.  
  16872.            { Program to demonstrate the StrLCat f u n c t i o n . }
  16873.  
  16874.            Const P1 : PChar = '1234567890' ;
  16875.  
  16876.            Var P2 : PChar ;
  16877.  
  16878.            begin
  16879.               P2:= S t r A l l o c ( StrLen ( P1) 2+1);
  16880.               P2 :=#0; { Zero length }
  16881.               StrCat ( P2 , P1 ) ;
  16882.               StrLCat ( P2 , P1 , 5 ) ;
  16883.               Writeln ( ' P2 = ' , P2 ) ;
  16884.            end .
  16885.  
  16886.  
  16887.            StrLComp
  16888. Declaration: Function StrLComp (S1,S2 : PChar; L : Longint) : Longint;
  16889.  
  16890. Description: Compares maximum L characters of the null-terminated strings S1 and S2. The
  16891.            result is
  16892.  
  16893.                *A negative Longint when S1<S2.
  16894.                *0 when S1=S2.
  16895.                *A positive Longint when S1>S2.
  16896.  
  16897.      Errors: None.
  16898.  
  16899.    See also: StrComp (280), StrIComp (282), StrLIComp (285)
  16900.  
  16901.            Program Example8 ;
  16902.  
  16903.            Uses s t r i n g s ;
  16904.  
  16905.            { Program to demonstrate the StrLComp f u n c t i o n . }
  16906.  
  16907.                                                    283
  16908.  
  16909.  
  16910.  
  16911.                                                    14.1. FUNCTIONS AND PROCEDURES.
  16912.  
  16913.  
  16914.  
  16915.            Const P1 : PChar = ' This i s the f i r s t s t r i n g . ' ;
  16916.                       P2 : PCHar = ' This i s the second s t r i n g . ' ;
  16917.  
  16918.            Var L : Longint ;
  16919.  
  16920.            begin
  16921.               Write ( ' P1 and P2 are ' ) ;
  16922.               I f StrComp ( P1 , P2)<>0 then write ( ' NOT ' ) ;
  16923.               write ( ' equal . The f i r s t ' ) ;
  16924.               L :=1;
  16925.               While StrLComp( P1 , P2 , L)=0 do inc ( L ) ;
  16926.               dec ( l ) ;
  16927.               Writeln ( l , ' c h a r a c t e r s are the same . ' ) ;
  16928.            end .
  16929.  
  16930.  
  16931.            StrLCopy
  16932. Declaration: Function StrLCopy (Dest,Source : PChar; MaxLen : Longint) : PChar;
  16933.  
  16934. Description: Copies MaxLen characters from Source to Dest, and makes Dest a null terminated
  16935.            string.
  16936.  
  16937.      Errors: No length checking is performed.
  16938.  
  16939.    See also: StrCopy (280), StrECopy (281)
  16940.  
  16941.            Program Example5 ;
  16942.  
  16943.            Uses s t r i n g s ;
  16944.  
  16945.            { Program to demonstrate the StrLCopy f u n c t i o n . }
  16946.  
  16947.            Const P : PCHar = '123456789 ABCDEF' ;
  16948.  
  16949.            var PP : PCHar ;
  16950.  
  16951.            begin
  16952.               PP:= S t r A l l o c ( 1 1 ) ;
  16953.               Writeln ( ' F i r s t 10 c h a r a c t e r s of P : ' , StrLCopy ( PP, P , 1 0 ) ) ;
  16954.            end .
  16955.  
  16956.  
  16957.            StrLen
  16958. Declaration: Function StrLen (p : PChar) : Longint;
  16959.  
  16960. Description: Returns the length of the null-terminated string P.
  16961.  
  16962.      Errors: None.
  16963.  
  16964.    See also: Length ()
  16965.  
  16966.  
  16967.  
  16968.  
  16969.  
  16970.                                                     284
  16971.  
  16972.  
  16973.  
  16974.                                                        14.1. FUNCTIONS AND PROCEDURES.
  16975.  
  16976.  
  16977.            Program Example1 ;
  16978.  
  16979.            Uses s t r i n g s ;
  16980.  
  16981.            { Program to demonstrate the StrLen f u n c t i o n . }
  16982.  
  16983.            Const P : PChar = ' This i s a constant pchar s t r i n g ' ;
  16984.  
  16985.            begin
  16986.               Writeln ( ' P                  : ' , p ) ;
  16987.               Writeln ( ' length (P ) : ' , StrLen (P) ) ;
  16988.            end .
  16989.  
  16990.  
  16991.            StrLIComp
  16992. Declaration: Function StrLIComp (S1,S2 : PChar; L : Longint) : Longint;
  16993. Description: Compares maximum L characters of the null-terminated strings S1 and S2, ignoring
  16994.            case. The result is
  16995.                *A negative Longint when S1<S2.
  16996.                *0 when S1=S2.
  16997.                *A positive Longint when S1>S2.
  16998.      Errors: None.
  16999.    See also: StrLComp (283), StrComp (280), StrIComp (282)
  17000.  
  17001.            For an example, see StrIComp (282)
  17002.  
  17003.  
  17004.            StrLower
  17005. Declaration: Function StrLower (P : PChar) : PChar;
  17006. Description: Converts P to an all-lowercase string. Returns P.
  17007.      Errors: None.
  17008.    See also: Upcase () , StrUpper (289)
  17009.  
  17010.            Program Example14 ;
  17011.  
  17012.            Uses s t r i n g s ;
  17013.  
  17014.            { Program to demonstrate the StrLower and StrUpper f u n c t i o n s . }
  17015.  
  17016.            ConstP1 : PChar = 'THIS IS AN UPPERCASE PCHAR STRING' ;
  17017.                     P2 : PChar = ' t h i s i s a lo w er ca s e s t r i n g ' ;
  17018.  
  17019.            begin
  17020.               Writeln ( ' Uppercase : ' , StrUpper ( P2 ) ) ;
  17021.               StrLower ( P1 ) ;
  17022.               Writeln ( ' Lowercase : ' , P1 ) ;
  17023.            end .
  17024.  
  17025.  
  17026.                                                             285
  17027.  
  17028.  
  17029.  
  17030.                                                     14.1. FUNCTIONS AND PROCEDURES.
  17031.  
  17032.  
  17033.            StrMove
  17034. Declaration: Function StrMove (Dest,Source : PChar; MaxLen : Longint) : PChar;
  17035.  
  17036. Description: Copies MaxLen characters from Source to Dest. No terminating null-character is
  17037.            copied. Returns Dest.
  17038.  
  17039.      Errors: None.
  17040.  
  17041.    See also: StrLCopy (284), StrCopy (280)
  17042.  
  17043.            Program Example10 ;
  17044.  
  17045.            Uses s t r i n g s ;
  17046.  
  17047.            { Program to demonstrate the StrMove f u n c t i o n . }
  17048.  
  17049.            Const P1 : PCHAR = ' This i s a pchar s t r i n g . ' ;
  17050.  
  17051.  
  17052.            Var P2 : Pchar ;
  17053.  
  17054.            begin
  17055.               P2:= S t r A l l o c ( StrLen ( P1)+1);
  17056.               StrMove ( P2 , P1 , StrLen ( P1 )+1); { P2:=P1 }
  17057.               Writeln ( ' P2 = ' , P2 ) ;
  17058.            end .
  17059.  
  17060.  
  17061.            StrNew
  17062. Declaration: Function StrNew (P : PChar) : PChar;
  17063.  
  17064. Description: Copies P to the Heap, and returns a pointer to the copy.
  17065.  
  17066.      Errors: Returns Nil if no memory was available for the copy.
  17067.  
  17068.    See also: New () , StrCopy (280), StrDispose (281)
  17069.  
  17070.            Program Example16 ;
  17071.  
  17072.            Uses s t r i n g s ;
  17073.  
  17074.            { Program to demonstrate the StrNew f u n c t i o n . }
  17075.  
  17076.            Const P1 : PChar = ' This i s a PChar s t r i n g ' ;
  17077.  
  17078.            var P2 : PChar ;
  17079.  
  17080.            begin
  17081.               P2:=StrNew ( P1 ) ;
  17082.               I f P1=P2 then
  17083.                     writeln ( ' This can ' ' t be happening . . . ' )
  17084.               else
  17085.                     writeln ( ' P2 : ' , P2 ) ;
  17086.            end .
  17087.  
  17088.  
  17089.                                                          286
  17090.  
  17091.  
  17092.  
  17093.                                                        14.1. FUNCTIONS AND PROCEDURES.
  17094.  
  17095.  
  17096.            StrPas
  17097. Declaration: Function StrPas (P : PChar) : String;
  17098.  
  17099. Description: Converts a null terminated string in P to a Pascal string, and returns this string.
  17100.            The string is truncated at 255 characters.
  17101.  
  17102.      Errors: None.
  17103.  
  17104.    See also: StrPCopy (287)
  17105.  
  17106.            Program Example3 ;
  17107.  
  17108.            Uses s t r i n g s ;
  17109.  
  17110.            { Program to demonstrate the StrPas f u n c t i o n . }
  17111.  
  17112.            Const P : PChar = ' This i s a PCHAR s t r i n g ' ;
  17113.  
  17114.            var S : st r ing ;
  17115.  
  17116.            begin
  17117.               S:= StrPas ( P) ;
  17118.               Writeln ( ' S : ' , S ) ;
  17119.            end .
  17120.  
  17121.  
  17122.            StrPCopy
  17123. Declaration: Function StrPCopy (Dest : PChar; Const Source : String) : PChar;
  17124.  
  17125. Description: Converts the Pascal string in Source to a Null-terminated string, and copies it to
  17126.            Dest. Dest needs enough room to contain the string Source, i.e. Length(Source)+1
  17127.            bytes.
  17128.  
  17129.      Errors: No length checking is performed.
  17130.  
  17131.    See also: StrPas (287)
  17132.  
  17133.            Program Example2 ;
  17134.  
  17135.            Uses s t r i n g s ;
  17136.  
  17137.            { Program to demonstrate the StrPCopy f u n c t i o n . }
  17138.  
  17139.            Const S = ' This i s a normal s t r i n g . ' ;
  17140.  
  17141.            Var P : Pchar ;
  17142.  
  17143.            begin
  17144.               p:= S t r A l l o c ( length ( S)+1);
  17145.               i f StrPCopy ( P, S)<>P then
  17146.                     Writeln ( ' This i s i m p o s s i b l e ! ! ' )
  17147.               else
  17148.                     writeln ( P) ;
  17149.            end .
  17150.  
  17151.  
  17152.                                                         287
  17153.  
  17154.  
  17155.  
  17156.                                                        14.1. FUNCTIONS AND PROCEDURES.
  17157.  
  17158.  
  17159.            StrPos
  17160. Declaration: Function StrPos (S1,S2 : PChar) : PChar;
  17161.  
  17162. Description: Returns a pointer to the first occurrence of S2 in S1. If S2 does not occur in S1,
  17163.            returns Nil.
  17164.  
  17165.      Errors: None.
  17166.  
  17167.    See also: Pos () , StrScan (288), StrRScan (288)
  17168.  
  17169.            Program Example15 ;
  17170.  
  17171.            Uses s t r i n g s ;
  17172.  
  17173.            { Program to demonstrate the StrPos f u n c t i o n . }
  17174.  
  17175.            Const P : PChar = ' This i s a PChar s t r i n g . ' ;
  17176.                       S : Pchar = ' i s ' ;
  17177.            begin
  17178.               Writeln ( ' P o s i t i o n of ' ' i s ' ' in P : ' , l o n g i n t ( StrPos (P, S))- Longint (P) ) ;
  17179.            end .
  17180.  
  17181.  
  17182.            StrRScan
  17183. Declaration: Function StrRScan (P : PChar; C : Char) : PChar;
  17184.  
  17185. Description: Returns a pointer to the last occurrence of the character C in the null-terminated
  17186.            string P. If C does not occur, returns Nil.
  17187.  
  17188.      Errors: None.
  17189.  
  17190.    See also: Pos () , StrScan (288), StrPos (288)
  17191.  
  17192.            For an example, see StrScan (288).
  17193.  
  17194.  
  17195.            StrScan
  17196. Declaration: Function StrScan (P : PChar; C : Char) : PChar;
  17197.  
  17198. Description: Returns a pointer to the first occurrence of the character C in the null-terminated
  17199.            string P. If C does not occur, returns Nil.
  17200.  
  17201.      Errors: None.
  17202.  
  17203.    See also: Pos () , StrRScan (288), StrPos (288)
  17204.  
  17205.            Program Example13 ;
  17206.  
  17207.            Uses s t r i n g s ;
  17208.  
  17209.            { Program to demonstrate the StrScan and StrRScan f u n c t i o n s . }
  17210.  
  17211.            Const P : PChar = ' This i s a PCHAR s t r i n g . ' ;
  17212.                       S : Char = ' s ' ;
  17213.  
  17214.  
  17215.                                                        288
  17216.  
  17217.  
  17218.  
  17219.                                                    14.1. FUNCTIONS AND PROCEDURES.
  17220.  
  17221.  
  17222.            begin
  17223.               Writeln ( ' P, s t a r t i n g from f i r s t ' ' s ' ' : ' , StrScan (P, s ) ) ;
  17224.               Writeln ( ' P, s t a r t i n g from l a s t ' ' s ' ' : ' , StrRScan (P, s ) ) ;
  17225.            end .
  17226.  
  17227.  
  17228.            StrUpper
  17229. Declaration: Function StrUpper (P : PChar) : PChar;
  17230.  
  17231. Description: Converts P to an all-uppercase string. Returns P.
  17232.  
  17233.      Errors: None.
  17234.  
  17235.    See also: Upcase () , StrLower (285)
  17236.  
  17237.            For an example, see StrLower (285)
  17238.  
  17239.  
  17240.  
  17241.  
  17242.  
  17243.  
  17244.  
  17245.  
  17246.  
  17247.  
  17248.  
  17249.  
  17250.  
  17251.  
  17252.  
  17253.  
  17254.  
  17255.  
  17256.  
  17257.  
  17258.  
  17259.  
  17260.  
  17261.  
  17262.  
  17263.  
  17264.  
  17265.  
  17266.  
  17267.  
  17268.  
  17269.  
  17270.  
  17271.  
  17272.  
  17273.  
  17274.                                                     289
  17275.  
  17276.  
  17277.  
  17278. Chapter 15
  17279.  
  17280. The SYSUTILS unit.
  17281.  
  17282. This chapter describes the sysutils unit. The sysutils unit was largely written by
  17283. Gertjan Schouten, and completed by michael Van Canneyt. It aims to be compatible
  17284. to the Delphi sysutils unit, but in contrast with the latter, it is designed to work
  17285. on multiple platforms.
  17286. This chapter starts out with a definition of all types and constants that are defined,
  17287. followed by a complete explanation of each function.
  17288.  
  17289.  
  17290. 15.1 Constants and types
  17291.  
  17292. The following general-purpose constants are defined:
  17293.  
  17294. const
  17295.    SecsPerDay = 24 * 60 * 60; // Seconds and milliseconds per day
  17296.    MSecsPerDay = SecsPerDay * 1000;
  17297.    DateDelta = 693594;               // Days between 1/1/0001 and 12/31/1899
  17298.    Eoln = #10;
  17299.  
  17300. The following types are used frequently in date and time functions. They are the
  17301. same on all platforms.
  17302.  
  17303. typeTSystemTime = record
  17304.          Year, Month, Day: word;
  17305.          Hour, Minute, Second, MilliSecond: word;
  17306.    end ;
  17307.  
  17308.    TDateTime = double;
  17309.  
  17310.    TTimeStamp = record
  17311.          Time: integer;     { Number of milliseconds since midnight }
  17312.          Date: integer;     { One plus number of days since 1/1/0001 }
  17313.    end ;
  17314.  
  17315. The following type is used in the FindFirst (322),FindNext (323) and FindClose (322)
  17316. functions. The win32 version di ers from the other versions. If code is to be
  17317. portable, that part shouldn't be used.
  17318.  
  17319.  
  17320.                                           290
  17321.  
  17322.  
  17323.  
  17324.                                                 15.1. CONSTANTS AND TYPES
  17325.  
  17326.  
  17327. Type
  17328.   THandle = Longint;
  17329.   TSearchRec = Record
  17330.          Time,Size, Attr : Longint;
  17331.          Name : TFileName;
  17332.          ExcludeAttr : Longint;
  17333.          FindHandle : THandle;
  17334.          {$ifdef Win32}
  17335.          FindData : TWin32FindData;
  17336.          {$endif}
  17337.          end;
  17338.  
  17339. The following constants are file-attributes that need to be matched in the findfirst
  17340. call.
  17341.  
  17342. Const
  17343.   faReadOnly = $00000001;
  17344.   faHidden           = $00000002;
  17345.   faSysFile          = $00000004;
  17346.   faVolumeId = $00000008;
  17347.   faDirectory = $00000010;
  17348.   faArchive          = $00000020;
  17349.   faAnyFile          = $0000003f;
  17350.  
  17351. The following constants can be used in the FileOpen (319) call.
  17352.  
  17353. Const
  17354.   fmOpenRead                = $0000;
  17355.   fmOpenWrite               = $0001;
  17356.   fmOpenReadWrite = $0002;
  17357.  
  17358. The following constants can be used in the FileSeek (320) call.
  17359.  
  17360. Const
  17361.   fsFromBeginning = 0;
  17362.   fsFromCurrent            = 1;
  17363.   fsFromEnd                = 2;
  17364.  
  17365.  
  17366. The following variables are used in the case translation routines.
  17367.  
  17368. typeTCaseTranslationTable = array[0..255] of char;
  17369. varUpperCaseTable: TCaseTranslationTable;
  17370.     LowerCaseTable: TCaseTranslationTable;
  17371.  
  17372. The initialization code of the sysutils unit fills these tables with the appropriate
  17373. values. For the win32 and go32v2 versions, this information is obtained from the
  17374. operating system.
  17375. The following constants control the formatting of dates. For the Win32 version
  17376. of the sysutils unit, these constants are set according to the internationalization
  17377. settings of Windows by the initialization code of the unit.
  17378.  
  17379.  
  17380.                                         291
  17381.  
  17382.  
  17383.  
  17384.                                                 15.1. CONSTANTS AND TYPES
  17385.  
  17386.  
  17387. Const
  17388.    DateSeparator: char = '-';
  17389.    ShortDateFormat: string = 'd/m/y';
  17390.    LongDateFormat: string = 'dd" "mmmm" "yyyy';
  17391.    ShortMonthNames: array[1..12] of string[128] =
  17392.          ('Jan','Feb','Mar','Apr','May','Jun',
  17393.           'Jul','Aug','Sep','Oct','Nov','Dec');
  17394.    LongMonthNames: array[1..12] of string[128] =
  17395.          ('January','February','March','April',
  17396.           'May','June','July','August',
  17397.           'September','October','November','December');
  17398.    ShortDayNames: array[1..7] of string[128] =
  17399.          ('Sun','Mon','Tue','Wed','Thu','Fri','Sat');
  17400.    LongDayNames: array[1..7] of string[128] =
  17401.          ('Sunday','Monday','Tuesday','Wednesday',
  17402.            'Thursday','Friday','Saturday');
  17403.  
  17404. The following constants control the formatting of times. For the Win32 version
  17405. of the sysutils unit, these constants are set according to the internationalization
  17406. settings of Windows by the initialization code of the unit.
  17407.  
  17408. Const
  17409.    ShortTimeFormat: string = 'hh:nn';
  17410.    LongTimeFormat: string = 'hh:nn:ss';
  17411.    TimeSeparator: char = ':';
  17412.    TimeAMString: string[7] = 'AM';
  17413.    TimePMString: string[7] = 'PM';
  17414.  
  17415. The following constants control the formatting of currencies and numbers. For
  17416. the Win32 version of the sysutils unit, these constants are set according to the
  17417. internationalization settings of Windows by the initialization code of the unit.
  17418.  
  17419. Const
  17420.   DecimalSeparator : Char = '.';
  17421.   ThousandSeparator : Char = ',';
  17422.   CurrencyDecimals : Byte = 2;
  17423.   CurrencyString : String[7] = '$';
  17424.   { Format to use when formatting currency :
  17425.         0 = $1           1 = 1$         2 = $ 1         3 = 1 $
  17426.         4 = Currency string replaces decimal indicator.
  17427.             e.g. 1$50
  17428.    }
  17429.   CurrencyFormat : Byte = 1;
  17430.   { Same as above, only for negative currencies:
  17431.         0 = ($1)
  17432.         1 = -$1
  17433.         2 = $-1
  17434.         3 = $1-
  17435.         4 = (1$)
  17436.         5 = -1$
  17437.         6 = 1-$
  17438.         7 = 1$-
  17439.         8 = -1 $
  17440.         9 = -$ 1
  17441.  
  17442.                                         292
  17443.  
  17444.  
  17445.  
  17446.                                           15.2. DATE AND TIME FUNCTIONS
  17447.  
  17448.  
  17449.         10 = $ 1-
  17450.    }
  17451.   NegCurrFormat : Byte = 5;
  17452.  
  17453. The following types are used in various string functions.
  17454.  
  17455. typePString = ^String;
  17456.    TFloatFormat = (ffGeneral, ffExponent, ffFixed, ffNumber, ffCurrency);
  17457.  
  17458. The following constants are used in the file name handling routines. Do not
  17459. use a slash of backslash character directly as a path separator; instead use the
  17460. OsDirSeparator character.
  17461.  
  17462. Const
  17463.   DirSeparators : set of char = ['/','\'];
  17464. {$ifdef Linux}
  17465.   OSDirSeparator = '/';
  17466. {$else}
  17467.   OsDirSeparator = '\';
  17468. {$endif}
  17469.  
  17470.  
  17471. 15.2 Date and time functions
  17472.  
  17473. Date and time formatting characters
  17474. Various date and time formatting routines accept a format string. to format the
  17475. date and or time. The following characters can be used to control the date and
  17476. time formatting:
  17477.  
  17478. c : shortdateformat + ' ' + shorttimeformat
  17479.  
  17480. d : day of month
  17481.  
  17482. dd : day of month (leading zero)
  17483.  
  17484. ddd : day of week (abbreviation)
  17485.  
  17486. dddd : day of week (full)
  17487.  
  17488. ddddd : shortdateformat
  17489.  
  17490. dddddd : longdateformat
  17491.  
  17492. m : month
  17493.  
  17494. mm : month (leading zero)
  17495.  
  17496. mmm : month (abbreviation)
  17497.  
  17498. mmmm : month (full)
  17499.  
  17500. y : year (four digits)
  17501.  
  17502. yy : year (two digits)
  17503.  
  17504. yyyy : year (with century)
  17505.  
  17506.  
  17507.                                         293
  17508.  
  17509.  
  17510.  
  17511.                                                       15.2. DATE AND TIME FUNCTIONS
  17512.  
  17513.  
  17514.           h : hour
  17515.  
  17516.           hh : hour (leading zero)
  17517.  
  17518.           n : minute
  17519.  
  17520.           nn : minute (leading zero)
  17521.  
  17522.           s : second
  17523.  
  17524.           ss : second (leading zero)
  17525.  
  17526.           t : shorttimeformat
  17527.  
  17528.           tt : longtimeformat
  17529.  
  17530.           am/pm : use 12 hour clock and display am and pm accordingly
  17531.  
  17532.           a/p : use 12 hour clock and display a and p accordingly
  17533.  
  17534.           / : insert date seperator
  17535.  
  17536.           : : insert time seperator
  17537.  
  17538.           "xx" : literal text
  17539.  
  17540.           'xx' : literal text
  17541.  
  17542.  
  17543.           TDateTime
  17544. Declaration: TDateTime = Double;
  17545.  
  17546. Description: Many functions return or require a TDateTime type, which contains a date and
  17547.           time in encoded form. The date and time are converted to a double as follows:
  17548.  
  17549.  
  17550.           Date
  17551. Declaration: Function Date: TDateTime;
  17552.  
  17553. Description: Date returns the current date in TDateTime format. For more information about
  17554.           the TDateTime type, see TDateTime (294).
  17555.  
  17556.     Errors: None.
  17557.  
  17558.   See also: Time (306),Now (303), TDateTime (294).
  17559.  
  17560.           Program Example1 ;
  17561.  
  17562.            { This program demonstrates the Date f u n c t i o n }
  17563.  
  17564.            uses s y s u t i l s ;
  17565.  
  17566.           Var YY,MM, DD : Word ;
  17567.  
  17568.            Begin
  17569.             Writeln ( ' Date : ' , Date ) ;
  17570.             DeCodeDate ( Date , YY,MM, DD) ;
  17571.             Writeln ( format ( ' Date i s (DD/MM/YY): % d/%d/%d ' , [ dd ,mm, yy ] ) ) ;
  17572.           End.
  17573.  
  17574.  
  17575.                                                 294
  17576.  
  17577.  
  17578.  
  17579.                                                        15.2. DATE AND TIME FUNCTIONS
  17580.  
  17581.  
  17582.            DateTimeToFileDate
  17583. Declaration: Function DateTimeToFileDate(DateTime : TDateTime) : Longint;
  17584.  
  17585. Description: DateTimeToFileDate function converts a date/time indication in TDateTime for-
  17586.            mat to a filedate function, such as returned for instance by the FileAge (315) func-
  17587.            tion.
  17588.  
  17589.     Errors: None.
  17590.  
  17591.   See also: Time (306), Date (294), FileDateToDateTime (300), DateTimeToSystemTime (296),
  17592.            DateTimeToTimeStamp (297)
  17593.  
  17594.            Program Example2 ;
  17595.  
  17596.            { This program demonstrates the DateTimeToFileDate f u n c t i o n }
  17597.  
  17598.            Uses s y s u t i l s ;
  17599.  
  17600.            Begin
  17601.               Writeln ( ' FileTime of now would be : ' , DateTimeToFileDate ( Now) ) ;
  17602.            End.
  17603.  
  17604.  
  17605.            DateTimeToStr
  17606. Declaration: Function DateTimeToStr(DateTime: TDateTime): string;
  17607.  
  17608. Description: DateTimeToStr returns a string representation of DateTime using the formatting
  17609.            specified in ShortDateTimeFormat. It corresponds to a call to FormatDateTime('c',DateTime)
  17610.            (see section 15.2, page 293).
  17611.  
  17612.     Errors: None.
  17613.  
  17614.   See also: FormatDateTime (301), TDateTime (294).
  17615.  
  17616.            Program Example3 ;
  17617.  
  17618.            { This program demonstrates the DateTimeToStr f u n c t i o n }
  17619.  
  17620.            Uses s y s u t i l s ;
  17621.  
  17622.            Begin
  17623.               Writeln ( ' Today i s : ' , DateTimeToStr (Now) ) ;
  17624.               Writeln ( ' Today i s : ' , FormatDateTime ( ' c ' , Now) ) ;
  17625.            End.
  17626.  
  17627.  
  17628.            DateTimeToString
  17629. Declaration: Procedure DateTimeToString(var Result: string; const FormatStr: string;
  17630.            const DateTime: TDateTime);
  17631.  
  17632. Description: DateTimeToString returns in Result a string representation of DateTime using
  17633.            the formatting specified in FormatStr.
  17634.            for a list of characters that can be used in the FormatStr formatting string, see
  17635.            section 15.2, page 293.
  17636.  
  17637.                                                      295
  17638.  
  17639.  
  17640.  
  17641.                                                         15.2. DATE AND TIME FUNCTIONS
  17642.  
  17643.  
  17644.     Errors: In case a wrong formatting character is found, an EConvertError is raised.
  17645.  
  17646.   See also: FormatDateTime (301), section 15.2, page 293.
  17647.  
  17648.           Program Example4 ;
  17649.  
  17650.           { This program demonstrates the DateTimeToString f u n c t i o n }
  17651.  
  17652.           Uses s y s u t i l s ;
  17653.  
  17654.  
  17655.           Procedure today ( Fmt : s tr in g ) ;
  17656.  
  17657.           Var S : A n s i S t r i n g ;
  17658.  
  17659.           begin
  17660.              DateTimeToString ( S , Fmt , Date ) ;
  17661.              Writeln ( S ) ;
  17662.           end ;
  17663.  
  17664.           Procedure Now ( Fmt : st r ing ) ;
  17665.  
  17666.           Var S : A n s i S t r i n g ;
  17667.  
  17668.           begin
  17669.              DateTimeToString ( S , Fmt , Time ) ;
  17670.              Writeln ( S ) ;
  17671.           end ;
  17672.  
  17673.           Begin
  17674.              Today ( '" Today i s " dddd dd mmmm y ' ) ;
  17675.              Today ( '" Today i s " d mmm yy ' ) ;
  17676.              Today ( '" Today i s " d/mmm/ yy ' ) ;
  17677.              Now ( ' ' ' The time i s ' ' am/pmh: n : s ' ) ;
  17678.              Now ( ' ' ' The time i s ' ' hh : nn : ssam /pm' ) ;
  17679.              Now ( ' ' ' The time i s ' ' tt ' ) ;
  17680.           End.
  17681.  
  17682.  
  17683.           DateTimeToSystemTime
  17684. Declaration: Procedure DateTimeToSystemTime(DateTime: TDateTime; var SystemTime: TSystemTime);
  17685.  
  17686. Description: DateTimeToSystemTime converts a date/time pair in DateTime, with TDateTime
  17687.           format to a system time SystemTime.
  17688.  
  17689.     Errors: None.
  17690.  
  17691.   See also: DateTimeToFileDate (295), SystemTimeToDateTime (305), DateTimeToTimeStamp
  17692.           (297)
  17693.  
  17694.           Program Example5 ;
  17695.  
  17696.           { This program demonstrates the DateTimeToSystemTime f u n c t i o n }
  17697.  
  17698.  
  17699.  
  17700.                                                       296
  17701.  
  17702.  
  17703.  
  17704.                                                             15.2. DATE AND TIME FUNCTIONS
  17705.  
  17706.  
  17707.            Uses s y s u t i l s ;
  17708.  
  17709.            Var ST : TSystemTime ;
  17710.  
  17711.            Begin
  17712.               DateTimeToSystemTime (Now, ST) ;
  17713.               With St do
  17714.                     begin
  17715.                     Writeln ( ' Today i s            ' , year , ' / ' , month , ' / ' , Day ) ;
  17716.                     Writeln ( ' The time i s ' , Hour , ' : ' , minute , ' : ' , Second , ' . ' , M i l l i S e c o n d ) ;
  17717.                     end ;
  17718.            End.
  17719.  
  17720.  
  17721.            DateTimeToTimeStamp
  17722. Declaration: Function DateTimeToTimeStamp(DateTime: TDateTime): TTimeStamp;
  17723.  
  17724. Description: DateTimeToSystemTime converts a date/time pair in DateTime, with TDateTime
  17725.            format to a TTimeStamp format.
  17726.  
  17727.     Errors: None.
  17728.  
  17729.   See also: DateTimeToFileDate (295), SystemTimeToDateTime (305), DateTimeToSystemTime
  17730.            (296)
  17731.  
  17732.            Program Example6 ;
  17733.  
  17734.            { This program demonstrates the DateTimeToTimeStamp f u n c t i o n }
  17735.  
  17736.            Uses s y s u t i l s ;
  17737.  
  17738.            Var TS : TTimeStamp ;
  17739.  
  17740.            Begin
  17741.               TS:=DateTimeToTimeStamp ( Now) ;
  17742.               With TS do
  17743.                     begin
  17744.                     Writeln ( ' Now i s ' , time , ' m i l l i s e c o n d past midnight ' ) ;
  17745.                     Writeln ( ' Today i s ' , Date , ' days past 1/1/0001' ) ;
  17746.                     end ;
  17747.            End.
  17748.  
  17749.  
  17750.            DateToStr
  17751. Declaration: Function DateToStr(Date: TDateTime): string;
  17752.  
  17753. Description: DateToStr converts Date to a string representation. It uses ShortDateFormat as
  17754.            it's formatting string. It is hence completely equivalent to a FormatDateTime('ddddd',
  17755.            Date).
  17756.  
  17757.     Errors: None.
  17758.  
  17759.   See also: TimeToStr (307), DateTimeToStr (295), FormatDateTime (301), StrToDate (303)
  17760.  
  17761.  
  17762.  
  17763.                                                          297
  17764.  
  17765.  
  17766.  
  17767.                                                      15.2. DATE AND TIME FUNCTIONS
  17768.  
  17769.  
  17770.           Program Example7 ;
  17771.  
  17772.            { This program demonstrates the DateToStr f u n c t i o n }
  17773.  
  17774.            Uses s y s u t i l s ;
  17775.  
  17776.            Begin
  17777.               Writeln ( Format ( ' Today i s : % s ' , [ DateToStr ( Date ) ] ) ) ;
  17778.           End.
  17779.  
  17780.  
  17781.           DayOfWeek
  17782. Declaration: Function DayOfWeek(DateTime: TDateTime): integer;
  17783. Description: DayOfWeek returns the day of the week from DateTime. Sunday is counted as day
  17784.           1, Saturday is counted as day 7. The result of DayOfWeek can serve as an index to
  17785.           the LongDayNames constant array, to retrieve the name of the day.
  17786.     Errors: None.
  17787.   See also: Date (294), DateToStr (297)
  17788.  
  17789.           Program Example8 ;
  17790.  
  17791.            { This program demonstrates the DayOfWeek f u n c t i o n }
  17792.  
  17793.            Uses s y s u t i l s ;
  17794.  
  17795.            Begin
  17796.               Writeln ( ' Today ' ' s day i s ' , LongDayNames [ DayOfWeek( Date ) ] ) ;
  17797.           End.
  17798.  
  17799.  
  17800.           DecodeDate
  17801. Declaration: Procedure DecodeDate(Date: TDateTime; var Year, Month, Day: word);
  17802. Description: DecodeDate decodes the Year, Month and Day stored in Date, and returns them
  17803.           in the Year, Month and Day variables.
  17804.     Errors: None.
  17805.   See also: EncodeDate (299), DecodeTime (299).
  17806.  
  17807.           Program Example9 ;
  17808.  
  17809.            { This program demonstrates the DecodeDate f u n c t i o n }
  17810.  
  17811.            Uses s y s u t i l s ;
  17812.  
  17813.           Var YY,MM, DD : Word ;
  17814.  
  17815.            Begin
  17816.               DecodeDate ( Date , YY,MM, DD) ;
  17817.               Writeln ( Format ( ' Today i s %d/%d/%d ' , [ dd ,mm, yy ] ) ) ;
  17818.           End.
  17819.  
  17820.  
  17821.                                                    298
  17822.  
  17823.  
  17824.  
  17825.                                                        15.2. DATE AND TIME FUNCTIONS
  17826.  
  17827.  
  17828.            DecodeTime
  17829. Declaration: Procedure DecodeTime(Time: TDateTime; var Hour, Minute, Second, MilliSecond:
  17830.            word);
  17831.  
  17832. Description: DecodeDate decodes the hours, minutes, second and milliseconds stored in Time,
  17833.            and returns them in the Hour, Minute and Second and MilliSecond variables.
  17834.  
  17835.     Errors: None.
  17836.  
  17837.   See also: EncodeTime (300), DecodeDate (298).
  17838.  
  17839.            Program Example10 ;
  17840.  
  17841.            { This program demonstrates the DecodeTime f u n c t i o n }
  17842.  
  17843.            Uses s y s u t i l s ;
  17844.  
  17845.            Var HH,MM, SS , MS: Word ;
  17846.  
  17847.            Begin
  17848.               DecodeTime( Time, HH,MM, SS , MS) ;
  17849.               Writeln ( format ( ' The time i s %d:%d:%d.%d ' , [ hh ,mm, ss , ms ] ) ) ;
  17850.            End.
  17851.  
  17852.  
  17853.            EncodeDate
  17854. Declaration: Function EncodeDate(Year, Month, Day :word): TDateTime;
  17855.  
  17856. Description: EncodeDate encodes the Year, Month and Day variables to a date in TDateTime
  17857.            format. It does the opposite of the DecodeDate (298) procedure.
  17858.            The parameters must lie withing valid ranges (boundaries included):
  17859.  
  17860.            Yearmust be between 1 and 9999.
  17861.            Monthmust be within the range 1-12.
  17862.            Daymsut be between 1 and 31.
  17863.  
  17864.     Errors: In case one of the parameters is out of it's valid range, 0 is returned.
  17865.  
  17866.   See also: EncodeTime (300), DecodeDate (298).
  17867.  
  17868.            Program Example11 ;
  17869.  
  17870.            { This program demonstrates the EncodeDate f u n c t i o n }
  17871.  
  17872.            Uses s y s u t i l s ;
  17873.  
  17874.            Var YY,MM, DD : Word ;
  17875.  
  17876.            Begin
  17877.               DecodeDate ( Date , YY,MM, DD) ;
  17878.               WriteLn ( ' Today i s : ' , FormatDateTime ( ' dd mmmm yyyy ' , EnCodeDate(YY,Mm, Dd ) ) ) ;
  17879.            End.
  17880.  
  17881.  
  17882.  
  17883.                                                     299
  17884.  
  17885.  
  17886.  
  17887.                                                         15.2. DATE AND TIME FUNCTIONS
  17888.  
  17889.  
  17890.           EncodeTime
  17891. Declaration: Function EncodeTime(Hour, Minute, Second, MilliSecond:word): TDateTime;
  17892.  
  17893. Description: EncodeTime encodes the Hour, Minute, Second, MilliSecond variables to a TDateTime
  17894.           format result. It does the opposite of the DecodeTime (299) procedure.
  17895.           The parameters must have a valid range (boundaries included):
  17896.  
  17897.           Hourmust be between 0 and 23.
  17898.           Minute,secondmust both be between 0 and 59.
  17899.           Millisecondmust be between 0 and 999.
  17900.  
  17901.     Errors: In case one of the parameters is outside of it's valid range, 0 is returned.
  17902.  
  17903.   See also: EncodeDate (299), DecodeTime (299).
  17904.  
  17905.            Program Example12 ;
  17906.  
  17907.            { This program demonstrates the EncodeTime f u n c t i o n }
  17908.  
  17909.            Uses s y s u t i l s ;
  17910.  
  17911.            Var Hh,MM, SS , MS : Word ;
  17912.  
  17913.            Begin
  17914.               DeCodeTime ( Time, Hh,MM, SS , MS) ;
  17915.               Writeln ( ' Present Time i s : ' , FormatDateTime ( ' hh :mm: ss ' , EnCodeTime ( HH,MM, SS , MS) ) ) ;
  17916.           End.
  17917.  
  17918.  
  17919.           FileDateToDateTime
  17920. Declaration: Function FileDateToDateTime(Filedate : Longint) : TDateTime;
  17921.  
  17922. Description: FileDateToDateTime converts the date/time encoded in filedate to a TDateTime
  17923.           encoded form. It can be used to convert date/time values returned by the FileAge
  17924.           (315) or FindFirst (322)/FindNext (323) functions to TDateTime form.
  17925.  
  17926.     Errors: None.
  17927.  
  17928.   See also: DateTimeToFileDate (295)
  17929.  
  17930.            Program Example13 ;
  17931.  
  17932.            { This program demonstrates the FileDateToDateTime f u n c t i o n }
  17933.  
  17934.            Uses s y s u t i l s ;
  17935.  
  17936.            VarThisAge : Longint ;
  17937.            Begin
  17938.             Write ( ' ex13 . pp cr eated on : ' ) ;
  17939.             ThisAge := FileAge ( ' ex13 . pp ' ) ;
  17940.             Writeln ( DateTimeToStr ( FileDateToDateTime ( ThisAge ) ) ) ;
  17941.           End.
  17942.  
  17943.  
  17944.                                                       300
  17945.  
  17946.  
  17947.  
  17948.                                                      15.2. DATE AND TIME FUNCTIONS
  17949.  
  17950.  
  17951.           FormatDateTime
  17952. Declaration: Function FormatDateTime(FormatStr: string; DateTime: TDateTime):string;
  17953.  
  17954. Description: FormatDateTime formats the date and time encoded in DateTime according to the
  17955.           formatting given in FormatStr. The complete list of formatting characters can be
  17956.           found in section 15.2, page 293.
  17957.  
  17958.     Errors: On error (such as an invalid character in the formatting string), and EConvertError
  17959.           exception is raised.
  17960.  
  17961.   See also: DateTimeToStr (295), DateToStr (297), TimeToStr (307), StrToDateTime (304)
  17962.  
  17963.           Program Example14 ;
  17964.  
  17965.            { This program demonstrates the FormatDateTime f u n c t i o n }
  17966.  
  17967.            Uses s y s u t i l s ;
  17968.  
  17969.           Var ThisMoment : TDateTime ;
  17970.  
  17971.            Begin
  17972.               ThisMoment :=Now;
  17973.               Writeln ( ' Now : ' , FormatDateTime ( ' hh :mm' , ThisMoment ) ) ;
  17974.               Writeln ( ' Now : ' , FormatDateTime ( ' DD MM YYYY' , ThisMoment ) ) ;
  17975.               Writeln ( ' Now : ' , FormatDateTime ( ' c ' , ThisMoment ) ) ;
  17976.           End.
  17977.  
  17978.  
  17979.           IncMonth
  17980. Declaration: Function IncMonth(const DateTime: TDateTime; NumberOfMonths: integer):
  17981.           TDateTime;
  17982.  
  17983. Description: IncMonth increases the month number in DateTime with NumberOfMonths. It
  17984.           wraps the result as to get a month between 1 and 12, and updates the year ac-
  17985.           cordingly. NumberOfMonths can be negative, and can be larger than 12 (in absolute
  17986.           value).
  17987.  
  17988.     Errors: None.
  17989.  
  17990.   See also: Date (294), Time (306), Now (303)
  17991.  
  17992.           Program Example15 ;
  17993.  
  17994.            { This program demonstrates the IncMonth f u n c t i o n }
  17995.  
  17996.            Uses s y s u t i l s ;
  17997.  
  17998.           Var ThisDay : TDateTime ;
  17999.  
  18000.            Begin
  18001.               ThisDay :=Date ;
  18002.               Writeln ( ' ThisDay : ' , DateToStr ( ThisDay ) ) ;
  18003.               Writeln ( '6 months ago : ' , DateToStr ( IncMonth ( ThisDay , - 6 ) ) ) ;
  18004.               Writeln ( '6 months from now : ' , DateToStr ( IncMonth ( ThisDay , 6 ) ) ) ;
  18005.               Writeln ( '12 months ago : ' , DateToStr ( IncMonth ( ThisDay , -12 ) ) ) ;
  18006.  
  18007.                                                   301
  18008.  
  18009.  
  18010.  
  18011.                                                      15.2. DATE AND TIME FUNCTIONS
  18012.  
  18013.  
  18014.               Writeln ( '12 months from now : ' , DateToStr ( IncMonth ( ThisDay , 1 2 ) ) ) ;
  18015.               Writeln ( '18 months ago : ' , DateToStr ( IncMonth ( ThisDay , -1 8) ) ) ;
  18016.               Writeln ( '18 months from now : ' , DateToStr ( IncMonth ( ThisDay , 1 8 ) ) ) ;
  18017.            End.
  18018.  
  18019.  
  18020.            IsLeapYear
  18021. Declaration: Function IsLeapYear(Year: Word): boolean;
  18022.  
  18023. Description: IsLeapYear returns True if Year is a leap year, False otherwise.
  18024.  
  18025.      Errors: None.
  18026.  
  18027.   See also: IncMonth (301), Date (294)
  18028.  
  18029.            Program Example16 ;
  18030.  
  18031.            { This program demonstrates the IsLeapYear f u n c t i o n }
  18032.  
  18033.            Uses s y s u t i l s ;
  18034.  
  18035.            Var YY,MM, dd : Word ;
  18036.  
  18037.            Procedure TestYear ( Y : Word ) ;
  18038.  
  18039.            begin
  18040.               Writeln ( Y, ' i s leap year : ' , IsLeapYear (Y) ) ;
  18041.            end ;
  18042.  
  18043.            Begin
  18044.               DeCodeDate( Date , YY,mm, dd ) ;
  18045.               TestYear ( yy ) ;
  18046.               TestYear (2000);
  18047.               TestYear (1900);
  18048.               TestYear (1600);
  18049.               TestYear (1992);
  18050.               TestYear (1995);
  18051.            End.
  18052.  
  18053.  
  18054.            MSecsToTimeStamp
  18055. Declaration: Function MSecsToTimeStamp(MSecs: Comp): TTimeStamp;
  18056.  
  18057. Description: MSecsTiTimeStamp converts the given number of milliseconds to a TTimeStamp
  18058.            date/time notation.
  18059.            Use TTimeStamp variables if you need to keep very precise track of time.
  18060.  
  18061.      Errors: None.
  18062.  
  18063.   See also: TimeStampToMSecs (307), DateTimeToTimeStamp (297),
  18064.  
  18065.            Program Example17 ;
  18066.  
  18067.            { This program demonstrates the MSecsToTimeStamp f u n c t i o n }
  18068.  
  18069.                                                   302
  18070.  
  18071.  
  18072.  
  18073.                                                      15.2. DATE AND TIME FUNCTIONS
  18074.  
  18075.  
  18076.  
  18077.            Uses s y s u t i l s ;
  18078.  
  18079.            Var MS : Comp;
  18080.                    TS : TTimeStamp ;
  18081.                    DT : TDateTime ;
  18082.            Begin
  18083.               TS:=DateTimeToTimeStamp (Now) ;
  18084.               Writeln ( ' Now in days s i n c e 1 / 1 / 0 0 0 1         : ' , TS. Date ) ;
  18085.               Writeln ( ' Now in m i l l i s e c s s i n c e midnight : ' , TS. Time ) ;
  18086.               MS:=TimeStampToMSecs ( TS) ;
  18087.               Writeln ( ' Now in m i l l i s e c s s i n c e 1/1/0001 : ' , MS) ;
  18088.               MS:=MS-1000 3600 2;
  18089.               TS:=MSecsToTimeStamp (MS) ;
  18090.               DT:=TimeStampToDateTime ( TS) ;
  18091.               Writeln ( ' Now minus 1 day : ' , DateTimeToStr (DT) ) ;
  18092.            End.
  18093.  
  18094.  
  18095.            Now
  18096. Declaration: Function Now: TDateTime;
  18097.  
  18098. Description: Now returns the current date and time. It is equivalent to Date+Time.
  18099.  
  18100.      Errors: None.
  18101.  
  18102.    See also: Date (294), Time (306)
  18103.  
  18104.            Program Example18 ;
  18105.  
  18106.            { This program demonstrates the Now f u n c t i o n }
  18107.  
  18108.            Uses s y s u t i l s ;
  18109.  
  18110.            Begin
  18111.               Writeln ( ' Now : ' , DateTimeToStr (Now) ) ;
  18112.            End.
  18113.  
  18114.  
  18115.            StrToDate
  18116. Declaration: Function StrToDate(const S: string): TDateTime;
  18117.  
  18118. Description: StrToDate converts the string S to a TDateTime date value. The Date must consist
  18119.            of 1 to three digits, separated by the DateSeparator character. If two numbers are
  18120.            given, they are supposed to form the day and month of the current year. If only one
  18121.            number is given, it is supposed to represent the day of the current month. (This is
  18122.            not supported in Delphi)
  18123.            The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the ShortDateFormat
  18124.            variable.
  18125.  
  18126.      Errors: On error (e.g. an invalid date or invalid character), an EConvertError exception
  18127.            is raised.
  18128.  
  18129.    See also: StrToTime (305), DateToStr (297)n TimeToStr (307).
  18130.  
  18131.                                                   303
  18132.  
  18133.  
  18134.  
  18135.                                                      15.2. DATE AND TIME FUNCTIONS
  18136.  
  18137.  
  18138.           Program Example19 ;
  18139.  
  18140.           { This program demonstrates the StrToDate f u n c t i o n }
  18141.  
  18142.           Uses s y s u t i l s ;
  18143.  
  18144.           Procedure TestStr ( S : String ) ;
  18145.  
  18146.           begin
  18147.              Writeln ( S , ' : ' , DateToStr ( StrToDate ( S ) ) ) ;
  18148.           end ;
  18149.  
  18150.           Begin
  18151.  
  18152.              Writeln ( ' ShortDateFormat ' , ShortDateFormat ) ;
  18153.              TestStr ( DateTimeToStr ( Date ) ) ;
  18154.              TestStr ( '05/05/1999' ) ;
  18155.              TestStr ( ' 5 / 5 ' ) ;
  18156.              TestStr ( ' 5 ' ) ;
  18157.           End.
  18158.  
  18159.  
  18160.           StrToDateTime
  18161. Declaration: Function StrToDateTime(const S: string): TDateTime;
  18162.  
  18163. Description: StrToDateTime converts the string S to a TDateTime date and time value. The
  18164.           Date must consist of 1 to three digits, separated by the DateSeparator character.
  18165.           If two numbers are given, they are supposed to form the day and month of the
  18166.           current year. If only one number is given, it is supposed to represent the day of the
  18167.           current month. (This is not supported in Delphi)
  18168.           The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the ShortDateFormat
  18169.           variable.
  18170.  
  18171.     Errors: On error (e.g. an invalid date or invalid character), an EConvertError exception
  18172.           is raised.
  18173.  
  18174.   See also: StrToDate (303), StrToTime (305), DateTimeToStr (295)
  18175.  
  18176.           Program Example20 ;
  18177.  
  18178.           { This program demonstrates the StrToDateTime f u n c t i o n }
  18179.  
  18180.           Uses s y s u t i l s ;
  18181.  
  18182.           Procedure TestStr ( S : String ) ;
  18183.  
  18184.           begin
  18185.              Writeln ( S , ' : ' , DateTimeToStr ( StrToDateTime ( S ) ) ) ;
  18186.           end ;
  18187.  
  18188.           Begin
  18189.  
  18190.              Writeln ( ' ShortDateFormat ' , ShortDateFormat ) ;
  18191.              TestStr ( DateTimeToStr (Now) ) ;
  18192.  
  18193.                                                   304
  18194.  
  18195.  
  18196.  
  18197.                                                           15.2. DATE AND TIME FUNCTIONS
  18198.  
  18199.  
  18200.               TestStr ( '05-05-1999 15:50' ) ;
  18201.               TestStr ( '5-5 13:30' ) ;
  18202.               TestStr ( ' 5 1 : 3 0 PM' ) ;
  18203.            End.
  18204.  
  18205.  
  18206.            StrToTime
  18207. Declaration: Function StrToTime(const S: string): TDateTime;
  18208.  
  18209. Description: StrToTime converts the string S to a TDateTime time value. The time must consist
  18210.            of 1 to 4 digits, separated by the TimeSeparator character. If two numbers are
  18211.            given, they are supposed to form the hour and minutes.
  18212.  
  18213.      Errors: On error (e.g. an invalid date or invalid character), an EConvertError exception
  18214.            is raised.
  18215.  
  18216.    See also: StrToDate (303), StrToDateTime (304), TimeToStr (307)
  18217.  
  18218.            Program Example21 ;
  18219.  
  18220.            { This program demonstrates the StrToTime f u n c t i o n }
  18221.  
  18222.            Uses s y s u t i l s ;
  18223.  
  18224.            Procedure TestStr ( S : String ) ;
  18225.  
  18226.            begin
  18227.               Writeln ( S , ' : ' , TimeToStr ( StrToTime ( S ) ) ) ;
  18228.            end ;
  18229.  
  18230.            Begin
  18231.               t e s t s t r ( TimeToStr ( Time ) ) ;
  18232.               t e s t s t r ( ' 1 2 : 0 0 ' ) ;
  18233.               t e s t s t r ( ' 1 5 : 3 0 ' ) ;
  18234.               t e s t s t r ( ' 3 : 3 0 PM' ) ;
  18235.            End.
  18236.  
  18237.  
  18238.            SystemTimeToDateTime
  18239. Declaration: Function SystemTimeToDateTime(const SystemTime: TSystemTime): TDateTime;
  18240.  
  18241. Description: SystemTimeToDateTime converts a TSystemTime record to a TDateTime style date/time
  18242.            indication.
  18243.  
  18244.      Errors: None.
  18245.  
  18246.    See also: DateTimeToSystemTime (296)
  18247.  
  18248.            Program Example22 ;
  18249.  
  18250.            { This program demonstrates the SystemTimeToDateTime f u n c t i o n }
  18251.  
  18252.            Uses s y s u t i l s ;
  18253.  
  18254.  
  18255.  
  18256.                                                         305
  18257.  
  18258.  
  18259.  
  18260.                                                            15.2. DATE AND TIME FUNCTIONS
  18261.  
  18262.  
  18263.            Var ST : TSystemTime ;
  18264.  
  18265.            Begin
  18266.               DateTimeToSystemTime (Now, ST) ;
  18267.               With St do
  18268.                    begin
  18269.                    Writeln ( ' Today i s            ' , year , ' / ' , month , ' / ' , Day ) ;
  18270.                    Writeln ( ' The time i s ' , Hour , ' : ' , minute , ' : ' , Second , ' . ' , M i l l i S e c o n d ) ;
  18271.                    end ;
  18272.               Writeln ( ' Converted : ' , DateTimeToStr ( SystemTimeToDateTime ( ST ) ) ) ;
  18273.            End.
  18274.  
  18275.  
  18276.            Time
  18277. Declaration: Function Time: TDateTime;
  18278.  
  18279. Description: Time returns the current time in TDateTime format. The date part of the TDateTimeValue
  18280.            is set to zero.
  18281.  
  18282.      Errors: None.
  18283.  
  18284.   See also: Now (303), Date (294)
  18285.  
  18286.            Program Example23 ;
  18287.  
  18288.            { This program demonstrates the Time f u n c t i o n }
  18289.  
  18290.            Uses s y s u t i l s ;
  18291.  
  18292.            Begin
  18293.               Writeln ( ' The time i s : ' , TimeToStr ( Time ) ) ;
  18294.            End.
  18295.  
  18296.  
  18297.            TimeStampToDateTime
  18298. Declaration: Function TimeStampToDateTime(const TimeStamp: TTimeStamp): TDateTime;
  18299.  
  18300. Description: TimeStampToDateTime converts TimeStamp to a TDateTime format variable. It is
  18301.            the inverse operation of DateTimeToTimeStamp (297).
  18302.  
  18303.      Errors: None.
  18304.  
  18305.   See also: DateTimeToTimeStamp (297), TimeStampToMSecs (307)
  18306.  
  18307.            Program Example24 ;
  18308.  
  18309.            { This program demonstrates the TimeStampToDateTime f u n c t i o n }
  18310.  
  18311.            Uses s y s u t i l s ;
  18312.  
  18313.            Var TS : TTimeStamp ;
  18314.                    DT : TDateTime ;
  18315.  
  18316.            Begin
  18317.  
  18318.  
  18319.                                                         306
  18320.  
  18321.  
  18322.  
  18323.                                                                          15.3. DISK FUNCTIONS
  18324.  
  18325.  
  18326.                   TS:=DateTimeToTimeStamp ( Now) ;
  18327.                   With TS do
  18328.                        begin
  18329.                        Writeln ( ' Now i s ' , time , ' m i l l i s e c o n d past midnight ' ) ;
  18330.                        Writeln ( ' Today i s ' , Date , ' days past 1/1/0001' ) ;
  18331.                        end ;
  18332.                  DT:=TimeStampToDateTime ( TS) ;
  18333.                   Writeln ( ' Together t h i s i s : ' , DateTimeToStr (DT) ) ;
  18334.                End.
  18335.  
  18336.  
  18337.            TimeStampToMSecs
  18338. Declaration: Function TimeStampToMSecs(const TimeStamp: TTimeStamp): comp;
  18339. Description: TimeStampToMSecs converts TimeStamp to the number of seconds since 1/1/0001.
  18340.            Use TTimeStamp variables if you need to keep very precise track of time.
  18341.     Errors: None.
  18342.   See also: MSecsToTimeStamp (302), TimeStampToDateTime (306)
  18343.  
  18344.            For an example, see MSecsToTimeStamp (302).
  18345.  
  18346.  
  18347.            TimeToStr
  18348. Declaration: Function TimeToStr(Time: TDateTime): string;
  18349. Description: TimeToStr converts the time in Time to a string. It uses the ShortTimeFormat
  18350.            variable to see what formatting needs to be applied. It is therefor entirely equivalent
  18351.            to a FormatDateTime('t',Time) call.
  18352.     Errors: None.
  18353.   See also:
  18354.  
  18355.                Program Example25 ;
  18356.  
  18357.                { This program demonstrates the TimeToStr f u n c t i o n }
  18358.  
  18359.                Uses s y s u t i l s ;
  18360.  
  18361.                Begin
  18362.                   Writeln ( ' The c u r r e n t time i s : ' , TimeToStr ( Time ) ) ;
  18363.                End.
  18364.  
  18365.  
  18366.            15.3 Disk functions
  18367.  
  18368.            AddDisk (Linux only)
  18369. Declaration: Function AddDisk (Const PAth : String) : Longint;
  18370. Description: On Linux both the DiskFree (36) and DiskSize (37) functions need a file on the
  18371.            specified drive, since is required for the statfs system call.
  18372.            These filenames are set in drivestr[0..26], and the first 4 have been preset to :
  18373.  
  18374.                                                          307
  18375.  
  18376.  
  18377.  
  18378.                                                                             15.3. DISK FUNCTIONS
  18379.  
  18380.  
  18381.            Disk 0'.' default drive - hence current directory is used.
  18382.            Disk 1'/fd0/.' floppy drive 1.
  18383.            Disk 2'/fd1/.' floppy drive 2.
  18384.            Disk 3'/' C: equivalent of DOS is the root partition.
  18385.  
  18386.            Drives 4..26 can be set by your own applications with the AddDisk call.
  18387.            The AddDisk call adds Path to the names of drive files, and returns the number of
  18388.            the disk that corresponds to this drive. If you add more than 21 drives, the count
  18389.            is wrapped to 4.
  18390.  
  18391.      Errors: None.
  18392.  
  18393.    See also: DiskFree (308), DiskSize (309)
  18394.  
  18395.  
  18396.            CreateDir
  18397. Declaration: Function CreateDir(Const NewDir : String) : Boolean;
  18398.  
  18399. Description: CreateDir creates a new directory with name NewDir. If the directory doesn't
  18400.            contain an absolute path, then the directory is created below the current working
  18401.            directory.
  18402.            The function returns True if the directory was successfully created, False otherwise.
  18403.  
  18404.      Errors: In case of an error, the function returns False.
  18405.  
  18406.    See also: RemoveDir (310)
  18407.  
  18408.            Program Example26 ;
  18409.  
  18410.            { This program demonstrates the CreateDir and RemoveDir f u n c t i o n s }
  18411.            { Run t h i s program twice in the same d i r e c t o r y }
  18412.  
  18413.            Uses s y s u t i l s ;
  18414.  
  18415.            Begin
  18416.               I f Not F i l e E x i s t s ( ' NewDir ' ) then
  18417.                    I f Not CreateDir ( ' NewDir ' ) Then
  18418.                       Writeln ( ' F a i l e d to c r e a t e d i r e c t o r y ! ' )
  18419.                    else
  18420.                       Writeln ( ' Created " NewDir " d i r e c t o r y ' )
  18421.               Else
  18422.                    I f Not RemoveDir ( ' NewDir ' ) Then
  18423.                       Writeln ( ' F a i l e d to remove d i r e c t o r y ! ' )
  18424.                    else
  18425.                       Writeln ( ' Removed " NewDir " d i r e c t o r y ' ) ;
  18426.            End.
  18427.  
  18428.  
  18429.            DiskFree
  18430. Declaration: Function DiskFree(Drive : Byte) : Longint;
  18431.  
  18432. Description: DiskFree returns the free space (in bytes) on disk Drive. Drive is the number of
  18433.            the disk drive:
  18434.  
  18435.  
  18436.                                                          308
  18437.  
  18438.  
  18439.  
  18440.                                                                     15.3. DISK FUNCTIONS
  18441.  
  18442.  
  18443.            0for the current drive.
  18444.            1for the first floppy drive.
  18445.            2for the second floppy drive.
  18446.            3for the first hard-disk parttion.
  18447.            4-26for all other drives and partitions.
  18448.  
  18449.            Remark Under linux, and Unix in general, the concept of disk is di erent than the
  18450.            dos one, since the filesystem is seen as one big directory tree. For this reason, the
  18451.            DiskFree and DiskSize (37) functions must be mimicked using filenames that reside
  18452.            on the partitions. For more information, see AddDisk (307)
  18453.  
  18454.     Errors: On error, -1 is returned.
  18455.  
  18456.   See also: DiskSize (309), AddDisk (307)
  18457.  
  18458.            Program Example27 ;
  18459.  
  18460.            { This program demonstrates the DiskFree f u n c t i o n }
  18461.  
  18462.            Uses s y s u t i l s ;
  18463.  
  18464.            Begin
  18465.               Write ( ' Size of c u r r e n t disk             : ' , DiskSize ( 0 ) ) ;
  18466.               Writeln ( ' (= ' , DiskSize ( 0 ) div 1024, ' k ) ' ) ;
  18467.               Write ( ' Free space of c u r r e n t disk : ' , Diskfree ( 0 ) ) ;
  18468.               Writeln ( ' (= ' , Diskfree ( 0 ) div 1024, ' k ) ' ) ;
  18469.            End.
  18470.  
  18471.  
  18472.            DiskSize
  18473. Declaration: Function DiskSize(Drive : Byte) : Longint;
  18474.  
  18475. Description: DiskSize returns the size (in bytes) of disk Drive. Drive is the number of the
  18476.            disk drive:
  18477.  
  18478.            0for the current drive.
  18479.            1for the first floppy drive.
  18480.            2for the second floppy drive.
  18481.            3for the first hard-disk parttion.
  18482.            4-26for all other drives and partitions.
  18483.  
  18484.            Remark Under linux, and Unix in general, the concept of disk is di erent than the
  18485.            dos one, since the filesystem is seen as one big directory tree. For this reason, the
  18486.            DiskFree (36) and DiskSize functions must be mimicked using filenames that reside
  18487.            on the partitions. For more information, see AddDisk (307)
  18488.  
  18489.     Errors: On error, -1 is returned.
  18490.  
  18491.   See also: DiskFree (308), AddDisk (307)
  18492.  
  18493.            For an example, see DiskFree (308).
  18494.  
  18495.  
  18496.  
  18497.                                                        309
  18498.  
  18499.  
  18500.  
  18501.                                                                               15.3. DISK FUNCTIONS
  18502.  
  18503.  
  18504.            GetCurrentDir
  18505. Declaration: Function GetCurrentDir : String;
  18506. Description: GetCurrentDir returns the current working directory.
  18507.      Errors: None.
  18508.    See also: SetCurrentDir (310), DiskFree (36), DiskSize (37)
  18509.  
  18510.                 Program Example28 ;
  18511.  
  18512.                 { This program demonstrates the GetCurrentDir f u n c t i o n }
  18513.  
  18514.                 Uses s y s u t i l s ;
  18515.  
  18516.                 Begin
  18517.                    Writeln ( ' Current D i r e c t o r y i s : ' , GetCurrentDir ) ;
  18518.                 End.
  18519.  
  18520.  
  18521.            RemoveDir
  18522. Declaration: Function RemoveDir(Const Dir : String) : Boolean;
  18523. Description: RemoveDir removes directory Dir from the disk. If the directory is not absolue, it
  18524.            is appended to the current working directory.
  18525.      Errors: In case of error (e.g. the directory isn't empty) the function returns False. If
  18526.            successful, True is returned.
  18527.    See also:
  18528.  
  18529.            For an example, see CreateDir (308).
  18530.  
  18531.  
  18532.            SetCurrentDir
  18533. Declaration: Function SetCurrentDir(Const NewDir : String) : Boolean;
  18534. Description: SetCurrentDir sets the current working directory of your program to NewDir. It
  18535.            returns True if the function was successfull, False otherwise.
  18536.      Errors: In case of error, False is returned.
  18537.    See also: GetCurrentDir (310)
  18538.  
  18539.                 Program Example29 ;
  18540.  
  18541.                 { This program demonstrates the S e t C u r r e n t D i r f u n c t i o n }
  18542.  
  18543.                 Uses s y s u t i l s ;
  18544.  
  18545.                 Begin
  18546.                    I f S e t C u r r e n t D i r ( ' . . ' ) Then
  18547.                         Writeln ( ' Now in d i r e c t o r y ' , GetCurrentDir )
  18548.                    else
  18549.                         Writeln ( ' Change d i r e c t o r y to . . f a i l e d . ' ) ;
  18550.                 End.
  18551.  
  18552.  
  18553.                                                                310
  18554.  
  18555.  
  18556.  
  18557.                                                                     15.4. FILE HANDLING FUNCTIONS
  18558.  
  18559.  
  18560.            15.4 File handling functions
  18561.  
  18562.            ChangeFileExt
  18563. Declaration: Function ChangeFileExt(const FileName, Extension: string): string;
  18564.  
  18565. Description: ChangeFileExt changes the file extension in FileName to Extension. The exten-
  18566.            sion Extension includes the starting . (dot). The previous extension of FileName
  18567.            are all characters after the last ., the . character included.
  18568.            If FileName doesn't have an extension, Extension is just appended.
  18569.  
  18570.      Errors: None.
  18571.  
  18572.    See also: ExtractFileName (314), ExtractFilePath (314), ExpandFileName (312)
  18573.  
  18574.  
  18575.            DeleteFile
  18576. Declaration: Function DeleteFile(Const FileName : String) : Boolean;
  18577.  
  18578. Description: DeleteFile deletes file FileName from disk. The function returns True if the file
  18579.            was successfully removed, False otherwise.
  18580.  
  18581.      Errors: On error, False is returned.
  18582.  
  18583.    See also: FileCreate (316), FileExists (317)
  18584.  
  18585.             Program Example31 ;
  18586.  
  18587.             { This program demonstrates the D e l e t e F i l e f u n c t i o n }
  18588.  
  18589.             Uses s y s u t i l s ;
  18590.  
  18591.             VarLine : String ;
  18592.                F, I : Longint ;
  18593.  
  18594.             Begin
  18595.                F:= F i l e C r e a t e ( ' t e s t . txt ' ) ;
  18596.                Line := ' Some s t r i n g l i n e . ' #10;
  18597.                For I :=1 to 10 do
  18598.                    F i l e W r i t e ( F, Line [ 1 ] , Length ( Line ) ) ;
  18599.                FileClose ( F ) ;
  18600.                DeleteFile ( ' t e s t . txt ' ) ;
  18601.            End.
  18602.  
  18603.  
  18604.            DoDirSeparators
  18605. Declaration: Procedure DoDirSeparators(Var FileName : String);
  18606.  
  18607. Description: This function replaces all directory separators '┤and '/' to the directory separator
  18608.            character for the current system.
  18609.  
  18610.      Errors: None.
  18611.  
  18612.    See also: ExtractFileName (314), ExtractFilePath (314)
  18613.  
  18614.  
  18615.                                                                   311
  18616.  
  18617.  
  18618.  
  18619.                                                              15.4. FILE HANDLING FUNCTIONS
  18620.  
  18621.  
  18622.           Program Example32 ;
  18623.  
  18624.           { This program demonstrates the DoDirSeparators f u n c t i o n }
  18625.           {$H+}
  18626.  
  18627.           Uses s y s u t i l s ;
  18628.  
  18629.           Procedure T e s t i t ( F : String ) ;
  18630.  
  18631.           begin
  18632.              Writeln ( ' Before : ' , F ) ;
  18633.              DoDirSeparators ( F ) ;
  18634.              Writeln ( ' After             : ' , F ) ;
  18635.           end ;
  18636.  
  18637.           Begin
  18638.              T e s t i t ( GetCurrentDir ) ;
  18639.              T e s t i t ( ' c :\ pp\ bin \ win32 ' ) ;
  18640.              T e s t i t ( '/ usr / l i b / fpc ' ) ;
  18641.              T e s t i t ( '\ usr \ l i b \ fpc ' ) ;
  18642.           End.
  18643.  
  18644.  
  18645.           ExpandFileName
  18646. Declaration: Function ExpandFileName(Const FileName : string): String;
  18647.  
  18648. Description: ExpandFileName expands the filename to an absolute filename. It changes all
  18649.           directory separator characters to the one appropriate for the system first.
  18650.  
  18651.     Errors: None.
  18652.  
  18653.   See also: ExtractFileName (314), ExtractFilePath (314), ExtractFileDir (313), ExtractFileDrive
  18654.           (313), ExtractFileExt (314), ExtractRelativePath (315)
  18655.  
  18656.           Program Example33 ;
  18657.  
  18658.           { This program demonstrates the ExpandFileName f u n c t i o n }
  18659.  
  18660.           Uses s y s u t i l s ;
  18661.  
  18662.           Procedure T e s t i t ( F : String ) ;
  18663.  
  18664.           begin
  18665.              Writeln ( F, ' expands to : ' , ExpandFileName ( F ) ) ;
  18666.           end ;
  18667.  
  18668.           Begin
  18669.              T e s t i t ( ' ex33 . pp ' ) ;
  18670.              T e s t i t ( ParamStr ( 0 ) ) ;
  18671.              T e s t i t ( '/ pp/ bin / win32 / ppc386 ' ) ;
  18672.              T e s t i t ( '\ pp\ bin \ win32 \ ppc386 ' ) ;
  18673.              T e s t i t ( ' . ' ) ;
  18674.           End.
  18675.  
  18676.  
  18677.                                                            312
  18678.  
  18679.  
  18680.  
  18681.                                                                    15.4. FILE HANDLING FUNCTIONS
  18682.  
  18683.  
  18684.                ExpandUNCFileName
  18685. Declaration: Function ExpandUNCFileName(Const FileName : string): String;
  18686.  
  18687. Description: ExpandUNCFileName runs ExpandFileName (312) on FileName and then attempts
  18688.                to replace the driveletter by the name of a shared disk.
  18689.  
  18690.     Errors:
  18691.  
  18692.   See also: ExtractFileName (314), ExtractFilePath (314), ExtractFileDir (313), ExtractFileDrive
  18693.                (313), ExtractFileExt (314), ExtractRelativePath (315)
  18694.  
  18695.  
  18696.                ExtractFileDir
  18697. Declaration: Function ExtractFileDir(Const FileName : string): string;
  18698.  
  18699. Description: ExtractFileDir returns only the directory part of FileName, not including a
  18700.                driveletter. The directory name has NO ending directory separator, in di erence
  18701.                with ExtractFilePath (314).
  18702.  
  18703.     Errors: None.
  18704.  
  18705.   See also: ExtractFileName (314), ExtractFilePath (314), ExtractFileDir (313), ExtractFileDrive
  18706.                (313), ExtractFileExt (314), ExtractRelativePath (315)
  18707.  
  18708.                Program Example34 ;
  18709.  
  18710.                { This program demonstrates the ExtractFileName f u n c t i o n }
  18711.                {$H+}
  18712.                Uses s y s u t i l s ;
  18713.  
  18714.                Procedure T e s t i t ( F : String ) ;
  18715.  
  18716.                begin
  18717.                 Writeln ( ' FileName                    : ' , F ) ;
  18718.                 Writeln ( ' Has Name                    : ' , ExtractFileName ( F ) ) ;
  18719.                 Writeln ( ' Has Path                    : ' , ExtractFilePath ( F ) ) ;
  18720.                 Writeln ( ' Has Extension : ' , ExtractFileExt ( F ) ) ;
  18721.                 Writeln ( ' Has D i r e c t o r y : ' , E x t r a c t F i l e D i r ( F ) ) ;
  18722.                 Writeln ( ' Has Drive                   : ' , E x t r a c t F i l e D r i v e ( F ) ) ;
  18723.                end ;
  18724.  
  18725.                Begin
  18726.                   T e s t i t ( Paramstr ( 0 ) ) ;
  18727.                   T e s t i t ( '/ usr / l o c a l / bin / mysqld ' ) ;
  18728.                   T e s t i t ( ' c :\ pp\ bin \ win32 \ ppc386 . exe ' ) ;
  18729.                   T e s t i t ( '/ pp/ bin / win32 / ppc386 . exe ' ) ;
  18730.                End.
  18731.  
  18732.  
  18733.                ExtractFileDrive
  18734. Declaration: Function ExtractFileDrive(const FileName: string): string;
  18735.  
  18736. Description: Extract
  18737.  
  18738.     Errors:
  18739.  
  18740.                                                               313
  18741.  
  18742.  
  18743.  
  18744.                                                           15.4. FILE HANDLING FUNCTIONS
  18745.  
  18746.  
  18747.    See also: ExtractFileName (314), ExtractFilePath (314), ExtractFileDir (313), ExtractFileDrive
  18748.            (313), ExtractFileExt (314), ExtractRelativePath (315)
  18749.  
  18750.            For an example, see ExtractFileDir (313).
  18751.  
  18752.  
  18753.            ExtractFileExt
  18754. Declaration: Function ExtractFileExt(const FileName: string): string;
  18755.  
  18756. Description: ExtractFileExt returns the extension (including the .(dot) character) of FileName.
  18757.  
  18758.      Errors: None.
  18759.  
  18760.    See also: ExtractFileName (314), ExtractFilePath (314), ExtractFileDir (313), ExtractFileDrive
  18761.            (313), ExtractFileExt (314), ExtractRelativePath (315)
  18762.  
  18763.            For an example, see ExtractFileDir (313).
  18764.  
  18765.  
  18766.            ExtractFileName
  18767. Declaration: Function ExtractFileName(const FileName: string): string;
  18768.  
  18769. Description: ExtractFileName returns the filename part from FileName. The filename consists
  18770.            of all characters after the last directory separator character ('/' or '┤) or drive letter.
  18771.            The full filename can always be reconstucted by concatenating the result of Extract-
  18772.            FilePath (314) and ExtractFileName.
  18773.  
  18774.      Errors: None.
  18775.  
  18776.    See also: ExtractFileName (314), ExtractFilePath (314), ExtractFileDir (313), ExtractFileDrive
  18777.            (313), ExtractFileExt (314),ExtractRelativePath (315)
  18778.  
  18779.            For an example, see ExtractFileDir (313).
  18780.  
  18781.  
  18782.            ExtractFilePath
  18783. Declaration: Function ExtractFilePath(const FileName: string): string;
  18784.  
  18785. Description: ExtractFilePath returns the path part (including driveletter) from FileName.
  18786.            The path consists of all characters before the last directory separator character ('/'
  18787.            or '┤), including the directory separator itself. In case there is only a drive letter,
  18788.            that will be returned.
  18789.            The full filename can always be reconstucted by concatenating the result of ExtractFilePath
  18790.            and ExtractFileName (314).
  18791.  
  18792.      Errors: None.
  18793.  
  18794.    See also: ExtractFileName (314), ExtractFilePath (314), ExtractFileDir (313), ExtractFileDrive
  18795.            (313), ExtractFileExt (314), ExtractRelativePath (315)
  18796.  
  18797.            For an example, see ExtractFileDir (313).
  18798.  
  18799.  
  18800.  
  18801.  
  18802.                                                       314
  18803.  
  18804.  
  18805.  
  18806.                                                              15.4. FILE HANDLING FUNCTIONS
  18807.  
  18808.  
  18809.            ExtractRelativePath
  18810. Declaration: Function ExtractRelativePath(Const BaseName,DestNAme : String): String;
  18811.  
  18812. Description: ExtractRelativePath constructs a relative path to go from BaseName to DestName.
  18813.            If DestName is on another drive (Not on Linux) then the whole Destname is returned.
  18814.            Note: This function does not exist in the Delphi unit.
  18815.  
  18816.     Errors: None.
  18817.  
  18818.   See also: ExtractFileName (314), ExtractFilePath (314), ExtractFileDir (313), ExtractFileDrive
  18819.            (313), ExtractFileExt (314),
  18820.  
  18821.            Program Example35 ;
  18822.  
  18823.            { This program demonstrates the E x t r a c t R e l a t i v e P a t h f u n c t i o n }
  18824.  
  18825.            Uses s y s u t i l s ;
  18826.  
  18827.            Procedure T e s t i t ( FromDir , ToDir : String ) ;
  18828.  
  18829.            begin
  18830.               Write ( ' From "' , FromDir , '" to "' , ToDir , '" via "' ) ;
  18831.               Writeln ( E x t r a c t R e l a t i v e P a t h ( FromDir , ToDir ) , ' " ' ) ;
  18832.            end ;
  18833.  
  18834.            Begin
  18835.             T e s t i t ( '/ pp/ src / compiler ' , '/ pp/ bin / win32 / ppc386 ' ) ;
  18836.             T e s t i t ( '/ pp/ bin / win32 / ppc386 ' , '/ pp/ src / compiler ' ) ;
  18837.             T e s t i t ( ' e :/ pp/ bin / win32 / ppc386 ' , ' d :/ pp/ src / compiler ' ) ;
  18838.             T e s t i t ( ' e :\ pp\ bin \ win32 \ ppc386 ' , ' d :\ pp\ src \ compiler ' ) ;
  18839.            End.
  18840.  
  18841.  
  18842.            FileAge
  18843. Declaration: Function FileAge(Const FileName : String): Longint;
  18844.  
  18845. Description: FileAge returns the last modification time of file FileName. The FileDate for-
  18846.            mat can be transformed to TDateTime format with the FileDateToDateTime (300)
  18847.            function.
  18848.  
  18849.     Errors: In case of errors, -1 is returned.
  18850.  
  18851.   See also: FileDateToDateTime (300), FileExists (317), FileGetAttr (317)
  18852.  
  18853.            Program Example36 ;
  18854.  
  18855.            { This program demonstrates the FileAge f u n c t i o n }
  18856.  
  18857.            Uses s y s u t i l s ;
  18858.  
  18859.            Var S : TDateTime ;
  18860.                     fa : Longint ;
  18861.            Begin
  18862.               fa := FileAge ( ' ex36 . pp ' ) ;
  18863.  
  18864.  
  18865.                                                          315
  18866.  
  18867.  
  18868.  
  18869.                                                                     15.4. FILE HANDLING FUNCTIONS
  18870.  
  18871.  
  18872.               I f Fa<>-1 then
  18873.                    begin
  18874.                    S:= FileDateTodateTime ( fa ) ;
  18875.                    Writeln ( ' I ' ' m from ' , DateTimeToStr ( S ))
  18876.                    end ;
  18877.            End.
  18878.  
  18879.  
  18880.            FileClose
  18881. Declaration: Procedure FileClose(Handle : Longint);
  18882.  
  18883. Description: FileClose closes the file handle Handle. After this call, attempting to read or
  18884.            write from the handle will result in an error.
  18885.  
  18886.     Errors: None.
  18887.  
  18888.   See also: FileCreate (316), FileWrite (322), FileOpen (319), FileRead (319), FileTruncate (321),
  18889.            FileSeek (320)
  18890.  
  18891.            For an example, see FileCreate (316)
  18892.  
  18893.  
  18894.            FileCreate
  18895. Declaration: Function FileCreate(Const FileName : String) : Longint;
  18896.  
  18897. Description: FileCreate creates a new file with name FileName on the disk and returns a file
  18898.            handle which can be used to read or write from the file with the FileRead (319) and
  18899.            FileWrite (322) functions.
  18900.            If a file with name FileName already existed on the disk, it is overwritten.
  18901.  
  18902.     Errors: If an error occurs (e.g. disk full or non-existent path), the function returns -1.
  18903.  
  18904.   See also: FileClose (316), FileWrite (322), FileOpen (319), FileRead (319), FileTruncate (321),
  18905.            FileSeek (320)
  18906.  
  18907.            Program Example37 ;
  18908.  
  18909.            { This program demonstrates the F i l e C r e a t e f u n c t i o n }
  18910.  
  18911.            Uses s y s u t i l s ;
  18912.  
  18913.            Var I , J , F : Longint ;
  18914.  
  18915.            Begin
  18916.               F:= F i l e C r e a t e ( ' t e s t . dat ' ) ;
  18917.               I f F=-1 then
  18918.                    Halt ( 1 ) ;
  18919.               For I :=0 to 100 do
  18920.                    F i l e W r i t e ( F, I , SizeOf ( i ) ) ;
  18921.               FileClose ( f ) ;
  18922.               F:= FileOpen ( ' t e s t . dat ' , fmOpenRead ) ;
  18923.               For I :=0 to 100 do
  18924.                    begin
  18925.                    FileRead ( F, J , SizeOF ( J ) ) ;
  18926.  
  18927.                                                                   316
  18928.  
  18929.  
  18930.  
  18931.                                                              15.4. FILE HANDLING FUNCTIONS
  18932.  
  18933.  
  18934.                    I f J<>I then
  18935.                       Writeln ( ' Mismatch at f i l e p o s i t i o n ' , I )
  18936.                    end ;
  18937.               FileSeek ( F , 0 , fsFromBeginning ) ;
  18938.               Randomize ;
  18939.               Repeat
  18940.                    FileSeek ( F, Random(100) 4, fsFromBeginning ) ;
  18941.                    FileRead ( F, J , SizeOf ( J ) ) ;
  18942.                    Writeln ( ' Random read : ' , j ) ;
  18943.               Until J >80;
  18944.               FileClose ( F ) ;
  18945.               F:= FileOpen ( ' t e s t . dat ' , fmOpenWrite ) ;
  18946.               I :=50  SizeOf ( Longint ) ;
  18947.               I f F i l e T r u n c a t e ( F, I ) then
  18948.                    Writeln ( ' S u c c e s s F u l l y truncated f i l e to ' , I , ' bytes . ' ) ;
  18949.               FileClose ( F ) ;
  18950.            End.
  18951.  
  18952.  
  18953.            FileExists
  18954. Declaration: Function FileExists(Const FileName : String) : Boolean;
  18955.  
  18956. Description: FileExists returns True if a file with name FileName exists on the disk, False
  18957.            otherwise.
  18958.  
  18959.     Errors: None.
  18960.  
  18961.   See also: FileAge (315), FileGetAttr (317), FileSetAttr (321)
  18962.  
  18963.            Program Example38 ;
  18964.  
  18965.            { This program demonstrates the F i l e E x i s t s f u n c t i o n }
  18966.  
  18967.            Uses s y s u t i l s ;
  18968.  
  18969.            Begin
  18970.               I f F i l e E x i s t s ( ParamStr ( 0 ) ) Then
  18971.                    Writeln ( ' A l l i s w e l l , I seem to e x i s t . ' ) ;
  18972.            End.
  18973.  
  18974.  
  18975.            FileGetAttr
  18976. Declaration: Function FileGetAttr(Const FileName : String) : Longint;
  18977.  
  18978. Description: FileGetAttr returns the attribute settings of file FileName. The attribute is a
  18979.            OR-ed combination of the following constants:
  18980.  
  18981.            faReadOnlyThe file is read-only.
  18982.            faHiddenThe file is hidden. (On linux, this means that the filename starts with
  18983.                    a dot)
  18984.            faSysFileThe file is a system file (On linux, this means that the file is a character,
  18985.                    block or FIFO file).
  18986.            faVolumeIdVolume Label. Not possible under linux.
  18987.  
  18988.                                                            317
  18989.  
  18990.  
  18991.  
  18992.                                                              15.4. FILE HANDLING FUNCTIONS
  18993.  
  18994.  
  18995.            faDirectoryFile is a directory.
  18996.            faArchivefile is an archive. Not possible on linux.
  18997.  
  18998.     Errors: In case of error, -1 is returned.
  18999.  
  19000.   See also: FileSetAttr (321), FileAge (315), FileGetDate (318).
  19001.  
  19002.            Program Example40 ;
  19003.  
  19004.            { This program demonstrates the F i l e G e t A t t r f u n c t i o n }
  19005.  
  19006.            Uses s y s u t i l s ;
  19007.  
  19008.            Procedure T e s t i t ( Name : String ) ;
  19009.  
  19010.            Var F : Longint ;
  19011.  
  19012.            Begin
  19013.               F:= FileGetAttr (Name) ;
  19014.               I f F<>-1 then
  19015.                     begin
  19016.                     Writeln ( ' Testing : ' , Name) ;
  19017.                     I f ( F and faReadOnly )<>0 then
  19018.                       Writeln ( ' F i l e i s ReadOnly ' ) ;
  19019.                     I f ( F and faHidden )<>0 then
  19020.                       Writeln ( ' F i l e i s hidden ' ) ;
  19021.                     I f ( F and f a S y s F i l e )<>0 then
  19022.                       Writeln ( ' F i l e i s a system f i l e ' ) ;
  19023.                     I f ( F and faVolumeID )<>0 then
  19024.                       Writeln ( ' F i l e i s a disk l a b e l ' ) ;
  19025.                     I f ( F and f a A r c h i v e )<>0 then
  19026.                       Writeln ( ' F i l e i s a r t c h i v e f i l e ' ) ;
  19027.                     I f ( F and f a D i r e c t o r y )<>0 then
  19028.                       Writeln ( ' F i l e i s a d i r e c t o r y ' ) ;
  19029.                     end
  19030.               else
  19031.                Writeln ( ' Error reading a t t r i b i t e s of ' , Name) ;
  19032.            end ;
  19033.  
  19034.            begin
  19035.               t e s t i t ( ' ex40 . pp ' ) ;
  19036.               t e s t i t ( ParamStr ( 0 ) ) ;
  19037.               t e s t i t ( ' . ' ) ;
  19038.               t e s t i t ( ' / ' ) ;
  19039.            End.
  19040.  
  19041.  
  19042.            FileGetDate
  19043. Declaration: Function FileGetDate(Handle : Longint) : Longint;
  19044.  
  19045. Description: FileGetdate returns the filetime of the opened file with filehandle Handle. It
  19046.            is the same as FileAge (315), with this di erence that FileAge only needs the file
  19047.            name, while FilegetDate needs an open file handle.
  19048.  
  19049.  
  19050.                                                           318
  19051.  
  19052.  
  19053.  
  19054.                                                                    15.4. FILE HANDLING FUNCTIONS
  19055.  
  19056.  
  19057.     Errors: On error, -1 is returned.
  19058.  
  19059.   See also: FileAge (315)
  19060.  
  19061.            Program Example39 ;
  19062.  
  19063.            { This program demonstrates the FileGetDate f u n c t i o n }
  19064.  
  19065.            Uses s y s u t i l s ;
  19066.  
  19067.            Var F, D : Longint ;
  19068.  
  19069.            Begin
  19070.               F:= F i l e C r e a t e ( ' t e s t . dat ' ) ;
  19071.               D:= FileGetDate (D) ;
  19072.               Writeln ( ' F i l e c r e r a t e d on ' , DateTimeToStr ( FileDateToDateTime (D) ) ) ;
  19073.               FileClose ( F ) ;
  19074.               DeleteFile ( ' t e s t . dat ' ) ;
  19075.            End.
  19076.  
  19077.  
  19078.            FileOpen
  19079. Declaration: Function FileOpen(Const FileName : string; Mode : Integer) : Longint;
  19080.  
  19081. Description: FileOpen opens a file with name FileName with mode Mode. Mode can be one of
  19082.            the following constants:
  19083.  
  19084.            fmOpenReadThe file is opened for reading.
  19085.            fmOpenWriteThe file is opened for writing.
  19086.            fmOpenReadWriteThe file is opened for reading and writing.
  19087.  
  19088.            If the file has been successfully opened, it can be read from or written to (depending
  19089.            on the Mode parameter) with the FileRead (319) and FileWrite functions.
  19090.            Remark that you cannot open a file if it doesn't exist yet, i.e. it will not be created
  19091.            for you. If you want tp create a new file, or overwrite an old one, use the FileCreate
  19092.            (316) function.
  19093.  
  19094.     Errors: On Error, -1 is returned.
  19095.  
  19096.   See also: FileClose (316), FileWrite (322), FileCreate (316), FileRead (319), FileTruncate (321),
  19097.            FileSeek (320)
  19098.  
  19099.            For an example, see FileRead (319)
  19100.  
  19101.  
  19102.            FileRead
  19103. Declaration: Function FileRead(Handle : Longint; Var Buffer; Count : longint) : Longint;
  19104.  
  19105. Description: FileRead reads Count bytes from file-handle Handle and stores them into Buffer.
  19106.            Bu er must be at least Count bytes long. No checking on this is performed, so be
  19107.            careful not to overwrite any memory. Handle must be the result of a FileOpen (319)
  19108.            call.
  19109.  
  19110.     Errors: On error, -1 is returned.
  19111.  
  19112.                                                                  319
  19113.  
  19114.  
  19115.  
  19116.                                                                15.4. FILE HANDLING FUNCTIONS
  19117.  
  19118.  
  19119.    See also: FileClose (316), FileWrite (322), FileCreate (316), FileOpen (319), FileTruncate (321),
  19120.             FileSeek (320)
  19121.  
  19122.             For an example, see FileOpen (319)
  19123.  
  19124.  
  19125.             FileSearch
  19126. Declaration: Function FileSearch(Const Name, DirList : String) : String;
  19127.  
  19128. Description: FileSearch looks for the file Name in DirList, where dirlist is a list of directories,
  19129.             separated by semicolons or colons. It returns the full filename of the first match
  19130.             found.
  19131.  
  19132.      Errors: On error, an empty string is returned.
  19133.  
  19134.    See also: ExpandFileName (312), FindFirst (322)
  19135.  
  19136.             Program Example41 ;
  19137.  
  19138.             { Program to demonstrate the F i l e S e a r c h f u n c t i o n . }
  19139.  
  19140.             Uses S y s u t i l s ;
  19141.  
  19142.             Const
  19143.             { $ i f d e f l i n u x }
  19144.                FN = ' f i n d ' ;
  19145.                P = ' . : / bin :/ usr / bin ' ;
  19146.             { $ e l s e }
  19147.                FN = ' f i n d . exe ' ;
  19148.                P = ' c :\ dos ; c :\ windows ; c :\ windows \ system ; c :\ windows \ system32 ' ;
  19149.             { $ e n d i f }
  19150.  
  19151.             begin
  19152.                 Writeln ( ' f i n d i s in : ' , FileSearch ( FN, P) ) ;
  19153.             end .
  19154.  
  19155.  
  19156.             FileSeek
  19157. Declaration: Function FileSeek(Handle,Offset,Origin : Longint) : Longint;
  19158.  
  19159. Description: FileSeek sets the file pointer on position Offset, starting from Origin. Origin
  19160.             can be one of the following values:
  19161.  
  19162.             fsFromBeginningOffset is relative to the first byte of the file. This position is
  19163.                      zero-based. i.e. the first byte is at o set 0.
  19164.             fsFromCurrentOffset is relative to the current position.
  19165.             fsFromEndOffset is relative to the end of the file. This means that Offset can
  19166.                      only be zero or negative in this case.
  19167.  
  19168.             If successfull, the function returns the new file position, relative to the beginning of
  19169.             the file.
  19170.             Remark: The abovementioned constants do not exist in Delphi.
  19171.  
  19172.      Errors: On error, -1 is returned.
  19173.  
  19174.                                                           320
  19175.  
  19176.  
  19177.  
  19178.                                                              15.4. FILE HANDLING FUNCTIONS
  19179.  
  19180.  
  19181.    See also: FileClose (316), FileWrite (322), FileCreate (316), FileOpen (319) FileRead (319),
  19182.            FileTruncate (321)
  19183.  
  19184.                 Program Example42 ;
  19185.  
  19186.                 { This program demonstrates the F i l e S e t A t t r f u n c t i o n }
  19187.  
  19188.                 Uses s y s u t i l s ;
  19189.  
  19190.                 Begin
  19191.                    I f FileSetAttr ( ' ex40 . pp ' , faReadOnly or faHidden )=0 then
  19192.                         Writeln ( ' S u c c e s s f u l l y made f i l e hidden and read -only . ' )
  19193.                    else
  19194.                         Writeln ( ' Coulnd ' ' t make f i l e hidden and read -only . ' ) ;
  19195.                 End.
  19196.            For an example, see FileCreate (316)
  19197.  
  19198.  
  19199.            FileSetAttr (Not on Linux)
  19200. Declaration: Function FileSetAttr(Const Filename : String; Attr: longint) : Longint;
  19201. Description: FileSetAttr sets the attributes of FileName to Attr. If the function was success-
  19202.            ful, 0 is returned, -1 otherwise.
  19203.            Attr can be set to an OR-ed combination of the pre-defined faXXX constants.
  19204.      Errors: On error, -1 is returned (always on linux).
  19205.    See also: FileGetAttr (317), FileGetDate (318), FileSetDate (321).
  19206.  
  19207.  
  19208.            FileSetDate (Not on Linux)
  19209. Declaration: Function FileSetDate(Handle,Age : Longint) : Longint;
  19210. Description: FileSetDate sets the file date of the file with handle Handle to Age, where Age is
  19211.            a DOS date-and-time stamp value.
  19212.            The function returns zero of successfull.
  19213.      Errors: On Linux, -1 is always returned, since this is impossible to implement. On Windows
  19214.            and DOS, a negative error code is returned.
  19215.    See also:
  19216.  
  19217.  
  19218.            FileTruncate
  19219. Declaration: Function FileTruncate(Handle,Size: Longint) : boolean;
  19220. Description: FileTruncate truncates the file with handle Handle to Size bytes. The file must
  19221.            have been opened for writing prior to this call. The function returns True is suc-
  19222.            cessful, False otherwise.
  19223.      Errors: On error, the function returns False.
  19224.    See also: FileClose (316), FileWrite (322), FileCreate (316), FileOpen (319) FileRead (319),
  19225.            FileSeek (320)
  19226.  
  19227.            For an example, see FileCreate (316).
  19228.  
  19229.                                                          321
  19230.  
  19231.  
  19232.  
  19233.                                                        15.4. FILE HANDLING FUNCTIONS
  19234.  
  19235.  
  19236.            FileWrite
  19237. Declaration: Function FileWrite(Handle : Longint; Var Buffer; Count : Longint) :
  19238.            Longint;
  19239.  
  19240. Description: FileWrite writes Count bytes from Buffer to the file with handle Handle. Prior
  19241.            to this call, the file must have been opened for writing. Buffer must be at least
  19242.            Count bytes large, or a memory access error may occur.
  19243.            The function returns the number of bytes written, or -1 in case of an error.
  19244.  
  19245.     Errors: In case of error, -1 is returned.
  19246.  
  19247.   See also: FileClose (316), FileCreate (316), FileOpen (319) FileRead (319), FileTruncate (321),
  19248.            FileSeek (320)
  19249.  
  19250.            For an example, see FileCreate (316).
  19251.  
  19252.  
  19253.            FindClose
  19254. Declaration: Procedure FindClose(Var F : TSearchrec);
  19255.  
  19256. Description: FindClose ends a series of FindFirst (322)/FindNext (323) calls, and frees any
  19257.            memory used by these calls. It is absolutely necessary to do this call, or huge
  19258.            memory losses may occur.
  19259.  
  19260.     Errors: None.
  19261.  
  19262.   See also: FindFirst (322), FindNext (323).
  19263.  
  19264.            For an example, see FindFirst (322).
  19265.  
  19266.  
  19267.            FindFirst
  19268. Declaration: Function FindFirst(Const Path : String; Attr : Longint; Var Rslt : TSearchRec)
  19269.            : Longint;
  19270.  
  19271. Description: FindFirst looks for files that match the name (possibly with wildcards) in Path
  19272.            and attributes Attr. It then fills up the Rslt record with data gathered about the
  19273.            file. It returns 0 if a file matching the specified criteria is found, a nonzero value
  19274.            (-1 on linux) otherwise.
  19275.            The Rslt record can be fed to subsequent calls to FindNext, in order to find other
  19276.            files matching the specifications.
  19277.            remark: A FindFirst call must always be followed by a FindClose (322) call with
  19278.            the same Rslt record. Failure to do so will result in memory loss.
  19279.  
  19280.     Errors: On error the function returns -1 on linux, a nonzero error code on Windows.
  19281.  
  19282.   See also: FindClose (40)FindCloseSys, FindNext (323).
  19283.  
  19284.            Program Example43 ;
  19285.  
  19286.            { This program demonstrates the F i n d F i r s t f u n c t i o n }
  19287.  
  19288.            Uses s y s u t i l s ;
  19289.  
  19290.  
  19291.                                                     322
  19292.  
  19293.  
  19294.  
  19295.                                                             15.4. FILE HANDLING FUNCTIONS
  19296.  
  19297.  
  19298.            Var I n f o : TSearchRec ;
  19299.                    Count : Longint ;
  19300.  
  19301.            Begin
  19302.               Count :=0;
  19303.               I f FindFirst ( '   . pp ' , f a A n y F i l e , I n f o )=0 then
  19304.                    begin
  19305.                    Repeat
  19306.                       Inc ( Count ) ;
  19307.                       With I n f o do
  19308.                             Writeln ( Name: 4 0 , Size : 1 5 ) ;
  19309.                    Until FindNext ( i n f o )<>0;
  19310.                    end ;
  19311.               FindClose ( I n f o ) ;
  19312.               Writeln ( ' F i n i s h e d search . Found ' , Count , ' matches ' ) ;
  19313.  
  19314.            End.
  19315.  
  19316.  
  19317.            FindNext
  19318. Declaration: Function FindNext(Var Rslt : TSearchRec) : Longint;
  19319.  
  19320. Description: FindNext finds a next occurrence of a search sequence initiated by FindFirst.
  19321.            If another record matching the criteria in Rslt is found, 0 is returned, a nonzero
  19322.            constant is returned otherwise.
  19323.            remark: The last FindNext call must always be followed by a FindClose call with
  19324.            the same Rslt record. Failure to do so will result in memory loss.
  19325.  
  19326.      Errors: On error (no more file is found), a nonzero constant is returned.
  19327.  
  19328.    See also: FindFirst (322), FindClose (40)
  19329.  
  19330.            For an example, see FindFirst (322)
  19331.  
  19332.  
  19333.            GetDirs
  19334. Declaration: Function GetDirs(Var DirName : String; Var Dirs : Array of pchar) :
  19335.            Longint;
  19336.  
  19337. Description: GetDirs splits DirName in a null-byte separated list of directory names, Dirs is
  19338.            an array of PChars, pointing to these directory names. The function returns the
  19339.            number of directories found, or -1 if none were found. DirName must contain only
  19340.            OSDirSeparator as Directory separator chars.
  19341.  
  19342.      Errors: None.
  19343.  
  19344.    See also: ExtractRelativePath (315)
  19345.  
  19346.            Program Example45 ;
  19347.  
  19348.            { This program demonstrates the GetDirs f u n c t i o n }
  19349.            {$H+}
  19350.  
  19351.            Uses s y s u t i l s ;
  19352.  
  19353.                                                          323
  19354.  
  19355.  
  19356.  
  19357.                                                                    15.4. FILE HANDLING FUNCTIONS
  19358.  
  19359.  
  19360.  
  19361.           Var Dirs : Array [ 0 . . 1 2 7 ] of pchar ;
  19362.                   I , Count : l o n g i n t ;
  19363.                   Dir , NewDir : String ;
  19364.  
  19365.            Begin
  19366.               Dir := GetCurrentDir ;
  19367.               Writeln ( ' Dir : ' , Dir ) ;
  19368.               NewDir := ' ' ;
  19369.               count := GetDirs ( Dir , Dirs ) ;
  19370.               For I :=0 to Count do
  19371.                   begin
  19372.                   NewDir :=NewDir+' / ' +StrPas ( Dirs [ I ] ) ;
  19373.                   Writeln ( NewDir ) ;
  19374.                   end ;
  19375.           End.
  19376.  
  19377.  
  19378.           RenameFile
  19379. Declaration: Function RenameFile(Const OldName, NewName : String) : Boolean;
  19380.  
  19381. Description: RenameFile renames a file from OldName to NewName. The function returns True
  19382.           if successful, False otherwise.
  19383.           Remark: you cannot rename across disks or partitions.
  19384.  
  19385.     Errors: On Error, False is returned.
  19386.  
  19387.   See also: DeleteFile (311)
  19388.  
  19389.           Program Example44 ;
  19390.  
  19391.            { This program demonstrates the RenameFile f u n c t i o n }
  19392.  
  19393.            Uses s y s u t i l s ;
  19394.  
  19395.           Var F : Longint ;
  19396.                   S : String ;
  19397.  
  19398.            Begin
  19399.               S:= ' Some short f i l e . ' ;
  19400.               F:= F i l e C r e a t e ( ' t e s t . dap ' ) ;
  19401.               F i l e W r i t e ( F, S [ 1 ] , Length ( S ) ) ;
  19402.               FileClose ( F ) ;
  19403.               I f RenameFile ( ' t e s t . dap ' , ' t e s t . dat ' ) then
  19404.                   Writeln ( ' S u c c e s s f u l l y renamed f i l e s . ' ) ;
  19405.           End.
  19406.  
  19407.  
  19408.           SetDirSeparators
  19409. Declaration: Function SetDirSeparators(Const FileName : String) : String;
  19410.  
  19411. Description: SetDirSeparators returns FileName with all possible DirSeparators replaced by
  19412.           OSDirSeparator.
  19413.  
  19414.  
  19415.                                                                  324
  19416.  
  19417.  
  19418.  
  19419.                                                                     15.5. PCHAR FUNCTIONS
  19420.  
  19421.  
  19422.   Errors: None.
  19423. See also: ExpandFileName (312), ExtractFilePath (314), ExtractFileDir (313)
  19424.  
  19425.         Program Example47 ;
  19426.  
  19427.         { This program demonstrates the S e t D i r S e p a r a t o r s f u n c t i o n }
  19428.  
  19429.         Uses s y s u t i l s ;
  19430.  
  19431.         Begin
  19432.            Writeln ( S e t D i r S e p a r a t o r s ( '/ pp\ bin / win32 \ ppc386 ' ) ) ;
  19433.         End.
  19434.  
  19435.  
  19436.         15.5 PChar functions
  19437.  
  19438.         Introduction
  19439.         Most PChar functions are the same as their counterparts in the STRINGS unit. The
  19440.         following functions are the same :
  19441.  
  19442.            1. StrCat (279) : Concatenates two PChar strings.
  19443.            2. StrComp (280) : Compares two PChar strings.
  19444.            3. StrCopy (280) : Copies a PChar string.
  19445.            4. StrECopy (281) : Copies a PChar string and returns a pointer to the termi-
  19446.                 nating null byte.
  19447.            5. StrEnd (282) : Returns a pointer to the terminating null byte.
  19448.            6. StrIComp (282) : Case insensitive compare of 2 PChar strings.
  19449.            7. StrLCat (283) : Appends at most L characters from one PChar to another
  19450.                 PChar.
  19451.            8. StrLComp (283) : Case sensitive compare of at most L characters of 2 PChar
  19452.                 strings.
  19453.            9. StrLCopy (284) : Copies at most L characters from one PChar to another.
  19454.           10. StrLen (284) : Returns the length (exclusive terminating null byte) of a PChar
  19455.                 string.
  19456.           11. StrLIComp (285) : Case insensitive compare of at most L characters of 2 PChar
  19457.                 strings.
  19458.           12. StrLower (285) : Converts a PChar to all lowercase letters.
  19459.           13. StrMove (286) : Moves one PChar to another.
  19460.           14. StrNew (286) : Makes a copy of a PChar on the heap, and returns a pointer
  19461.                 to this copy.
  19462.           15. StrPos (288) : Returns the position of one PChar string in another?
  19463.           16. StrRScan (288) : returns a pointer to the last occurrence of on PChar string
  19464.                 in another one.
  19465.  
  19466.                                                     325
  19467.  
  19468.  
  19469.  
  19470.                                                                           15.5. PCHAR FUNCTIONS
  19471.  
  19472.  
  19473.             17. StrScan (288) : returns a pointer to the first occurrence of on PChar string in
  19474.                    another one.
  19475.  
  19476.             18. StrUpper (289) : Converts a PChar to all uppercase letters.
  19477.  
  19478.            The subsequent functions are di erent from their counterparts in STRINGS, al-
  19479.            though the same examples can be used.
  19480.  
  19481.  
  19482.            StrAlloc
  19483. Declaration: Function StrAlloc(Size: cardinal): PChar;
  19484.  
  19485. Description: StrAlloc reserves memory on the heap for a string with length Len, terminating
  19486.            #0 included, and returns a pointer to it.
  19487.            Additionally, StrAlloc allocates 4 extra bytes to store the size of the allocated
  19488.            memory. Therefore this function is NOT compatible with the StrAlloc (279) function
  19489.            of the Strings unit.
  19490.  
  19491.     Errors: None.
  19492.  
  19493.   See also: StrBufSize (326), StrDispose (327), StrAlloc (279)
  19494.  
  19495.            For an example, see StrBufSize (326).
  19496.  
  19497.  
  19498.            StrBufSize
  19499. Declaration: Function StrBufSize(var Str: PChar): cardinal;
  19500.  
  19501. Description: StrBufSize returns the memory allocated for Str. This function ONLY gives the
  19502.            correct result if Str was allocated using StrAlloc (326).
  19503.  
  19504.     Errors: If no more memory is available, a runtime error occurs.
  19505.  
  19506.   See also: StrAlloc (326).StrDispose (327).
  19507.  
  19508.            Program Example46 ;
  19509.  
  19510.            { This program demonstrates the S t r B u f S i z e f u n c t i o n }
  19511.            {$H+}
  19512.  
  19513.            Uses s y s u t i l s ;
  19514.  
  19515.            Const S = ' Some nice s t r i n g ' ;
  19516.  
  19517.            Var P : Pchar ;
  19518.  
  19519.            Begin
  19520.                P:= S t r A l l o c ( Length ( S)+1);
  19521.                StrPCopy (P, S ) ;
  19522.                Write ( P, ' has length ' , length ( S ) ) ;
  19523.                Writeln ( ' and         b u f f e r s i z e ' , S t r B u f S i z e (P) ) ;
  19524.                StrDispose (P) ;
  19525.            End.
  19526.  
  19527.  
  19528.  
  19529.                                                         326
  19530.  
  19531.  
  19532.  
  19533.                                                                     15.5. PCHAR FUNCTIONS
  19534.  
  19535.  
  19536.                 StrDispose
  19537. Declaration: Procedure StrDispose(var Str: PChar);
  19538.  
  19539. Description: StrDispose frees any memory allocated for Str. This function will only function
  19540.                 correctly if Str has been allocated using StrAlloc (326) from the SYSUTILS unit.
  19541.  
  19542.      Errors: If an invalid pointer is passed, or a pointer not allocated with StrAlloc, an error
  19543.                 may occur.
  19544.  
  19545.    See also: StrBufSize (326), StrAlloc (326), StrDispose (281)
  19546.  
  19547.                 For an example, see StrBufSize (326).
  19548.  
  19549.  
  19550.                 StrPCopy
  19551. Declaration: Function StrPCopy(Dest: PChar; Source: string): PChar;
  19552.  
  19553. Description: StrPCopy Converts the Ansistring in Source to a Null-terminated string, and
  19554.                 copies it to Dest. Dest needs enough room to contain the string Source, i.e.
  19555.                 Length(Source)+1 bytes.
  19556.  
  19557.      Errors: No checking is performed to see whether Dest points to enough memory to contain
  19558.                 Source.
  19559.  
  19560.    See also: StrPLCopy (327), StrPCopy (287)
  19561.  
  19562.                 For an example, see StrPCopy (287).
  19563.  
  19564.  
  19565.                 StrPLCopy
  19566. Declaration: Function StrPLCopy(Dest: PChar; Source: string; MaxLen: cardinal):
  19567.                 PChar;
  19568.  
  19569. Description: StrPLCopy Converts maximally MaxLen characters of the Ansistring in Source to
  19570.                 a Null-terminated string, and copies it to Dest. Dest needs enough room to contain
  19571.                 the characters.
  19572.  
  19573.      Errors: No checking is performed to see whether Dest points to enough memory to contain
  19574.                 L characters of Source.
  19575.  
  19576.      Errors:
  19577.  
  19578.    See also: StrPCopy (327).
  19579.  
  19580.  
  19581.                 StrPas
  19582. Declaration: Function StrPas(Str: PChar): string;
  19583.  
  19584. Description: Converts a null terminated string in Str to an Ansitring, and returns this string.
  19585.                 This string is NOT truncated at 255 characters as is the
  19586.  
  19587.      Errors: None.
  19588.  
  19589.    See also: StrPas (287).
  19590.  
  19591.                 For an example, see StrPas (287).
  19592.  
  19593.                                                          327
  19594.  
  19595.  
  19596.  
  19597.                                                             15.6. STRING HANDLING FUNCTIONS
  19598.  
  19599.  
  19600.            15.6 String handling functions
  19601.  
  19602.            AdjustLineBreaks
  19603. Declaration: Function AdjustLineBreaks(const S: string): string;
  19604.  
  19605. Description: AdjustLineBreaks will change all #13 characters with #13#10 on Windows NT
  19606.            and dos. On linux, all #13#10 character pairs are converted to #10 and single #13
  19607.            characters also.
  19608.  
  19609.     Errors: None.
  19610.  
  19611.   See also: AnsiCompareStr (328), AnsiCompareText (329)
  19612.  
  19613.            Program Example48 ;
  19614.  
  19615.            { This program demonstrates the A d j u s t L i n eBr e a k s f u n c t i o n }
  19616.  
  19617.            Uses s y s u t i l s ;
  19618.  
  19619.            Const
  19620.               S = ' This i s a s t r i n g ' #13' with embedded ' #10' l i n e f e e d and ' +
  19621.                          #13' CR c h a r a c t e r s ' ;
  19622.  
  19623.            Begin
  19624.               Writeln ( A d ju s t Li n eB r e a k s ( S ) ) ;
  19625.            End.
  19626.  
  19627.  
  19628.            AnsiCompareStr
  19629. Declaration: Function AnsiCompareStr(const S1, S2: string): integer;
  19630.  
  19631. Description: AnsiCompareStr compares two strings and returns the following result:
  19632.  
  19633.            í0if S1<S2.
  19634.            0if S1=S2.
  19635.            ┐0if S1>S2.
  19636.  
  19637.            the comparision takes into account Ansi characters, i.e. it takes care of strange
  19638.            accented characters. Contrary to AnsiCompareText (329), the comparision is case
  19639.            sensitive.
  19640.  
  19641.     Errors: None.
  19642.  
  19643.   See also: AdjustLineBreaks (328), AnsiCompareText (329)
  19644.  
  19645.            Program Example49 ;
  19646.  
  19647.            { This program demonstrates the AnsiCompareStr f u n c t i o n }
  19648.            {$H+}
  19649.  
  19650.            Uses s y s u t i l s ;
  19651.  
  19652.            Procedure T e s t I t ( S1 , S2 : String ) ;
  19653.  
  19654.  
  19655.  
  19656.                                                             328
  19657.  
  19658.  
  19659.  
  19660.                                                                  15.6. STRING HANDLING FUNCTIONS
  19661.  
  19662.  
  19663.                 Var R : Longint ;
  19664.  
  19665.                 begin
  19666.                    R:= AnsiCompareStr ( S1 , S2 ) ;
  19667.                    Write ( ' " ' , S1 , '" i s ' ) ;
  19668.                    I f R<0 then
  19669.                          write ( ' l e s s than ' )
  19670.                    else I f R=0 then
  19671.                          Write ( ' equal to ' )
  19672.                    else
  19673.                          Write ( ' l a r g e r than ' ) ;
  19674.                    Writeln ( ' " ' , S2 , ' " ' ) ;
  19675.                 end ;
  19676.  
  19677.                 Begin
  19678.                    T e s t i t ( ' One s t r i n g ' , ' One s m a l l e r s t r i n g ' ) ;
  19679.                    T e s t i t ( ' One s t r i n g ' , ' one s t r i n g ' ) ;
  19680.                    T e s t i t ( ' One s t r i n g ' , ' One s t r i n g ' ) ;
  19681.                    T e s t i t ( ' One s t r i n g ' , ' One t a l l s t r i n g ' ) ;
  19682.                 End.
  19683.  
  19684.  
  19685.            AnsiCompareText
  19686. Declaration: Function AnsiCompareText(const S1, S2: string): integer;
  19687.  
  19688. Description:
  19689.  
  19690. Description: AnsiCompareText compares two strings and returns the following result:
  19691.  
  19692.            í0if S1<S2.
  19693.            0if S1=S2.
  19694.            ┐0if S1>S2.
  19695.  
  19696.            the comparision takes into account Ansi characters, i.e. it takes care of strange
  19697.            accented characters. Contrary to AnsiCompareStr (328), the comparision is case
  19698.            insensitive.
  19699.  
  19700.      Errors: None.
  19701.  
  19702.    See also: AdjustLineBreaks (328), AnsiCompareText (329)
  19703.  
  19704.                 Program Example49 ;
  19705.  
  19706.                 { This program demonstrates the AnsiCompareText f u n c t i o n }
  19707.                 {$H+}
  19708.  
  19709.                 Uses s y s u t i l s ;
  19710.  
  19711.                 Procedure T e s t I t ( S1 , S2 : String ) ;
  19712.  
  19713.                 Var R : Longint ;
  19714.  
  19715.                 begin
  19716.                    R:=AnsiCompareText ( S1 , S2 ) ;
  19717.  
  19718.  
  19719.                                                                   329
  19720.  
  19721.  
  19722.  
  19723.                                                             15.6. STRING HANDLING FUNCTIONS
  19724.  
  19725.  
  19726.               Write ( ' " ' , S1 , '" i s ' ) ;
  19727.               I f R<0 then
  19728.                     write ( ' l e s s than ' )
  19729.               else I f R=0 then
  19730.                     Write ( ' equal to ' )
  19731.               else
  19732.                     Write ( ' l a r g e r than ' ) ;
  19733.               Writeln ( ' " ' , S2 , ' " ' ) ;
  19734.            end ;
  19735.  
  19736.            Begin
  19737.               T e s t i t ( ' One s t r i n g ' , ' One s m a l l e r s t r i n g ' ) ;
  19738.               T e s t i t ( ' One s t r i n g ' , ' one s t r i n g ' ) ;
  19739.               T e s t i t ( ' One s t r i n g ' , ' One s t r i n g ' ) ;
  19740.               T e s t i t ( ' One s t r i n g ' , ' One t a l l s t r i n g ' ) ;
  19741.            End.
  19742.  
  19743.  
  19744.            AnsiExtractQuotedStr
  19745. Declaration: Function AnsiExtractQuotedStr(var Src: PChar; Quote: Char): string;
  19746.  
  19747. Description: AnsiExtractQuotedStr Returns Src as a string,, with Quute characters removed
  19748.            from the beginning and end of the string, and double Quote characters replaced by
  19749.            a single Quote characters. As such, it revereses the action of AnsiQuotedStr (331).
  19750.  
  19751.      Errors: None.
  19752.  
  19753.    See also: AnsiQuotedStr (331)
  19754.  
  19755.            Program Example51 ;
  19756.  
  19757.            { This program demonstrates the AnsiQuotedStr f u n c t i o n }
  19758.  
  19759.            Uses s y s u t i l s ;
  19760.  
  19761.            Var S : A n s i S t r i n g ;
  19762.  
  19763.            Begin
  19764.               S:= ' He s a i d " Hello " and walked on ' ;
  19765.               S:= AnsiQuotedStr ( Pchar ( S ) , ' " ' ) ;
  19766.               Writeln ( S ) ;
  19767.               Writeln ( AnsiExtractQuotedStr ( Pchar ( S ) , ' " ' ) ) ;
  19768.            End.
  19769.  
  19770.  
  19771.            AnsiLastChar
  19772. Declaration: Function AnsiLastChar(const S: string): PChar;
  19773.  
  19774. Description: This function returns a pointer to the last character of S. Since multibyte charac-
  19775.            ters are not yet supported, this is the same as @S[Length(S)]).
  19776.  
  19777.      Errors: None.
  19778.  
  19779.    See also: AnsiStrLastChar (333)
  19780.  
  19781.  
  19782.                                                              330
  19783.  
  19784.  
  19785.  
  19786.                                                                15.6. STRING HANDLING FUNCTIONS
  19787.  
  19788.  
  19789.            Program Example52 ;
  19790.  
  19791.            { This program demonstrates the AnsiLastChar f u n c t i o n }
  19792.  
  19793.            Uses s y s u t i l s ;
  19794.  
  19795.            Var S : A n s i S t r i n g ;
  19796.                     L : Longint ;
  19797.  
  19798.            Begin
  19799.               S:= ' This i s an a n s i s t r i n g . ' ;
  19800.               Writeln ( ' Last c h a r a c t e r of S i s : ' , AnsiLastChar ( S ) ) ;
  19801.               L:= Longint ( AnsiLastChar ( S))- Longint ( @S[ 1 ] ) + 1 ;
  19802.               Writeln ( ' Length of S i s : ' , L ) ;
  19803.            End.
  19804.  
  19805.  
  19806.            AnsiLowerCase
  19807. Declaration: Function AnsiLowerCase(const s: string): string;
  19808. Description: AnsiLowerCase converts the string S to lowercase characters and returns the re-
  19809.            sulting string. It takes into account the operating system language settings when
  19810.            doing this, so spcial characters are converted correctly as well.
  19811.            Remark On linux, no language setting is taken in account yet.
  19812.     Errors: None.
  19813.   See also: AnsiUpperCase (337), AnsiStrLower (336), AnsiStrUpper (336)
  19814.            Program Example53 ;
  19815.  
  19816.            { This program demonstrates the AnsiLowerCase f u n c t i o n }
  19817.  
  19818.            Uses s y s u t i l s ;
  19819.  
  19820.            Procedure T e s t i t ( S : String ) ;
  19821.  
  19822.            begin
  19823.             Writeln ( S , ' -> ' , AnsiLowerCase ( S ))
  19824.            end ;
  19825.  
  19826.            Begin
  19827.               T e s t i t ( ' AN UPPERCASE STRING ' ) ;
  19828.               T e s t i t ( ' Some mixed STring ' ) ;
  19829.               T e s t i t ( ' a l o w e r c a s e s t r i n g ' ) ;
  19830.            End.
  19831.  
  19832.  
  19833.            AnsiQuotedStr
  19834. Declaration: Function AnsiQuotedStr(const S: string; Quote: char): string;
  19835. Description: AnsiQuotedString quotes the string S and returns the result. This means that
  19836.            it puts the Quote character at both the beginning and end of the string and re-
  19837.            places any occurrence of Quote in S with 2 Quote characters. The action of
  19838.            AnsiQuotedString can be reversed by AnsiExtractQuotedStr (330).
  19839.  
  19840.                                                                331
  19841.  
  19842.  
  19843.  
  19844.                                                             15.6. STRING HANDLING FUNCTIONS
  19845.  
  19846.  
  19847.      Errors: None.
  19848.  
  19849.   See also: AnsiExtractQuotedStr (330)
  19850.  
  19851.            For an example, see AnsiExtractQuotedStr (330)
  19852.  
  19853.  
  19854.            AnsiStrComp
  19855. Declaration: Function AnsiStrComp(S1, S2: PChar): integer;
  19856.  
  19857. Description: AnsiStrComp compares 2 PChar strings, and returns the following result:
  19858.  
  19859.            í0if S1<S2.
  19860.            0if S1=S2.
  19861.            ┐0if S1>S2.
  19862.  
  19863.            The comparision of the two strings is case-sensitive. The function does not yet take
  19864.            internationalization settings into account.
  19865.  
  19866.      Errors: None.
  19867.  
  19868.   See also: AnsiCompareText (329), AnsiCompareStr (328)
  19869.  
  19870.            Program Example54 ;
  19871.  
  19872.            { This program demonstrates the AnsiStrComp f u n c t i o n }
  19873.  
  19874.            Uses s y s u t i l s ;
  19875.  
  19876.            Procedure T e s t I t ( S1 , S2 : Pchar ) ;
  19877.  
  19878.            Var R : Longint ;
  19879.  
  19880.            begin
  19881.               R:= AnsiStrComp ( S1 , S2 ) ;
  19882.               Write ( ' " ' , S1 , '" i s ' ) ;
  19883.               I f R<0 then
  19884.                     write ( ' l e s s than ' )
  19885.               else I f R=0 then
  19886.                     Write ( ' equal to ' )
  19887.               else
  19888.                     Write ( ' l a r g e r than ' ) ;
  19889.               Writeln ( ' " ' , S2 , ' " ' ) ;
  19890.            end ;
  19891.  
  19892.            Begin
  19893.               T e s t i t ( ' One s t r i n g ' , ' One s m a l l e r s t r i n g ' ) ;
  19894.               T e s t i t ( ' One s t r i n g ' , ' one s t r i n g ' ) ;
  19895.               T e s t i t ( ' One s t r i n g ' , ' One s t r i n g ' ) ;
  19896.               T e s t i t ( ' One s t r i n g ' , ' One t a l l s t r i n g ' ) ;
  19897.            End.
  19898.  
  19899.  
  19900.  
  19901.  
  19902.  
  19903.                                                              332
  19904.  
  19905.  
  19906.  
  19907.                                                             15.6. STRING HANDLING FUNCTIONS
  19908.  
  19909.  
  19910.            AnsiStrIComp
  19911. Declaration: Function AnsiStrIComp(S1, S2: PChar): integer;
  19912.  
  19913. Description: AnsiStrIComp compares 2 PChar strings, and returns the following result:
  19914.  
  19915.            í0if S1<S2.
  19916.            0if S1=S2.
  19917.            ┐0if S1>S2.
  19918.  
  19919.            The comparision of the two strings is case-insensitive. The function does not yet
  19920.            take internationalization settings into account.
  19921.  
  19922.     Errors: None.
  19923.  
  19924.   See also: AnsiCompareText (329), AnsiCompareStr (328)
  19925.  
  19926.            Program Example55 ;
  19927.  
  19928.            { This program demonstrates the AnsiStrIComp f u n c t i o n }
  19929.  
  19930.            Uses s y s u t i l s ;
  19931.  
  19932.            Procedure T e s t I t ( S1 , S2 : Pchar ) ;
  19933.  
  19934.            Var R : Longint ;
  19935.  
  19936.            begin
  19937.               R:= AnsiStrIComp ( S1 , S2 ) ;
  19938.               Write ( ' " ' , S1 , '" i s ' ) ;
  19939.               I f R<0 then
  19940.                     write ( ' l e s s than ' )
  19941.               else I f R=0 then
  19942.                     Write ( ' equal to ' )
  19943.               else
  19944.                     Write ( ' l a r g e r than ' ) ;
  19945.               Writeln ( ' " ' , S2 , ' " ' ) ;
  19946.            end ;
  19947.  
  19948.            Begin
  19949.               T e s t i t ( ' One s t r i n g ' , ' One s m a l l e r s t r i n g ' ) ;
  19950.               T e s t i t ( ' One s t r i n g ' , ' one s t r i n g ' ) ;
  19951.               T e s t i t ( ' One s t r i n g ' , ' One s t r i n g ' ) ;
  19952.               T e s t i t ( ' One s t r i n g ' , ' One t a l l s t r i n g ' ) ;
  19953.            End.
  19954.  
  19955.  
  19956.            AnsiStrLastChar
  19957. Declaration: function AnsiStrLastChar(Str: PChar): PChar;
  19958.  
  19959. Declaration: AnsiStrLastChar returns a pointer to the last character of Str. Since
  19960.            multibyte characters are not yet supported, this is the same as StrEnd(Str)-1.
  19961.  
  19962.     Errors: None.
  19963.  
  19964.   See also: AnsiLastChar (330)
  19965.  
  19966.                                                              333
  19967.  
  19968.  
  19969.  
  19970.                                                        15.6. STRING HANDLING FUNCTIONS
  19971.  
  19972.  
  19973.            Program Example58 ;
  19974.  
  19975.            { This program demonstrates the AnsiStrLastChar f u n c t i o n }
  19976.  
  19977.            Uses s y s u t i l s ;
  19978.  
  19979.            Var P : Pchar ;
  19980.                    L : Longint ;
  19981.  
  19982.            Begin
  19983.               P:= ' This i s an PChar s t r i n g . ' ;
  19984.               Writeln ( ' Last c h a r a c t e r of P i s : ' , AnsiStrLas tChar (P) ) ;
  19985.               L:= Longint ( AnsiStrLastChar (P))- Longint (P)+1;
  19986.               Writeln ( ' Length of P ( ' , P, ' ) i s : ' , L ) ;
  19987.            End.
  19988.  
  19989.  
  19990.            AnsiStrLComp
  19991. Declaration: Function AnsiStrLComp(S1, S2: PChar; MaxLen: cardinal): integer;
  19992.  
  19993. Description: AnsiStrLComp compares the first Maxlen characters of 2 PChar strings, S1 and S2,
  19994.            and returns the following result:
  19995.  
  19996.            í0if S1<S2.
  19997.            0if S1=S2.
  19998.            ┐0if S1>S2.
  19999.  
  20000.            The comparision of the two strings is case-sensitive. The function does not yet take
  20001.            internationalization settings into account.
  20002.  
  20003.      Errors: None.
  20004.  
  20005.    See also: AnsiCompareText (329), AnsiCompareStr (328)
  20006.  
  20007.            Program Example56 ;
  20008.  
  20009.            { This program demonstrates the AnsiStrLComp f u n c t i o n }
  20010.  
  20011.            Uses s y s u t i l s ;
  20012.  
  20013.            Procedure T e s t I t ( S1 , S2 : Pchar ; L : l o n g i n t ) ;
  20014.  
  20015.            Var R : Longint ;
  20016.  
  20017.            begin
  20018.               R:= AnsiStrLComp ( S1 , S2 , L ) ;
  20019.               Write ( ' F i r s t ' , L , ' c h a r a c t e r s of "' , S1 , '" are ' ) ;
  20020.               I f R<0 then
  20021.                    write ( ' l e s s than ' )
  20022.               else I f R=0 then
  20023.                    Write ( ' equal to ' )
  20024.               else
  20025.                    Write ( ' l a r g e r than ' ) ;
  20026.               Writeln ( ' those of "' , S2 , ' " ' ) ;
  20027.  
  20028.                                                        334
  20029.  
  20030.  
  20031.  
  20032.                                                              15.6. STRING HANDLING FUNCTIONS
  20033.  
  20034.  
  20035.           end ;
  20036.  
  20037.            Begin
  20038.               T e s t i t ( ' One s t r i n g ' , ' One s m a l l e r s t r i n g ' , 2 5 5 ) ;
  20039.               T e s t i t ( ' One s t r i n g ' , ' One S t r i n g ' , 4 ) ;
  20040.               T e s t i t ( ' One s t r i n g ' , '1 s t r i n g ' , 0 ) ;
  20041.               T e s t i t ( ' One s t r i n g ' , ' One s t r i n g . ' , 9 ) ;
  20042.           End.
  20043.  
  20044.  
  20045.           AnsiStrLIComp
  20046. Declaration: Function AnsiStrLIComp(S1, S2: PChar; MaxLen: cardinal): integer;
  20047. Description: AnsiStrLIComp compares the first Maxlen characters of 2 PChar strings, S1 and
  20048.           S2, and returns the following result:
  20049.           í0if S1<S2.
  20050.           0if S1=S2.
  20051.           ┐0if S1>S2.
  20052.           The comparision of the two strings is case-insensitive. The function does not yet
  20053.           take internationalization settings into account.
  20054.     Errors: None.
  20055.   See also: AnsiCompareText (329), AnsiCompareStr (328)
  20056.  
  20057.           Program Example57 ;
  20058.  
  20059.            { This program demonstrates the AnsiStrLIComp f u n c t i o n }
  20060.  
  20061.            Uses s y s u t i l s ;
  20062.  
  20063.            Procedure T e s t I t ( S1 , S2 : Pchar ; L : l o n g i n t ) ;
  20064.  
  20065.           Var R : Longint ;
  20066.  
  20067.            begin
  20068.               R:= AnsiStrLIComp ( S1 , S2 , L ) ;
  20069.               Write ( ' F i r s t ' , L , ' c h a r a c t e r s of "' , S1 , '" are ' ) ;
  20070.               I f R<0 then
  20071.                    write ( ' l e s s than ' )
  20072.               else I f R=0 then
  20073.                    Write ( ' equal to ' )
  20074.               else
  20075.                    Write ( ' l a r g e r than ' ) ;
  20076.               Writeln ( ' those of "' , S2 , ' " ' ) ;
  20077.           end ;
  20078.  
  20079.            Begin
  20080.               T e s t i t ( ' One s t r i n g ' , ' One s m a l l e r s t r i n g ' , 2 5 5 ) ;
  20081.               T e s t i t ( ' ONE STRING ' , ' one S t r i n g ' , 4 ) ;
  20082.               T e s t i t ( ' One s t r i n g ' , '1 STRING ' , 0 ) ;
  20083.               T e s t i t ( ' One STRING ' , ' one s t r i n g . ' , 9 ) ;
  20084.           End.
  20085.  
  20086.                                                               335
  20087.  
  20088.  
  20089.  
  20090.                                                              15.6. STRING HANDLING FUNCTIONS
  20091.  
  20092.  
  20093.           AnsiStrLower
  20094. Declaration: Function AnsiStrLower(Str: PChar): PChar;
  20095.  
  20096. Description: AnsiStrLower converts the PChar Str to lowercase characters and returns the
  20097.           resulting pchar. Note that Str itself is modified, not a copy, as in the case of
  20098.           AnsiLowerCase (331). It takes into account the operating system language settings
  20099.           when doing this, so spcial characters are converted correctly as well.
  20100.           Remark On linux, no language setting is taken in account yet.
  20101.  
  20102.     Errors: None.
  20103.  
  20104.   See also: AnsiStrUpper (336), AnsiLowerCase (331)
  20105.  
  20106.           Program Example59 ;
  20107.  
  20108.           { This program demonstrates the AnsiStrLower f u n c t i o n }
  20109.  
  20110.           Uses s y s u t i l s ;
  20111.  
  20112.           Procedure T e s t i t ( S : Pchar ) ;
  20113.  
  20114.           begin
  20115.             Writeln ( S , ' -> ' , AnsiStrLower ( S ))
  20116.           end ;
  20117.  
  20118.           Begin
  20119.              T e s t i t ( ' AN UPPERCASE STRING ' ) ;
  20120.              T e s t i t ( ' Some mixed STring ' ) ;
  20121.              T e s t i t ( ' a l o w er c a s e s t r i n g ' ) ;
  20122.           End.
  20123.  
  20124.  
  20125.           AnsiStrUpper
  20126. Declaration: Function AnsiStrUpper(Str: PChar): PChar;
  20127.  
  20128. Description: AnsiStrUpper converts the PChar Str to uppercase characters and returns the
  20129.           resulting string. Note that Str itself is modified, not a copy, as in the case of
  20130.           AnsiUpperCase (337). It takes into account the operating system language settings
  20131.           when doing this, so spcial characters are converted correctly as well.
  20132.           Remark On linux, no language setting is taken in account yet.
  20133.  
  20134.     Errors: None.
  20135.  
  20136.   See also: AnsiUpperCase (337), AnsiStrLower (336), AnsiLowerCase (331)
  20137.  
  20138.           Program Example60 ;
  20139.  
  20140.           { This program demonstrates the AnsiStrUpper f u n c t i o n }
  20141.  
  20142.           Uses s y s u t i l s ;
  20143.  
  20144.           Procedure T e s t i t ( S : Pchar ) ;
  20145.  
  20146.           begin
  20147.  
  20148.                                                              336
  20149.  
  20150.  
  20151.  
  20152.                                                               15.6. STRING HANDLING FUNCTIONS
  20153.  
  20154.  
  20155.             Writeln ( S , ' -> ' , AnsiStrUpper ( S ))
  20156.           end ;
  20157.  
  20158.           Begin
  20159.              T e s t i t ( ' AN UPPERCASE STRING ' ) ;
  20160.              T e s t i t ( ' Some mixed STring ' ) ;
  20161.              T e s t i t ( ' a l o w e r c a s e s t r i n g ' ) ;
  20162.           End.
  20163.  
  20164.  
  20165.           AnsiUpperCase
  20166. Declaration: Function AnsiUpperCase(const s: string): string;
  20167.  
  20168. Description: AnsiUpperCase converts the string S to uppercase characters and returns the
  20169.           resulting string. It takes into account the operating system language settings when
  20170.           doing this, so spcial characters are converted correctly as well.
  20171.           Remark On linux, no language setting is taken in account yet.
  20172.  
  20173.     Errors: None.
  20174.  
  20175.   See also: AnsiStrUpper (336), AnsiStrLower (336), AnsiLowerCase (331)
  20176.  
  20177.           Program Example60 ;
  20178.  
  20179.            { This program demonstrates the AnsiUpperCase f u n c t i o n }
  20180.  
  20181.           Uses s y s u t i l s ;
  20182.  
  20183.            Procedure T e s t i t ( S : String ) ;
  20184.  
  20185.            begin
  20186.             Writeln ( S , ' -> ' , AnsiUpperCase ( S ))
  20187.           end ;
  20188.  
  20189.           Begin
  20190.              T e s t i t ( ' AN UPPERCASE STRING ' ) ;
  20191.              T e s t i t ( ' Some mixed STring ' ) ;
  20192.              T e s t i t ( ' a l o w e r c a s e s t r i n g ' ) ;
  20193.           End.
  20194.  
  20195.  
  20196.           AppendStr
  20197. Declaration: Procedure AppendStr(var Dest: String; const S: string);
  20198.  
  20199. Description: AppendStr appends S to Dest.
  20200.           This function is provided for Delphi compatibility only, since it is completely equiv-
  20201.           alent to Dest:=Dest+S.
  20202.  
  20203.     Errors: None.
  20204.  
  20205.   See also: AssignStr (338),NewStr (206), DisposeStr (207)
  20206.  
  20207.  
  20208.  
  20209.  
  20210.                                                               337
  20211.  
  20212.  
  20213.  
  20214.                                                              15.6. STRING HANDLING FUNCTIONS
  20215.  
  20216.  
  20217.            Program Example62 ;
  20218.  
  20219.            { This program demonstrates the AppendStr f u n c t i o n }
  20220.  
  20221.            Uses s y s u t i l s ;
  20222.  
  20223.            Var S : A n s i S t r i n g ;
  20224.  
  20225.            Begin
  20226.               S:= ' This i s an ' ;
  20227.               AppendStr ( S , ' A n s i S t r i n g ' ) ;
  20228.               Writeln ( ' S = "' , S , ' " ' ) ;
  20229.            End.
  20230.  
  20231.  
  20232.            AssignStr
  20233. Declaration: Procedure AssignStr(var P: PString; const S: string);
  20234.  
  20235. Description: AssignStr allocates S to P. The old value of P is disposed of.
  20236.            This function is provided for Delphi compatibility only. AnsiStrings are managed
  20237.            on the heap and should be preferred to the mechanism of dynamically allocated
  20238.            strings.
  20239.  
  20240.      Errors: None.
  20241.  
  20242.    See also: NewStr (206), AppendStr (337), DisposeStr (207)
  20243.  
  20244.            Program Example63 ;
  20245.  
  20246.            { This program demonstrates the A s s i g n S t r f u n c t i o n }
  20247.            {$H+}
  20248.  
  20249.            Uses s y s u t i l s ;
  20250.  
  20251.            Var P : PString ;
  20252.  
  20253.            Begin
  20254.              P:=NewStr( ' A f i r s t A n s i S t r i n g ' ) ;
  20255.              Writeln ( ' Before : P = "' , P , ' " ' ) ;
  20256.              A s s i g n S t r (P, ' A Second a n s i s t r i n g ' ) ;
  20257.              Writeln ( ' After : P = "' , P , ' " ' ) ;
  20258.              DisposeStr (P) ;
  20259.            End.
  20260.  
  20261.  
  20262.            BCDToInt
  20263. Declaration: Function BCDToInt(Value: integer): integer;
  20264.  
  20265. Description: BCDToInt converts a BCD coded integer to a normal integer.
  20266.  
  20267.      Errors: None.
  20268.  
  20269.    See also: StrToInt (356), IntToStr (352)
  20270.  
  20271.  
  20272.                                                              338
  20273.  
  20274.  
  20275.  
  20276.                                                         15.6. STRING HANDLING FUNCTIONS
  20277.  
  20278.  
  20279.                 Program Example64 ;
  20280.  
  20281.                 { This program demonstrates the BCDToInt f u n c t i o n }
  20282.  
  20283.                 Uses s y s u t i l s ;
  20284.  
  20285.                 Procedure T e s t i t ( L : l o n g i n t ) ;
  20286.                 begin
  20287.                      Writeln ( L , ' -> ' , BCDToInt ( L ) ) ;
  20288.                 end ;
  20289.  
  20290.                 Begin
  20291.                      T e s t i t ( 1 0 ) ;
  20292.                      T e s t i t ( 1 0 0 ) ;
  20293.                      T e s t i t (1000);
  20294.                 End.
  20295.  
  20296.  
  20297.                 CompareMem
  20298. Declaration: Function CompareMem(P1, P2: Pointer; Length: cardinal): integer;
  20299.  
  20300. Description: CompareMem compares, byte by byte, 2 memory areas pointed to by P1 and P2, for
  20301.                 a length of L bytes.
  20302.                 It returns the following values:
  20303.  
  20304.                 í0if at some position the byte at P1 is less than the byte at the same postion at P2.
  20305.                 0if all L bytes are the same.
  20306.                 3
  20307.  
  20308.      Errors:
  20309.  
  20310.   See also:
  20311.  
  20312.  
  20313.                 CompareStr
  20314. Declaration: Function CompareStr(const S1, S2: string): Integer;
  20315.  
  20316. Description: CompareStr compares two strings, S1 and S2, and returns the following result:
  20317.  
  20318.                 í0if S1<S2.
  20319.                 0if S1=S2.
  20320.                 ┐0if S1>S2.
  20321.  
  20322.                 The comparision of the two strings is case-sensitive. The function does not take
  20323.                 internationalization settings into account, it simply compares ASCII values.
  20324.  
  20325.      Errors: None.
  20326.  
  20327.   See also: AnsiCompareText (329), AnsiCompareStr (328), CompareText (340)
  20328.  
  20329.                 Program Example65 ;
  20330.  
  20331.                 { This program demonstrates the CompareStr f u n c t i o n }
  20332.                 {$H+}
  20333.  
  20334.                                                          339
  20335.  
  20336.  
  20337.  
  20338.                                                             15.6. STRING HANDLING FUNCTIONS
  20339.  
  20340.  
  20341.  
  20342.            Uses s y s u t i l s ;
  20343.  
  20344.            Procedure T e s t I t ( S1 , S2 : String ) ;
  20345.  
  20346.            Var R : Longint ;
  20347.  
  20348.            begin
  20349.               R:= CompareStr ( S1 , S2 ) ;
  20350.               Write ( ' " ' , S1 , '" i s ' ) ;
  20351.               I f R<0 then
  20352.                     write ( ' l e s s than ' )
  20353.               else I f R=0 then
  20354.                     Write ( ' equal to ' )
  20355.               else
  20356.                     Write ( ' l a r g e r than ' ) ;
  20357.               Writeln ( ' " ' , S2 , ' " ' ) ;
  20358.            end ;
  20359.  
  20360.            Begin
  20361.               T e s t i t ( ' One s t r i n g ' , ' One s m a l l e r s t r i n g ' ) ;
  20362.               T e s t i t ( ' One s t r i n g ' , ' one s t r i n g ' ) ;
  20363.               T e s t i t ( ' One s t r i n g ' , ' One s t r i n g ' ) ;
  20364.               T e s t i t ( ' One s t r i n g ' , ' One t a l l s t r i n g ' ) ;
  20365.            End.
  20366.  
  20367.  
  20368.            CompareText
  20369. Declaration: Function CompareText(const S1, S2: string): integer;
  20370.  
  20371. Description: CompareText compares two strings, S1 and S2, and returns the following result:
  20372.  
  20373.            í0if S1<S2.
  20374.            0if S1=S2.
  20375.            ┐0if S1>S2.
  20376.  
  20377.            The comparision of the two strings is case-insensitive. The function does not take
  20378.            internationalization settings into account, it simply compares ASCII values.
  20379.  
  20380.      Errors: None.
  20381.  
  20382.   See also: AnsiCompareText (329), AnsiCompareStr (328), CompareStr (339)
  20383.  
  20384.            Program Example66 ;
  20385.  
  20386.            { This program demonstrates the CompareText f u n c t i o n }
  20387.            {$H+}
  20388.  
  20389.            Uses s y s u t i l s ;
  20390.  
  20391.            Procedure T e s t I t ( S1 , S2 : String ) ;
  20392.  
  20393.            Var R : Longint ;
  20394.  
  20395.  
  20396.                                                              340
  20397.  
  20398.  
  20399.  
  20400.                                                             15.6. STRING HANDLING FUNCTIONS
  20401.  
  20402.  
  20403.            begin
  20404.               R:= CompareText ( S1 , S2 ) ;
  20405.               Write ( ' " ' , S1 , '" i s ' ) ;
  20406.               I f R<0 then
  20407.                     write ( ' l e s s than ' )
  20408.               else I f R=0 then
  20409.                     Write ( ' equal to ' )
  20410.               else
  20411.                     Write ( ' l a r g e r than ' ) ;
  20412.               Writeln ( ' " ' , S2 , ' " ' ) ;
  20413.            end ;
  20414.  
  20415.            Begin
  20416.               T e s t i t ( ' One s t r i n g ' , ' One s m a l l e r s t r i n g ' ) ;
  20417.               T e s t i t ( ' One s t r i n g ' , ' one s t r i n g ' ) ;
  20418.               T e s t i t ( ' One s t r i n g ' , ' One s t r i n g ' ) ;
  20419.               T e s t i t ( ' One s t r i n g ' , ' One t a l l s t r i n g ' ) ;
  20420.            End.
  20421.  
  20422.  
  20423.            DisposeStr
  20424. Declaration: Procedure DisposeStr(S: PString);
  20425.  
  20426. Description: DisposeStr removes the dynamically allocated string S from the heap, and releases
  20427.            the occupied memory.
  20428.            This function is provided for Delphi compatibility only. AnsiStrings are managed
  20429.            on the heap and should be preferred to the mechanism of dynamically allocated
  20430.            strings.
  20431.  
  20432.      Errors: None.
  20433.  
  20434.    See also: NewStr (206), AppendStr (337), AssignStr (338)
  20435.  
  20436.            For an example, see DisposeStr (207).
  20437.  
  20438.  
  20439.            FloatToStr
  20440. Declaration: Function FloatToStr(Value: Extended): String;
  20441.  
  20442. Description: FloatToStr converts the floating point variable Value to a string representation.
  20443.            It will choose the shortest possible notation of the two following formats:
  20444.  
  20445.            Fixed formatwill represent the string in fixed notation,
  20446.            Decimal formatwill represent the string in scientific notation.
  20447.  
  20448.            (more information on these formats can be found in FloatToStrF (342)) FloatToStr
  20449.            is completely equivalent to a FloatToStrF(Value, ffGeneral, 15, 0); call.
  20450.  
  20451.      Errors: None.
  20452.  
  20453.    See also: FloatToStrF (342)
  20454.  
  20455.  
  20456.  
  20457.  
  20458.  
  20459.                                                              341
  20460.  
  20461.  
  20462.  
  20463.                                                        15.6. STRING HANDLING FUNCTIONS
  20464.  
  20465.  
  20466.            Program Example67 ;
  20467.  
  20468.            { This program demonstrates the FloatToStr f u n c t i o n }
  20469.  
  20470.            Uses s y s u t i l s ;
  20471.  
  20472.            Procedure T e s t i t ( Value : Extended ) ;
  20473.  
  20474.            begin
  20475.               Writeln ( Value , ' -> ' , FloatToStr ( Value ) ) ;
  20476.               Writeln (- Value , ' -> ' , FloatToStr (-Value ) ) ;
  20477.            end ;
  20478.  
  20479.            Begin
  20480.               T e s t i t ( 0 . 0 ) ;
  20481.               T e s t i t ( 1 . 1 ) ;
  20482.               T e s t i t ( 1 . 1 e -3);
  20483.               T e s t i t ( 1 . 1 e -20);
  20484.               T e s t i t ( 1 . 1 e -200);
  20485.               T e s t i t ( 1 . 1 e +3);
  20486.               T e s t i t ( 1 . 1 e +20);
  20487.               T e s t i t ( 1 . 1 e +200);
  20488.            End.
  20489.  
  20490.  
  20491.            FloatToStrF
  20492. Declaration: Function FloatToStrF(Value: Extended; format: TFloatFormat; Precision,
  20493.            Digits: Integer): String;
  20494.  
  20495. Description: FloatToStrF converts the floating point number value to a string representation,
  20496.            according to the settings of the parameters Format, Precision and Digits.
  20497.            The meaning of the Precision and Digits parameter depends on the Format
  20498.            parameter. The format is controlled mainly by the Format parameter. It can have
  20499.            one of the following values:
  20500.  
  20501.             currencyMoney format. Value is converted to a string using the global variables
  20502.                     CurrencyString, CurrencyFormat and NegCurrencyFormat. The Digits
  20503.                     paramater specifies the number of digits following the decimal point and should
  20504.                     be in the range -1 to 18. If Digits equals -1, CurrencyDecimals is assumed.
  20505.                     The Precision parameter is ignored.
  20506.             ExponentScientific format. Value is converted to a string using scientific nota-
  20507.                     tion: 1 digit before the decimal point, possibly preceded by a minus sign if
  20508.                     Value is negative. The number of digits after the decimal point is controlled
  20509.                     by Precision and must lie in the range 0 to 15.
  20510.             FixedFixed point format. Value is converted to a string using fixed point no-
  20511.                     tation. The result is composed of all digits of the integer part of Value,
  20512.                     preceded by a minus sign if Value is negative. Following the integer part
  20513.                     is DecimalSeparator and then the fractional part of Value, rounded o  to
  20514.                     Digits numbers. If the number is too large then the result will be in scientific
  20515.                     notation.
  20516.             GeneralGeneral number format. The argument is converted to a string using
  20517.                     ffExponent or ffFixed format, depending on wich one gives the shortest
  20518.  
  20519.  
  20520.                                                        342
  20521.  
  20522.  
  20523.  
  20524.                                                         15.6. STRING HANDLING FUNCTIONS
  20525.  
  20526.  
  20527.                  string. There will be no trailing zeroes. If Value is less than 0.00001 or if the
  20528.                  number of decimals left of the decimal point is larger than Precision then
  20529.                  scientific notation is used, and Digits is the minimum number of digits in the
  20530.                  exponent. Otherwise Digits is ignored.
  20531.          numberIs the same as ffFixed, except that thousand separators are inserted in
  20532.                  the resultig string.
  20533.  
  20534.   Errors: None.
  20535.  
  20536. See also: FloatToStr (341), FloatToText (344)
  20537.  
  20538.         Program Example68 ;
  20539.  
  20540.         { This program demonstrates the FloatToStrF f u n c t i o n }
  20541.  
  20542.         Uses s y s u t i l s ;
  20543.  
  20544.         Const Fmt : Array [ TFloatFormat ] of stri ng [10] =
  20545.                          ( ' g e n e r a l ' , ' exponent ' , ' f i x e d ' , ' number ' , ' Currency ' ) ;
  20546.  
  20547.         Procedure T e s t i t ( Value :               Extended ) ;
  20548.  
  20549.         Var I , J : l o n g i n t ;
  20550.                  FF : TFloatFormat ;
  20551.  
  20552.         begin
  20553.            For I :=5 to 15 do
  20554.                  For J :=1 to 4 do
  20555.                     For FF:= f f g e n e r a l to f f c u r r e n c y do
  20556.                        begin
  20557.                        Write ( Value , ' ( Prec : ' , I : 2 , ' , Dig : ' , J , ' , fmt : ' , Fmt [ f f ] , ' ) : ' ) ;
  20558.                        Writeln ( FloatToStrf ( Value , FF , I , J ) ) ;
  20559.                        Write (- Value , ' ( Prec : ' , I : 2 , ' , Dig : ' , J , ' , fmt : ' , Fmt [ f f ] , ' ) : ' ) ;
  20560.                        Writeln ( FloatToStrf (-Value , FF , I , J ) ) ;
  20561.                        end ;
  20562.         end ;
  20563.  
  20564.         Begin
  20565.            T e s t i t ( 1 . 1 ) ;
  20566.            T e s t i t ( 1 . 1 E1 ) ;
  20567.            T e s t i t ( 1 . 1 E-1);
  20568.            T e s t i t ( 1 . 1 E5 ) ;
  20569.            T e s t i t ( 1 . 1 E-5);
  20570.            T e s t i t ( 1 . 1 E10 ) ;
  20571.            T e s t i t ( 1 . 1 E-10);
  20572.            T e s t i t ( 1 . 1 E15 ) ;
  20573.            T e s t i t ( 1 . 1 E-15);
  20574.            T e s t i t ( 1 . 1 E100 ) ;
  20575.            T e s t i t ( 1 . 1 E-100);
  20576.         End.
  20577.  
  20578.  
  20579.  
  20580.  
  20581.  
  20582.                                                          343
  20583.  
  20584.  
  20585.  
  20586.                                                            15.6. STRING HANDLING FUNCTIONS
  20587.  
  20588.  
  20589.            FloatToText
  20590. Declaration: Function FloatToText(Buffer : Pchar;Value: Extended; Format: TFloatFormat;
  20591.            Precision, Digits: Integer): Longint;
  20592.  
  20593. Description: FloatToText converts the floating point variable Value to a string representation
  20594.            and stores it in Buffer. The conversion is giverned by format, Precisison and
  20595.            Digits. more information on these parameters can be found in FloatToStrF (342).
  20596.            Buffer should point to enough space to hold the result. No checking on this is
  20597.            performed.
  20598.            The result is the number of characters that was copied in Buffer.
  20599.  
  20600.      Errors: None.
  20601.  
  20602.    See also: FloatToStr (341), FloatToStrF (342)
  20603.  
  20604.            Program Example68 ;
  20605.  
  20606.            { This program demonstrates the FloatToStrF f u n c t i o n }
  20607.  
  20608.            Uses s y s u t i l s ;
  20609.  
  20610.            Const Fmt : Array [ TFloatFormat ] of st ri ng [10] =
  20611.                             ( ' g e n e r a l ' , ' exponent ' , ' f i x e d ' , ' number ' , ' Currency ' ) ;
  20612.  
  20613.            Procedure T e s t i t ( Value :               Extended ) ;
  20614.  
  20615.            Var I , J : l o n g i n t ;
  20616.                     FF : TFloatFormat ;
  20617.                     S : S h o r t S t r i n g ;
  20618.  
  20619.            begin
  20620.               For I :=5 to 15 do
  20621.                     For J :=1 to 4 do
  20622.                        For FF:= f f g e n e r a l to f f c u r r e n c y do
  20623.                            begin
  20624.                            Write ( Value , ' ( Prec : ' , I : 2 , ' , Dig : ' , J , ' , fmt : ' , Fmt [ f f ] , ' ) : ' ) ;
  20625.                            SetLength ( S , FloatToText ( @S [ 1 ] , Value , FF , I , J ) ) ;
  20626.                            Writeln ( S ) ;
  20627.                            Write (- Value , ' ( Prec : ' , I : 2 , ' , Dig : ' , J , ' , fmt : ' , Fmt [ f f ] , ' ) : ' ) ;
  20628.                            SetLength ( S , FloatToText ( @S[1],- Value , FF , I , J ) ) ;
  20629.                            Writeln ( S ) ;
  20630.                           end ;
  20631.            end ;
  20632.  
  20633.            Begin
  20634.               T e s t i t ( 1 . 1 ) ;
  20635.               T e s t i t ( 1 . 1 E1 ) ;
  20636.               T e s t i t ( 1 . 1 E-1);
  20637.               T e s t i t ( 1 . 1 E5 ) ;
  20638.               T e s t i t ( 1 . 1 E-5);
  20639.               T e s t i t ( 1 . 1 E10 ) ;
  20640.               T e s t i t ( 1 . 1 E-10);
  20641.               T e s t i t ( 1 . 1 E15 ) ;
  20642.               T e s t i t ( 1 . 1 E-15);
  20643.  
  20644.                                                             344
  20645.  
  20646.  
  20647.  
  20648.                                                       15.6. STRING HANDLING FUNCTIONS
  20649.  
  20650.  
  20651.               T e s t i t ( 1 . 1 E100 ) ;
  20652.               T e s t i t ( 1 . 1 E-100);
  20653.            End.
  20654.  
  20655.  
  20656.            FmtStr
  20657. Declaration: Procedure (Var Res: String; Const Fmt : String; Const args: Array of
  20658.            const);
  20659.  
  20660. Description: FmtStr calls Format (345) with Fmt and Args as arguments, and stores the result
  20661.            in Res. For more information on how the resulting string is composed, see Format
  20662.            (345).
  20663.  
  20664.     Errors: In case of error, a EConvertError exception is raised.
  20665.  
  20666.   See also: Format (345), FormatBuf (351).
  20667.  
  20668.            Program Example70 ;
  20669.  
  20670.            { This program demonstrates the FmtStr f u n c t i o n }
  20671.  
  20672.            Uses s y s u t i l s ;
  20673.  
  20674.            Var S : A n s i S t r i n g ;
  20675.  
  20676.            Begin
  20677.               S:= ' ' ;
  20678.               FmtStr ( S , ' For some nice examples of fomatting see %s . ' , [ ' Format ' ] ) ;
  20679.               Writeln ( S ) ;
  20680.            End.
  20681.  
  20682.  
  20683.            Format
  20684. Declaration: Function Format(Const Fmt : String; const Args : Array of const) : String;
  20685.  
  20686. Description: Format replaces all placeholders inFmt with the arguments passed in Args and
  20687.            returns the resulting string. A placeholder looks as follows:
  20688.  
  20689.            '%' [Index':'] ['-'] [Width] ['.' Precision] ArgType
  20690.  
  20691.            elements between single quotes must be typed as shown without the quotes, and
  20692.            elements between square brackets [ ] are optional. The meaning of the di erent
  20693.            elements is shown below:
  20694.  
  20695.            '%'starts the placeholder. If you want to insert a literal % character, then you must
  20696.                    insert two of them : %%.
  20697.            Index ':'takes the Index-th element in the argument array as the element to insert.
  20698.            '-'tells Format to left-align the inserted text. The default behaviour is to right-align
  20699.                    inserted text. This can only take e ect if the Width element is also specified.
  20700.            Widththe inserted string must have at least have Width characters. If not, the
  20701.                    inserted string will be padded with spaces. By default, the string is left-
  20702.                    padded, resulting in a right-aligned string. This behaviour can be changed by
  20703.                    the '-' character.
  20704.  
  20705.                                                       345
  20706.  
  20707.  
  20708.  
  20709.                                         15.6. STRING HANDLING FUNCTIONS
  20710.  
  20711.  
  20712. '.' PrecisionIndicates the precision to be used when converting the argument. The
  20713.      exact meaning of this parameter depends on ArgType.
  20714.  
  20715. The Index, Width and Precision parameters can be replaced by *, in which case
  20716. their value will be read from the next element in the Args array. This value must
  20717. be an integer, or an EConvertError exception will be raised.
  20718. The argument type is determined from ArgType. It can have one of the following
  20719. values (case insensitive):
  20720.  
  20721. DDecimal format. The next argument in the Args array should be an integer. The
  20722.      argument is converted to a decimal string,. If precision is specified, then the
  20723.      string will have at least Precision digits in it. If needed, the string is (left)
  20724.      padded with zeroes.
  20725. Escientific format. The next argument in the Args array should be a Floating point
  20726.      value. The argument is converted to a decimal string using scientific notation,
  20727.      using FloatToStrF (342), where the optional precision is used to specify the
  20728.      total number of decimals. (defalt a valueof 15 is used). The exponent is
  20729.      formatted using maximally 3 digits.
  20730.      In short, the E specifier formats it's arguument as follows:
  20731.      FloatToStrF(Argument,ffexponent,Precision,3)
  20732. Ffixed point format. The next argument in the Args array should be a floating point
  20733.      value. The argument is converted to a decimal string, using fixed notation
  20734.      (see FloatToStrF (342)). Precision indicates the number of digits following
  20735.      the decimal point.
  20736.      In short, the F specifier formats it's arguument as follows:
  20737.      FloatToStrF(Argument,ffFixed,ffixed,9999,Precision)
  20738. GGeneral number format. The next argument in the Args array should be a floating
  20739.      point value. The argument is converted to a decimal string using fixed point
  20740.      notation or scientific notation, depending on which gives the shortest result.
  20741.      Precision is used to determine the number of digits after the decimal point.
  20742.      In short, the G specifier formats it's arguument as follows:
  20743.      FloatToStrF(Argument,ffGeneral,Precision,3)
  20744. MCurrency format. the next argument in the varArgs array must be a floating
  20745.      point value. The argument is converted to a decimal string using currency
  20746.      notation. This means that fixed-point notation is used, but that the cur-
  20747.      rency symbol is appended. If precision is specified, then then it overrides the
  20748.      CurrencyDecimals global variable used in the FloatToStrF (342)
  20749.      In short, the M specifier formats it's arguument as follows:
  20750.      FloatToStrF(Argument,ffCurrency,9999,Precision)
  20751. NNumber format. This is the same as fixed point format, except that thousand
  20752.      separators are inserted in the resulting string.
  20753. PPointer format. The next argument in the Args array must be a pointer (typed or
  20754.      untyped). The pointer value is converted to a string of length 8, representing
  20755.      the hexadecimal value of the pointer.
  20756. SString format. The next argument in the Args array must be a string. The
  20757.      argument is simply copied to the result string. If Precision is specified, then
  20758.      only Precision characters are copied to the result string.
  20759.  
  20760.  
  20761.  
  20762.                                          346
  20763.  
  20764.  
  20765.  
  20766.                                                       15.6. STRING HANDLING FUNCTIONS
  20767.  
  20768.  
  20769.         Xhexadecimal format. The next argument in the Args array must be an integer.
  20770.                  The argument is converted to a hexadecimal string with just enough characters
  20771.                  to contain the value of the integer. If Precision is specified then the resulting
  20772.                  hexadecimal representation will have at least Precision characters in it (with
  20773.                  a maximum value of 32).
  20774.  
  20775.   Errors: In case of error, an EConversionError exception is raised. Possible errors are:
  20776.  
  20777.            1.Errors in the format specifiers.
  20778.            2.The next argument is not of the type needed by a specifier.
  20779.            3.The number of arguments is not su cient for all format specifiers.
  20780.  
  20781. See also: FormatBuf (351)
  20782.  
  20783.         Program example71 ;
  20784.  
  20785.         { This program demonstrates the Format f u n c t i o n }
  20786.  
  20787.         Uses s y s u t i l s ;
  20788.  
  20789.         Var P : Pointer ;
  20790.                  fmt , S : str in g ;
  20791.  
  20792.         Procedure T e s t I n t e g e r ;
  20793.  
  20794.         begin
  20795.            TryFmt:='[%d]' ;S:=Format ( Fmt,[10]); writeln (Fmt:12, ' => ' , s );
  20796.                  Fmt:= '[%%]' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20797.                  Fmt:= '[%10 d ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20798.                  fmt := '[%.4 d ] ' ; S:=Format ( fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20799.                  Fmt:= '[%10.4 d ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20800.                  Fmt:= '[%0: d ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20801.                  Fmt:= '[%0:10 d ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20802.                  Fmt:= ' [ % 0 : 1 0 . 4 d ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20803.                  Fmt:= '[%0:-10 d ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20804.                  Fmt:= '[%0:-10.4 d ] ' ; S:=Format ( fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20805.                  Fmt:= '[%- .  d ] ' ; S:=Format ( fmt , [ 4 , 5 , 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20806.            except
  20807.                  On E : Exception do
  20808.                     begin
  20809.                     Writeln ( ' Exception caught : ' , E. Message ) ;
  20810.                     end ;
  20811.            end ;
  20812.            writeln ( ' Press enter ' ) ;
  20813.            readln ;
  20814.         end ;
  20815.  
  20816.         Procedure TestHexaDecimal ;
  20817.  
  20818.         begin
  20819.            tryFmt:='[%x ]' ;S:=Format ( Fmt,[10]); writeln (Fmt:12, ' => ' , s );
  20820.                  Fmt:= '[%10 x ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20821.  
  20822.  
  20823.                                                        347
  20824.  
  20825.  
  20826.  
  20827.                                               15.6. STRING HANDLING FUNCTIONS
  20828.  
  20829.  
  20830.          Fmt:= '[%10.4 x ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20831.          Fmt:= '[%0: x ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20832.          Fmt:= '[%0:10 x ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20833.          Fmt:= ' [ % 0 : 1 0 . 4 x ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20834.          Fmt:= '[%0:-10 x ] ' ; S:=Format ( Fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20835.          Fmt:= '[%0:-10.4 x ] ' ; S:=Format ( fmt , [ 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20836.          Fmt:= '[%- .  x ] ' ; S:=Format ( fmt , [ 4 , 5 , 1 0 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20837.    except
  20838.          On E : Exception do
  20839.             begin
  20840.             Writeln ( ' Exception caught : ' , E. Message ) ;
  20841.             end ;
  20842.   end ;
  20843.    writeln ( ' Press enter ' ) ;
  20844.    readln ;
  20845. end ;
  20846.  
  20847. Procedure T es tP o i n ter ;
  20848.  
  20849. begin
  20850.   P:= Pointer (1234567);
  20851.    tryFmt:='[0 x%p]' ;S:=Format ( Fmt,[ P]); writeln (Fmt:12, ' => ' , s );
  20852.          Fmt:= ' [ 0 x%10p ] ' ; S:=Format ( Fmt , [ P ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20853.          Fmt:= ' [ 0 x %10.4 p ] ' ; S:=Format ( Fmt , [ P ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20854.          Fmt:= ' [ 0 x %0:p ] ' ; S:=Format ( Fmt , [ P ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20855.          Fmt:= ' [ 0 x %0:10 p ] ' ; S:=Format ( Fmt , [ P ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20856.          Fmt:= ' [ 0 x %0:10.4 p ] ' ; S:=Format ( Fmt , [ P ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20857.          Fmt:= ' [ 0 x%0:-10p ] ' ; S:=Format ( Fmt , [ P ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20858.          Fmt:= ' [ 0 x %0:-10.4 p ] ' ; S:=Format ( fmt , [ P ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20859.          Fmt:= '[%- .  p ] ' ; S:=Format ( fmt , [ 4 , 5 , P ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20860.    except
  20861.          On E : Exception do
  20862.             begin
  20863.             Writeln ( ' Exception caught : ' , E. Message ) ;
  20864.             end ;
  20865.   end ;
  20866.    writeln ( ' Press enter ' ) ;
  20867.    readln ;
  20868. end ;
  20869.  
  20870. Procedure T e s t S t r i n g ;
  20871.  
  20872. begin
  20873.    tryFmt:='[%s ]' ;S:=Format(fmt ,[ ' This is a string ' ]); Writeln (fmt :12, '=> ', s );
  20874.          fmt := '[%0: s ] ' ; s :=Format ( fmt , [ ' This i s a s t r i n g ' ] ) ; Writeln ( fmt : 1 2 , '=> ' , s ) ;
  20875.          fmt := '[%0:18 s ] ' ; s :=Format ( fmt , [ ' This i s a s t r i n g ' ] ) ; Writeln ( fmt : 1 2 , '=> ' , s ) ;
  20876.          fmt := '[%0:-18 s ] ' ; s :=Format ( fmt , [ ' This i s a s t r i n g ' ] ) ; Writeln ( fmt : 1 2 , '=> ' , s ) ;
  20877.          fmt := '[%0:18.12 s ] ' ; s :=Format ( fmt , [ ' This i s a s t r i n g ' ] ) ; Writeln ( fmt : 1 2 , '=> ' , s ) ;
  20878.          fmt := '[%- .  s ] ' ; s :=Format ( fmt , [ 1 8 , 1 2 , ' This i s a s t r i n g ' ] ) ; Writeln ( fmt : 1 2 , '=> ' , s ) ;
  20879.    except
  20880.          On E : Exception do
  20881.             begin
  20882.  
  20883.                                                348
  20884.  
  20885.  
  20886.  
  20887.                                                 15.6. STRING HANDLING FUNCTIONS
  20888.  
  20889.  
  20890.             Writeln ( ' Exception caught : ' , E. Message ) ;
  20891.             end ;
  20892.    end ;
  20893.    writeln ( ' Press enter ' ) ;
  20894.    readln ;
  20895. end ;
  20896.  
  20897. Procedure T e s t E x p o n e n t i a l ;
  20898.  
  20899. begin
  20900.    TryFmt:='[%e ]' ;S:=Format ( Fmt,[1.234]); writeln (Fmt:12, ' => ' , s );
  20901.          Fmt:= '[%10 e ] ' ; S:=Format ( Fmt , [ 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20902.          Fmt:= '[%10.4 e ] ' ; S:=Format ( Fmt , [ 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20903.          Fmt:= '[%0: e ] ' ; S:=Format ( Fmt , [ 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20904.          Fmt:= '[%0:10 e ] ' ; S:=Format ( Fmt , [ 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20905.          Fmt:= ' [ % 0 : 1 0 . 4 e ] ' ; S:=Format ( Fmt , [ 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20906.          Fmt:= '[%0:-10 e ] ' ; S:=Format ( Fmt , [ 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20907.          Fmt:= '[%0:-10.4 e ] ' ; S:=Format ( fmt , [ 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20908.          Fmt:= '[%- .  e ] ' ; S:=Format ( fmt , [ 4 , 5 , 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20909.    except
  20910.          On E : Exception do
  20911.             begin
  20912.             Writeln ( ' Exception caught : ' , E. Message ) ;
  20913.             end ;
  20914.    end ;
  20915.    writeln ( ' Press enter ' ) ;
  20916.    readln ;
  20917. end ;
  20918.  
  20919. Procedure T e s t N e g a t i v e E x p o n e n t i a l ;
  20920.  
  20921. begin
  20922.    TryFmt:='[%e ]' ;S:=Format ( Fmt,[-1.234]); writeln (Fmt:12, ' => ' , s );
  20923.          Fmt:= '[%10 e ] ' ; S:=Format ( Fmt , [ - 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20924.          Fmt:= '[%10.4 e ] ' ; S:=Format ( Fmt , [ - 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20925.          Fmt:= '[%0: e ] ' ; S:=Format ( Fmt , [ - 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20926.          Fmt:= '[%0:10 e ] ' ; S:=Format ( Fmt , [ - 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20927.          Fmt:= ' [ % 0 : 1 0 . 4 e ] ' ; S:=Format ( Fmt , [ - 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20928.          Fmt:= '[%0:-10 e ] ' ; S:=Format ( Fmt , [ - 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20929.          Fmt:= '[%0:-10.4 e ] ' ; S:=Format ( fmt , [ - 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20930.          Fmt:= '[%- .  e ] ' ; S:=Format ( fmt , [ 4 , 5 , - 1 . 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20931.    except
  20932.          On E : Exception do
  20933.             begin
  20934.             Writeln ( ' Exception caught : ' , E. Message ) ;
  20935.             end ;
  20936.    end ;
  20937.    writeln ( ' Press enter ' ) ;
  20938.    readln ;
  20939. end ;
  20940.  
  20941. Procedure T e s t S m a l l E x p o n e n t i a l ;
  20942.  
  20943.                                                 349
  20944.  
  20945.  
  20946.  
  20947.                                                       15.6. STRING HANDLING FUNCTIONS
  20948.  
  20949.  
  20950.  
  20951. begin
  20952.   TryFmt:='[%e ]' ;S:=Format ( Fmt,[0.01234]); writeln (Fmt:12, ' => ' , s );
  20953.          Fmt:= '[%10 e ] ' ; S:=Format ( Fmt , [ 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20954.          Fmt:= '[%10.4 e ] ' ; S:=Format ( Fmt , [ 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20955.          Fmt:= '[%0: e ] ' ; S:=Format ( Fmt , [ 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20956.          Fmt:= '[%0:10 e ] ' ; S:=Format ( Fmt , [ 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20957.          Fmt:= ' [ % 0 : 1 0 . 4 e ] ' ; S:=Format ( Fmt , [ 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20958.          Fmt:= '[%0:-10 e ] ' ; S:=Format ( Fmt , [ 0 . 0 1 2 3 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20959.          Fmt:= '[%0:-10.4 e ] ' ; S:=Format ( fmt , [ 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20960.          Fmt:= '[%- .  e ] ' ; S:=Format ( fmt , [ 4 , 5 , 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20961.   except
  20962.          On E : Exception do
  20963.             begin
  20964.             Writeln ( ' Exception caught : ' , E. Message ) ;
  20965.             end ;
  20966.   end ;
  20967.   writeln ( ' Press enter ' ) ;
  20968.   readln ;
  20969. end ;
  20970.  
  20971. Procedure TestSmallNegExponential ;
  20972.  
  20973. begin
  20974.   TryFmt:='[%e ]' ;S:=Format ( Fmt,[-0.01234]); writeln (Fmt:12, ' => ' , s );
  20975.          Fmt:= '[%10 e ] ' ; S:=Format ( Fmt , [ - 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20976.          Fmt:= '[%10.4 e ] ' ; S:=Format ( Fmt , [ - 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20977.          Fmt:= '[%0: e ] ' ; S:=Format ( Fmt , [ - 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20978.          Fmt:= '[%0:10 e ] ' ; S:=Format ( Fmt , [ - 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20979.          Fmt:= ' [ % 0 : 1 0 . 4 e ] ' ; S:=Format ( Fmt , [ - 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20980.          Fmt:= '[%0:-10 e ] ' ; S:=Format ( Fmt , [ - 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20981.          Fmt:= '[%0:-10.4 e ] ' ; S:=Format ( fmt , [ - 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20982.          Fmt:= '[%- .  e ] ' ; S:=Format ( fmt , [ 4 , 5 , - 0 . 0 1 2 3 4 ] ) ; writeln ( Fmt : 1 2 , ' => ' , s ) ;
  20983.   except
  20984.          On E : Exception do
  20985.             begin
  20986.             Writeln ( ' Exception caught : ' , E. Message ) ;
  20987.             end ;
  20988.   end ;
  20989.   writeln ( ' Press enter ' ) ;
  20990.   readln ;
  20991. end ;
  20992.  
  20993. begin
  20994.    T e s t I n t e g e r ;
  20995.   TestHexadecimal ;
  20996.    Tes t Po i nt er ;
  20997.    T e s t E x p o n e n t i a l ;
  20998.    T e s t N e g a t i v e E x p o n e n t i a l ;
  20999.    T e s t S m a l l E x p o n e n t i a l ;
  21000.   TestSmallNegExponential ;
  21001. end .
  21002.  
  21003.                                                       350
  21004.  
  21005.  
  21006.  
  21007.                                                          15.6. STRING HANDLING FUNCTIONS
  21008.  
  21009.  
  21010.                FormatBuf
  21011. Declaration: Function FormatBuf(Var Buffer; BufLen : Cardinal; Const Fmt; fmtLen :
  21012.                Cardinal; Const Args : Array of const) : Cardinal;
  21013. Description: Format
  21014.     Errors:
  21015.   See also:
  21016.  
  21017.                Program Example72 ;
  21018.  
  21019.                { This program demonstrates the FormatBuf f u n c t i o n }
  21020.  
  21021.                Uses s y s u t i l s ;
  21022.  
  21023.                VarS : ShortString ;
  21024.                Const
  21025.                   Fmt : S h o r t S t r i n g = ' For some nice examples of fomatting see %s . ' ;
  21026.  
  21027.                Begin
  21028.                   S:= ' ' ;
  21029.                   SetLength ( S , FormatBuf ( S [ 1 ] , 2 5 5 , Fmt [ 1 ] , Length ( Fmt ) , [ ' Format ' ] ) ) ;
  21030.                   Writeln ( S ) ;
  21031.                End.
  21032.  
  21033.  
  21034.                IntToHex
  21035. Declaration: Function IntToHex(Value: integer; Digits: integer): string;
  21036. Description: IntToHex converts Value to a hexadecimal string representation. The result will
  21037.                contain at least Digits characters. If Digits is less than the needed number of
  21038.                characters, the string will NOT be truncated. If Digits is larger than the needed
  21039.                number of characters, the result is padded with zeroes.
  21040.     Errors: None.
  21041.   See also: IntToStr (352), StrToInt
  21042.  
  21043.                Program Example73 ;
  21044.  
  21045.                { This program demonstrates the IntToHex f u n c t i o n }
  21046.  
  21047.                Uses s y s u t i l s ;
  21048.  
  21049.                Var I : l o n g i n t ;
  21050.  
  21051.                Begin
  21052.                   For I :=0 to 31 do
  21053.                         begin
  21054.                         Writeln ( IntToHex (1 shl I , 8 ) ) ;
  21055.                         Writeln ( IntToHex (15 shl I , 8 ) )
  21056.                         end ;
  21057.                End.
  21058.  
  21059.                                                           351
  21060.  
  21061.  
  21062.  
  21063.                                                              15.6. STRING HANDLING FUNCTIONS
  21064.  
  21065.  
  21066.            IntToStr
  21067. Declaration: Function IntToStr(Value: integer): string;
  21068.  
  21069. Description: IntToStr coverts Value to it's string representation. The resulting string has only
  21070.            as much characters as needed to represent the value. If the value is negative a minus
  21071.            sign is prepended to the string.
  21072.  
  21073.      Errors: None.
  21074.  
  21075.    See also: IntToHex (351), StrToInt (356)
  21076.  
  21077.                 Program Example74 ;
  21078.  
  21079.                 { This program demonstrates the IntToStr f u n c t i o n }
  21080.  
  21081.                 Uses s y s u t i l s ;
  21082.  
  21083.                 Var I : l o n g i n t ;
  21084.  
  21085.                 Begin
  21086.                    For I :=0 to 31 do
  21087.                            begin
  21088.                            Writeln ( IntToStr (1 shl I ) ) ;
  21089.                            Writeln ( IntToStr (15 shl I ) ) ;
  21090.                            end ;
  21091.                 End.
  21092.  
  21093.  
  21094.            IsValidIdent
  21095. Declaration: Function IsValidIdent(const Ident: string): boolean;
  21096.  
  21097. Description: IsValidIdent returns True if Ident can be used as a compoent name. It re-
  21098.            turns False otherwise. Ident must consist of a letter or underscore, followed by a
  21099.            combination of letters, numbers or underscores to be a valid identifier.
  21100.  
  21101.      Errors: None.
  21102.  
  21103.    See also:
  21104.  
  21105.                 Program Example75 ;
  21106.  
  21107.                 { This program demonstrates the I s V a l i d I d e n t f u n c t i o n }
  21108.  
  21109.                 Uses s y s u t i l s ;
  21110.  
  21111.                 Procedure T e s t i t ( S : String ) ;
  21112.  
  21113.                 begin
  21114.                    Write ( ' " ' , S , '" i s ' ) ;
  21115.                    I f not IsVAlidIdent ( S ) then
  21116.                          Write ( ' NOT ' ) ;
  21117.                    Writeln ( ' a v a l i d i d e n t i f i e r ' ) ;
  21118.                 end ;
  21119.  
  21120.                 Begin
  21121.  
  21122.                                                               352
  21123.  
  21124.  
  21125.  
  21126.                                                                    15.6. STRING HANDLING FUNCTIONS
  21127.  
  21128.  
  21129.                    T e s t i t ( ' MyObj' ) ;
  21130.                    T e s t i t ( ' My      Obj1' ) ;
  21131.                    T e s t i t ( ' My 1 Obj' ) ;
  21132.                    T e s t i t ( '1 MyObject ' ) ;
  21133.                    T e s t i t ( ' My@Object ' ) ;
  21134.                    T e s t i t ( ' M123' ) ;
  21135.                 End.
  21136.  
  21137.  
  21138.                 LeftStr
  21139. Declaration: Function LeftStr(const S: string; Count: integer): string;
  21140.  
  21141. Description: LeftStr returns the Count leftmost characters of S. It is equivalent to a call to
  21142.                 Copy(S,1,Count).
  21143.  
  21144.      Errors: None.
  21145.  
  21146.    See also: RightStr (355), TrimLeft (358), TrimRight (358), Trim (357)
  21147.  
  21148.                 Program Example76 ;
  21149.  
  21150.                 { This program demonstrates the L e f t S t r f u n c t i o n }
  21151.  
  21152.                 Uses s y s u t i l s ;
  21153.  
  21154.                 Begin
  21155.                    Writeln ( L e f t S t r ( ' a b c d e f g h i j k l m n o p q r s t u v w x y z ' , 2 0 ) ) ;
  21156.                    Writeln ( L e f t S t r ( ' a b c d e f g h i j k l m n o p q r s t u v w x y z ' , 1 5 ) ) ;
  21157.                    Writeln ( L e f t S t r ( ' a b c d e f g h i j k l m n o p q r s t u v w x y z ' , 1 ) ) ;
  21158.                    Writeln ( L e f t S t r ( ' a b c d e f g h i j k l m n o p q r s t u v w x y z ' , 2 0 0 ) ) ;
  21159.                 End.
  21160.  
  21161.  
  21162.                 LoadStr
  21163. Declaration: Function LoadStr(Ident: integer): string;
  21164.  
  21165. Description: This function is not yet implemented. resources are not yet supported.
  21166.  
  21167.      Errors:
  21168.  
  21169.    See also:
  21170.  
  21171.  
  21172.                 LowerCase
  21173. Declaration: Function LowerCase(const s: string): string;
  21174.  
  21175. Description: LowerCase returns the lowercase equivalent of S. Ansi characters are not taken into
  21176.                 account, only ASCII codes below 127 are converted. It is completely equivalent to
  21177.                 the lowercase function of the system unit, and is provided for compatiibility only.
  21178.  
  21179.      Errors: None.
  21180.  
  21181.    See also: AnsiLowerCase (331), UpperCase (359), AnsiUpperCase (337)
  21182.  
  21183.  
  21184.  
  21185.                                                                     353
  21186.  
  21187.  
  21188.  
  21189.                                                       15.6. STRING HANDLING FUNCTIONS
  21190.  
  21191.  
  21192.            Program Example77 ;
  21193.  
  21194.            { This program demonstrates the LowerCase f u n c t i o n }
  21195.  
  21196.            Uses s y s u t i l s ;
  21197.  
  21198.            Begin
  21199.               Writeln ( LowerCase ( ' THIS WILL COME out a l l LoWeRcAsE ! ' ) ) ;
  21200.            End.
  21201.  
  21202.  
  21203.            NewStr
  21204. Declaration: Function NewStr(const S: string): PString;
  21205.  
  21206. Description: NewStr assigns a new dynamic string on the heap, copies S into it, and returns a
  21207.            pointer to the newly assigned string.
  21208.            This function is obsolete, and shouldn't be used any more. The AnsiString mech-
  21209.            anism also allocates ansistrings on the heap, and should be preferred over this
  21210.            mechanism.
  21211.  
  21212.      Errors: If not enough memory is present, an EOutOfMemory exception will be raised.
  21213.  
  21214.    See also: AssignStr (338), DisposeStr (341)
  21215.  
  21216.            For an example, see AssignStr (338).
  21217.  
  21218.  
  21219.            QuotedStr
  21220. Declaration: Function QuotedStr(const S: string): string;
  21221.  
  21222. Description: QuotedStr returns the string S, quoted with single quotes. This means that S is
  21223.            enclosed in single quotes, and every single quote in S is doubled. It is equivalent to
  21224.            a call to AnsiQuotedStr(s, '''').
  21225.  
  21226.      Errors: None.
  21227.  
  21228.    See also: AnsiQuotedStr (331), AnsiExtractQuotedStr (330).
  21229.  
  21230.            Program Example78 ;
  21231.  
  21232.            { This program demonstrates the QuotedStr f u n c t i o n }
  21233.  
  21234.            Uses s y s u t i l s ;
  21235.  
  21236.            Var S : A n s i S t r i n g ;
  21237.  
  21238.            Begin
  21239.               S:= ' He s a i d ' ' Hello ' ' and walked on ' ;
  21240.               Writeln ( S ) ;
  21241.               Writeln ( '            becomes ' ) ;
  21242.               Writeln ( QuotedStr ( S ) ) ;
  21243.            End.
  21244.  
  21245.  
  21246.  
  21247.                                                       354
  21248.  
  21249.  
  21250.  
  21251.                                                             15.6. STRING HANDLING FUNCTIONS
  21252.  
  21253.  
  21254.            RightStr
  21255. Declaration: Function RightStr(const S: string; Count: integer): string;
  21256.  
  21257. Description: RightStr returns the Count rightmost characters of S. It is equivalent to a call to
  21258.            Copy(S,Length(S)+1-Count,Count).
  21259.            If Count is larger than the actual length of S only the real length will be used.
  21260.  
  21261.      Errors: None.
  21262.  
  21263.    See also: LeftStr (353),Trim (357), TrimLeft (358), TrimRight (358)
  21264.  
  21265.            Program Example79 ;
  21266.  
  21267.             { This program demonstrates the RightStr f u n c t i o n }
  21268.  
  21269.            Uses s y s u t i l s ;
  21270.  
  21271.            Begin
  21272.                Writeln ( RightStr ( ' a b c d e f g h i j k l m n o p q r s t u v w x y z ' , 2 0 ) ) ;
  21273.                Writeln ( RightStr ( ' a b c d e f g h i j k l m n o p q r s t u v w x y z ' , 1 5 ) ) ;
  21274.                Writeln ( RightStr ( ' a b c d e f g h i j k l m n o p q r s t u v w x y z ' , 1 ) ) ;
  21275.                Writeln ( RightStr ( ' a b c d e f g h i j k l m n o p q r s t u v w x y z ' , 2 0 0 ) ) ;
  21276.            End.
  21277.  
  21278.  
  21279.            StrFmt
  21280. Declaration: Function StrFmt(Buffer,Fmt : PChar; Const args: Array of const) : Pchar;
  21281.  
  21282. Description: StrFmt will format fmt with Args, as the Format (345) function does, and it will
  21283.            store the result in Buffer. The function returns Buffer. Buffer should point to
  21284.            enough space to contain the whole result.
  21285.  
  21286.      Errors: for a list of errors, see Format (345).
  21287.  
  21288.    See also: StrLFmt (355), FmtStr (345), Format (345), FormatBuf (351)
  21289.  
  21290.            Program Example80 ;
  21291.  
  21292.             { This program demonstrates the StrFmt f u n c t i o n }
  21293.  
  21294.            Uses s y s u t i l s ;
  21295.  
  21296.            Var S : A n s i S t r i n g ;
  21297.  
  21298.            Begin
  21299.                SetLEngth ( S , 8 0 ) ;
  21300.                Writeln ( StrFmt ( @S [ 1 ] , ' For some nice examples of fomatting see %s . ' , [ ' Format ' ] ) ) ;
  21301.            End.
  21302.  
  21303.  
  21304.            StrLFmt
  21305. Declaration: Function StrLFmt(Buffer : PCHar; Maxlen : Cardinal;Fmt : PChar; Const
  21306.            args: Array of const) : Pchar;
  21307.  
  21308.  
  21309.                                                             355
  21310.  
  21311.  
  21312.  
  21313.                                                          15.6. STRING HANDLING FUNCTIONS
  21314.  
  21315.  
  21316. Description: StrLFmt will format fmt with Args, as the Format (345) function does, and it will
  21317.            store maximally Maxlen characters of the result in Buffer. The function returns
  21318.            Buffer. Buffer should point to enough space to contain MaxLen characters.
  21319.  
  21320.      Errors: for a list of errors, see Format (345).
  21321.  
  21322.    See also: StrFmt (355), FmtStr (345), Format (345), FormatBuf (351)
  21323.  
  21324.            Program Example80 ;
  21325.  
  21326.             { This program demonstrates the StrFmt f u n c t i o n }
  21327.  
  21328.            Uses s y s u t i l s ;
  21329.  
  21330.            Var S : A n s i S t r i n g ;
  21331.  
  21332.            Begin
  21333.                SetLEngth ( S , 8 0 ) ;
  21334.                Writeln ( StrLFmt ( @S [ 1 ] , 8 0 , ' For some nice examples of fomatting see %s . ' , [ ' Format ' ] ) ) ;
  21335.            End.
  21336.  
  21337.  
  21338.            StrToInt
  21339. Declaration: Function StrToInt(const s: string): integer;
  21340.  
  21341. Description: StrToInt will convert the string Sto an integer. If the string contains invalid
  21342.            characters or has an invalid format, then an EConvertError is raised.
  21343.            To be successfully converted, a string can contain a combination of numerical
  21344.            characters, possibly preceded by a minus sign (-). Spaces are not allowed.
  21345.  
  21346.      Errors: In case of error, an EConvertError is raised.
  21347.  
  21348.    See also: IntToStr (352), StrToIntDef (357)
  21349.  
  21350.            Program Example82 ;
  21351.  
  21352.             { This program demonstrates the StrToInt f u n c t i o n }
  21353.  
  21354.            Uses s y s u t i l s ;
  21355.  
  21356.            Begin
  21357.                Writeln ( StrToInt ( ' 1 2 3 4 ' ) ) ;
  21358.                Writeln ( StrToInt ( '-1234' ) ) ;
  21359.                Writeln ( StrToInt ( ' 0 ' ) ) ;
  21360.               TryWriteln ( StrToInt( '12345678901234567890' ));
  21361.                except
  21362.                    On E : EConvertError do
  21363.                        Writeln ( ' I n v a l i d number encountered ' ) ;
  21364.               end ;
  21365.            End.
  21366.  
  21367.  
  21368.  
  21369.  
  21370.                                                          356
  21371.  
  21372.  
  21373.  
  21374.                                                           15.6. STRING HANDLING FUNCTIONS
  21375.  
  21376.  
  21377.            StrToIntDef
  21378. Declaration: Function StrToIntDef(const S: string; Default: integer): integer;
  21379.  
  21380. Description: StrToIntDef will convert a string to an integer. If the string contains invalid
  21381.            characters or has an invalid format, then Default is returned.
  21382.            To be successfully converted, a string can contain a combination of numerical
  21383.            characters, possibly preceded by a minus sign (-). Spaces are not allowed.
  21384.  
  21385.     Errors: None.
  21386.  
  21387.   See also: IntToStr (352), StrToInt (356)
  21388.  
  21389.            Program Example82 ;
  21390.  
  21391.            { This program demonstrates the StrToInt f u n c t i o n }
  21392.  
  21393.            Uses s y s u t i l s ;
  21394.  
  21395.            Begin
  21396.               Writeln ( StrToIntDef ( ' 1 2 3 4 ' , 0 ) ) ;
  21397.               Writeln ( StrToIntDef ( '-1234' , 0 ) ) ;
  21398.               Writeln ( StrToIntDef ( ' 0 ' , 0 ) ) ;
  21399.               TryWriteln ( StrToIntDef( '12345678901234567890' ,0));
  21400.               except
  21401.                     On E : EConvertError do
  21402.                        Writeln ( ' I n v a l i d number encountered ' ) ;
  21403.               end ;
  21404.            End.
  21405.  
  21406.  
  21407.            Trim
  21408. Declaration: Function Trim(const S: string): string;
  21409.  
  21410. Description: Trim strips blank characters (spaces) at the beginning and end of S and returns
  21411.            the resulting string. Only #32 characters are stripped.
  21412.            If the string contains only spaces, an empty string is returned.
  21413.  
  21414.     Errors: None.
  21415.  
  21416.   See also: TrimLeft (358), TrimRight (358)
  21417.  
  21418.            Program Example84 ;
  21419.  
  21420.            { This program demonstrates the Trim f u n c t i o n }
  21421.  
  21422.            Uses s y s u t i l s ;
  21423.            {$H+}
  21424.  
  21425.            Procedure T e s t i t ( S : String ) ;
  21426.  
  21427.            begin
  21428.               Writeln ( ' " ' , Trim ( S ) , ' " ' ) ;
  21429.            end ;
  21430.  
  21431.                                                           357
  21432.  
  21433.  
  21434.  
  21435.                                                            15.6. STRING HANDLING FUNCTIONS
  21436.  
  21437.  
  21438.  
  21439.            Begin
  21440.               T e s t i t ( '    ha ha what gets l o s t ? ' ) ;
  21441.               T e s t i t (#10#13 ' haha ' ) ;
  21442.               T e s t i t ( '                     ' ) ;
  21443.            End.
  21444.  
  21445.  
  21446.            TrimLeft
  21447. Declaration: Function TrimLeft(const S: string): string;
  21448.  
  21449. Description: TrimLeft strips blank characters (spaces) at the beginning of S and returns the
  21450.            resulting string. Only #32 characters are stripped.
  21451.            If the string contains only spaces, an empty string is returned.
  21452.  
  21453.     Errors: None.
  21454.  
  21455.   See also: Trim (357), TrimRight (358)
  21456.  
  21457.            Program Example85 ;
  21458.  
  21459.            { This program demonstrates the TrimLeft f u n c t i o n }
  21460.  
  21461.            Uses s y s u t i l s ;
  21462.            {$H+}
  21463.  
  21464.            Procedure T e s t i t ( S : String ) ;
  21465.  
  21466.            begin
  21467.               Writeln ( ' " ' , TrimLeft ( S ) , ' " ' ) ;
  21468.            end ;
  21469.  
  21470.            Begin
  21471.               T e s t i t ( '    ha ha what gets l o s t ? ' ) ;
  21472.               T e s t i t (#10#13 ' haha ' ) ;
  21473.               T e s t i t ( '                     ' ) ;
  21474.            End.
  21475.  
  21476.  
  21477.            TrimRight
  21478. Declaration: Function TrimRight(const S: string): string;
  21479.  
  21480. Description: Trim strips blank characters (spaces) at the end of S and returns the resulting
  21481.            string. Only #32 characters are stripped.
  21482.            If the string contains only spaces, an empty string is returned.
  21483.  
  21484.     Errors: None.
  21485.  
  21486.   See also: Trim (357), TrimLeft (358)
  21487.  
  21488.            Program Example86 ;
  21489.  
  21490.            { This program demonstrates the TrimRight f u n c t i o n }
  21491.  
  21492.  
  21493.                                                            358
  21494.  
  21495.  
  21496.  
  21497.                                                                15.6. STRING HANDLING FUNCTIONS
  21498.  
  21499.  
  21500.                Uses s y s u t i l s ;
  21501.                {$H+}
  21502.  
  21503.                Procedure T e s t i t ( S : String ) ;
  21504.  
  21505.                begin
  21506.                   Writeln ( ' " ' , TrimRight ( S ) , ' " ' ) ;
  21507.                end ;
  21508.  
  21509.                Begin
  21510.                   T e s t i t ( '    ha ha what gets l o s t ? ' ) ;
  21511.                   T e s t i t (#10#13 ' haha ' ) ;
  21512.                   T e s t i t ( '                     ' ) ;
  21513.                End.
  21514.  
  21515.  
  21516.                UpperCase
  21517. Declaration: Function UpperCase(const s: string): string;
  21518.  
  21519. Description: UpperCase returns the uppercase equivalent of S. Ansi characters are not taken
  21520.                into account, only ASCII codes below 127 are converted. It is completely equivalent
  21521.                to the UpCase function of the system unit, and is provided for compatiibility only.
  21522.  
  21523.     Errors: None.
  21524.  
  21525.   See also: AnsiLowerCase (331), LowerCase (353), AnsiUpperCase (337)
  21526.  
  21527.     Errors:
  21528.  
  21529.   See also:
  21530.  
  21531.                Program Example87 ;
  21532.  
  21533.                { This program demonstrates the UpperCase f u n c t i o n }
  21534.  
  21535.                Uses s y s u t i l s ;
  21536.  
  21537.                Begin
  21538.                   Writeln ( UpperCase ( ' t h i s w i l l come OUT ALL uPpErCaSe ! ' ) ) ;
  21539.                End.
  21540.  
  21541.  
  21542.  
  21543.  
  21544.  
  21545.  
  21546.  
  21547.  
  21548.  
  21549.  
  21550.  
  21551.  
  21552.  
  21553.  
  21554.  
  21555.                                                                359
  21556.  
  21557.  
  21558.  
  21559. Index
  21560.  
  21561. Abstract, 207                          ClearViewPort, 93
  21562. Accept, 268, 270                       CloseDir, 146
  21563. Access, 139                            CloseGraph, 93
  21564. AddDisk, 36                            ClrEol, 23
  21565. AddDisk (Linux only), 307              ClrScr, 24
  21566. AdjustLineBreaks, 328                  CompareMem, 339
  21567. allocate ldt descriptors, 64           CompareStr, 339
  21568. allocate memory block, 66              CompareText, 340
  21569. AnsiCompareStr, 328                    Connect, 271, 272
  21570. AnsiCompareText, 329                   copyfromdos, 66
  21571. AnsiExtractQuotedStr, 330              copytodos, 67
  21572. AnsiLastChar, 330                      create code segment alias descriptor,
  21573. AnsiLowerCase, 331                              67
  21574. AnsiQuotedStr, 331                     CreateDir, 308
  21575. AnsiStrComp, 332                       CursorO , 24
  21576. AnsiStrIComp, 333                      CursorOn, 24
  21577. AnsiStrLastChar, 333
  21578. AnsiStrLComp, 334                      Date, 294
  21579. AnsiStrLIComp, 335                     DateTimeToFileDate, 295
  21580. AnsiStrLower, 336                      DateTimeToStr, 295
  21581. AnsiStrUpper, 336                      DateTimeToString, 295
  21582. AnsiUpperCase, 337                     DateTimeToSystemTime, 296
  21583. AppendStr, 337                         DateTimeToTimeStamp, 297
  21584. Arc, 92                                DateToStr, 297
  21585. AssignCrt, 22                          DayOfWeek, 298
  21586. AssignLst, 265                         DecodeDate, 298
  21587. AssignPipe, 140                        DecodeTime, 299
  21588. AssignStr, 338                         Delay, 24
  21589. AssignStream, 141                      DeleteFile, 311
  21590.                                        DelLine, 25
  21591. Bar, 92                                DetectGraph, 93
  21592. Bar3D, 92                              DirName, 146
  21593. BaseName, 142                          disable, 67
  21594. BCDToInt, 338                          DiskFree, 36, 308
  21595. BigCursor, 23                          DiskSize, 37, 309
  21596. Bind, 270, 271                         DisposeStr, 207, 341
  21597.                                        DoDirSeparators, 311
  21598. CFMakeRaw, 143                         DosExitCode, 37
  21599. CFSetISpeed, 143                       dosmemfillchar, 68
  21600. CFSetOSpeed, 143                       dosmemfillword, 69
  21601. ChangeFileExt, 311                     dosmemget, 69
  21602. Chmod, 144                             dosmemmove, 69
  21603. Chown, 143                             dosmemput, 70
  21604. Circle, 92                             DosVersion, 38
  21605. ClearDevice, 93                        DrawPoly, 93
  21606.  
  21607.  
  21608.                                 360
  21609.  
  21610.  
  21611.  
  21612.                                                                       INDEX
  21613.  
  21614.  
  21615. DumpHeap, 111                             FileTruncate, 321
  21616. Dup, 146                                  FileWrite, 322
  21617. Dup2, 147                                 FillEllipse, 94
  21618.                                           FillPoly, 94
  21619. Ellipse, 94                               FindClose, 40, 322
  21620. Emms, 192                                 FindFirst, 40, 322
  21621. enable, 70                                FindNext, 41, 323
  21622. EncodeDate, 299                           FloatToStr, 341
  21623. EncodeTime, 300                           FloatToStrF, 342
  21624. EnvCount, 38                              FloatToText, 344
  21625. EnvStr, 39                                FLock, 157
  21626. EpochToLocal, 148                         FloodFill, 94
  21627. Exec, 39                                  FmtStr, 345
  21628. Execl, 148                                Fork, 161
  21629. Execle, 149                               Format, 345
  21630. Execlp, 150                               FormatBuf, 351
  21631. Execv, 150                                FormatDateTime, 301
  21632. Execve, 151                               free ldt descriptor, 70
  21633. Execvp, 152                               free memory block, 71
  21634. ExpandFileName, 312                       free rm callback, 71
  21635. ExpandUNCFileName, 313                    FSearch, 41, 159
  21636. ExtractFileDir, 313                       FSplit, 42
  21637. ExtractFileDrive, 313                     FSStat, 158
  21638. ExtractFileExt, 314                       FStat, 159
  21639. ExtractFileName, 314                      ftok, 119
  21640. ExtractFilePath, 314
  21641. ExtractRelativePath, 315                  get cs, 71
  21642.                                           get descriptor access rights, 71
  21643. Fcntl, 160                                get ds, 72
  21644. FD Clr, 153                               get linear addr, 72
  21645. FD IsSet, 153                             get meminfo, 72
  21646. FD Set, 154                               get next selector increment value, 73
  21647. FD ZERO, 153                              get page size, 74
  21648. fdClose, 154                              get pm interrupt, 74
  21649. fdFlush, 154                              get rm callback, 74
  21650. fdOpen, 154                               get rm interrupt, 77
  21651. fdRead, 155                               get run mode, 78
  21652. fdSeek, 156                               get segment base address, 78
  21653. fdTruncate, 156                           get segment limit, 79
  21654. fdWrite, 157                              get ss, 79
  21655. FExpand, 39, 157                          GetArcCoords, 94
  21656. FileAge, 315                              GetAspectRatio, 95
  21657. FileClose, 316                            GetBkColor, 95
  21658. FileCreate, 316                           GetCBreak, 42
  21659. FileDateToDateTime, 300                   GetColor, 95
  21660. FileExists, 317                           GetCurrentDir, 310
  21661. FileGetAttr, 317                          GetDate, 42, 161
  21662. FileGetDate, 318                          GetDefaultPalette, 95
  21663. FileOpen, 319                             GetDirs, 323
  21664. FileRead, 319                             GetDomainName, 162
  21665. FileSearch, 320                           GetDriverName, 95
  21666. FileSeek, 320                             GetEGid, 162
  21667. FileSetAttr (Not on Linux), 321           GetEnv, 43, 163
  21668. FileSetDate (Not on Linux), 321           GetEpochTime, 163
  21669.  
  21670.                                    361
  21671.  
  21672.  
  21673.  
  21674.                                                               INDEX
  21675.  
  21676.  
  21677. GetEUid, 163                        InitMouse, 197
  21678. GetFAttr, 43                        inportb, 81
  21679. GetFillPattern, 95                  inportl, 81
  21680. GetFillSettings, 96                 inportw, 81
  21681. GetFS, 164                          InsLine, 26
  21682. GetFTime, 44                        InstallUserDriver, 100
  21683. GetGid, 164                         InstallUserFont, 100
  21684. GetGraphMode, 96                    Intr, 46
  21685. GetHostName, 165                    IntToHex, 351
  21686. GetImage, 96                        IntToStr, 352
  21687. GetIntVec, 45                       IOCtl, 168
  21688. GetLastButtonPress, 194             IOperm, 169
  21689. GetLastButtonRelease, 195           IsATTY, 169
  21690. GetLineSettings, 96                 IsLeapYear, 302
  21691. GetLongOpts, 51                     IsValidIdent, 352
  21692. GetMaxColor, 96
  21693. GetMaxMode, 96                      Keep, 46
  21694. GetMaxX, 97                         KeyPressed, 27
  21695. GetMaxY, 97                         Kill, 171
  21696. GetModeName, 97
  21697. GetModeRange, 97                    LeftStr, 353
  21698. GetMouseState, 196                  Line, 101
  21699. Getopt, 51                          LineRel, 101
  21700. GetPalette, 97                      LineTo, 101
  21701. GetPaletteSize, 97                  Link, 173
  21702. GetPeerName, 273                    Listen, 274
  21703. GetPid, 165                         LoadStr, 353
  21704. GetPixel, 98                        LocalToEpoch, 174
  21705. GetPPid, 166                        lock code, 82
  21706. GetPriority, 166                    lock data, 82
  21707. GetSocketName, 274                  lock linear region, 82
  21708. GetSocketOptions, 274               LongDiv, 209
  21709. GetTextSettings, 98                 LongMul, 209
  21710. GetTime, 45, 166                    LowerCase, 353
  21711. GetUid, 167                         LowVideo, 27
  21712. GetVerify, 46                       LPressed, 198
  21713. GetViewSettings, 98                 LStat, 172
  21714. GetX, 98
  21715. GetY, 98                            MarkHeap, 111
  21716. Glob, 167                           MkFifo, 175
  21717. global dos alloc, 79                MoveRel, 101
  21718. global dos free, 81                 MoveTo, 101
  21719. GlobFree, 168                       MPressed, 198
  21720. GotoXY, 25                          MSDos, 46
  21721. GraphDefaults, 99                   MSecsToTimeStamp, 302
  21722. GraphErrorMsg, 99                   msgctl, 120
  21723. GraphResult, 99                     msgget, 119
  21724.                                     msgrcv, 120
  21725. HideMouse, 197                      msgsnd, 119
  21726. HighVideo, 26                       NewStr, 206, 354
  21727. ImageSize, 99                       Nice, 175
  21728. IncMonth, 301                       NormVideo, 28
  21729. InitGraph, 100                      NoSound, 28
  21730.  
  21731.  
  21732.                              362
  21733.  
  21734.  
  21735.  
  21736.                                                                       INDEX
  21737.  
  21738.  
  21739. Now, 303                                   set segment base address, 88
  21740.                                            set segment limit, 88
  21741. OpenDir, 176                               SetActivePage, 104
  21742. outportb, 83                               SetAllPallette, 104
  21743. outportl, 83                               SetAspectRatio, 104
  21744. outportw, 83                               SetBkColor, 104
  21745. OutText, 102                               SetCBreak, 47
  21746. OutTextXY, 102                             SetColor, 104
  21747.                                            SetCurrentDir, 310
  21748. PackTime, 47                               SetDate, 48
  21749. PClose, 177                                SetDirSeparators, 324
  21750. PieSlice, 102                              SetExtraInfo, 112
  21751. POpen, 177                                 SetFAttr, 48
  21752. PutImage, 102                              SetFillPattern, 105
  21753. PutPixel, 102                              SetFillStyle, 105
  21754. QuotedStr, 354                             SetFTime, 48
  21755.                                            SetGraphBufSize, 105
  21756. ReadDir, 178                               SetGraphMode, 105
  21757. ReadKey, 28                                SetIntVec, 48
  21758. realintr, 84                               SetLineStyle, 106
  21759. Rectangle, 103                             SetMouseAscii, 198
  21760. Recv, 275                                  SetMouseHideWindow, 199
  21761. RegisterBGIDriver, 103                     SetMousePos, 200
  21762. RegisterBGIFont, 103                       SetMouseShape, 200
  21763. RegisterObjects, 207                       SetMouseSpeed, 201
  21764. RegisterType, 207                          SetMouseWindow, 202
  21765. RemoveDir, 310                             SetMouseXRange, 202
  21766. RenameFile, 324                            SetMouseYRange, 203
  21767. RestoreCRTMode, 103                        SetPalette, 106
  21768. RightStr, 355                              SetPriority, 180
  21769. RPressed, 198                              SetRGBPalette, 106
  21770.                                            SetSocketOptions, 276
  21771. S ISBLK, 169                               SetTextJustify, 106
  21772. S ISCHR, 169                               SetTextStyle, 107
  21773. S ISDIR, 170                               SetTime, 49
  21774. S ISFIFO, 170                              SetUserCharSize, 107
  21775. S ISLNK, 170                               SetVerify, 49
  21776. S ISREG, 171                               SetViewPort, 107
  21777. S ISSOCK, 171                              SetVisualPage, 108
  21778. Sector, 103                                SetWriteMode, 108
  21779. SeekDir, 178                               Shell, 180
  21780. seg fillchar, 84                           shmat, 129
  21781. seg fillword, 85                           shmctl, 130
  21782. seg move, 86                               shmdt, 130
  21783. segment to descriptor, 85                  shmget, 129
  21784. Select, 178                                ShowMouse, 203
  21785. SelectText, 180                            Shutdown, 276
  21786. semctl, 124                                SigAction, 181
  21787. semget, 123                                Signal, 183
  21788. semop, 123                                 SigPending, 182
  21789. Send, 275                                  SigProcMask, 182
  21790. set descriptor access rights, 86           SigSuspend, 183
  21791. set pm interrupt, 86                       Sock2File, 276
  21792. set rm interrupt, 88                       Sock2Text, 277
  21793.  
  21794.                                     363
  21795.  
  21796.  
  21797.  
  21798.                                                                   INDEX
  21799.  
  21800.  
  21801. Socket, 277                         TCollection.At, 236
  21802. SocketPair, 277                     TCollection.AtDelete, 245
  21803. Sound, 29                           TCollection.AtFree, 244
  21804. Str2UnixSockAddr, 277               TCollection.AtInsert, 247
  21805. StrAlloc, 279, 326                  TCollection.AtPut, 247
  21806. StrBufSize, 326                     TCollection.Delete, 243
  21807. StrCat, 279                         TCollection.DeleteAll, 241
  21808. StrComp, 280                        TCollection.Done, 236
  21809. StrCopy, 280                        TCollection.Error, 246
  21810. StrDispose, 281, 327                TCollection.FirstThat, 239
  21811. StrECopy, 281                       TCollection.ForEach, 245
  21812. StrEnd, 282                         TCollection.Free, 242
  21813. StrFmt, 355                         TCollection.FreeAll, 240
  21814. StrIComp, 282                       TCollection.FreeItem, 244
  21815. StrLCat, 283                        TCollection.GetItem, 238
  21816. StrLComp, 283                       TCollection.IndexOf, 237
  21817. StrLCopy, 284                       TCollection.Init, 235
  21818. StrLen, 284                         TCollection.Insert, 243
  21819. StrLFmt, 355                        TCollection.LastThat, 238
  21820. StrLIComp, 285                      TCollection.Load, 235
  21821. StrLower, 285                       TCollection.Pack, 239
  21822. StrMove, 286                        TCollection.PutItem, 248
  21823. StrNew, 286                         TCollection.SetLimit, 246
  21824. StrPas, 287, 327                    TCollection.Store, 248
  21825. StrPCopy, 287, 327                  TCSendBreak, 187
  21826. StrPLCopy, 327                      TCSetAttr, 187
  21827. StrPos, 288                         TCSetPGrp, 187
  21828. StrRScan, 288                       TDateTime, 294
  21829. StrScan, 288                        TDosStream.Close, 225
  21830. StrToDate, 303                      TDosStream.Done, 225
  21831. StrToDateTime, 304                  TDosStream.Init, 224
  21832. StrToInt, 356                       TDosStream.Open, 227
  21833. StrToIntDef, 357                    TDosStream.Read, 227
  21834. StrToTime, 305                      TDosStream.Seek, 226
  21835. StrUpper, 289                       TDosStream.Truncate, 225
  21836. SwapVectors, 49                     TDosStream.Write, 228
  21837. SymLink, 184                        TellDir, 188
  21838. SystemTimeToDateTime, 305           TextBackground, 29
  21839.                                     TextColor, 30
  21840. tb size, 89                         TextHeight, 108
  21841. TBufStream.Close, 229               TextWidth, 108
  21842. TBufStream.Done, 229                Time, 306
  21843. TBufStream.Flush, 230               TimeStampToDateTime, 306
  21844. TBufStream.Init, 229                TimeStampToMSecs, 307
  21845. TBufStream.Open, 231                TimeToStr, 307
  21846. TBufStream.Read, 231                TMemoryStream.Done, 232
  21847. TBufStream.Seek, 231                TMemoryStream.Init, 232
  21848. TBufStream.Truncate, 230            TMemoryStream.Read, 233
  21849. TBufStream.Write, 231               TMemoryStream.Truncate, 233
  21850. TCDrain, 185                        TMemoryStream.Write, 234
  21851. TCFlow, 185                         TObject.Done, 215
  21852. TCFlush, 185                        TObject.Free, 215
  21853. TCGetAttr, 186                      TObject.Init, 215
  21854. TCGetPGrp, 186                      transfer bu er, 89
  21855.  
  21856.                              364
  21857.  
  21858.  
  21859.  
  21860.                                                                         INDEX
  21861.  
  21862.  
  21863. TRect.Assign, 214                           TStream.WriteStr, 221
  21864. TRect.Contains, 211                         TStringCollection.Compare, 254
  21865. TRect.Copy, 211                             TStringCollection.FreeItem, 255
  21866. TRect.Empty, 210                            TStringCollection.GetItem, 254
  21867. TRect.Equals, 211                           TStringCollection.PutItem, 255
  21868. TRect.Grow, 214                             TStringList.Done, 263
  21869. TRect.Intersect, 212                        TStringList.Get, 263
  21870. TRect.Move, 213                             TStringList.Load, 263
  21871. TRect.Union, 212                            TStrListMaker.Done, 264
  21872. TResourceCollection.FreeItem, 259           TStrListMaker.Init, 264
  21873. TResourceCollection.GetItem, 259            TStrListMaker.Put, 264
  21874. TResourceCollection.KeyOf, 259              TStrListMaker.Store, 264
  21875. TResourceCollection.PutItem, 260            TTYName, 187
  21876. TResourceFile.Count, 261                    TUnSortedStrCollection.Insert, 258
  21877. TResourceFile.Delete, 262
  21878. TResourceFile.Done, 261                     Umask, 188
  21879. TResourceFile.Flush, 262                    Uname, 188
  21880. TResourceFile.Get, 261                      UnLink, 188
  21881. TResourceFile.Init, 260                     unlock code, 89
  21882. TResourceFile.KeyAt, 261                    unlock data, 89
  21883. TResourceFile.Put, 262                      unlock linear region, 90
  21884. TResourceFile.SwitchTo, 261                 UnPackTime, 49
  21885. Trim, 357                                   UpperCase, 359
  21886. TrimLeft, 358                               Utime, 189
  21887. TrimRight, 358
  21888. TSortedCollection.Compare, 250              WaitPid, 190
  21889. TSortedCollection.IndexOf, 250              WhereX, 30
  21890. TSortedCollection.Init, 249                 WhereY, 31
  21891. TSortedCollection.Insert, 252               Window, 31
  21892. TSortedCollection.KeyOf, 250
  21893. TSortedCollection.Load, 250
  21894. TSortedCollection.Search, 251
  21895. TSortedCollection.Store, 253
  21896. TStrCollection.Compare, 256
  21897. TStrCollection.FreeItem, 257
  21898. TStrCollection.GetItem, 256
  21899. TStrCollection.PutItem, 257
  21900. TStream.Close, 220
  21901. TStream.CopyFrom, 223
  21902. TStream.Error, 222
  21903. TStream.Flush, 220
  21904. TStream.Get, 217
  21905. TStream.GetPos, 218
  21906. TStream.GetSize, 219
  21907. TStream.Open, 220
  21908. TStream.Put, 221
  21909. TStream.Read, 222
  21910. TStream.ReadStr, 219
  21911. TStream.Reset, 220
  21912. TStream.Seek, 222
  21913. TStream.StrRead, 217
  21914. TStream.StrWrite, 221
  21915. TStream.Truncate, 221
  21916. TStream.Write, 223
  21917.  
  21918.                                      365
  21919.  
  21920.  
  21921.  
  21922.