home *** CD-ROM | disk | FTP | other *** search
/ Merciful 5 / Merciful - Disc 5.iso / software / p / pcqpascalv1.2d.lha / Docs / PCQ.lib.DOC < prev    next >
Encoding:
Text File  |  1991-09-19  |  135.0 KB  |  6,343 lines
  1.  
  2.  
  3.     PCQ.LIB.DOC
  4.  
  5. This file contains descriptions of all the routines that are
  6. either internal to PCQ Pascal, or defined in the Include:Utils
  7. directory.  The routines defined in other directories are all
  8. described in Commodore's AutoDocs, which I recommend that you get
  9. (see Pascal.DOC for information on ordering it from Commodore).
  10.  
  11. This file is organized just like the AutoDocs, in a format that is
  12. compatible with DME's REF feature.  Each function takes the
  13. following form:
  14.  
  15.  
  16.  
  17. Directory/RoutineName            Directory/RoutineNm
  18.  
  19. NAME
  20.     The routine name, with a short description
  21.  
  22. SYNOPSIS
  23.     The actual Pascal declaration of the routine
  24.  
  25. DESCRIPTION
  26.     Comments about the routine
  27.  
  28. EXAMPLE
  29.     A short example program, or a reference to one of the programs
  30.     in the Example directory.
  31.  
  32. INPUT
  33.     A description of each of the parameters
  34.  
  35. RESULT
  36.     For functions, a description of the returned value
  37.  
  38. BUGS
  39.     Any known bugs of the function
  40.  
  41. SEE ALSO
  42.     A list of related routines
  43.  
  44.  
  45. Note that procedures and functions defined internally in PCQ
  46. Pascal are listed as PCQ/RoutineName.
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.                         TABLE OF CONTENTS
  55.  
  56. PCQ/Abs
  57. PCQ/Adr
  58. Utils/StringLib/AllocString
  59. Utils/DOSUtils/APTRtoBPTR
  60. PCQ/ArcTan
  61. Utils/CRT/AttachConsole
  62. Utils/BuildMenu/AttachMenu
  63. PCQ/Bit
  64. Utils/DOSUtils/BPTRtoAPTR
  65. PCQ/Ceil
  66. Utils/Break/CheckBreak
  67. PCQ/Chr
  68. PCQ/Close
  69. Utils/ConsoleUtils/CloseConsoleDevice
  70. Utils/DoubleBuffer/CloseDoubleBuffer
  71. Utils/MathTransUtils/CloseMathTrans
  72. Utils/CRT/ClrEOL
  73. Utils/CRT/ClrScr
  74. Utils/ConsoleIO/ConGetChar
  75. Utils/ConsoleIO/ConPutChar
  76. Utils/ConsoleIO/ConPutStr
  77. Utils/ConsoleIO/ConWrite
  78. PCQ/Cos
  79. Utils/CRC16/CRCCheck
  80. Utils/IOUtils/CreatePort
  81. Utils/IOUtils/CreateStdIO
  82. Utils/TaskUtils/CreateTask
  83. Utils/TimerUtils/CreateTimer
  84. Utils/CRT/CursOff
  85. Utils/CRT/CursOn
  86. Utils/DeadKeyConvert/DeadKeyConvert
  87. PCQ/Dec
  88. Utils/IOUtils/DeletePort
  89. Utils/IOUtils/DeleteStdIO
  90. Utils/TaskUtils/DeleteTask
  91. Utils/TimerUtils/DeleteTimer
  92. Utils/CRT/DelLine
  93. Utils/CRT/DetachConsole
  94. Utils/BuildMenu/DetachMenu
  95. PCQ/Dispose
  96. Utils/BuildMenu/DisposeMenu
  97. PCQ/EOF
  98. PCQ/Exit
  99. PCQ/Exp
  100. Utils/RunProgram/FinishProgram
  101. PCQ/Float
  102. PCQ/Floor
  103. Utils/MathTransUtils/FlushMathTrans
  104. Utils/PCQMemory/FreePCQMem
  105. Utils/StringLib/FreeString
  106. PCQ/Get
  107. Utils/DateTools/GetDescription
  108. Utils/DOSUtils/GetFileHandle
  109. Utils/PCQMemory/GetMem
  110. Utils/Parameters/GetParam
  111. Utils/Parameters/GetStartupMsg
  112. Utils/TimerUtils/GetSysTime
  113. Utils/CRT/GotoXY
  114. Utils/StringLib/Hash
  115. PCQ/Inc
  116. Utils/BuildMenu/InitializeMenu
  117. Utils/CRT/InsLine
  118. Utils/StringLib/IntToStr
  119. Utils/StringLib/isalnum
  120. Utils/StringLib/isalpha
  121. Utils/StringLib/isdigit
  122. Utils/StringLib/islower
  123. Utils/StringLib/isspace
  124. Utils/StringLib/isupper
  125. Utils/CRT/KeyPressed
  126. PCQ/Ln
  127. Utils/CRT/MaxX
  128. Utils/CRT/MaxY
  129. PCQ/New
  130. Utils/BuildMenu/NewItem
  131. Utils/BuildMenu/NewMenu
  132. Utils/BuildMenu/NewSubItem
  133. PCQ/Open
  134. Utils/ConsoleUtils/OpenConsoleDevice
  135. Utils/DoubleBuffer/OpenDoubleBuffer
  136. Utils/MathTransUtils/OpenMathTrans
  137. PCQ/Ord
  138. PCQ/Pred
  139. Utils/RunProgram/ProgramFinished
  140. PCQ/Put
  141. Utils/ConsoleIO/QueueRead
  142. Utils/Random/RangeRandom
  143. PCQ/Read
  144. Utils/CRT/ReadKey
  145. PCQ/Readln
  146. Utils/Random/RealRandom
  147. PCQ/ReOpen
  148. PCQ/Reset
  149. PCQ/Rewrite
  150. PCQ/Round
  151. Utils/RunProgram/RunProgram
  152. Utils/RunProgram/RunProgramNW
  153. Utils/RunProgram/RunSegment
  154. Utils/RunProgram/RunSegmentNW
  155. Utils/SameName/SameName
  156. Utils/Random/SelfSeed
  157. Utils/TimerUtils/SetTimer
  158. PCQ/Sin
  159. PCQ/SizeOf
  160. PCQ/Sqr
  161. PCQ/Sqrt
  162. Utils/DateTools/StampDesc
  163. Utils/StringLib/strcat
  164. Utils/StringLib/strcmp
  165. Utils/StringLib/strcpy
  166. Utils/StringLib/strdup
  167. Utils/StringLib/streq
  168. Utils/StringLib/stricmp
  169. Utils/StringLib/strieq
  170. Utils/StringLib/strlen
  171. Utils/StringLib/strncat
  172. Utils/StringLib/strncmp
  173. Utils/StringLib/strncpy
  174. Utils/StringLib/strneq
  175. Utils/StringLib/strnicmp
  176. Utils/StringLib/strnieq
  177. Utils/StringLib/strpos
  178. Utils/StringLib/strrpos
  179. PCQ/Succ
  180. Utils/DoubleBuffer/SwapBuffers
  181. PCQ/Tan
  182. Utils/CRT/TextBackground
  183. Utils/CRT/TextColor
  184. Utils/DateTools/TimeDesc
  185. Utils/StringLib/tolower
  186. Utils/StringLib/toupper
  187. PCQ/Trap
  188. PCQ/Trunc
  189. Utils/CRC16/UpdCRC
  190. Utils/Random/UseSeed
  191. PCQ/VA_Arg
  192. PCQ/VA_Start
  193. Utils/TimerUtils/WaitTimer
  194. Utils/CRT/WhereX
  195. Utils/CRT/WhereY
  196. PCQ/Write
  197. PCQ/Writeln
  198.  
  199.  
  200.  
  201. PCQ/Abs                    PCQ/Abs
  202.  
  203.     NAME
  204.     Abs - return the absolute value of a numeric expression
  205.  
  206.     SYNOPSIS
  207.     Function Abs(Expr : Any numeric expression) : The same type;
  208.  
  209.     DESCRIPTION
  210.     The Abs() function takes the absolute value of the
  211.     expression Expr.  If Expr is greater than or equal to
  212.     zero it returns Expr, and otherwise it returns -Expr.
  213.  
  214.     EXAMPLE
  215.  
  216.     Program ShowAbs;
  217.     var
  218.         n : Real;
  219.     begin
  220.         Write('Enter a number: ');
  221.         Readln(n);
  222.         Writeln('The absolute value is: ', Abs(n));
  223.     end.
  224.  
  225.     INPUTS
  226.  
  227.     Expr  : Any numeric expression
  228.  
  229.     RESULTS
  230.     A non-negative number of the same type as Expr
  231.  
  232.     BUGS
  233.  
  234.     SEE ALSO
  235.  
  236.  
  237. PCQ/Adr                    PCQ/Adr
  238.  
  239.     NAME
  240.     Adr - return the address of a variable
  241.  
  242.     SYNOPSIS
  243.     Function Adr(VAR V : Any type) : Address;
  244.  
  245.     DESCRIPTION
  246.     The Adr function returns the address of the variable
  247.     V.  You can also use the address-of operator @ for
  248.     the same purpose.
  249.  
  250.     EXAMPLE
  251.  
  252.     Program ShowAdr;
  253.     var
  254.         h : Char;
  255.     begin
  256.         Writeln('Address of H is ', Integer(Adr(h)));
  257.     end.
  258.  
  259.     INPUTS
  260.  
  261.     V     : Any variable, of any type.
  262.  
  263.     RESULTS
  264.     The address of V.
  265.  
  266.     BUGS
  267.  
  268.     SEE ALSO
  269.  
  270.  
  271. Utils/StringLib/AllocString        Utils/StringLib/AllocString
  272.  
  273.     NAME
  274.     AllocString - allocate memory for a string
  275.  
  276.     SYNOPSIS
  277.     Function AllocString(Size : Integer) : String;
  278.  
  279.     DESCRIPTION
  280.     AllocString allocates a block of memory at least Size
  281.     bytes, and returns a pointer to it.  This memory is
  282.     allocated using PCQ's memory allocator, which means
  283.     that HeapError could come into play, and that the
  284.     memory will automatically be returned to the system
  285.     at the end of the program.
  286.  
  287.     Since AllocString uses PCQ memory allocation, each
  288.     allocation will use from 12 to 20 extra bytes.  Thus
  289.     if you are allocating lots of strings and can keep
  290.     track of them through some other means, you might
  291.     want to call AllocMem directly.
  292.  
  293.     EXAMPLE
  294.  
  295.     Program Allocator;
  296.     {$I "Include:Utils/StringLib.i"}
  297.     var
  298.         Str : String;
  299.     begin
  300.         Str := AllocString(256);
  301.     end. { The memory is automatically freed }
  302.  
  303.     INPUTS
  304.  
  305.     Size : The number of bytes to allocate.
  306.  
  307.     RESULTS
  308.     A pointer to the newly allocated memory, or possibly
  309.     Nil if you have set up HeapError appropriately.
  310.  
  311.     BUGS
  312.  
  313.     SEE ALSO
  314.     GetMem, AllocMem
  315.  
  316.  
  317. Utils/DOSUtils/APTRtoBPTR        Utils/DOSUtils/APTRtoBPTR
  318.  
  319.     NAME
  320.     APTRtoBPTR - convert an Address into a BCPL pointer
  321.  
  322.     SYNOPSIS
  323.     Function APTRtoBPTR(a : Address) : BPTR;
  324.  
  325.     DESCRIPTION
  326.     This function converts a normal Amiga Address into its
  327.     equivalent BCPL pointer, or BPTR.  BCPL apparently
  328.     looks at memory as a big array of longwords, Addresses
  329.     have to be divided by four to be valid BPTRs.  This
  330.     also means that BPTRs should never point to a memory
  331.     location that is not longword aligned.
  332.  
  333.     EXAMPLE
  334.  
  335.     Program Convert;
  336.     {$I "Include:Utils/DOSUtils.i"}
  337.     var
  338.         a : Address;
  339.         b : Integer;
  340.     begin
  341.         Write('Enter a decimal address: ');
  342.         Readln(b);
  343.         a := Address(b);
  344.         Writeln('The equivalent BPTR is ', Integer(APTRtoBPTR(a)));
  345.     end.
  346.  
  347.     INPUTS
  348.  
  349.     a     : A normal Amiga Address
  350.  
  351.     RESULTS
  352.     The equivalent BPTR, which is just (a shr 2)
  353.  
  354.     BUGS
  355.  
  356.     SEE ALSO
  357.     BPTRtoAPTR
  358.  
  359.  
  360. PCQ/ArcTan                PCQ/ArcTan
  361.  
  362.     NAME
  363.     ArcTan - computes the arctangent in radians of the argument
  364.  
  365.     SYNOPSIS
  366.     Function ArcTan(Value : Real) : Real;
  367.  
  368.     DESCRIPTION
  369.     The ArcTan function computes the principal arctangent of the
  370.     specified value.  The result is in radians.
  371.  
  372.     If you have used the $N+ option this value will be computed
  373.     by the mathtrans.library.  Otherwise, internal PCQ routines
  374.     will be used.
  375.  
  376.     EXAMPLE
  377.  
  378.     Program ShowArcTan;
  379.     var
  380.         Value : Real;
  381.     begin
  382.         Write('Please enter a value: ');
  383.         Readln(Value);
  384.         Writeln('ArcTan(', Value:0:3, ') = ', ArcTan(Value):0:3);
  385.     end.
  386.  
  387.     INPUTS
  388.  
  389.     Value : A Real type expression
  390.  
  391.     RESULTS
  392.     The principal arctangent, in radians.
  393.  
  394.     BUGS
  395.  
  396.     SEE ALSO
  397.     Sin, Cos, Tan
  398.  
  399. Utils/CRT/AttachConsole            Utils/CRT/AttachConsole
  400.  
  401.     NAME
  402.     AttachConsole - initialize the CRT routines for a window
  403.  
  404.     SYNOPSIS
  405.     Function AttachConsole(w : WindowPtr) : Address;
  406.  
  407.     DESCRIPTION
  408.     AttachConsole is used to set up all the structures needed
  409.     by the rest of the CRT routines.  It must be called before
  410.     any of the other routines.
  411.  
  412.     The address it returns points to a record used to store all
  413.     the vital information the rest of the routines will need.
  414.     You will pass this address to all the other CRT routines.
  415.  
  416.     EXAMPLE
  417.     see Examples/Map.p and Examples/ConsoleTest.p
  418.  
  419.     INPUTS
  420.     w : a pointer to a valid (open) Window.
  421.  
  422.     RESULTS
  423.     The address of a bookkeeping record, or Nil if anything
  424.     goes wrong.
  425.  
  426.     SEE ALSO
  427.     ClrEOL, ClrScr, CursOff, CursOn, DetachConsole, GotoXY,
  428.     InsLine, KeyPressed, MaxX, MaxY, ReadKey, TextColor,
  429.     TextBackground, WhereX, WhereY, WriteString
  430.  
  431.  
  432. Utils/BuildMenu/AttachMenu        Utils/BuildMenu/AttachMenu
  433.  
  434.     NAME
  435.     AttachMenu - attach a BuildMenu menu to its window
  436.  
  437.     SYNOPSIS
  438.     Procedure AttachMenu;
  439.  
  440.     DESCRIPTION
  441.     AttachMenu makes a menu defined using the NewMenu,
  442.     NewItem and other routines available to the user.
  443.     You must, of course, have already called InitializeMenu
  444.     and defined the menu using NewMenu and NewItem calls.
  445.  
  446.     You will need to set the IDCMP flag MENUPICK_f in order
  447.     to receive messages from Intuition about this menu.  You
  448.     can set the flag in the NewWindow structure, or through
  449.     a call to ModifyIDCMP.
  450.  
  451.     EXAMPLE
  452.     See Examples/SmallCom.p, Examples/ConsoleTest.p,
  453.         Examples/DeadKeysPlus.p
  454.  
  455.     INPUTS
  456.     None
  457.  
  458.     RESULTS
  459.     None
  460.  
  461.     SEE ALSO
  462.     InitializeMenu, DisposeMenu, NewMenu, NewItem,
  463.     NewSubItem, DetachMenu
  464.  
  465.  
  466. PCQ/Bit                    PCQ/Bit
  467.  
  468.     NAME
  469.     Bit - return an Integer with only the specified bit set.
  470.  
  471.     SYNOPSIS
  472.     Function Bit(BitNumber : Integer) : Integer;
  473.  
  474.     DESCRIPTION
  475.     The Bit function returns an Integer value that has only
  476.     the specified bit set.  The bit number must therefore
  477.     be in the range 0 to 31.  This function is identical to
  478.     the expression (1 shl BitNumber).
  479.  
  480.     EXAMPLE
  481.  
  482.     Program ShowBit;
  483.     var
  484.         BitNum : Integer;
  485.     begin
  486.         for BitNum := 0 to 31 do
  487.         Writeln('Bit ', BitNum, ' set = ', Bit(BitNum));
  488.     end.
  489.  
  490.     INPUTS
  491.  
  492.     BitNum : An Integer in the range 0 to 31.
  493.  
  494.     RESULTS
  495.     An Integer with just the specified bit set.
  496.  
  497.     BUGS
  498.  
  499.     SEE ALSO
  500.     shl, shr
  501.  
  502. Utils/DOSUtils/BPTRtoAPTR        Utils/DOSUtils/BPTRtoAPTR
  503.  
  504.     NAME
  505.     BPTRtoAPTR - convert a BCPL pointer to an Address
  506.  
  507.     SYNOPSIS
  508.     Function BPTRtoAPTR(b : BPTR) : Address;
  509.  
  510.     DESCRIPTION
  511.     This function converts a BCPL pointer value into its
  512.     equivalent Amiga address by multiplying the BPTR by
  513.     four.
  514.  
  515.     EXAMPLE
  516.  
  517.     Program LocateInput;
  518.     {$I "Include:Utils/DOSUtils.i"}
  519.     begin
  520.         Writeln('The input file handle is at ',
  521.             Integer(BPTRtoAPTR(GetFileHandle(Input))));
  522.     end.
  523.  
  524.     INPUTS
  525.  
  526.     b     : A BCPL pointer value, e.g. from an AmigaDOS record
  527.  
  528.     RESULTS
  529.     The equivalent Amiga Address, which is just (b shl 4)
  530.  
  531.     BUGS
  532.  
  533.     SEE ALSO
  534.     APTRtoBPTR
  535.  
  536.  
  537. PCQ/Ceil                PCQ/Ceil
  538.  
  539.     NAME
  540.     Ceil - return the least whole number greater than or equal
  541.  
  542.     SYNOPSIS
  543.     Function Ceil(Expr : Real) : Real;
  544.  
  545.     DESCRIPTION
  546.     The Ceil function returns the least whole number, expressed
  547.     as a Real value, greater than or equal to the number passed
  548.     in.
  549.  
  550.     EXAMPLE
  551.  
  552.     Program ShowCeil;
  553.     var
  554.         FloatValue : Real;
  555.     begin
  556.         Write('Please enter a Real value: ');
  557.         Readln(FloatValue);
  558.         Writeln(FloatValue:0:3, ' becomes ',
  559.                 Ceil(FloatValue):0:3);
  560.     end.
  561.  
  562.     Ceil(5.4)  =  6.0
  563.     Ceil(-5.4) = -5.0
  564.  
  565.     INPUTS
  566.  
  567.     Expr : Any Real type expression
  568.  
  569.     RESULTS
  570.     A Real value that is the least whole number greater than
  571.     or equal to Expr.
  572.  
  573.     BUGS
  574.  
  575.     SEE ALSO
  576.     Floor, Trunc, Round, Float
  577.  
  578.  
  579. Utils/Break/CheckBreak            Utils/Break/CheckBreak
  580.  
  581.     NAME
  582.     CheckBreak - check if user struck CTRL-C
  583.  
  584.     SYNOPSIS
  585.     Function CheckBreak;
  586.  
  587.     DESCRIPTION
  588.     This routine checks for the SIGBREAK_C signal in the
  589.     Task structure, and returns TRUE if it is found.
  590.  
  591.     CheckBreak will only return true for routines that
  592.     have a console open, since the console.device is what
  593.     actually sets the SIGBREAK_C flag.
  594.  
  595.     EXAMPLE
  596.  
  597.     Program Test;
  598.     {$I "Include:Utils/BuildMenu/Break.i"}
  599.     begin
  600.         while not CheckBreak do
  601.         Write('Waiting');
  602.     end.
  603.  
  604.     INPUTS
  605.     None
  606.  
  607.     RESULTS
  608.     TRUE if the user has pressed CTRL-C, or
  609.     FALSE if it hasn't been pressed, or if the console.device
  610.         wasn't in use.
  611.  
  612.     SEE ALSO
  613.  
  614.  
  615. PCQ/Chr                    PCQ/Chr
  616.  
  617.     NAME
  618.     Chr - convert a number to its corresponding Char value
  619.  
  620.     SYNOPSIS
  621.     Function Chr(Expr : Any numeric expression) : Char;
  622.  
  623.     DESCRIPTION
  624.     The Chr() function converts a numeric expression into
  625.     a character based on its ASCII value.
  626.  
  627.     EXAMPLE
  628.  
  629.     Program ShowChr;
  630.     var
  631.         n : Real;
  632.     begin
  633.         Write('Enter a number: ');
  634.         Readln(n);
  635.         Write('That corresponds to the character: ', Chr(n));
  636.     end.
  637.  
  638.     INPUTS
  639.  
  640.     Expr  : Any numeric expression
  641.  
  642.     RESULTS
  643.     The corresponding character
  644.  
  645.     BUGS
  646.  
  647.     SEE ALSO
  648.  
  649.  
  650. PCQ/Close                PCQ/Close
  651.  
  652.     NAME
  653.     Close - completes access to a PCQ file
  654.  
  655.     SYNOPSIS
  656.     Procedure Close(VAR F : Any file type);
  657.  
  658.     DESCRIPTION
  659.     Close writes any pending output to the file, closes
  660.     the associated AmigaDOS file, and frees the file
  661.     buffer.
  662.  
  663.     If you do not close a PCQ file, it will be closed
  664.     automatically at the end of the program.
  665.  
  666.     EXAMPLE
  667.  
  668.     Program Closer;
  669.     var
  670.         F : Text;
  671.     begin
  672.         if Open("CON:0/0/640/320/TempOutput",F) then begin
  673.         Writeln(F,'The window is open.  Hit a key.');
  674.         Readln(F);
  675.         Close(F);
  676.         end else
  677.         Writeln('Could not open file');
  678.     end.
  679.  
  680.     INPUTS
  681.  
  682.     F     : An open PCQ file variable, either a type file or
  683.         a Text file.
  684.  
  685.     RESULTS
  686.     None
  687.  
  688.     BUGS
  689.  
  690.     SEE ALSO
  691.     Open, Reopen, Reset, Rewrite
  692.  
  693.  
  694. Utils/ConsoleUtils/CloseConsoleDevice    Utils/ConsoleUtils/CloseConsoleDevice
  695.  
  696.     NAME
  697.     CloseConsoleDevice - close the console.device
  698.  
  699.     SYNOPSIS
  700.     Procedure CloseConsoleDevice;
  701.  
  702.     DESCRIPTION
  703.     This routine closes the console.device opened by a call to
  704.     OpenConsoleDevice.
  705.  
  706.     EXAMPLE
  707.     See Examples/SmallCom.p, Examples/3d.p, Examples/Map.p
  708.  
  709.     INPUTS
  710.     None
  711.  
  712.     RESULTS
  713.     None
  714.  
  715.     SEE ALSO
  716.     OpenConsoleDevice, DeadKeyConvert
  717.  
  718.  
  719. Utils/DoubleBuffer/CloseDoubleBuffer    Utils/DoubleBuffer/CloseDoubleBuffer
  720.  
  721.     NAME
  722.     CloseDoubleBuffer - closes a double-buffered window and screen
  723.  
  724.     SYNOPSIS
  725.     Procedure CloseDoubleBuffer(w : WindowPtr);
  726.  
  727.     DESCRIPTION
  728.     This routine frees up all the resources allocated by a call
  729.     to OpenDoubleBuffer.  It closes the Screen and the Window,
  730.     and frees the memory used for the extra buffer.
  731.  
  732.     You should not call this routine on normal windows, and you
  733.     should not use the normal CloseWindow and CloseScreen calls
  734.     on Windows and Screens created with OpenDoubleBuffer.
  735.  
  736.     EXAMPLE
  737.     See Examples/3d.p
  738.  
  739.     INPUTS
  740.  
  741.     w     : A pointer to a Window opened with a call to
  742.         OpenDoubleBuffer.
  743.  
  744.     RESULTS
  745.     None
  746.  
  747.     BUGS
  748.  
  749.     SEE ALSO
  750.     OpenDoubleBuffer, SwapBuffers
  751.  
  752.  
  753. Utils/MathTransUtils/CloseMathTrans    Utils/MathTransUtils/CloseMathTrans
  754.  
  755.     NAME
  756.     CloseMathTrans - closes the FFP mathtrans.library
  757.  
  758.     SYNOPSIS
  759.     Procedure CloseMathTrans;
  760.  
  761.     DESCRIPTION
  762.     This routine closes the Motorola FFP transcendental library
  763.     opened by OpenMathTrans.  It is important that you call this
  764.     routine because the mathtrans.library is disk-based, and it
  765.     will not be unloaded from memory if it thinks someone is
  766.     still using it.
  767.  
  768.     EXAMPLE
  769.  
  770.     Program CheckTrans;
  771.     {$I "Include:Utils/MathTransUtils.i"}
  772.     {$I "Include:Libraries/MathTrans.i"}
  773.     begin
  774.         if OpenMathTrans then begin
  775.         Writeln('Pi is about ', SPAcos(-1.0));
  776.         CloseMathTrans;
  777.         end else
  778.         Writeln('mathtrans.library was unavailable');
  779.     end.
  780.  
  781.     INPUTS
  782.     None
  783.  
  784.     RESULTS
  785.     None
  786.  
  787.     BUGS
  788.  
  789.     SEE ALSO
  790.     OpenMathTrans, FlushMathTrans, and the mathtrans.library
  791.     routines like SPAsin, SPSqrt, etc.
  792.  
  793.  
  794. Utils/CRT/ClrEOL            Utils/CRT/ClrEOL
  795.  
  796.     NAME
  797.     ClrEOL - clear the screen from the cursor to the end of line
  798.  
  799.     SYNOPSIS
  800.     Procedure ClrEOL(CRT : Address);
  801.  
  802.     DESCRIPTION
  803.     This routine clears the text area from the cursor to the
  804.     end of the line.
  805.  
  806.     EXAMPLE
  807.  
  808.     Procedure CopyOver(CRT : Address);
  809.     begin
  810.         GotoXY(CRT, 1,WhereY);
  811.         WriteString(CRT, "This line is far too long");
  812.         GotoXY(CRT, 14,WhereY);
  813.         ClrEOL(CRT);
  814.         WriteString(CRT, "just right");
  815.     end;
  816.  
  817.     INPUTS
  818.  
  819.     CRT : A pointer to a valid CRT information block, as
  820.         returned by AttachConsole
  821.  
  822.     RESULTS
  823.     None
  824.  
  825.     SEE ALSO
  826.     AttachConsole, ClrScr, GotoXY, WriteString
  827.  
  828.  
  829. Utils/CRT/ClrScr            Utils/CRT/ClrScr
  830.  
  831.     NAME
  832.     ClrScr - clear the text area and move to 1,1
  833.  
  834.     SYNOPSIS
  835.     Procedure ClrScr(CRT : Address);
  836.  
  837.     DESCRIPTION
  838.     ClrScr clears the text area of the window, and moves the
  839.     cursor to the upper left hand corner.
  840.  
  841.     EXAMPLE
  842.  
  843.     Procedure ClearWindow(w : WindowPtr);
  844.     var
  845.         CRT : Address
  846.     begin
  847.         CRT := AttachConsole(w);
  848.         ClrScr(CRT);
  849.         DetachConsole(w);
  850.     end;
  851.  
  852.     INPUTS
  853.  
  854.     CRT : A pointer to a valid CRT information block, as
  855.           returned by AttachConsole.
  856.  
  857.     RESULTS
  858.     None
  859.  
  860.     SEE ALSO
  861.     AttachConsole, ClrEOL, GotoXY
  862.  
  863.  
  864. Utils/ConsoleIO/ConGetChar        Utils/ConsoleIO/ConGetChar
  865.  
  866.     NAME
  867.     ConGetChar - read a character from the console.device
  868.  
  869.     SYNOPSIS
  870.     Function ConGetChar(ConsolePort : MsgPortPtr;
  871.                 Request    : IOStdReqPtr;
  872.                 WhereTo    : String) : Char;
  873.  
  874.     DESCRIPTION
  875.     ConGetChar waits until a previous QueueRead is satified,
  876.     then queues up another and returns the character.
  877.  
  878.     You need to call OpenDevice to initialize Request and
  879.     attach the console.device to your window.
  880.  
  881.     EXAMPLE
  882.  
  883.     {$I "Include:Utils/IOUtils.i"}
  884.  
  885.     Function ReadOneCharacter(w : WindowPtr);
  886.     var
  887.         MyPort : MsgPortPtr;
  888.         MyReq  : IOStdReqPtr;
  889.         Buffer,
  890.         Value  : Char;
  891.         Error  : Integer;
  892.         Dummy  : MessagePtr;
  893.     begin
  894.         MyPort := CreatePort(Nil, 0);
  895.         MyReq  := CreateStdIO(MyPort);
  896.         MyReq^.io_Data := Address(w);
  897.         MyReq^.io_Length := SizeOf(Window);
  898.         Error := OpenDevice("console.device",0,
  899.                 IORequestPtr(MyReq), 0);
  900.         QueueRead(MyReq, @Buffer);
  901.         Value := ConGetChar(MyPort, MyReq, @Buffer);
  902.         if CheckIO(IORequestPtr(MyReq)) then begin
  903.         Error := AbortIO(IORequestPtr(MyReq));
  904.         Dummy := WaitPort(MyPort);
  905.         Dummy := GetMsg(MyPort);
  906.         end;
  907.         CloseDevice(MyReq);
  908.         DeleteStdIO(MyReq);
  909.         DeletePort(MyPort);
  910.         ReadOneCharacter := Value;
  911.     end;
  912.  
  913.     INPUTS
  914.     ConsolePort : A pointer to a valid MsgPort, the one used
  915.               by the IOStdReq used for QueueRead.
  916.     Request     : A pointer to a valid IOStdReq, which will be
  917.               used to reset QueueRead.
  918.     WhereTo     : A pointer to the buffer used by QueueRead,
  919.               which also will be used to reset QueueRead.
  920.  
  921.     RESULTS
  922.     The character read.
  923.  
  924.     SEE ALSO
  925.     ConPutChar, ConWrite, ConPutStr, QueueRead
  926.  
  927.  
  928. Utils/ConsoleIO/ConPutChar        Utils/ConsoleIO/ConPutChar
  929.  
  930.     NAME
  931.     ConPutChar - write one character to the console device
  932.  
  933.     SYNOPSIS
  934.     Procedure ConPutChar(Req : IOStdReqPtr; Character : Char);
  935.  
  936.     DESCRIPTION
  937.     This routine writes a single character through the console
  938.     device to a window.  You should already have called
  939.     OpenDevice to open the console.device and attach it to
  940.     your window.
  941.  
  942.     Note that for many applications, the routines in Utils/CRT.i
  943.     will be easier to use.
  944.  
  945.     EXAMPLE
  946.     see Examples/DeadKeysPlus.p
  947.  
  948.     INPUTS
  949.     Req : A pointer to a valid IOStdReq, initialized by a
  950.           call to OpenDevice.
  951.     Character : The Char to write.
  952.  
  953.     RESULTS
  954.     None
  955.  
  956.     SEE ALSO
  957.     ConWrite, ConPutStr, QueueRead, ConGetChar
  958.  
  959.  
  960. Utils/ConsoleIO/ConPutStr        Utils/ConsoleIO/ConPutStr
  961.  
  962.     NAME
  963.     ConPutStr - write a null-terminated string
  964.  
  965.     SYNOPSIS
  966.     Procedure ConPutStr(Req : IOStdReqPtr; Str : String);
  967.  
  968.     DESCRIPTION
  969.     ConPutStr writes a null-terminated string through the
  970.     console.device to the screen.  You must use OpenDevice
  971.     to attach the console.device to the window.
  972.  
  973.     EXAMPLE
  974.     see Examples/DeadKeysPlus.p
  975.  
  976.     INPUTS
  977.     Req : a pointer to a valid IOStdReq, initialized
  978.           by a call to OpenDevice.
  979.     Str : The string to write, which must be null-terminated.
  980.  
  981.     RESULTS
  982.     None
  983.  
  984.     SEE ALSO
  985.     ConPutChar, ConWrite, QueueRead, ConGetChar
  986.  
  987.  
  988. Utils/ConsoleIO/ConWrite        Utils/ConsoleIO/ConWrite
  989.  
  990.     NAME
  991.     ConWrite - write any amount of data to the console.device
  992.  
  993.     SYNOPSIS
  994.     Procedure ConWrite(Req    : IOStdReqPtr;
  995.                Str    : String;
  996.                Length : Integer);
  997.  
  998.     DESCRIPTION
  999.     ConWrite writes any amount of data to the console device.
  1000.     Although Str is defined as a string, it can in fact point
  1001.     to any arbitrary data and does not have to be null
  1002.     terminated.  If the data is already null-terminated and
  1003.     you don't know its length, you can call ConPutStr instead.
  1004.  
  1005.     Before you call this routine, you must use OpenDevice to
  1006.     attach the console.device to your window.
  1007.  
  1008.     EXAMPLE
  1009.     See Examples/SmallCom.p, Examples/DeadKeysPlus.p
  1010.  
  1011.     INPUTS
  1012.     Req : A pointer to a valid IOStdReq, initialized by a
  1013.           call to OpenDevice.
  1014.     Str : A pointer to any arbitrary data
  1015.     Length : The number of bytes to write.
  1016.  
  1017.     RESULTS
  1018.     None
  1019.  
  1020.     SEE ALSO
  1021.     ConPutChar, ConPutStr, QueueRead, ConGetChar
  1022.  
  1023.  
  1024. PCQ/Cos                    PCQ/Cos
  1025.  
  1026.     NAME
  1027.     Cos - compute the cosine of an angle in radians
  1028.  
  1029.     SYNOPSIS
  1030.     Function Cos(Radians : Real) : Real;
  1031.  
  1032.     DESCRIPTION
  1033.     This function returns the cosine of the specified
  1034.     angle.  Normally this is computed by private PCQ
  1035.     routines, but if you can use the $N+ directive to
  1036.     specify that mathtrans.library should be used
  1037.     instead.
  1038.  
  1039.     EXAMPLE
  1040.  
  1041.     Program ShowCos;
  1042.     var
  1043.         Value : Real;
  1044.     begin
  1045.         Write('Enter a number of DEGREES: ');
  1046.         Readln(Value);
  1047.         Writen('The cosine of ', Value:0:3, ' degrees is ',
  1048.             Cos(Value * (180 / 3.14159)):0:3);
  1049.     end.
  1050.  
  1051.     INPUTS
  1052.  
  1053.     Radians : The angle in radians
  1054.  
  1055.     RESULTS
  1056.     The cosine of the specified angle
  1057.  
  1058.     BUGS
  1059.  
  1060.     SEE ALSO
  1061.     Sin, Tan, ArcTan
  1062.  
  1063. Utils/CRC16/CRCCheck            Utils/CRC16/CRCCheck
  1064.  
  1065.     NAME
  1066.     CRCCheck - calculate the CRC of a buffer
  1067.  
  1068.     SYNOPSIS
  1069.     Function CRCCheck(Buffer : Address; Length : Integer) : Word;
  1070.  
  1071.     DESCRIPTION
  1072.     CRCCheck uses UpdCRC to calculate the CRC value for an
  1073.     entire buffer at once.  If you are processing data one byte
  1074.     at a time, you can use UpdCRC to calculate the CRC, but if
  1075.     you have the entire buffer at hand you can use this routine.
  1076.  
  1077.     EXAMPLE
  1078.  
  1079.     Program CRCStr;
  1080.     {$I "Include:Utils/CRC16.i"}
  1081.     {$I "Include:Utils/StringLib.i"}
  1082.     var
  1083.         Str : String;
  1084.     begin
  1085.         Str := AllocString(256);
  1086.         Write('Enter a string: ');
  1087.         ReadLn(Str);
  1088.         Writeln('The CRC of "', Str, '" is ',
  1089.             CRCCheck(Str, strlen(Str)));
  1090.     end.
  1091.  
  1092.     INPUTS
  1093.     Buffer : A pointer to the data buffer
  1094.     Length : The number of bytes to calculate
  1095.  
  1096.     RESULTS
  1097.     The CRC value of the entire buffer
  1098.  
  1099.     SEE ALSO
  1100.     UpdCRC
  1101.  
  1102.  
  1103. Utils/IOUtils/CreatePort        Utils/IOUtils/CreatePort
  1104.  
  1105.     NAME
  1106.     CreatePort - allocate a MsgPort
  1107.  
  1108.     SYNOPSIS
  1109.     Function CreatePort(Name : String; Pri : Integer) : MsgPortPtr;
  1110.  
  1111.     DESCRIPTION
  1112.     This routine allocates the memory and signal for a message
  1113.     port.  If you have specified a Name, it will also add the
  1114.     port to the system list (that's only necessary if some other
  1115.     task is going to search for your port).  If the Name is
  1116.     Nil, the port is not added.
  1117.  
  1118.     Since the memory for the port is not allocated through PCQ
  1119.     memory routines, you must call DeletePort explicitly or the
  1120.     memory will not be returned to the system.
  1121.  
  1122.     EXAMPLE
  1123.     See Examples/DeadKeysPlus.p and Examples/Play8.p
  1124.  
  1125.     INPUTS
  1126.  
  1127.     Name  : The port name, or Nil if you don't want to add the
  1128.         port to the Exec system list.
  1129.     Pri   : The port priority, which will determine where the
  1130.         port is added to the system list.
  1131.  
  1132.     RESULTS
  1133.     A MsgPortPtr or Nil if something went wrong
  1134.  
  1135.     BUGS
  1136.  
  1137.     SEE ALSO
  1138.     DeletePort
  1139.  
  1140.  
  1141. Utils/IOUtils/CreateStdIO        Utils/IOUtils/CreateStdIO
  1142.  
  1143.     NAME
  1144.     CreateStdIO - allocate an IOStdReq record
  1145.  
  1146.     SYNOPSIS
  1147.     Function CreateStdIO(Reply : MsgPortPtr) : IOStdReqPtr;
  1148.  
  1149.     DESCRIPTION
  1150.     This routine allocates and initializes an IOStdReq used by
  1151.     the Exec IO routines.  Since the memory is not allocated by
  1152.     the PCQ allocation routines, you must call DeleteStdIO or
  1153.     the memory will not be freed.
  1154.  
  1155.     EXAMPLE
  1156.     See Examples/SmallCom.p and Examples/DeadKeysPlus.p
  1157.  
  1158.     INPUTS
  1159.  
  1160.     Reply : A pointer to a valid MsgPort that will serve as the
  1161.         IO record's reply port.  The port can be created
  1162.         with CreatePort.
  1163.  
  1164.     RESULTS
  1165.     A pointer to an IOStdReq, or Nil if something went wrong.
  1166.  
  1167.     BUGS
  1168.  
  1169.     SEE ALSO
  1170.     DeleteStdIO, CreatePort
  1171.  
  1172.  
  1173. Utils/TaskUtils/CreateTask        Utils/TaskUtils/CreateTask
  1174.  
  1175.     NAME
  1176.     CreateTask - initialize a new task
  1177.  
  1178.     SYNOPSIS
  1179.     Function CreateTask(Name      : String;
  1180.                 Pri       : Byte;
  1181.                 InitialPC : Address;
  1182.                 StackSize : Integer) : TaskPtr;
  1183.  
  1184.     DESCRIPTION
  1185.     CreateTask initializes a new task and adds it to the
  1186.     system list.  Sometime later it will begin executing.
  1187.     Keep in mind that a task, not a process, is created,
  1188.     so it cannot use any AmigaDOS routines, directly or
  1189.     indirectly (e.g. through Pascal Write() or Read()
  1190.     calls).
  1191.  
  1192.     EXAMPLE
  1193.     See Examples/Task.p
  1194.  
  1195.     INPUTS
  1196.  
  1197.     Name      : The name for the new task
  1198.     Pri       : The new task's priority.  For most tasks this
  1199.             should be very low, say from -5 to 5 at most.
  1200.     InitialPC : The address of the beginning of the task.
  1201.     StackSize : The size in bytes of the stack that should be
  1202.             allocated for the new task.
  1203.  
  1204.     RESULTS
  1205.     If the task was successfully added, CreateTask returns a
  1206.     pointer to its Task record.  If not, it returns Nil.
  1207.  
  1208.     BUGS
  1209.  
  1210.     SEE ALSO
  1211.     DeleteTask, CreateProc
  1212.  
  1213.  
  1214. Utils/TimerUtils/CreateTimer        Utils/TimerUtils/CreateTimer
  1215.  
  1216.     NAME
  1217.     CreateTimer - open the timer.device and allocate an IO record
  1218.  
  1219.     SYNOPSIS
  1220.     Function CreateTimer(Unit : Integer) : TimeRequestPtr;
  1221.  
  1222.     DESCRIPTION
  1223.     CreateTimer opens the timer.device, allocates and initializes
  1224.     an IO structure, and passes back the IO structure address to
  1225.     use with the other TimerUtils routines.
  1226.  
  1227.     This routine initializes TimerBase, so you can also call
  1228.     SubTime, AddTime, etc.
  1229.  
  1230.     EXAMPLE
  1231.     See Examples/Dry.p, Examples/TimerTest.p, Examples/TimeProg.p
  1232.  
  1233.     INPUTS
  1234.  
  1235.     Unit  : The unit of the timer.device that should be used.  This
  1236.         can be either UNIT_MICROHZ (0), which is highly
  1237.         accurate, or UNIT_VBLANK (1), which has less resolution
  1238.         but much less overhead.  UNIT_VBLANK should not be used
  1239.         if you intend to measure small time differences, less
  1240.         than a half second.
  1241.  
  1242.     RESULTS
  1243.     If everything goes correctly, CreateTimer returns a pointer
  1244.     to an initialized TimeRequest, or Nil if something went
  1245.     wrong.
  1246.  
  1247.     BUGS
  1248.  
  1249.     SEE ALSO
  1250.     DeleteTimer, SetTimer, WaitTimer, GetSysTime
  1251.  
  1252.  
  1253. Utils/CRT/CursOff            Utils/CRT/CursOff
  1254.  
  1255.     NAME
  1256.     CursOff - turn the text cursor off
  1257.  
  1258.     SYNOPSIS
  1259.     Procedure CursOff(CRT : Address);
  1260.  
  1261.     DESCRIPTION
  1262.     Normally a console window displays a full-block text
  1263.     cursor.  This routine turns it off.
  1264.  
  1265.     EXAMPLE
  1266.     See Examples/Map.p
  1267.  
  1268.     INPUTS
  1269.  
  1270.     CRT   : A pointer to a valid CRT information block,
  1271.         as returned by AttachConsole.
  1272.  
  1273.     RESULTS
  1274.     None
  1275.  
  1276.     SEE ALSO
  1277.     AttachConsole, CursOn
  1278.  
  1279.  
  1280. Utils/CRT/CursOn            Utils/CRT/CursOn
  1281.  
  1282.     NAME
  1283.     CursOn - turn the text cursor on
  1284.  
  1285.     SYNOPSIS
  1286.     Procedure CursOn(CRT : Address);
  1287.  
  1288.     DESCRIPTION
  1289.     This routine turns the console.device's text cursor
  1290.     on.  It starts out on, so the only reason you'll need
  1291.     to call this routine is if you have previously called
  1292.     CursOff.
  1293.  
  1294.     EXAMPLE
  1295.     See Examples/Map.p
  1296.  
  1297.     INPUTS
  1298.  
  1299.     CRT   : A pointer to a valid CRT information block, as
  1300.         returned by AttachConsole.
  1301.  
  1302.     RESULTS
  1303.     None
  1304.  
  1305.     SEE ALSO
  1306.     AttachConsole, CursOff
  1307.  
  1308.  
  1309. Utils/DeadKeyConvert/DeadKeyConvert    Utils/DeadKeyConvert/DeadKeyConvert
  1310.  
  1311.     NAME
  1312.     DeadKeyConvert - convert raw key event to complete key sequence
  1313.  
  1314.     SYNOPSIS
  1315.     Function DeadKeyConvert(Msg     : IntuiMessagePtr;
  1316.                 Buffer  : String;
  1317.                 BufSize : Integer;
  1318.                 KeyMap  : Address) : Integer;
  1319.  
  1320.     DESCRIPTION
  1321.     This function takes an Intuition RAWKEY_f IDCMP message,
  1322.     and converts it into a finished command sequence.  The
  1323.     single keypress in the message is converted into zero
  1324.     or more characters in the Buffer, according to an optional
  1325.     KeyMap.
  1326.  
  1327.     EXAMPLE
  1328.     See Examples/DeadKeysPlus.p, Examples/Map.p, Examples/3d.p
  1329.         Examples/SmallCom.p
  1330.  
  1331.     INPUTS
  1332.  
  1333.     Msg     : A pointer to an Intuition IDCMP message of class
  1334.           RAWKEY_f
  1335.     Buffer  : The buffer that will hold the converted keystrokes
  1336.     BufSize : The size in bytes of the buffer
  1337.     KeyMap  : Either a pointer to a valid KeyMap, or Nil to use
  1338.           the standard KeyMap
  1339.  
  1340.     RESULTS
  1341.  
  1342.     -2 if it was not a RAWKEY_f message
  1343.     -1 if there was a buffer overflow
  1344.     Otherwise, it returns the number of characters 0..BufSize
  1345.     in the converted sequence
  1346.  
  1347.     BUGS
  1348.     If you get a buffer overflow (i.e. it returns -1) the
  1349.     characters in the buffer are not valid
  1350.  
  1351.     SEE ALSO
  1352.     RawKeyConvert
  1353.  
  1354.  
  1355. PCQ/Dec                    PCQ/Dec
  1356.  
  1357.     NAME
  1358.     Dec - subtract from a variable
  1359.  
  1360.     SYNOPSIS
  1361.     Procedure Dec(VAR v : Any Integer or pointer type
  1362.             [ ; Amount : Integer ] );
  1363.  
  1364.     DESCRIPTION
  1365.     The Dec procedure subtracts from a variable.  If the
  1366.     variable is an Integer type, Dec subtracts Amount from
  1367.     it, or 1 if there is no Amount specified.
  1368.  
  1369.     If v is a pointer type, Dec subtracts the size of the
  1370.     element referred to by v multiplied by Amount.  That
  1371.     way you can easily move a pointer along an array.
  1372.  
  1373.     EXAMPLE
  1374.  
  1375.     Program ShowDec;
  1376.     var
  1377.         i : Integer;
  1378.         s : Short;
  1379.         p : ^Integer;
  1380.         q : ^Short;
  1381.     begin
  1382.         Dec(i);      { i := i - 1 }
  1383.         Dec(s,i);    { i := i - s }
  1384.         Dec(p);      { p := p - 4 }
  1385.         Dec(q,s);    { q := q - s*2 }
  1386.     end.
  1387.  
  1388.     INPUTS
  1389.  
  1390.     v      : A variable Integer or pointer
  1391.     Amount : An optional amount to be subtracted
  1392.  
  1393.     RESULTS
  1394.     None
  1395.  
  1396.     BUGS
  1397.  
  1398.     SEE ALSO
  1399.     Inc
  1400.  
  1401. Utils/IOUtils/DeletePort        Utils/IOUtils/DeletePort
  1402.  
  1403.     NAME
  1404.     DeletePort - free the resources of a MsgPort
  1405.  
  1406.     SYNOPSIS
  1407.     Procedure DeletePort(Port : MsgPortPtr);
  1408.  
  1409.     DESCRIPTION
  1410.     This routine frees the memory and signal used by the
  1411.     MsgPort, and removes it from the system list if
  1412.     appropriate.
  1413.  
  1414.     EXAMPLE
  1415.     See Examples/DeadKeysPlus.p and Examples/Play8.p
  1416.  
  1417.     INPUTS
  1418.  
  1419.     Port  : A pointer to the MsgPort to close
  1420.  
  1421.     RESULTS
  1422.     None
  1423.  
  1424.     BUGS
  1425.  
  1426.     SEE ALSO
  1427.     CreatePort
  1428.  
  1429.  
  1430. Utils/IOUtils/DeleteStdIO        Utils/IOUtils/DeleteStdIO
  1431.  
  1432.     NAME
  1433.     DeleteStdIO - free the memory of an IOStdReq record
  1434.  
  1435.     SYNOPSIS
  1436.     Procedure DeleteStdIO(Request : IOStdReqPtr);
  1437.  
  1438.     DESCRIPTION
  1439.     This routine deallocated the memory used by the IOStdReq.
  1440.  
  1441.     EXAMPLE
  1442.     See Examples/SmallCom.p and Examples/DeadKeysPlus.p
  1443.  
  1444.     INPUTS
  1445.     Request : A pointer to the IOStdReq to free
  1446.  
  1447.     RESULTS
  1448.     None
  1449.  
  1450.     BUGS
  1451.  
  1452.     SEE ALSO
  1453.     CreateStdIO, CreatePort, DeletePort
  1454.  
  1455.  
  1456. Utils/TaskUtils/DeleteTask        Utils/TaskUtils/DeleteTask
  1457.  
  1458.     NAME
  1459.     DeleteTask - remove a task from the system list
  1460.  
  1461.     SYNOPSIS
  1462.     Procedure DeleteTask(Task : TaskPtr);
  1463.  
  1464.     DESCRIPTION
  1465.     DeleteTask terminates a task and frees the memory used
  1466.     for its stack.  It should only be called on tasks
  1467.     created by CreateTask.
  1468.  
  1469.     You should be careful to ensure that the new task is
  1470.     ready to be deleted before you call this routine, or
  1471.     you could catch it in the middle of something important.
  1472.  
  1473.     EXAMPLE
  1474.     See Examples/Task.p
  1475.  
  1476.     INPUTS
  1477.  
  1478.     Task  : A pointer to a Task, as returned by CreateTask
  1479.  
  1480.     RESULTS
  1481.     None
  1482.  
  1483.     BUGS
  1484.  
  1485.     SEE ALSO
  1486.     CreateTask, CreateProc
  1487.  
  1488.  
  1489. Utils/TimerUtils/DeleteTimer        Utils/TimerUtils/DeleteTimer
  1490.  
  1491.     NAME
  1492.     DeleteTimer - close the timer.device and free the IO record
  1493.  
  1494.     SYNOPSIS
  1495.     Procedure DeleteTimer(WhichTimer : TimeRequestptr);
  1496.  
  1497.     DESCRIPTION
  1498.     DeleteTimer frees all the system resources allocated by
  1499.     CreateTimer.  It closes the timer.device, then deallocates
  1500.     the memory and port used for the TimeRequestPtr.
  1501.  
  1502.     EXAMPLE
  1503.     See Examples/Dry.p, Examples/TimerTest.p, Examples/TimeProg.p
  1504.  
  1505.     INPUTS
  1506.  
  1507.     WhichTimer : A pointer to a TimeRequest record as returned
  1508.              by CreateTimer
  1509.  
  1510.     RESULTS
  1511.     None
  1512.  
  1513.     BUGS
  1514.  
  1515.     SEE ALSO
  1516.     CreateTimer
  1517.  
  1518.  
  1519. Utils/CRT/DelLine            Utils/CRT/DelLine
  1520.  
  1521.     NAME
  1522.     DelLine - delete the current line
  1523.  
  1524.     SYNOPSIS
  1525.     Procedure DelLine(CRT : Address);
  1526.  
  1527.     DESCRIPTION
  1528.     DelLine deletes the line on which the cursor rests.  It
  1529.     moves all the lines below it up one, and clears the
  1530.     bottom line.
  1531.  
  1532.     EXAMPLE
  1533.  
  1534.     Procedure BringTogether(CRT : Address);
  1535.     begin
  1536.         ClrScr(CRT);
  1537.         WriteString(CRT, "The First Line");
  1538.         GotoXY(CRT,1,3);
  1539.         WriteString(CRT, "The Second Line");
  1540.         GotoXY(CRT,1,2);
  1541.         DelLine(CRT);
  1542.     end;
  1543.  
  1544.     INPUTS
  1545.  
  1546.     CRT   : A pointer to a valid CRT information block, as
  1547.         returned by AttachConsole
  1548.  
  1549.     RESULTS
  1550.     None
  1551.  
  1552.     SEE ALSO
  1553.     AttachConsole, InsLine, GotoXY
  1554.  
  1555.  
  1556. Utils/CRT/DetachConsole            Utils/CRT/DetachConsole
  1557.  
  1558.     NAME
  1559.     DetachConsole - close the console.device and free memory
  1560.  
  1561.     SYNOPSIS
  1562.     Procedure DetachConsole(CRT : Address);
  1563.  
  1564.     DESCRIPTION
  1565.     When you have finished using the CRT routines, you need
  1566.     to call DetachConsole to free up all the resources they
  1567.     are using.  This routine does not close the window,
  1568.     however.
  1569.  
  1570.     EXAMPLE
  1571.     See Examples/Map.p and Examples/ConsoleTest.p
  1572.  
  1573.     INPUTS
  1574.  
  1575.     CRT   : A pointer to a valid CRT information block,
  1576.         as returned by AttachConsole
  1577.  
  1578.     RESULTS
  1579.     None
  1580.  
  1581.     SEE ALSO
  1582.     AttachConsole
  1583.  
  1584.  
  1585. Utils/BuildMenu/DetachMenu        Utils/BuildMenu/DetachMenu
  1586.  
  1587.     NAME
  1588.     DetachMenu - remove a menu strip from a window
  1589.  
  1590.     SYNOPSIS
  1591.     Procedure DetachMenu;
  1592.  
  1593.     DESCRIPTION
  1594.     This routine removes the menu strip from the window.
  1595.     You must call this routine before closing a window or
  1596.     messing around with the menu itself.
  1597.  
  1598.     EXAMPLE
  1599.     See Examples/SmallCom.p, Examples/DeadKeysPlus.p,
  1600.         Examples/ConsoleTest.p
  1601.  
  1602.     INPUTS
  1603.     None
  1604.  
  1605.     RESULTS
  1606.     None
  1607.  
  1608.     SEE ALSO
  1609.     InitializeMenu, AttachMenu
  1610.  
  1611. PCQ/Dispose                PCQ/Dispose
  1612.  
  1613.     NAME
  1614.     Dispose - free memory allocation through New()
  1615.  
  1616.     SYNOPSIS
  1617.     Procedure Dispose(p : Any pointer type);
  1618.  
  1619.     DESCRIPTION
  1620.     Dispose frees the memory allocated for the pointer p by
  1621.     the standard procedure New().  If you do not call Dispose,
  1622.     the memory will be freed at the end of the program.
  1623.  
  1624.     EXAMPLE
  1625.  
  1626.     Program DisposeMem;
  1627.     var
  1628.         p : ^Integer;
  1629.     begin
  1630.         New(p);
  1631.         Writeln('p allocated at ', Integer(p));
  1632.         Dispose(p);
  1633.         New(p);
  1634.         Writeln('p allocated at ', Integer(p));
  1635.     end. { automatically disposed this time }
  1636.  
  1637.     INPUTS
  1638.  
  1639.     p     : Any pointer type.  The pointer must point to the
  1640.         first byte of the allocated block.
  1641.  
  1642.     RESULTS
  1643.     None
  1644.  
  1645.     BUGS
  1646.  
  1647.     SEE ALSO
  1648.     New, FreePCQMem, FreeString, FreeMem
  1649.  
  1650.  
  1651. Utils/BuildMenu/DisposeMenu        Utils/BuildMenu/DisposeMenu
  1652.  
  1653.     NAME
  1654.     DisposeMenu - Free the memory used by a BuildMenu menu strip.
  1655.  
  1656.     SYNOPSIS
  1657.     Procedure DisposeMenu;
  1658.  
  1659.     DESCRIPTION
  1660.     DisposeMenu frees the memory allocated by the NewMenu and
  1661.     NewItem routines.
  1662.  
  1663.     This routine is not for general use - it only works with
  1664.     the rest of the BuildMenu routines.  Also, you'll have to
  1665.     call DetachMenu before this routine to let Intuition know
  1666.     the menu is no longer available.
  1667.  
  1668.     Since NewItem and the related routines use PCQ memory
  1669.     allocation, the memory used by the menus will be freed auto-
  1670.     matically at the end of the program.  Thus you don't have to
  1671.     call this routine unless you want to free it beforehand.
  1672.  
  1673.     EXAMPLE
  1674.     see Examples/SmallCom.p
  1675.  
  1676.     INPUTS
  1677.     None
  1678.  
  1679.     RESULTS
  1680.     The memory used by the current menu is deallocated.
  1681.  
  1682.     BUGS
  1683.  
  1684.     SEE ALSO
  1685.     InitializeMenu, AttachMenu, DetachMenu
  1686.  
  1687.  
  1688. PCQ/EOF                    PCQ/EOF
  1689.  
  1690.     NAME
  1691.     EOF - determine whether a file is at the end-of-file
  1692.  
  1693.     SYNOPSIS
  1694.     Function EOF(VAR F : Any file type) : Boolean;
  1695.  
  1696.     DESCRIPTION
  1697.     The EOF function returns True if an input file has
  1698.     been entirely read, or False if data remains to be
  1699.     read.  If a file is at the EOF position, it is an
  1700.     error to attempt to Read from it.
  1701.  
  1702.     If the file was opened for output using Open or Rewrite,
  1703.     EOF is undefined.
  1704.  
  1705.     EXAMPLE
  1706.  
  1707.     Program ShowText;
  1708.     {$I "Include:Utils/StringLib.i"}
  1709.     {$I "Include:Utils/Parameters.i"}
  1710.     var
  1711.         InFile   : Text;
  1712.         FileName : String;
  1713.     begin
  1714.         FileName := AllocString(256);
  1715.         GetParam(1,FileName);
  1716.         if ReOpen(FileName, InFile) then begin
  1717.         while not EOF(InFile) do begin
  1718.             Write(InFile^);
  1719.             Get(InFile);
  1720.         end;
  1721.         Close(InFile);
  1722.         end else
  1723.         Writeln('Could not open ', FileName);
  1724.     end.
  1725.  
  1726.     INPUTS
  1727.  
  1728.     F     : Any Pascal file opened for input using ReOpen or
  1729.         Reset.
  1730.  
  1731.     RESULTS
  1732.     TRUE if all the data has been read, or
  1733.     FALSE if data remains to be read.
  1734.  
  1735.     BUGS
  1736.  
  1737.     SEE ALSO
  1738.     ReOpen, Reset, IOResult, Close, Rewrite, Open
  1739.  
  1740.  
  1741. PCQ/Exit                PCQ/Exit
  1742.  
  1743.     NAME
  1744.     Exit - quit the program
  1745.  
  1746.     SYNOPSIS
  1747.     Procedure Exit [ (ReturnCode : Integer) ] ;
  1748.  
  1749.     DESCRIPTION
  1750.     The standard procedure Exit terminates the program.  If
  1751.     you supply a return code, it is passed back to AmigaDOS.
  1752.     If not, a return code of 0 is passed back.
  1753.  
  1754.     Calling exit invokes all the exit procedures, as if the
  1755.     program had ended normally.  It is therefore the
  1756.     recommending way to end a program early.  You should not
  1757.     call the AmigaDOS procedure DOSExit(), since the exit
  1758.     procedures will not be able to take effect.
  1759.  
  1760.     EXAMPLE
  1761.  
  1762.     Program Reader;
  1763.     {$I "Include:Utils/StringLib.i"}
  1764.     var
  1765.         Str : String;
  1766.     begin
  1767.         Str := AllocString(256);
  1768.         repeat
  1769.         Readln(Str);
  1770.         if strieq(Str,"quit") then
  1771.             Exit;
  1772.         Writeln(Str);
  1773.         until false;
  1774.     end.
  1775.  
  1776.     INPUTS
  1777.  
  1778.     ReturnCode : An optional AmigaDOS return code.
  1779.  
  1780.     RESULTS
  1781.     None
  1782.  
  1783.     BUGS
  1784.  
  1785.     SEE ALSO
  1786.  
  1787.  
  1788. PCQ/Exp                    PCQ/Exp
  1789.  
  1790.     NAME
  1791.     Exp - compute e raised to the specified power
  1792.  
  1793.     SYNOPSIS
  1794.     Function Exp(Power : Real) : Real;
  1795.  
  1796.     DESCRIPTION
  1797.     This value computes the exponential value of the argument,
  1798.     i.e. the value e (about 2.71) raised to the power of the
  1799.     argument.  If you have used the $N+ directive, this is
  1800.     computed by the mathtrans.library.  Otherwise, internal
  1801.     PCQ routines handle it.
  1802.  
  1803.     EXAMPLE
  1804.  
  1805.     Program ShowExp;
  1806.     var
  1807.         Power : Real;
  1808.     begin
  1809.         Write('Enter an exponent: ');
  1810.         Readln(Power);
  1811.         Writeln('e raised to the ', Power:0:3, ' power is ',
  1812.                 Exp(Power):0:3);
  1813.     end.
  1814.  
  1815.     INPUTS
  1816.  
  1817.     Power : A Real type expression
  1818.  
  1819.     RESULTS
  1820.     e raised to the specified power
  1821.  
  1822.     BUGS
  1823.  
  1824.     SEE ALSO
  1825.     Ln
  1826.  
  1827. Utils/RunProgram/FinishProgram        Utils/RunProgram/FinishProgram
  1828.  
  1829.     NAME
  1830.     FinishProgram - wait for the program to finish and clean up
  1831.  
  1832.     SYNOPSIS
  1833.     Procedure FinishProgram(RP : RunProgPtr);
  1834.  
  1835.     DESCRIPTION
  1836.     FinishProgram waits for a child process launched by
  1837.     RunProgramNW or RunSegmentNW to finish, then frees any
  1838.     resources allocated by the run routines.  It will not
  1839.     free anything it didn't allocate - for example, it will
  1840.     not unload a segment that it didn't load.
  1841.  
  1842.     EXAMPLE
  1843.  
  1844.     Program RunChild;
  1845.     {$I "Include:Utils/RunProgram.i"}
  1846.     var
  1847.         Child : RunProgPtr;
  1848.     begin
  1849.         Child := RunProgramNW("OtherProgram", 4000);
  1850.         if Child <> Nil then
  1851.         FinishProgram(Child);
  1852.     end.
  1853.  
  1854.     INPUTS
  1855.  
  1856.     RP    : A pointer to a private information block, as
  1857.         returned by RunSegmentNW or RunProgramNW.
  1858.  
  1859.     RESULTS
  1860.     None
  1861.  
  1862.     BUGS
  1863.  
  1864.     SEE ALSO
  1865.     RunSegment, RunSegmentNW, RunProgram, RunProgramNW,
  1866.     ProgramFinished
  1867.  
  1868.  
  1869. PCQ/Float                PCQ/Float
  1870.  
  1871.     NAME
  1872.     Float - convert an Integer to a Real value.
  1873.  
  1874.     SYNOPSIS
  1875.     Function Float(Expr : Integer) : Float;
  1876.  
  1877.     DESCRIPTION
  1878.     This function converts the Integer expression into its
  1879.     Real type counterpart.  Float is called automatically
  1880.     by the compiler to "promote" Integer values in expressions
  1881.     when necessary.
  1882.  
  1883.     EXAMPLE
  1884.  
  1885.     Program ShowFloat;
  1886.     var
  1887.         IntValue : Integer;
  1888.     begin
  1889.         Write('Please enter an Integer: ');
  1890.         Readln(IntValue);
  1891.         Writeln(IntValue, ' becomes ', Float(IntValue):0:5);
  1892.     end.
  1893.  
  1894.     INPUTS
  1895.  
  1896.     Expr : Any Integer type expression
  1897.  
  1898.     RESULTS
  1899.     The expression converted to a Real value
  1900.  
  1901.     BUGS
  1902.  
  1903.     SEE ALSO
  1904.     Trunc, Round
  1905.  
  1906.  
  1907. PCQ/Floor                PCQ/Floor
  1908.  
  1909.     NAME
  1910.     Floor - return the greatest whole number less than or equal
  1911.  
  1912.     SYNOPSIS
  1913.     Function Floor(Expr : Real) : Real;
  1914.  
  1915.     DESCRIPTION
  1916.     The Floor function returns the greatest whole number (still
  1917.     in Real format, however) less than or equal to the value
  1918.     passed in.
  1919.  
  1920.     EXAMPLE
  1921.  
  1922.     Program ShowFloor;
  1923.     var
  1924.         FloatValue : Real;
  1925.     begin
  1926.         Write('Please enter a Real value: ');
  1927.         Readln(FloatValue);
  1928.         Writeln(FloatValue:0:3, ' becomes ',
  1929.               Floor(FloatValue):0:3);
  1930.     end.
  1931.  
  1932.     Floor(5.4) = 5.0
  1933.     Floor(-5.4) = -6.0
  1934.  
  1935.     INPUTS
  1936.  
  1937.     Expr  : Any Real type expression
  1938.  
  1939.     RESULTS
  1940.     A Real value less than or equal to the original expression
  1941.  
  1942.     BUGS
  1943.  
  1944.     SEE ALSO
  1945.     Ceil, Round, Trunc, Float
  1946.  
  1947.  
  1948. Utils/MathTransUtils/FlushMathTrans    Utils/MathTransUtils/FlushMathTrans
  1949.  
  1950.     NAME
  1951.     FlushMathTrans - close and remove the mathtrans.library
  1952.  
  1953.     SYNOPSIS
  1954.     Procedure FlushMathTrans;
  1955.  
  1956.     DESCRIPTION
  1957.     FlushMathTrans is the same as CloseMathTrans library,
  1958.     but it also signals the mathtrans.library that it should
  1959.     remove itself from the system as soon as possible.
  1960.     If no other tasks have opened the mathtrans.library, it
  1961.     will normally remove itself immediately.
  1962.  
  1963.     EXAMPLE
  1964.  
  1965.     Program CheckTrans;
  1966.     {$I "Include:Utils/MathTransUtils.i"}
  1967.     {$I "Include:Libraries/MathTrans.i"}
  1968.     begin
  1969.         if OpenMathTrans then begin
  1970.         Writeln(SPSin(4.7));
  1971.         FlushMathTrans;
  1972.         end else
  1973.         Writeln('Could not open mathtrans.library');
  1974.     end.
  1975.  
  1976.     INPUTS
  1977.     None
  1978.  
  1979.     RESULTS
  1980.     None
  1981.  
  1982.     BUGS
  1983.  
  1984.     SEE ALSO
  1985.     OpenMathTrans, CloseMathTrans, and the mathtrans.library
  1986.     routines like SPSin, SPCos, etc.
  1987.  
  1988.  
  1989. Utils/PCQMemory/FreePCQMem        Utils/PCQMemory/FreePCQMem
  1990.  
  1991.     NAME
  1992.     FreePCQMem - return PCQ memory to the system
  1993.  
  1994.     SYNOPSIS
  1995.     Procedure FreePCQMem(VAR Ptr : Address; Size : Integer);
  1996.  
  1997.     DESCRIPTION
  1998.     FreePCQMem returns memory allocated by GetMem to the system
  1999.     memory pool.  This memory would normally be freed at the
  2000.     end of the program, but using this routine allows you to
  2001.     adjust your memory requirements within the program.
  2002.  
  2003.     EXAMPLE
  2004.  
  2005.     Procedure Behave;
  2006.     {$I "Include:Utils/PCQMemory.i"}
  2007.     var
  2008.         p : Address;
  2009.     begin
  2010.         GetMem(p, 100000);
  2011.         FreePCQMem(p, 100000);
  2012.     end.
  2013.  
  2014.     INPUTS
  2015.  
  2016.     Ptr   : Any pointer variable
  2017.     Size  : The amount of memory to be freed.  This number must
  2018.         match the amount that was initially allocated.
  2019.  
  2020.     RESULTS
  2021.     None
  2022.  
  2023.     BUGS
  2024.  
  2025.     SEE ALSO
  2026.     GetMem, AllocString, FreeString
  2027.  
  2028.  
  2029. Utils/StringLib/FreeString        Utils/StringLib/FreeString
  2030.  
  2031.     NAME
  2032.     FreeString - free memory allocated by AllocString
  2033.  
  2034.     SYNOPSIS
  2035.     Procedure FreeString(Str : String);
  2036.  
  2037.     DESCRIPTION
  2038.     FreeString returns memory allocated through PCQ's
  2039.     memory allocation routines to the system.  You need
  2040.     not supply the length of the string, since it is
  2041.     recorded when the block is allocated.
  2042.  
  2043.     Note that PCQ memory is automatically freed at the
  2044.     end of the program, but this routine lets you use
  2045.     the memory earlier.
  2046.  
  2047.     EXAMPLE
  2048.  
  2049.     Program Deallocator;
  2050.     {$I "Include:Utils/StringLib.i"}
  2051.     var
  2052.         Str : String;
  2053.     begin
  2054.         Str := AllocString(256);
  2055.         Writeln('Allocated space at ', Integer(Str));
  2056.         FreeString(Str);
  2057.         Str := AllocString(256);
  2058.         Writeln('Allocated space at ', Integer(Str));
  2059.     end.
  2060.  
  2061.     INPUTS
  2062.  
  2063.     Str   : The address of the block to free, as returned by
  2064.         AllocString.  Str must point to the beginning of
  2065.         the block, and the entire block will be freed.
  2066.  
  2067.     RESULTS
  2068.     None
  2069.  
  2070.     BUGS
  2071.  
  2072.     SEE ALSO
  2073.     AllocString, GetMem, FreePCQMem, AllocMem, FreeMem
  2074.  
  2075.  
  2076. PCQ/Get                    PCQ/Get
  2077.  
  2078.     NAME
  2079.     Get - advance the input file pointer
  2080.  
  2081.     SYNOPSIS
  2082.     Procedure Get(VAR F : Any file type);
  2083.  
  2084.     DESCRIPTION
  2085.     Get advances the file pointer to the next record.  In
  2086.     a Text file, it advances it to the next character.
  2087.  
  2088.     Get is normally used by programs that access the file
  2089.     buffer directly through the F^ syntax.  It lets you
  2090.     examine the contents of a file without reading values
  2091.     into an extra variable.
  2092.  
  2093.     EXAMPLE
  2094.  
  2095.     Program TypeFiles;
  2096.     {$I "Include:Utils/Parameters.i"}
  2097.     {$I "Include:Utils/StringLib.i"}
  2098.     var
  2099.         InFile   : Text;
  2100.         FileName : String;
  2101.         ParamNum : Integer;
  2102.     begin
  2103.         FileName := AllocString(256);
  2104.         ParamNum := 1;
  2105.         repeat
  2106.         GetParam(ParamNum,FileName);
  2107.         if strlen(FileName) > 0 then begin
  2108.             if ReOpen(FileName, InFile) then begin
  2109.             while not EOF(InFile) do begin
  2110.                 Write(InFile^);
  2111.                 Get(InFile);
  2112.             end;
  2113.             Close(InFile);
  2114.             end else
  2115.             Writeln('Could not open ', FileName);
  2116.         end;
  2117.         Inc(ParamNum);
  2118.         until strlen(FileName) = 0;
  2119.     end.
  2120.  
  2121.     INPUTS
  2122.  
  2123.     F     : Any PCQ file variable open for input
  2124.  
  2125.     RESULTS
  2126.     None
  2127.  
  2128.     BUGS
  2129.  
  2130.     SEE ALSO
  2131.     Reopen, Reset, Put, Read, Readln
  2132.  
  2133.  
  2134. Utils/DateTools/GetDescription        Utils/DateTools/GetDescription
  2135.  
  2136.     NAME
  2137.     GetDescription - convert seconds to a date description
  2138.  
  2139.     SYNOPSIS
  2140.     Procedure GetDescription(Total  : Integer;
  2141.                  VAR DD : DateDesription);
  2142.  
  2143.     DESCRIPTION
  2144.     This routine converts the time format of the timer.device
  2145.     into a more easily used form.  The timer.device returns
  2146.     a time that is the number of seconds and microseconds after
  2147.     midnight on January 1, 1978, the same numbers Intuition
  2148.     returns in the CurrentTime function.  This routine takes
  2149.     that number of seconds and converts it into a year, month,
  2150.     day, etc.
  2151.  
  2152.     If you have the time in a DateStamp format (from AmigaDOS),
  2153.     you can use the StampDesc routine to do the same thing.
  2154.  
  2155.     The DateDescription record is defined as follows:
  2156.  
  2157.         DaysOfTheWeek = (Sunday, Monday, Tuesday, Wednesday,
  2158.                 Thursday, Friday, Saturday);
  2159.  
  2160.         DateDescription = record
  2161.         Day    : Byte;         { Day of month, 1..31 }
  2162.         Month    : Byte;         { Month, 1..12 }
  2163.         Year    : Short;     { Year, 1978... }
  2164.         DOW    : DaysOfTheWeek; { Sunday .. Saturday }
  2165.         Hour    : Byte;         { 0..23.  0 = 12 AM, 12 = Noon }
  2166.         Minute    : Byte;         { 0..59 }
  2167.         Second    : Byte;         { 0..59 }
  2168.         end;
  2169.  
  2170.     EXAMPLE
  2171.  
  2172.     Program ShowDate;
  2173.     {$I "Include:Utils/DateTools.i"}
  2174.     {$I "Include:Intuition/Intuition.i"}
  2175.     var
  2176.         MySecs, MyMicros : Integer;
  2177.         MyDate  : DateDescription;
  2178.     begin
  2179.         CurrentTime(MySecs, MyMicros);
  2180.         GetDescription(MySecs, MyDate);
  2181.         with MyDate do
  2182.         Writeln(MonthNames[Month], ' ', Day, ', ', Year);
  2183.     end.
  2184.  
  2185.     INPUTS
  2186.  
  2187.     Total : The total number of seconds after midnight on
  2188.         January 1, 1978, e.g. from a TimeVal.
  2189.     DD    : A DateDescription record
  2190.  
  2191.     RESULTS
  2192.     None
  2193.  
  2194.     BUGS
  2195.  
  2196.     SEE ALSO
  2197.     CreateTimer, GetSysTime, TimeDesc, StampDesc, CurrentTime
  2198.  
  2199.  
  2200. Utils/DOSUtils/GetFileHandle        Utils/DOSUtils/GetFileHandle
  2201.  
  2202.     NAME
  2203.     GetFileHandle - return the AmigaDOS handle of a PCQ file
  2204.  
  2205.     SYNOPSIS
  2206.     Function GetFileHandle(VAR f : Text) : FileHandle;
  2207.  
  2208.     DESCRIPTION
  2209.     GetFileHandle returns the AmigaDOS FileHandle BPTR of the
  2210.     specified PCQ file so you can use it in DOS routines.
  2211.  
  2212.     EXAMPLE
  2213.  
  2214.     Program WhereFrom;
  2215.     {$I "Include:Utils/DOSUtils.i"}
  2216.     {$I "Include:Libraries/DOS.i"}
  2217.     begin
  2218.         if IsInteractive(GetFileHandle(Input)) then
  2219.         Writeln('Input is coming from the console')
  2220.         else
  2221.         Writeln('Input is coming from a file');
  2222.     end.
  2223.  
  2224.     INPUTS
  2225.  
  2226.     f     : An open PCQ file variable
  2227.  
  2228.     RESULTS
  2229.     The associated AmigaDOS FileHandle
  2230.  
  2231.     BUGS
  2232.  
  2233.     SEE ALSO
  2234.     IsInteractive, Seek, DOSRead, DOSWrite
  2235.  
  2236.  
  2237. Utils/PCQMemory/GetMem            Utils/PCQMemory/GetMem
  2238.  
  2239.     NAME
  2240.     GetMem - allocate PCQ memory
  2241.  
  2242.     SYNOPSIS
  2243.     Procedure GetMem(VAR Ptr : Address; Size : Integer);
  2244.  
  2245.     DESCRIPTION
  2246.     GetMem allocates PCQ memory from the system pool.  PCQ
  2247.     memory is automatically returned to the system at the
  2248.     end of the program's run.  It also makes use of the
  2249.     HeapError routine to help recover from low memory
  2250.     situations.
  2251.  
  2252.     PCQ memory, which is also returned by AllocString and
  2253.     New, is always allocated with the flags MEMF_PUBLIC and
  2254.     MEMF_CLEAR.  If you have different requirements, you'll
  2255.     need to call Exec's AllocMem or Intuition's AllocRemember
  2256.     explicitly.
  2257.  
  2258.     Since the PCQ memory allocation scheme uses calls to
  2259.     AllocRemember, each memory allocation will actually try
  2260.     to allocate between 12 and 20 extra bytes.  If the memory
  2261.     not available, the HeapError function takes over.  By
  2262.     default, the program aborts with run-time error 54.
  2263.  
  2264.     EXAMPLE
  2265.  
  2266.     Program HogMemory;
  2267.     {$I "Include:Utils/PCQMemory.i"}
  2268.     var
  2269.         p : Address;
  2270.     begin
  2271.         GetMem(p,100000);
  2272.     end. { The memory is automatically returned }
  2273.  
  2274.     INPUTS
  2275.  
  2276.     Ptr   : Any pointer type
  2277.     Size  : The amount of memory, in bytes, to allocate
  2278.  
  2279.     RESULTS
  2280.     None
  2281.  
  2282.     BUGS
  2283.  
  2284.     SEE ALSO
  2285.     FreePCQMem, AllocString, FreeString
  2286.  
  2287.  
  2288. Utils/Parameters/GetParam        Utils/Parameters/GetParam
  2289.  
  2290.     NAME
  2291.     GetParam - return an argument from the command line
  2292.  
  2293.     SYNOPSIS
  2294.     Procedure GetParam(Num : Short; Dest : String);
  2295.  
  2296.     DESCRIPTION
  2297.     GetParam copies a parameter into the string Dest.  Dest
  2298.     must already be allocated.  The parameter can come from
  2299.     the CLI CommandLine, or it could be the name of an icon
  2300.     from the Workbench startup message.  If the parameter
  2301.     doesn't exist, Dest will have zero length.
  2302.  
  2303.     GetParam handles quotes correctly, and does not modify
  2304.     CommandLine.
  2305.  
  2306.     EXAMPLE
  2307.  
  2308.     Program ShowParams;
  2309.     {$I "Include:Utils/Parameters.i"}
  2310.     {$I "Include:Utils/StringLib.i"}
  2311.     var
  2312.         n         : Short;
  2313.         Parameter : String;
  2314.     begin
  2315.         Parameter := AllocString(256);
  2316.         n := 1;
  2317.         repeat
  2318.         GetParam(n, Parameter);
  2319.         if strlen(Parameter) > 0 then
  2320.             Writeln('Parameter ', n, ' is "', Parameter, '"');
  2321.         until strlen(Parameter) = 0;
  2322.     end.
  2323.  
  2324.     INPUTS
  2325.  
  2326.     Num   : The number of the parameter to copy, starting at 1.
  2327.     Dest  : The buffer into which to copy the parameter.  It must
  2328.         already be allocated.
  2329.  
  2330.     RESULTS
  2331.     None
  2332.  
  2333.     BUGS
  2334.  
  2335.     SEE ALSO
  2336.     GetStartupMsg
  2337.  
  2338.  
  2339. Utils/Parameters/GetStartupMsg        Utils/Parameters/GetStartupMsg
  2340.  
  2341.     NAME
  2342.     GetStartupMsg - return the Workbench startup message
  2343.  
  2344.     SYNOPSIS
  2345.     Function GetStartupMsg : WBStartupPtr;
  2346.  
  2347.     DESCRIPTION
  2348.     This routine returns a pointer to the message sent by the
  2349.     workbench to start up your task.  If your task was started
  2350.     from the CLI, it will return Nil.
  2351.  
  2352.     EXAMPLE
  2353.     See Examples/Icons.p
  2354.  
  2355.     INPUTS
  2356.     None
  2357.  
  2358.     RESULTS
  2359.     A pointer to a WBStartup record, or Nil if the process was
  2360.     executed from the CLI.
  2361.  
  2362.     BUGS
  2363.  
  2364.     SEE ALSO
  2365.  
  2366.  
  2367. Utils/TimerUtils/GetSysTime        Utils/TimerUtils/GetSysTime
  2368.  
  2369.     NAME
  2370.     GetSysTime - return the current system date and time
  2371.  
  2372.     SYNOPSIS
  2373.     Procedure GetSysTime(WhichTimer : TimeRequestPtr;
  2374.                  VAR TV     : TimeVal);
  2375.  
  2376.     DESCRIPTION
  2377.     GetSysTime fills in the TimeVal structure with the current
  2378.     date and time, expressed as the number of seconds since
  2379.     midnight, January 1, 1978.
  2380.  
  2381.     EXAMPLE
  2382.     See Examples/Dry.p, Examples/TimerTest.p, Examples/TimeProg.p
  2383.  
  2384.     INPUTS
  2385.  
  2386.     WhichTimer : A pointer to a TimeRequest record, returned by
  2387.              CreateTimer.
  2388.     TV         : A TimeVal record to store the current time.
  2389.  
  2390.     RESULTS
  2391.     None
  2392.  
  2393.     BUGS
  2394.  
  2395.     SEE ALSO
  2396.     CreateTimer, CurrentTime, DateStamp, GetDescription
  2397.  
  2398.  
  2399. Utils/CRT/GotoXY            Utils/CRT/GotoXY
  2400.  
  2401.     NAME
  2402.     GotoXY - move the cursor to column X and row Y
  2403.  
  2404.     SYNOPSIS
  2405.     Procedure GotoXY(CRT : Address; X, Y : Short);
  2406.  
  2407.     DESCRIPTION
  2408.     This routine moves the window's text cursor (which
  2409.     is not the same as the graphics cursor) to the
  2410.     position X,Y.  This position is measured in characters,
  2411.     not pixels.
  2412.  
  2413.     EXAMPLE
  2414.     See Examples/Map.p
  2415.  
  2416.     INPUTS
  2417.  
  2418.     CRT   : A pointer to a valid CRT information block,
  2419.         as returned by AttachConsole
  2420.  
  2421.     RESULTS
  2422.     None
  2423.  
  2424.     SEE ALSO
  2425.     AttachConsole, MaxX, MaxY
  2426.  
  2427.  
  2428. Utils/StringLib/Hash            Utils/StringLib/Hash
  2429.  
  2430.     NAME
  2431.     Hash - calculate the AmigaDOS hash value of a string
  2432.  
  2433.     SYNOPSIS
  2434.     Function Hash(Str : String) : Short;
  2435.  
  2436.     DESCRIPTION
  2437.     This function calculates a hash value for a given string
  2438.     the same way they are calculated for DOS0 (the original
  2439.     file system) directories.  This method looks like this:
  2440.  
  2441.         Function Hash(Str : String) : Short;
  2442.         var
  2443.             i, Result : Short;
  2444.         begin
  2445.             Result := strlen(Str);
  2446.             for i := 0 to strlen(Str) do
  2447.             Result := ((Result * 13) +
  2448.                    Ord(toupper(Str[i]))) and $07FF;
  2449.         end;
  2450.  
  2451.     EXAMPLE
  2452.  
  2453.     Program CalculateHash;
  2454.     {$I "Include:Utils/StringLib.i"}
  2455.     begin
  2456.         Writeln('The hash value of the command line is: ',
  2457.             Hash(CommandLine));
  2458.     end.
  2459.  
  2460.     INPUTS
  2461.  
  2462.     Str   : The string to examine
  2463.  
  2464.     RESULTS
  2465.     A hash value between 0 and 16383
  2466.  
  2467.     BUGS
  2468.  
  2469.     SEE ALSO
  2470.  
  2471.  
  2472. PCQ/Inc                    PCQ/Inc
  2473.  
  2474.     NAME
  2475.     Inc - increment a variable
  2476.  
  2477.     SYNOPSIS
  2478.     Procedure Inc(VAR v : Any Integer or pointer type
  2479.             [ ; Amount : Integer ] );
  2480.  
  2481.     DESCRIPTION
  2482.     The Inc procedure is normally used to add to an Integer
  2483.     type.  If v is an integer type and there is no amount
  2484.     specified, Inc will add 1.  Otherwise, it will add Amount.
  2485.     Note that this is somewhat faster than v := v + Amount.
  2486.  
  2487.     For pointer types, Inc advances the pointer to the next
  2488.     element.  For example, if v is a pointer to Real, Inc(v)
  2489.     will actually add 4 (the size of a Real) to v.  If you
  2490.     used an Amount, Inc would add Amount*4 to v.  This lets
  2491.     you move a pointer along an array of items.
  2492.  
  2493.     EXAMPLE
  2494.  
  2495.     Program ShowInc;
  2496.     var
  2497.         i : Integer;
  2498.         s : Short;
  2499.         p : ^Integer;
  2500.         q : ^Short;
  2501.     begin
  2502.         Inc(i);    { i := i + 1 }
  2503.         Inc(s,45); { s := s + 45 }
  2504.         Inc(p,3);  { p := p + 3*4 }
  2505.         Inc(q);    { q := q + 2 }
  2506.     end.
  2507.  
  2508.     INPUTS
  2509.  
  2510.     v      : Any Integer or pointer type.
  2511.     Amount : An amount to add to v.
  2512.  
  2513.     RESULTS
  2514.     None
  2515.  
  2516.     BUGS
  2517.  
  2518.     SEE ALSO
  2519.     Dec
  2520.  
  2521.  
  2522. Utils/BuildMenu/InitializeMenu        Utils/BuildMenu/InitializeMenu
  2523.  
  2524.     NAME
  2525.     InitializeMenu - set up the BuildMenu system.
  2526.  
  2527.     SYNOPSIS
  2528.     Procedure InitializeMenu(w : WindowPtr);
  2529.  
  2530.     DESCRIPTION
  2531.     InitializeMenu creates a blank menu system for a the
  2532.     BuildMenu system.
  2533.  
  2534.     InitializeMenu must be called before any of the other
  2535.     BuildMenu routines.
  2536.  
  2537.     Note that the BuildMenu routines can only define one
  2538.     menu strip at a time.
  2539.  
  2540.     EXAMPLE
  2541.     see Examples/SmallCom.p, Examples/DeadKeysPlus.p,
  2542.         Examples/ConsoleTest.p
  2543.  
  2544.     INPUTS
  2545.     w : a pointer to an open Window.
  2546.  
  2547.     RESULTS
  2548.     None
  2549.  
  2550.     BUGS
  2551.  
  2552.     SEE ALSO
  2553.     DisposeMenu, NewMenu, NewItem, NewSubItem, AttachMenu,
  2554.     DetachMenu
  2555.  
  2556.  
  2557.  
  2558. Utils/CRT/InsLine            Utils/CRT/InsLine
  2559.  
  2560.     NAME
  2561.     InsLine - insert a text line
  2562.  
  2563.     SYNOPSIS
  2564.     Procedure InsLine(CRT : Address);
  2565.  
  2566.     DESCRIPTION
  2567.     InsLine inserts one text line at the current cursor
  2568.     position, moving all lines below it down.
  2569.  
  2570.     EXAMPLE
  2571.  
  2572.     Procedure SplitApart(CRT : Address);
  2573.     begin
  2574.         ClrScr(CRT);
  2575.         WriteString(CRT, "The First Line\n");
  2576.         WriteString(CRT, "The Third Line");
  2577.         GotoXY(CRT,1,2);
  2578.         InsLine(CRT);
  2579.         WriteString(CRT, "The Second Line");
  2580.     end;
  2581.  
  2582.     INPUTS
  2583.  
  2584.     CRT   : A pointer to a valid CRT information block,
  2585.         as returned by AttachConsole
  2586.  
  2587.     RESULTS
  2588.     None
  2589.  
  2590.     SEE ALSO
  2591.     AttachConsole, DelLine, GotoXY
  2592.  
  2593.  
  2594. Utils/StringLib/IntToStr        Utils/StringLib/IntToStr
  2595.  
  2596.     NAME
  2597.     IntToStr - convert an integer to its character representation
  2598.  
  2599.     SYNOPSIS
  2600.     Function IntToStr(Dest : String; Int : Integer) : Integer;
  2601.  
  2602.     DESCRIPTION
  2603.     IntToStr converts the integer Int to its string form in the
  2604.     Dest string.  It returns the number of characters in the
  2605.     new string, from 0 to 11.  If Int is negative, the string
  2606.     will start off with a minus sign, but there will be no
  2607.     extra spaces before or after the number.  The string will
  2608.     be null-terminated.
  2609.  
  2610.     EXAMPLE
  2611.  
  2612.     Program ShowInts;
  2613.     {$I "Include:Utils/StringLib.i"}
  2614.     var
  2615.         MyInt : Integer;
  2616.         Str   : String;
  2617.     begin
  2618.         Str := AllocString(12);
  2619.         Write('Enter an integer: ');
  2620.         Readln(MyInt);
  2621.         MyInt := IntToStr(Str, MyInt);
  2622.         Writeln('That looks like "', Str, '"');
  2623.     end.
  2624.  
  2625.     INPUTS
  2626.  
  2627.     Str   : The destination string, which must be long enough
  2628.         to hold the result, which will be no more than
  2629.         11 characters.
  2630.     Int   : The number to represent.
  2631.  
  2632.     RESULTS
  2633.     The number of characters, from 1 to 11, in the character
  2634.     representation.
  2635.  
  2636.     BUGS
  2637.  
  2638.     SEE ALSO
  2639.  
  2640.  
  2641. Utils/StringLib/isalnum            Utils/StringLib/isalnum
  2642.  
  2643.     NAME
  2644.     isalnum - check if the character is a letter or digit
  2645.  
  2646.     SYNOPSIS
  2647.     Function isalnum(c : Char) : Boolean;
  2648.  
  2649.     DESCRIPTION
  2650.     This function checks whether the character is in the
  2651.     range a..z, A..Z or '0'..'9'.  In other words, it returns
  2652.     TRUE if isalpha(c) or isdigit(c) is TRUE.
  2653.  
  2654.     EXAMPLE
  2655.  
  2656.     Program CheckAll;
  2657.     {$I "Include:Utils/StringLib.i"}
  2658.     var
  2659.         c : Char;
  2660.     begin
  2661.         for c := Chr(0) to Chr(255) do begin
  2662.         Write('Chr(', Ord(c), ') is ');
  2663.         if not isalnum(c) then
  2664.             Write('not ');
  2665.         Writeln('alphanumeric');
  2666.         end;
  2667.     end.
  2668.  
  2669.     INPUTS
  2670.  
  2671.     c     : The character to check.
  2672.  
  2673.     RESULTS
  2674.     TRUE if the character is in the range a..z, A..Z or 0..9, or
  2675.     FALSE otherwise
  2676.  
  2677.     BUGS
  2678.  
  2679.     SEE ALSO
  2680.     isalpha, isdigit
  2681.  
  2682.  
  2683. Utils/StringLib/isalpha            Utils/StringLib/isalpha
  2684.  
  2685.     NAME
  2686.     isalpha - check if character is in a..z or A..Z
  2687.  
  2688.     SYNOPSIS
  2689.     Function isalpha(c : Char) : Boolean;
  2690.  
  2691.     DESCRIPTION
  2692.     This function checks whether the character is an
  2693.     alphabetic character, i.e. in the range a..z or
  2694.     A..Z.
  2695.  
  2696.     EXAMPLE
  2697.  
  2698.     Program CheckAll;
  2699.     {$I "Include:Utils/StringLib.i"}
  2700.     var
  2701.         c : Char;
  2702.     begin
  2703.         for c := Chr(0) to Chr(255) do begin
  2704.         Write('Chr(', Ord(c), ') is ');
  2705.         if not isalpha(c) then
  2706.             Write('not ');
  2707.         Writeln('a letter');
  2708.         end;
  2709.     end.
  2710.  
  2711.     INPUTS
  2712.  
  2713.     c     : The character to check
  2714.  
  2715.     RESULTS
  2716.     TRUE if the character is in a..z or A..Z, or
  2717.     FALSE otherwise
  2718.  
  2719.     BUGS
  2720.  
  2721.     SEE ALSO
  2722.     isalnum, isupper, islower
  2723.  
  2724.  
  2725. Utils/StringLib/isdigit            Utils/StringLib/isdigit
  2726.  
  2727.     NAME
  2728.     isdigit - check if character is in the range '0'..'9'
  2729.  
  2730.     SYNOPSIS
  2731.     Function isdigit(c : Char) : Boolean;
  2732.  
  2733.     DESCRIPTION
  2734.     isdigit returns TRUE if the character is a digit character,
  2735.     i.e. it's in the range Chr(48) to Chr(57), or '0'..'9'.
  2736.  
  2737.     EXAMPLE
  2738.  
  2739.     Program CheckAll;
  2740.     {$I "Include:Utils/StringLib.i"}
  2741.     var
  2742.         c : Char;
  2743.     begin
  2744.         for c := Chr(0) to Chr(255) do begin
  2745.         Write('Chr(', Ord(c), ') is ');
  2746.         if not isdigit(c) then
  2747.             Write('not ');
  2748.         Writeln('a digit');
  2749.         end;
  2750.     end.
  2751.  
  2752.     INPUTS
  2753.  
  2754.     c     : The character to check
  2755.  
  2756.     RESULTS
  2757.     TRUE if the character is in the range '0'..'9', or
  2758.     FALSE otherwise
  2759.  
  2760.     BUGS
  2761.  
  2762.     SEE ALSO
  2763.     isalnum, isalpha
  2764.  
  2765.  
  2766. Utils/StringLib/islower            Utils/StringLib/islower
  2767.  
  2768.     NAME
  2769.     islower - check if character is in a..z
  2770.  
  2771.     SYNOPSIS
  2772.     Function islower(c : Char) : Boolean;
  2773.  
  2774.     DESCRIPTION
  2775.     This function returns TRUE if the character is a lower
  2776.     case letter, i.e. a..z.
  2777.  
  2778.     EXAMPLE
  2779.  
  2780.     Program CheckAll;
  2781.     {$I "Include:Utils/StringLib.i"}
  2782.     var
  2783.         c : Char;
  2784.     begin
  2785.         for c := Chr(0) to Chr(255) do begin
  2786.         Write('Chr(', Ord(c), ') is ');
  2787.         if not islower(c) then
  2788.             Write('not ');
  2789.         Writeln('a lower case letter');
  2790.         end;
  2791.     end.
  2792.  
  2793.     INPUTS
  2794.  
  2795.     c     : The character to check
  2796.  
  2797.     RESULTS
  2798.     TRUE if the character is in the range a..z, or
  2799.     FALSE otherwise
  2800.  
  2801.     BUGS
  2802.  
  2803.     SEE ALSO
  2804.     isupper
  2805.  
  2806.  
  2807. Utils/StringLib/isspace            Utils/StringLib/isspace
  2808.  
  2809.     NAME
  2810.     isspace - check if character is 'white space'
  2811.  
  2812.     SYNOPSIS
  2813.     Function isspace(c : Char) : Boolean;
  2814.  
  2815.     DESCRIPTION
  2816.     This function checks whether the character is a white
  2817.     space character, which is either a space, carraige
  2818.     return, line feed, tab, or form feed.
  2819.  
  2820.     EXAMPLE
  2821.  
  2822.     Program CheckAll;
  2823.     {$I "Include:Utils/StringLib.i"}
  2824.     var
  2825.         c : Char;
  2826.     begin
  2827.         for c := Chr(0) to Chr(255) do begin
  2828.         Write('Chr(', Ord(c), ') is ');
  2829.         if not isupper(c) then
  2830.             Write('not ');
  2831.         Writeln('white space');
  2832.         end;
  2833.     end.
  2834.  
  2835.     INPUTS
  2836.  
  2837.     c     : The character to check.
  2838.  
  2839.     RESULTS
  2840.     TRUE if the character is white space, or
  2841.     FALSE otherwise
  2842.  
  2843.     BUGS
  2844.  
  2845.     SEE ALSO
  2846.     isalpha, isdigit
  2847.  
  2848.  
  2849. Utils/StringLib/isupper            Utils/StringLib/isupper
  2850.  
  2851.     NAME
  2852.     isupper - check if character is in A..Z
  2853.  
  2854.     SYNOPSIS
  2855.     Function isupper(c : Char) : Boolean;
  2856.  
  2857.     DESCRIPTION
  2858.     This routine checks whether the character is an upper
  2859.     case letter.
  2860.  
  2861.     EXAMPLE
  2862.  
  2863.     Program CheckAll;
  2864.     {$I "Include:Utils/StringLib.i"}
  2865.     var
  2866.         c : Char;
  2867.     begin
  2868.         for c := Chr(0) to Chr(255) do begin
  2869.         Write('Chr(', Ord(c), ') is ');
  2870.         if not isupper(c) then
  2871.             Write('not ');
  2872.         Writeln('an uppercase letter');
  2873.         end;
  2874.     end.
  2875.  
  2876.     INPUTS
  2877.  
  2878.     c     : The character to check
  2879.  
  2880.     RESULTS
  2881.     TRUE if the character is in the range A .. Z, or
  2882.     FALSE otherwise
  2883.  
  2884.     BUGS
  2885.  
  2886.     SEE ALSO
  2887.     islower
  2888.  
  2889.  
  2890. Utils/CRT/KeyPressed            Utils/CRT/KeyPressed
  2891.  
  2892.     NAME
  2893.     KeyPressed - test whether a key has been pressed
  2894.  
  2895.     SYNOPSIS
  2896.     Function KeyPressed(CRT : Address) : Boolean;
  2897.  
  2898.     DESCRIPTION
  2899.     This routine tests whether a key is waiting to be
  2900.     read with ReadKey.
  2901.  
  2902.     EXAMPLE
  2903.  
  2904.     Procedure ReallyBusyWait(CRT : Address);
  2905.     begin
  2906.         while not KeyPressed(CRT) do
  2907.         WriteString(CRT, "Waiting!");
  2908.         ClrScr(CRT);
  2909.     end;
  2910.  
  2911.     INPUTS
  2912.  
  2913.     CRT   : A pointer to a valid CRT information block, as
  2914.         returned by the AttachConsole function.
  2915.  
  2916.     RESULTS
  2917.     TRUE if a key is waiting, FALSE otherwise.
  2918.  
  2919.     SEE ALSO
  2920.     AttachConsole, ReadKey
  2921.  
  2922.  
  2923. PCQ/Ln                    PCQ/Ln
  2924.  
  2925.     NAME
  2926.     Ln - compute the natural logarithm
  2927.  
  2928.     SYNOPSIS
  2929.     Function Ln(Expr : Real) : Real;
  2930.  
  2931.     DESCRIPTION
  2932.     The Ln function computes the natural logarithm of the
  2933.     argument.  If you have used the $N+ directive, this
  2934.     value is computed by the mathtrans.library.  Otherwise,
  2935.     it is calculated by internal PCQ routines.
  2936.  
  2937.     EXAMPLE
  2938.  
  2939.     Program ShowLn;
  2940.     var
  2941.         Value : Real;
  2942.     begin
  2943.         Write('Please enter a value: ');
  2944.         Readln(Value);
  2945.         Writeln('Natural logarithm is ', Ln(Value):0:3);
  2946.     end.
  2947.  
  2948.     INPUTS
  2949.  
  2950.     Expr  : A Real type expression
  2951.  
  2952.     RESULTS
  2953.     The natural logarithm of Expr
  2954.  
  2955.     BUGS
  2956.  
  2957.     SEE ALSO
  2958.     Exp
  2959.  
  2960. Utils/CRT/MaxX                Utils/CRT/MaxX
  2961.  
  2962.     NAME
  2963.     MaxX - returns the maximum column of the window
  2964.  
  2965.     SYNOPSIS
  2966.     Function MaxX(CRT : Address) : Short;
  2967.  
  2968.     DESCRIPTION
  2969.     MaxX returns the rightmost column of the window, in
  2970.     character coordinates, not pixels.  If the window has
  2971.     a sizing gadget, this value might change.
  2972.  
  2973.     EXAMPLE
  2974.  
  2975.     Procedure BorderBox(CRT : Address);
  2976.     var
  2977.         i : Short;
  2978.     begin
  2979.         for i := 1 to MaxX(CRT) do begin
  2980.         GotoXY(CRT, i, 1);
  2981.         WriteString(CRT, "=");
  2982.         GotoXY(CRT, i, MaxY(CRT));
  2983.         WriteString(CRT, "=");
  2984.         end;
  2985.         for i := 2 to Pred(MaxY(CRT)) do begin
  2986.         GotoXY(CRT, 1, i);
  2987.         WriteString(CRT, "|");
  2988.         GotoXY(CRT, MaxX(CRT), i);
  2989.         WriteString(CRT, "|");
  2990.         end;
  2991.     end;
  2992.  
  2993.     INPUTS
  2994.  
  2995.     CRT   : A pointer to a valid CRT information block, as
  2996.         returned by AttachConsole
  2997.  
  2998.     RESULTS
  2999.     The rightmost column, in character coordinates, for the
  3000.     window at the moment.
  3001.  
  3002.     SEE ALSO
  3003.     AttachConsole, MaxY, GotoXY, WhereX, WhereY
  3004.  
  3005.  
  3006. Utils/CRT/MaxY                Utils/CRT/MaxY
  3007.  
  3008.     NAME
  3009.     MaxY - return the maximum row of the window
  3010.  
  3011.     SYNOPSIS
  3012.     Function MaxY(CRT : Address) : Short;
  3013.  
  3014.     DESCRIPTION
  3015.     This function returns the bottommost row for the window.
  3016.     If the window has a sizing gadget, this value could change
  3017.     throughout the program.
  3018.  
  3019.     EXAMPLE
  3020.  
  3021.     Procedure BorderBox(CRT : Address);
  3022.     var
  3023.         i : Short;
  3024.     begin
  3025.         for i := 1 to MaxX(CRT) do begin
  3026.         GotoXY(CRT, i, 1);
  3027.         WriteString(CRT, "=");
  3028.         GotoXY(CRT, i, MaxY(CRT));
  3029.         WriteString(CRT, "=");
  3030.         end;
  3031.         for i := 2 to Pred(MaxY(CRT)) do begin
  3032.         GotoXY(CRT, 1, i);
  3033.         WriteString(CRT, "|");
  3034.         GotoXY(CRT, MaxX(CRT), i);
  3035.         WriteString(CRT, "|");
  3036.         end;
  3037.     end;
  3038.  
  3039.     INPUTS
  3040.  
  3041.     CRT   : A pointer to a valid CRT information block, as
  3042.         returned by AttachConsole.
  3043.  
  3044.     RESULTS
  3045.     The bottommost row, in character coordinates, of the
  3046.     window at the moment.
  3047.  
  3048.     SEE ALSO
  3049.     AttachConsole, MaxX, GotoXY, WhereX, WhereY
  3050.  
  3051.  
  3052. PCQ/New                    PCQ/New
  3053.  
  3054.     NAME
  3055.     New - allocate space for a record
  3056.  
  3057.     SYNOPSIS
  3058.     Procedure New(var p : Any pointer type);
  3059.  
  3060.     DESCRIPTION
  3061.     The New procedure allocates memory for an instance of the
  3062.     type referenced by the pointer.  The memory is allocated
  3063.     through the PCQ memory allocation mechanism, which means
  3064.     that each allocation will have between 12 and 19 bytes of
  3065.     overhead (compared to 0 to 7 bytes for direct Exec calls).
  3066.  
  3067.     If the memory is not available, the HeapError function is
  3068.     called, and it determines the action taken from that point.
  3069.     By default, the program terminates with runtime error 54,
  3070.     but it could simply assign Nil to the variable p.
  3071.  
  3072.     PCQ memory is always allocated with the flags MEMF_PUBLIC
  3073.     and MEMF_CLEAR.  If you need any other flags, you'll need
  3074.     to call AllocMem directly.
  3075.  
  3076.     EXAMPLE
  3077.  
  3078.     Program ShowNew;
  3079.     type
  3080.         Rec = record
  3081.               Field1, Field2 : Integer;
  3082.           end;
  3083.     var
  3084.         Ptr : ^Rec;
  3085.     begin
  3086.         New(Ptr);
  3087.         Writeln('Ptr allocated at ', Integer(Ptr));
  3088.     end.
  3089.  
  3090.     INPUTS
  3091.  
  3092.     p     : Any pointer variable.  You should not use the
  3093.         Address type, since Address does not point to a
  3094.         specific type.
  3095.  
  3096.     RESULTS
  3097.     None
  3098.  
  3099.     BUGS
  3100.  
  3101.     SEE ALSO
  3102.     Dispose, GetMem, AllocString, AllocMem
  3103.  
  3104.  
  3105. Utils/BuildMenu/NewItem            Utils/BuildMenu/NewItem
  3106.  
  3107.     NAME
  3108.     NewItem - add a menu item to the current menu
  3109.  
  3110.     SYNOPSIS
  3111.     Procedure NewItem(Name : String; Comm : Char);
  3112.  
  3113.     DESCRIPTION
  3114.     NewItem adds a menu item to the current menu strip, under
  3115.     the menu defined in the most recent NewMenu call.  The
  3116.     item is placed directly below any previous item defined
  3117.     for the same menu.
  3118.  
  3119.     You must call NewMenu before calling this routine, and you
  3120.     must call this routine before calling NewSubItem.
  3121.  
  3122.     NewItem lets you set up a command key for the item by
  3123.     passing a character in the Comm parameter.  If you don't
  3124.     want a keyboard equivalent for this item (if the item has
  3125.     a SubItem, for example, it shouldn't have one), just pass
  3126.     Chr(0) for Comm.
  3127.  
  3128.     When defining items and sub-items, you should add spaces to
  3129.     the text of the shortest items to make all the text the same
  3130.     length.  That will make all of the selection boxes the same
  3131.     size, which looks better and is easier to use than different
  3132.     sized boxes.
  3133.  
  3134.     EXAMPLE
  3135.     see Examples/SmallCom.p, Examples/DeadKeysPlus.p,
  3136.         Examples/ConsoleTest.p
  3137.  
  3138.     INPUTS
  3139.     Name : a string defining the text to be displayed for the
  3140.            item.
  3141.     Comm : the command key to be used for this item, or Chr(0)
  3142.            if no command key should be used.
  3143.  
  3144.     RESULTS
  3145.     None
  3146.  
  3147.     SEE ALSO
  3148.     InitializeMenu, NewMenu, NewSubItem, AttachMenu,
  3149.     DetachMenu
  3150.  
  3151.  
  3152. Utils/BuildMenu/NewMenu            Utils/BuildMenu/NewMenu
  3153.  
  3154.     NAME
  3155.     NewMenu - attach a menu to the current menu strip
  3156.  
  3157.     SYNOPSIS
  3158.     Procedure NewMenu(MenuText : String);
  3159.  
  3160.     DESCRIPTION
  3161.     NewMenu adds another menu to the current menu strip.
  3162.     The menu is placed just to the right of any previous one,
  3163.     with a width based on the window's font.
  3164.  
  3165.     NewMenu must be called at least once before any calls
  3166.     to NewItem.
  3167.  
  3168.     EXAMPLE
  3169.     See Examples/SmallCom.p, Examples/DeadKeysPlus.p,
  3170.         Examples/ConsoleTest.p
  3171.  
  3172.     INPUTS
  3173.     MenuText : The text you want displayed on the menu bar.
  3174.  
  3175.     RESULTS
  3176.     None
  3177.  
  3178.     SEE ALSO
  3179.     InitializeMenu, NewItem, NewSubItem, AttachMenu,
  3180.     DetachMenu
  3181.  
  3182.  
  3183. Utils/BuildMenu/NewSubItem        Utils/BuildMenu/NewSubItem
  3184.  
  3185.     NAME
  3186.     NewSubItem - add a sub-item to a menu item
  3187.  
  3188.     SYNOPSIS
  3189.     Procedure NewSubItem(Name : String; Comm : Char);
  3190.  
  3191.     DESCRIPTION
  3192.     NewSubItem is the same as NewItem, but adds the new item
  3193.     to the most recent item, rather than the most recent menu.
  3194.  
  3195.     You must call NewItem before calling this routine.
  3196.  
  3197.     If you do not want to use a keyboard equivalent for the
  3198.     item, pass Chr(0) in the Comm parameter.
  3199.  
  3200.     EXAMPLE
  3201.     See Examples/SmallCom.p and Examples/DeadKeysPlus.p
  3202.  
  3203.     INPUTS
  3204.     Name : The text to be displayed in the sub item.
  3205.     Comm : A command key, or Chr(0) if no keyboard equivalent
  3206.            should be used.
  3207.  
  3208.     RESULTS
  3209.     None
  3210.  
  3211.     SEE ALSO
  3212.     InitializeMenu, NewMenu, NewItem, AttachMenu,
  3213.     DetachMenu
  3214.  
  3215.  
  3216. PCQ/Open                PCQ/Open
  3217.  
  3218.     NAME
  3219.     Open - open a Pascal file for writing
  3220.  
  3221.     SYNOPSIS
  3222.     Function Open(    FileName   : String;
  3223.             FileVar    : VAR Any file type
  3224.             [ ; BufferSize : Integer ] ) : Boolean;
  3225.  
  3226.     DESCRIPTION
  3227.     The Open function opens a file for output, erasing any
  3228.     existing file of the same name.  If the file opens
  3229.     correctly, Open returns True.  If anything goes wrong,
  3230.     it returns False.  The Open function is provided for
  3231.     convenience only - you can do the same job by calling
  3232.     Rewrite and checking IOResult.
  3233.  
  3234.     The BufferSize parameter determines how large the file
  3235.     buffer will be (i.e. how many bytes you can write before
  3236.     the program has to call AmigaDOS).  It is optional - if
  3237.     you don't specify a value, 128 is used.
  3238.  
  3239.     Open does not affect IOResult, so you never need to
  3240.     check it after calling Open.  The downside of that is
  3241.     you can't find out exactly why the file could not be
  3242.     opened - to do that, use Rewrite and check IOResult.
  3243.  
  3244.     EXAMPLE
  3245.  
  3246.     Program ConToCon;
  3247.     var
  3248.         OutFile : Text;
  3249.         c       : Char;
  3250.     begin
  3251.         if Open("CON:100/50/200/100/Copy Output",OutFile) then begin
  3252.         repeat
  3253.             Read(c);
  3254.             Write(OutFile, c);
  3255.         until c = '!';
  3256.         Readln;
  3257.         Close(OutFile);
  3258.         end else
  3259.         Writeln('Could not open console window');
  3260.     end.
  3261.  
  3262.     INPUTS
  3263.  
  3264.     FileName   : A String containing the AmigaDOS file name and
  3265.              optional path.
  3266.     FileVar    : Any PCQ file type.
  3267.     BufferSize : The number of bytes to allocate as a buffer.  If
  3268.              no value is given, 128 will be used.
  3269.  
  3270.     RESULTS
  3271.     TRUE if the file opened correctly, or
  3272.     FALSE if anything at all went wrong.
  3273.  
  3274.     BUGS
  3275.  
  3276.     SEE ALSO
  3277.     Rewrite, ReOpen, Reset, Close, IOResult
  3278.  
  3279.  
  3280. Utils/ConsoleUtils/OpenConsoleDevice    Utils/ConsoleUtils/OpenConsoleDevice
  3281.  
  3282.     NAME
  3283.     OpenConsoleDevice - assign a valid value to ConsoleBase
  3284.  
  3285.     SYNOPSIS
  3286.     Procedure OpenConsoleDevice;
  3287.  
  3288.     DESCRIPTION
  3289.     This routine just opens the console.device without attaching
  3290.     it to a window, so you can make calls to RawKeyConvert and
  3291.     CDInputHandler.  It also needs to be open for DeadKeyConvert.
  3292.  
  3293.     EXAMPLE
  3294.     see Examples/SmallCom.p, Examples/Map.p, Examples/3d.p
  3295.  
  3296.     INPUTS
  3297.     None
  3298.  
  3299.     RESULTS
  3300.     None
  3301.  
  3302.     SEE ALSO
  3303.     CloseConsoleDevice, DeadKeyConvert
  3304.  
  3305.  
  3306. Utils/DoubleBuffer/OpenDoubleBuffer    Utils/DoubleBuffer/OpenDoubleBuffer
  3307.  
  3308.     NAME
  3309.     OpenDoubleBuffer - create a double buffered screen and window
  3310.  
  3311.     SYNOPSIS
  3312.     Function OpenDoubleBuffer(ns : NewScreenPtr) : WindowPtr;
  3313.  
  3314.     DESCRIPTION
  3315.     OpenDoubleBuffer creates a screen according to the NewScreen
  3316.     passed to it, then opens a borderless backdrop window on it.
  3317.     It then allocates extra BitMap memory, and sets the Window's
  3318.     BitMap to point to this second buffer.  When the function
  3319.     returns, you can pull the RastPortPtr from the Window
  3320.     structure, and draw into that same RastPort for the entire
  3321.     program.  When you want to display the RastPort, just call
  3322.     SwapBuffers.
  3323.  
  3324.     Since this routine creates Screens and Windows that the
  3325.     system doesn't expect, you should try to avoid having the
  3326.     system draw into them.  This means that you should not add
  3327.     menus or Window imagery - you should only use RastPort-level
  3328.     graphics.library calls.
  3329.  
  3330.     Windows and Screens opened with OpenDoubleBuffer should
  3331.     only be closed with CloseDoubleBuffer.
  3332.  
  3333.     EXAMPLE
  3334.     See Examples/3d.p
  3335.  
  3336.     INPUTS
  3337.  
  3338.     ns    : A pointer to a NewScreen structure.
  3339.  
  3340.     RESULTS
  3341.     A valid WindowPtr, or Nil if something went wrong.
  3342.  
  3343.     BUGS
  3344.  
  3345.     SEE ALSO
  3346.     CloseDoubleBuffer, SwapBuffers
  3347.  
  3348.  
  3349. Utils/MathTransUtils/OpenMathTrans    Utils/MathTransUtils/OpenMathTrans
  3350.  
  3351.     NAME
  3352.     OpenMathTrans - open the mathtrans.library
  3353.  
  3354.     SYNOPSIS
  3355.     Function OpenMathTrans : Boolean;
  3356.  
  3357.     DESCRIPTION
  3358.     This routine is equivalent to calling OpenLibrary on the
  3359.     Motorola FFP trancendental math library.  If the library
  3360.     can be opened, OpenMathTrans returns TRUE, and otherwise
  3361.     it returns FALSE.
  3362.  
  3363.     This routine initializes MathTransBase, which is defined
  3364.     in Libraries/MathTrans.i.
  3365.  
  3366.     EXAMPLE
  3367.  
  3368.     Program TryTrans;
  3369.     {$I "Include:Utils/MathTransUtils.i"}
  3370.     begin
  3371.         if OpenMathTrans then begin
  3372.         Writeln('mathtrans.library is available');
  3373.         CloseMathTrans;
  3374.         end else
  3375.         Writeln('mathtrans.library is not available');
  3376.     end.
  3377.  
  3378.     INPUTS
  3379.     None
  3380.  
  3381.     RESULTS
  3382.     TRUE if the library could be opened, or
  3383.     FALSE if something went wrong
  3384.  
  3385.     BUGS
  3386.  
  3387.     SEE ALSO
  3388.     CloseMathTrans, FlushMathTrans, and all the mathtrans.library
  3389.     routines themselves (e.g. SPAcos, APCosh, etc).
  3390.  
  3391.  
  3392. PCQ/Ord                    PCQ/Ord
  3393.  
  3394.     NAME
  3395.     Ord - return the ordinal value of an expression
  3396.  
  3397.     SYNOPSIS
  3398.     Function Ord(Expr : Any ordinal expression) : Integer;
  3399.  
  3400.     DESCRIPTION
  3401.     The Ord function returns the Integer value of any ordinal
  3402.     type.
  3403.  
  3404.     EXAMPLE
  3405.  
  3406.     Program ShowOrd;
  3407.     var
  3408.         Ch : Char;
  3409.     begin
  3410.         Write('Enter a character: ');
  3411.         Readln(Ch);
  3412.         Writeln('The ordinal value of ', Ch, ' is ', Ord(Ch));
  3413.     end.
  3414.  
  3415.     INPUTS
  3416.  
  3417.     Expr  : Any ordinal expression
  3418.  
  3419.     RESULTS
  3420.     The Integer corresponding to its ordinal value within
  3421.     the type.
  3422.  
  3423.     BUGS
  3424.  
  3425.     SEE ALSO
  3426.  
  3427.  
  3428. PCQ/Pred                PCQ/Pred
  3429.  
  3430.     NAME
  3431.     Pred - return the predecessor of an expression
  3432.  
  3433.     SYNOPSIS
  3434.     Function Pred(Expr : Any ordinal type) : The same type;
  3435.  
  3436.     DESCRIPTION
  3437.     The Pred function returns the previous value within an
  3438.     ordinal type.  If the expression is already at its
  3439.     minimum value, it will wrap around.  In the case of
  3440.     enumerated types, that will almost always produce
  3441.     nonsense results.
  3442.  
  3443.     EXAMPLE
  3444.  
  3445.     Program ShowPred;
  3446.     var
  3447.         month : (january,february,march,april,may,
  3448.              june,july,august,september,october,
  3449.              november,december);
  3450.     begin
  3451.         month := december;
  3452.         while month > january do
  3453.         month := Pred(month);
  3454.     end.
  3455.  
  3456.     INPUTS
  3457.  
  3458.     Expr  : Any ordinal expression
  3459.  
  3460.     RESULTS
  3461.     A value of the same ordinal type
  3462.  
  3463.     BUGS
  3464.  
  3465.     SEE ALSO
  3466.     Dec, Succ
  3467.  
  3468.  
  3469. Utils/RunProgram/ProgramFinished    Utils/RunProgram/ProgramFinished
  3470.  
  3471.     NAME
  3472.     ProgramFinished - check child status
  3473.  
  3474.     SYNOPSIS
  3475.     Funtion ProgramFinished(RP : RunProgPtr) : Boolean;
  3476.  
  3477.     DESCRIPTION
  3478.     If a child created by RunSegmentNW or RunProgramNW has
  3479.     finished, this routine deallocates all the resources
  3480.     allocated by the run routines and returns TRUE.  If not,
  3481.     it returns FALSE.
  3482.  
  3483.     Note that this routine will only free resources it has
  3484.     allocated - it will not, for example, unload a segment
  3485.     that it did not load.
  3486.  
  3487.     EXAMPLE
  3488.  
  3489.     Program BusySystem;
  3490.     {$I "Include:Utils/RunProgram.i"}
  3491.     var
  3492.         Child : RunProgPtr;
  3493.     begin
  3494.         Child := RunProgramNW("OtherFile",4000);
  3495.         if Child <> Nil then begin
  3496.         repeat
  3497.             Writeln('Otherfile is still running');
  3498.         until ProgramFinished(Child);
  3499.         end else
  3500.         Writeln('Could not load OtherFile');
  3501.     end.
  3502.  
  3503.     INPUTS
  3504.  
  3505.     RP    : A pointer to a private information block as
  3506.         returned by RunSegmentNW or RunProgramNW.
  3507.  
  3508.     RESULTS
  3509.     TRUE if the child process has finished execution, in
  3510.          which case the resources allocated for the process
  3511.          will have been freed.
  3512.     FALSE if the child is still running.
  3513.  
  3514.     BUGS
  3515.  
  3516.     SEE ALSO
  3517.     RunProgramNW, RunProgram, RunSegmentNW, RunSegment,
  3518.     FinishProgram
  3519.  
  3520.  
  3521. PCQ/Put                    PCQ/Put
  3522.  
  3523.     NAME
  3524.     Put - advance an output file pointer
  3525.  
  3526.     SYNOPSIS
  3527.     Procedure Put(VAR F : Any type of file);
  3528.  
  3529.     DESCRIPTION
  3530.     The Put procedure advances the file pointer on an
  3531.     output file past the current record.  If the file
  3532.     pointer is advanced to the end of the file buffer,
  3533.     the buffer is flushed.
  3534.  
  3535.     This routine is normally used in conjunction with
  3536.     the file pointer to write information to a file
  3537.     directly.
  3538.  
  3539.     EXAMPLE
  3540.  
  3541.     Program ShowPut;
  3542.     begin
  3543.         Output^ := 'z';
  3544.         Put(Output);  { Same as Write(Output, 'z'); }
  3545.     end.
  3546.  
  3547.     INPUTS
  3548.  
  3549.     F     : A PCQ file open for output
  3550.  
  3551.     RESULTS
  3552.     None
  3553.  
  3554.     BUGS
  3555.  
  3556.     SEE ALSO
  3557.     Get, Write, Writeln, Open, Rewrite
  3558.  
  3559.  
  3560. Utils/ConsoleIO/QueueRead        Utils/ConsoleIO/QueueRead
  3561.  
  3562.     NAME
  3563.     QueueRead - tell the console.device where to put character
  3564.  
  3565.     SYNOPSIS
  3566.     Procedure QueueRead(Req : IOStdReqPtr; Where : String);
  3567.  
  3568.     DESCRIPTION
  3569.     The QueueRead routine lets the console.device know that
  3570.     you want to read a character.  If a character arrives,
  3571.     the console.device will put it in Where and return the
  3572.     Req.  Note that you must have already called OpenDevice
  3573.     to initialize the Req and attach it to a window.
  3574.  
  3575.     Remember that the QueueRead returns immediately - it does
  3576.     not wait until a character is available.  You must use
  3577.     CheckIO to see if a character has arrived.
  3578.  
  3579.     You might want to check the routines in Utils/CRT.i to see
  3580.     if they better suit your needs.
  3581.  
  3582.     EXAMPLE
  3583.  
  3584.     Function ReadConCharacter(IO : IOStdReqPtr) : Char;
  3585.     var
  3586.         CharBuffer  : Char;
  3587.         Dummy    : Integer;
  3588.     begin
  3589.         QueueRead(IO, @CharBuffer);
  3590.         Dummy := WaitIO(IO);
  3591.         ReadConCharacter := CharBuffer;
  3592.     end;
  3593.  
  3594.     INPUTS
  3595.     Req : a pointer to a valid IOStdReq, intialized by
  3596.           OpenDevice.
  3597.     Where : A pointer to at least one byte of memory to
  3598.         receive the character.
  3599.  
  3600.     RESULTS
  3601.     None
  3602.  
  3603.     SEE ALSO
  3604.     ConGetChar, ConPutChar, ConPutStr, ConWrite
  3605.  
  3606. Utils/Random/RangeRandom        Utils/Random/RangeRandom
  3607.  
  3608.     NAME
  3609.     RangeRandom - return a psuedo random integer
  3610.  
  3611.     SYNOPSIS
  3612.     Function RangeRandom(MaxValue : Integer) : Integer;
  3613.  
  3614.     DESCRIPTION
  3615.     RangeRandom returns a psuedo random number in the range
  3616.     0..MaxValue.  It uses a faster generator than RealRandom,
  3617.     and has a maximum cycle length of 1,000,002.
  3618.  
  3619.     EXAMPLE
  3620.  
  3621.     Program CheckCycle;
  3622.     {$I "Include:Utils/Random.i"}
  3623.     var
  3624.         StartPoint : Integer;
  3625.         Count      : Integer;
  3626.     begin
  3627.         SelfSeed;
  3628.         Count := 0;
  3629.         StartPoint := RangeRandom(Pred(MaxInt));
  3630.         repeat
  3631.         Inc(Count);
  3632.         until RangeRandom(Pred(MaxInt)) = StartPoint;
  3633.         Writeln('The cycle length is ', Count);
  3634.     end.
  3635.  
  3636.     INPUTS
  3637.  
  3638.     MaxValue : The greatest value the result should take on
  3639.  
  3640.     RESULTS
  3641.     An unpredictable Integer in the range 0 to MaxValue
  3642.  
  3643.     BUGS
  3644.     Since RangeRandom scales the result using something like
  3645.     (Value mod Succ(MaxValue)), you should not use MaxInt as
  3646.     the maximum value, or you'll cause a divide by zero error.
  3647.  
  3648.     SEE ALSO
  3649.     RealRandom, UseSeed, SelfSeed
  3650.  
  3651.  
  3652. PCQ/Read                PCQ/Read
  3653.  
  3654.     NAME
  3655.     Read - input data from a PCQ file
  3656.  
  3657.     SYNOPSIS
  3658.     Procedure Read([VAR InputFile; ] References );
  3659.  
  3660.     DESCRIPTION
  3661.     The Read procedure gets input from the specified file,
  3662.     or from the standard input file Input if no file is
  3663.     specified.  It assigns to each of the variable
  3664.     references the next value from the file.  If the
  3665.     file is a typed file, each reference must have the
  3666.     same type as the file.  If it is a Text file, the
  3667.     references can have one of several different types,
  3668.     and the sequence of characters read is converted to
  3669.     that type.
  3670.  
  3671.     If the reference is an Integer, Short, Word, or Byte
  3672.     type, Read first skips over any 'white space', e.g.
  3673.     spaces, tabs, etc.  It then reads a decimal number,
  3674.     possibly beginning with a minus sign.  The procedure
  3675.     reads all the decimal digits, and leaves the file
  3676.     pointer on the first character following the last
  3677.     digit.  If there were no digits before the first
  3678.     letter, Read sets IOResult to 59.  If there are no
  3679.     digits before the end of file, it sets IOResult to
  3680.     58.
  3681.  
  3682.     If the reference is a Char type, Read assigns to it
  3683.     the next character in the file.  Standard Pascal
  3684.     converts control characters into spaces, but PCQ
  3685.     passes them through unchanged.
  3686.  
  3687.     If the reference is a Real type, Read inputs the
  3688.     integer portion as described above.  If the next
  3689.     character is a decimal point, Read continues reading
  3690.     digits until the next character is a non-digit.  The
  3691.     file pointer is left on that digit.  The decimal point
  3692.     is optional, and there does not have to be any digits
  3693.     following the decimal point.  There does, however,
  3694.     have to be at least one digit before a decimal point.
  3695.  
  3696.     If the reference is a String type, Read inputs
  3697.     all the characters up to, but not including, the
  3698.     next end-of-line marker into the string.  The string
  3699.     must be long enough to hold all these characters.
  3700.     The file pointer is left on the end-of-line marker.
  3701.  
  3702.     If the reference is an Array of Char, Read inputs
  3703.     characters until it fills the entire array, or until
  3704.     the end-of-line is reached, whichever comes first.
  3705.     If it hits the end-of-line before filling the array,
  3706.     it pads the remaining part of the array with spaces.
  3707.     The file pointer is left either on the next character
  3708.     or the end-of-line marker.
  3709.  
  3710.     Read will set IOResult if it has any errors.  If
  3711.     IOResult is not zero when Read is called, no input
  3712.     will take place.
  3713.  
  3714.     EXAMPLE
  3715.  
  3716.     Program ShowRead;
  3717.     var
  3718.         i : Integer;
  3719.         r : Real;
  3720.         a : Array [0..9] of Char;
  3721.     begin
  3722.         Read(i, a, r);
  3723.         Writeln(i, a:11, r:0:2);
  3724.     end.
  3725.  
  3726.     Given the input ' 456abcdefgh' (new line)
  3727.             '      45.'
  3728.     this program will write: '456 abcdefgh  45.00'
  3729.  
  3730.     INPUTS
  3731.  
  3732.     InputFile  : A PCQ file variable, which must be opened
  3733.              for input using Reopen or Reset
  3734.     References : Any number of variable references
  3735.  
  3736.     RESULTS
  3737.     None
  3738.  
  3739.     BUGS
  3740.  
  3741.     SEE ALSO
  3742.     Readln, Write, Writeln, Reopen, Reset, Get
  3743.  
  3744. Utils/CRT/ReadKey            Utils/CRT/ReadKey
  3745.  
  3746.     NAME
  3747.     ReadKey - wait for a keypress, then return the key
  3748.  
  3749.     SYNOPSIS
  3750.     Function ReadKey(CRT : Address) : Char;
  3751.  
  3752.     DESCRIPTION
  3753.     ReadKey waits until the user presses a key, then returns
  3754.     that key.
  3755.  
  3756.     EXAMPLE
  3757.  
  3758.     Procedure Typer(CRT : Address);
  3759.     var
  3760.         Buf : Array [0..1] of Char;
  3761.     begin
  3762.         Buf[1] := Chr(0);
  3763.         repeat
  3764.         Buf[0] := ReadKey(CRT);
  3765.         WriteString(CRT, String(@Buf));
  3766.         until Buf[0] = 'q';
  3767.     end;
  3768.  
  3769.     INPUTS
  3770.  
  3771.     CRT   : A pointer to a valid CRT information block as
  3772.         returned by AttachConsole
  3773.  
  3774.     RESULTS
  3775.     The character read
  3776.  
  3777.     SEE ALSO
  3778.     AttachConsole, KeyPressed
  3779.  
  3780.  
  3781. PCQ/Readln                PCQ/Readln
  3782.  
  3783.     NAME
  3784.     Readln - Read input, then read the rest of the line
  3785.  
  3786.     SYNOPSIS
  3787.     Procedure Readln([VAR InputFile : Text;] References );
  3788.  
  3789.     DESCRIPTION
  3790.     Readln calls Read to fill in each of the variables
  3791.     references, then continues reading from the file until
  3792.     either the end of file is reached, or the end-of-line
  3793.     marker has been read.  In the latter case the file
  3794.     pointer is placed on the first character of the next
  3795.     line.
  3796.  
  3797.     Readln can only be called on Text files, since Typed
  3798.     files do not use lines.
  3799.  
  3800.     EXAMPLE
  3801.  
  3802.     Program ShowReadln;
  3803.     var
  3804.         i,j : Integer;
  3805.     begin
  3806.         Readln(i);
  3807.         Readln(j);
  3808.         Writeln(i, ',', j);
  3809.     end.
  3810.  
  3811.     Given the input: '456 The rest of the line is ignored' (new line)
  3812.              '' (new line)
  3813.              '678' (new line)
  3814.  
  3815.     the program will write: '456,678'
  3816.  
  3817.     INPUTS
  3818.  
  3819.     InputFile  : An open PCQ Text file
  3820.     References : Any number of variable references.
  3821.  
  3822.     RESULTS
  3823.     None
  3824.  
  3825.     BUGS
  3826.  
  3827.     SEE ALSO
  3828.     Read, Write, Writeln, Reopen, Reset, Get
  3829.  
  3830.  
  3831. Utils/Random/RealRandom            Utils/Random/RealRandom
  3832.  
  3833.     NAME
  3834.     RealRandom - return a floating point psuedo-random number
  3835.  
  3836.     SYNOPSIS
  3837.     Function RealRandom : Real;
  3838.  
  3839.     DESCRIPTION
  3840.     RealRandom calculates a psuedo random number using a slow
  3841.     but extremely random method - it actually combines the
  3842.     results of three seperate random number generators to
  3843.     create very long cycle sequences.  The technique was
  3844.     described in the March 1987 issue of Byte.
  3845.  
  3846.     EXAMPLE
  3847.  
  3848.     Program TemptFate;
  3849.     {$I "Include:Utils/Random.i"}
  3850.     var
  3851.         R : Float;
  3852.     begin
  3853.         SelfSeed;
  3854.         repeat
  3855.         R := RealRandom;
  3856.         Writeln(R:0:4);
  3857.         until R < 0.1;
  3858.     end.
  3859.  
  3860.     INPUTS
  3861.     None
  3862.  
  3863.     RESULTS
  3864.     An unexpected FFP floating point value
  3865.  
  3866.     BUGS
  3867.  
  3868.     SEE ALSO
  3869.     RangeRandom, UseSeed, SelfSeed
  3870.  
  3871.  
  3872. PCQ/ReOpen                PCQ/ReOpen
  3873.  
  3874.     NAME
  3875.     ReOpen - open a file for reading
  3876.  
  3877.     SYNOPSIS
  3878.     Function ReOpen(FileName    : String;
  3879.             VAR FileVar    : Any file type
  3880.             [ ; BufferSize    : Integer ] ) : Boolean;
  3881.  
  3882.     DESCRIPTION
  3883.     ReOpen attempts to open an existing file for reading.
  3884.     ReOpen will return True if the file opens correctly, and
  3885.     False otherwise.  The opened file behaves exactly as if
  3886.     it was opened with Reset - this routine is provided just
  3887.     for convenience.
  3888.  
  3889.     ReOpen does not set IOResult, so you don't have to check
  3890.     it after a failed call.  If you want specific information
  3891.     about why the file could not be opened, use Reset and
  3892.     check IOResult directly.
  3893.  
  3894.     The BufferSize parameter is optional - if it is omitted,
  3895.     the compiler will use the value 128.
  3896.  
  3897.     EXAMPLE
  3898.  
  3899.     Program ShowText;
  3900.     {$I "Include:Utils/StringLib.i"}
  3901.     {$I "Include:Utils/Parameters.i"}
  3902.     var
  3903.         c        : Char;
  3904.         InFile   : Text;
  3905.         FileName : String;
  3906.     begin
  3907.         FileName := AllocString(256);
  3908.         GetParam(1,FileName);
  3909.         if ReOpen(FileName, InFile, 10000) then begin
  3910.         while not EOF(InFile) do begin
  3911.             Read(InFile, c);
  3912.             Write(c);
  3913.         end;
  3914.         Close(InFile);
  3915.         end else
  3916.         Writeln('Could not open ', FileName);
  3917.     end.
  3918.  
  3919.     INPUTS
  3920.  
  3921.     FileName   : The AmigaDOS file name, with path if necessary.
  3922.     FileVar    : Any Pascal file type
  3923.     BufferSize : The number of bytes to allocate as a file buffer.
  3924.              If this parameter is omitted, 128 is used.
  3925.  
  3926.     RESULTS
  3927.     TRUE if the file opened correctly, or
  3928.     FALSE if anything went wrong.
  3929.  
  3930.     BUGS
  3931.  
  3932.     SEE ALSO
  3933.     Reset, Rewrite, Open, IOResult
  3934.  
  3935.  
  3936. PCQ/Reset                PCQ/Reset
  3937.  
  3938.     NAME
  3939.     Reset - open a file for reading
  3940.  
  3941.     SYNOPSIS
  3942.     Procedure Reset(VAR F    : Any file type;
  3943.             FileName : String
  3944.             [ ; BufferSize : Integer ] );
  3945.  
  3946.     DESCRIPTION
  3947.     The Reset procedure opens a PCQ file for input.  If the
  3948.     file cannot be opened, IOResult is set to a non-zero
  3949.     value.  If you are using automatic IO checking, the
  3950.     default, your program will terminate.  If you have used
  3951.     the {$I-} option to set IO checking to manual, you will
  3952.     need to check the IOResult function before continuing.
  3953.  
  3954.     If you specify a BufferSize, Reset will attempt to
  3955.     allocate a buffer of that size (actually the closest
  3956.     multiple of the record size).  If the BufferSize parameter
  3957.     is not used, the default is 128.
  3958.  
  3959.     EXAMPLE
  3960.  
  3961.     Program OpenUp;
  3962.     {$I "Include:Utils/StringLib.i"}
  3963.     {$I "Include:Utils/Parameters.i"}
  3964.     {$I-  set IO checking to manual }
  3965.     var
  3966.         FileName : String;
  3967.         TestFile : Text;
  3968.     begin
  3969.         FileName := AllocString(256);
  3970.         GetParam(1,FileName);
  3971.         Reset(TestFile,FileName,1024);
  3972.         if IOResult = 0 then begin
  3973.         Writeln('The file is open');
  3974.         Close(TestFile);
  3975.         end else
  3976.         Writeln('Could not open ', FileName);
  3977.     end.
  3978.  
  3979.     INPUTS
  3980.  
  3981.     F          : Any PCQ File type
  3982.     FileName   : A String specifying the file name and path, if
  3983.              necessary.
  3984.     BufferSize : The size of the input buffer to allocate.
  3985.  
  3986.     RESULTS
  3987.     None
  3988.  
  3989.     BUGS
  3990.  
  3991.     SEE ALSO
  3992.     Reopen, Rewrite, Open
  3993.  
  3994.  
  3995. PCQ/Rewrite                PCQ/Rewrite
  3996.  
  3997.     NAME
  3998.     Rewrite - open a file for output
  3999.  
  4000.     SYNOPSIS
  4001.     Procedure Rewrite(VAR F      : Any file type;
  4002.               FileName   : String
  4003.               [ ; BufferSize : Integer ] );
  4004.  
  4005.     DESCRIPTION
  4006.     Rewrite opens a PCQ file for output, erasing any existing
  4007.     file of the same name.  If the file does not open
  4008.     correctly, IOResult is set to a non-zero value, which
  4009.     will cause programs using automatic IO checking to
  4010.     abort.
  4011.  
  4012.     If a buffer size is not specified, a value of 128 is used.
  4013.  
  4014.     EXAMPLE
  4015.  
  4016.     Program ShowRewrite;
  4017.     {$I "Include:Utils/Parameters.i"}
  4018.     {$I "Include:Utils/StringLib.i"}
  4019.     {$I- turn off automatic IO checking }
  4020.     var
  4021.         FileName : String;
  4022.         TempFile : Text;
  4023.     begin
  4024.         FileName := AllocString(256);
  4025.         GetParam(1,FileName);
  4026.         Rewrite(TempFile, FileName, 10);
  4027.         if IOResult = 0 then begin
  4028.         Writeln('File opened correctly');
  4029.         Close(TempFile);
  4030.         end else
  4031.         Writeln('Could not open ', FileName);
  4032.     end.
  4033.  
  4034.     INPUTS
  4035.  
  4036.     F          : Any file variable.  It should not already
  4037.              be open.
  4038.     FileName   : The file name and path if necessary
  4039.     BufferSize : The size of the buffer to allocate for
  4040.              this file.  This value is optional, and
  4041.              if it's not supplied 128 is used.
  4042.  
  4043.     RESULTS
  4044.     None
  4045.  
  4046.     BUGS
  4047.  
  4048.     SEE ALSO
  4049.     Open, Reset, Reopen
  4050.  
  4051.  
  4052. PCQ/Round                PCQ/Round
  4053.  
  4054.     NAME
  4055.     Round - convert a Real value to an Integer by rounding
  4056.  
  4057.     SYNOPSIS
  4058.     Function Round(Expr : Real) : Integer;
  4059.  
  4060.     DESCRIPTION
  4061.     This routine converts a floating point value to an Integer
  4062.     by rounding it to the nearest whole value.  This routine
  4063.     is implemented as Trunc(Expr + 0.5) for positive Expr or
  4064.     Trunc(Expr - 0.5) for negative values.  Thus it is somewhat
  4065.     slower than the Trunc function, and it always rounds 0.5
  4066.     up for positive values or down for negative.
  4067.  
  4068.     EXAMPLE
  4069.  
  4070.     Program ShowRound;
  4071.     var
  4072.         FloatValue : Real;
  4073.     begin
  4074.         Write('Please enter a Real value: ');
  4075.         Readln(FloatValue);
  4076.         Writeln(FloatValue:0:3, ' rounds to ',
  4077.                 Round(FloatValue));
  4078.     end.
  4079.  
  4080.     INPUTS
  4081.  
  4082.     Expr : Any Real type expression
  4083.  
  4084.     RESULTS
  4085.     An integer formed by rounding Expr to the nearest whole
  4086.     number.
  4087.  
  4088.     BUGS
  4089.  
  4090.     SEE ALSO
  4091.     Trunc, Float
  4092.  
  4093.  
  4094. Utils/RunProgram/RunProgram        Utils/RunProgram/RunProgram
  4095.  
  4096.     NAME
  4097.     RunProgram - load and run a program
  4098.  
  4099.     SYNOPSIS
  4100.     Function RunProgram(FileName  : String;
  4101.                 StackSize : Integer) : Boolean;
  4102.  
  4103.     DESCRIPTION
  4104.     RunProgram loads a program, then runs it as a seperate
  4105.     process.  The child process acts as if it were run from
  4106.     the Workbench, so any programs that can't handle that
  4107.     should not be used with this routine.
  4108.  
  4109.     RunProgram returns TRUE if it was able to load the
  4110.     program and successfully create a new process, and
  4111.     FALSE otherwise.  This result doesn't tell you anything
  4112.     about the program's returncode, or any other measure of
  4113.     its success - you'll have to check that some other way.
  4114.  
  4115.     This routine provides no way of passing command line
  4116.     parameters to the new process.  Again, you'll have to
  4117.     handle that through configuration files or some other
  4118.     means.
  4119.  
  4120.     EXAMPLE
  4121.  
  4122.     Program RunOther;
  4123.     {$I "Include:Utils/RunProgram.i"}
  4124.     {$I "Include:Utils/StringLib.i"}
  4125.     {$I "Include:Utils/Parameters.i"}
  4126.     var
  4127.         ChildName : String;
  4128.     begin
  4129.         ChildName := AllocString(256);
  4130.         GetParam(1,ChildName);
  4131.         if RunProgram(ChildName,4000) then
  4132.         Writeln('Successfully ran ', ChildName)
  4133.         else
  4134.         Writeln('Could not run ', ChildName);
  4135.     end.
  4136.  
  4137.     INPUTS
  4138.  
  4139.     FileName  : The filename of the program to load.  It can
  4140.             include a full path if necessary, and it will
  4141.             also serve as the process name.
  4142.     StackSize : The number of bytes to allocate for the stack
  4143.  
  4144.     RESULTS
  4145.     TRUE if the program was loaded and launched successfully
  4146.     FALSE if RunProgram was not able to load the program, or
  4147.           was not able to create the new process.
  4148.  
  4149.     BUGS
  4150.  
  4151.     SEE ALSO
  4152.     RunProgramNW, RunSegment, RunSegmentNW, FinishProgram,
  4153.     ProgramFinished
  4154.  
  4155.  
  4156. Utils/RunProgram/RunProgramNW        Utils/RunProgram/RunProgramNW
  4157.  
  4158.     NAME
  4159.     RunProgramNW - load and run a file, returning immediately
  4160.  
  4161.     SYNOPSIS
  4162.     Function RunProgramNW(FileName  : String;
  4163.                   StackSize : Integer) : RunProgPtr;
  4164.  
  4165.     DESCRIPTION
  4166.     RunProgramNW loads a program file from the disk, then
  4167.     launches it as a new process.  Unlike RunProgram, this
  4168.     routine returns immediately, while the child process is
  4169.     still running.
  4170.  
  4171.     Programs run with this routine behave as if they were
  4172.     run from the Workbench, so AmigaDOS commands like Dir
  4173.     and Copy are out of the question.  PCQ Pascal programs
  4174.     should not have any problems.  The calling program must
  4175.     wait until the child ends before ending itself.
  4176.  
  4177.     This routine does not provide a method for passing
  4178.     parameters to the new program.
  4179.  
  4180.     If the program is loaded and run successfully, this
  4181.     routine returns a pointer to a private block of memory
  4182.     that tracks system resources allocated for the new
  4183.     process.  RunProgramNW returns Nil if the program could
  4184.     not be loaded, or if the new process could not be created.
  4185.  
  4186.     EXAMPLE
  4187.  
  4188.     Program MakeChild;
  4189.     {$I "Include:Utils/RunProgram.i"}
  4190.     {$I "Include:Utils/Parameters.i"}
  4191.     {$I "Include:Utils/StringLib.i"}
  4192.     var
  4193.         ChildName : String;
  4194.         Child     : RunProgPtr;
  4195.     begin
  4196.         ChildName := AllocString(256);
  4197.         GetParam(1,ChildName);
  4198.         Child := RunProgramNW(ChildName, 4000);
  4199.         if Child <> Nil then begin
  4200.         repeat
  4201.             Writeln('It is still running');
  4202.         until ProgramFinished(Child);
  4203.         end else
  4204.         Writeln('Could not run ', ChildName);
  4205.     end.
  4206.  
  4207.     INPUTS
  4208.  
  4209.     FileName  : The file name of the program to run, which can
  4210.             include path information as necessary.  It will
  4211.             also be used as the process name.
  4212.     StackSize : The size in bytes of the stack to allocate.
  4213.  
  4214.     RESULTS
  4215.     If everything goes OK, this routine returns a pointer to
  4216.     a private information block.  If anything went wrong, it
  4217.     returns Nil.
  4218.  
  4219.     BUGS
  4220.  
  4221.     SEE ALSO
  4222.     RunProgram, RunSegmentNW, RunSegment, FinishProgram,
  4223.     ProgramFinished
  4224.  
  4225. Utils/RunProgram/RunSegment        Utils/RunProgram/RunSegment
  4226.  
  4227.     NAME
  4228.     RunSegment - create a process from the segment and run it
  4229.  
  4230.     SYNOPSIS
  4231.     Function RunSegment(ProcName  : String;
  4232.                 Segment   : Address;
  4233.                 StackSize : Integer) : Boolean;
  4234.  
  4235.     DESCRIPTION
  4236.     RunSegment creates a new process from the supplied Segment,
  4237.     and waits for it to finish.  The segment is run as if it
  4238.     were launched from the Workbench, so programs that can't
  4239.     handle that (e.g. AmigaDOS commands like Dir) should not
  4240.     be used with this routine.  Programs compiled by PCQ Pascal
  4241.     should not have a problem.
  4242.  
  4243.     If you want the parent and child processes to run at the
  4244.     same time, try RunSegmentNW instead.
  4245.  
  4246.     EXAMPLE
  4247.  
  4248.     See Exampes/TimeProg.p
  4249.  
  4250.     INPUTS
  4251.  
  4252.     ProcName  : The new process name, which can be anything.
  4253.     Segment   : A BPTR to the first segment of the program, as
  4254.             returned by LoadSeg.
  4255.     StackSize : The number of bytes to allocate for the program's
  4256.             stack.
  4257.  
  4258.     RESULTS
  4259.     TRUE indicates that the program run, but does not tell you
  4260.          anything about returncodes or other problems.
  4261.     FALSE indicates that the process could not be launched.
  4262.  
  4263.     BUGS
  4264.  
  4265.     SEE ALSO
  4266.     RunSegmentNW, RunProgram, RunProgramNW, FinishProgram,
  4267.     ProgramFinished
  4268.  
  4269.  
  4270. Utils/RunProgram/RunSegmentNW        Utils/RunProgram/RunSegmentNW
  4271.  
  4272.     NAME
  4273.     RunSegmentNW - create a process from a supplied segment
  4274.  
  4275.     SYNOPSIS
  4276.     Function RunSegmentNW(  ProcName  : String;
  4277.                 Segment   : Address;
  4278.                 StackSize : Integer) : RunProgPtr;
  4279.  
  4280.     DESCRIPTION
  4281.     RunSegmentNW is one of several related routines for easily
  4282.     creating seperate processes.  In this case, it creates a
  4283.     new process if you loaded it as a segment, or otherwise
  4284.     have the segment available to you.  "NW" stands for No Wait,
  4285.     which means that after launching the new process, this
  4286.     function returns immediately.
  4287.  
  4288.     If it could not launch the program, it returns Nil.  That
  4289.     indicates that the program was unable to create the new
  4290.     process or allocate associated memory - it does not tell
  4291.     you anything about the new processes return code, or
  4292.     anything else about its run.  If everything went OK, this
  4293.     function will return a pointer to a private area of memory
  4294.     used to track resources allocated to run this new process.
  4295.  
  4296.     As with the other RunProgram routines, the program thinks
  4297.     it was run from the Workbench, so it must be able to handle
  4298.     that.  PCQ Pascal programs should not have a problem, but
  4299.     normal AmigaDOS programs like Dir or List will not work.
  4300.     Also, these routines provide no method for setting up a
  4301.     CommandLine, or passing parameters in any way.
  4302.  
  4303.     The parent process cannot end before the child process is
  4304.     finished running.
  4305.  
  4306.     EXAMPLE
  4307.  
  4308.     Program Twofer;
  4309.     {$I "Include:Utils/RunProgram.i"}
  4310.     {$I "Include:Libraries/DOS.i"}
  4311.     {$I "Include:Libraries/DOSExtens.i"}
  4312.     var
  4313.         Child : RunProgPtr;
  4314.         MySeg : BPTR;
  4315.     begin
  4316.         MySeg := LoadSegment("Proc2");
  4317.         Child := RunSegmentNW("The Second Proc", MySeg, 4000);
  4318.         if Child <> Nil then begin
  4319.         Writeln('Running two processes');
  4320.         FinishProgram(Child);
  4321.         end else
  4322.         Writeln('Could not run the child');
  4323.     end.
  4324.  
  4325.     INPUTS
  4326.  
  4327.     ProcName  : The name to use for the new process
  4328.     Segment   : A BPTR to the start of the program's segments,
  4329.             returned by LoadSeg, for example.
  4330.     StackSize : The size of the stack to allocate for the new
  4331.             process
  4332.  
  4333.     RESULTS
  4334.     A pointer to a RunProgram information block, or Nil if the
  4335.     new process could not be created.
  4336.  
  4337.     BUGS
  4338.  
  4339.     SEE ALSO
  4340.     RunProgramNW, FinishProgram, RunProgram, RunSegment,
  4341.     ProgramFinished
  4342.  
  4343.  
  4344. Utils/SameName/SameName            Utils/SameName/SameName
  4345.  
  4346.     NAME
  4347.     SameName - match Amiga wildcards against a string
  4348.  
  4349.     SYNOPSIS
  4350.     Function SameName(Mask, Target : String) : Boolean;
  4351.  
  4352.     DESCRIPTION
  4353.     SameName determines whether a given string matches an
  4354.     Amiga wildcard expression.  This routine does not handle
  4355.     all of the Amiga wildcard options, but does take care of
  4356.     the most frequently used ones: ?, # and #?, along with
  4357.     the single quote to match literally.
  4358.  
  4359.     EXAMPLE
  4360.     See Examples/Find.p
  4361.  
  4362.     INPUTS
  4363.  
  4364.     Mask   : The Amiga wildcard expression to match against
  4365.     Target : The string to test - this one does not contain
  4366.          wildcards.
  4367.  
  4368.     RESULTS
  4369.     TRUE if the Target matches the Mask, or
  4370.     FALSE otherwise
  4371.  
  4372.     BUGS
  4373.     SameName does not handle the (), % or | options of Amiga
  4374.     expressions.
  4375.  
  4376.     SEE ALSO
  4377.  
  4378.  
  4379. Utils/Random/SelfSeed            Utils/Random/SelfSeed
  4380.  
  4381.     NAME
  4382.     SelfSeed - seed the random number generator from the clock
  4383.  
  4384.     SYNOPSIS
  4385.     Procedure SelfSeed;
  4386.  
  4387.     DESCRIPTION
  4388.     SelfSeed establishes the seed values used by RangeRandom
  4389.     RealRandom, using numbers derived from the current time.
  4390.     For most purposes this should be completely unpredictable.
  4391.  
  4392.     EXAMPLE
  4393.     See Examples/MapMaker.p
  4394.  
  4395.     INPUTS
  4396.     None
  4397.  
  4398.     RESULTS
  4399.     None
  4400.  
  4401.     BUGS
  4402.  
  4403.     SEE ALSO
  4404.     UseSeed, RangeRandom, RealRandom
  4405.  
  4406.  
  4407. Utils/TimerUtils/SetTimer        Utils/TimerUtils/SetTimer
  4408.  
  4409.     NAME
  4410.     SetTimer - request to be notified at a given time
  4411.  
  4412.     SYNOPSIS
  4413.     Function SetTimer(WhichTimer   : TimeRequestPtr;
  4414.               Seconds,
  4415.               MicroSeconds : Integer) : MsgPortPtr;
  4416.  
  4417.     DESCRIPTION
  4418.     SetTimer asks the timer.device to notify the task sometime
  4419.     after the given number of seconds and microseconds.  When
  4420.     the timer.device returns SetTimer's request at the message
  4421.     port returned by this function, at least that many seconds
  4422.     and microseconds will have elapsed.
  4423.  
  4424.     EXAMPLE
  4425.  
  4426.     Program Wait10;
  4427.     {$I "Include:Utils/TimerUtils.i"}
  4428.     {$I "Include:Exec/Ports.i"}
  4429.     var
  4430.         MyTimer : TimeRequestPtr;
  4431.         MyPort  : MsgPortPtr;
  4432.         MyMsg   : MessagePtr;
  4433.     begin
  4434.         MyTimer := CreateTimer(UNIT_VBLANK);
  4435.         MyPort  := SetTimer(MyTimer,10,0);
  4436.         MyMsg   := WaitPort(MyPort);
  4437.         MyMsg   := GetMsg(MyPort);
  4438.         Writeln('Ten seconds has elapsed');
  4439.         DeleteTimer(MyTimer);
  4440.     end.
  4441.  
  4442.     INPUTS
  4443.  
  4444.     WhichTimer   : A pointer to the TimeRequest record returned
  4445.                by CreateTimer
  4446.     Seconds      : The number of seconds to wait
  4447.     MicroSeconds : The number of microseconds to wait
  4448.  
  4449.     RESULTS
  4450.     A pointer to the MsgPort from WhichTimer, which will receive
  4451.     the reply of the timer.device.
  4452.  
  4453.     BUGS
  4454.  
  4455.     SEE ALSO
  4456.     CreateTimer, Delay, WaitTimer, GetSysTime
  4457.  
  4458.  
  4459. PCQ/Sin                    PCQ/Sin
  4460.  
  4461.     NAME
  4462.     Sin - return the sine of an expression
  4463.  
  4464.     SYNOPSIS
  4465.     Function Sin(Radians : Real) : Real;
  4466.  
  4467.     DESCRIPTION
  4468.     The Sin function returns the sine of the specified value
  4469.     in radians.  This routine will normally use a private
  4470.     sine approximation algorithm, but if you use the $N+
  4471.     directive, it will call the more accurate mathtrans
  4472.     library routine.
  4473.  
  4474.     If your program uses degrees, you can convert to radians
  4475.     using Degrees * (180 / PI), where PI is 3.14159....
  4476.  
  4477.     EXAMPLE
  4478.  
  4479.     Program ShowSin;
  4480.     var
  4481.         Value : Real;
  4482.     begin
  4483.         Write('Enter a value in radians: ');
  4484.         Readln(Value);
  4485.         Writeln('The sine of ', Value:0:3, ' is ', Sin(Value):0:3);
  4486.     end.
  4487.  
  4488.     INPUTS
  4489.  
  4490.     Radians : A Real type expression of an angle in radians.
  4491.  
  4492.     RESULTS
  4493.     The sine of the specified angle
  4494.  
  4495.     BUGS
  4496.  
  4497.     SEE ALSO
  4498.     Cos, Tan, ArcTan
  4499.  
  4500. PCQ/SizeOf                PCQ/SizeOf
  4501.  
  4502.     NAME
  4503.     SizeOf - return the size of a type
  4504.  
  4505.     SYNOPSIS
  4506.     Function SizeOf(TP : Any type identifier) : Integer;
  4507.  
  4508.     DESCRIPTION
  4509.     This function returns the size of the specified type
  4510.     in bytes.  Using this function never generates any
  4511.     code - it is simply replaced by the actual number of
  4512.     bytes, as if it were a constant.  Therefore it is a
  4513.     good idea to use this function wherever it's
  4514.     appropriate.
  4515.  
  4516.     Note that although the size of a type might be odd,
  4517.     if the size is greater than 1 any variable of that
  4518.     type will always begin on an even word boundary.
  4519.     This applies within records, arrays, or anywhere the
  4520.     variable can occur.
  4521.  
  4522.     EXAMPLE
  4523.  
  4524.     Program ShowSizes;
  4525.     begin
  4526.         Writeln('SizeOf(Real)    = ', SizeOf(Real));
  4527.         Writeln('SizeOf(Integer) = ', SizeOf(Integer));
  4528.         Writeln('SizeOf(Word)    = ', SizeOf(Word));
  4529.         Writeln('SizeOf(Short)   = ', SizeOf(Short));
  4530.         Writeln('SizeOf(Byte)    = ', SizeOf(Byte));
  4531.         Writeln('SizeOf(Address) = ', SizeOf(Address));
  4532.         Writeln('SizeOf(Boolean) = ', SizeOf(Boolean));
  4533.         Writeln('SizeOf(Char)    = ', SizeOf(Char));
  4534.         Writeln('SizeOf(Text)    = ', SizeOf(Text));
  4535.         Writeln('SizeOf(String)  = ', SizeOf(String));
  4536.     end.
  4537.  
  4538.     INPUTS
  4539.  
  4540.     TP    : Any type identifier.  This must be a simple
  4541.         identifier, not a complete type specification.
  4542.  
  4543.     RESULTS
  4544.     The size of the specified type in bytes
  4545.  
  4546.     BUGS
  4547.  
  4548.     SEE ALSO
  4549.  
  4550.  
  4551. PCQ/Sqr                    PCQ/Sqr
  4552.  
  4553.     NAME
  4554.     Sqr - return the expression squared
  4555.  
  4556.     SYNOPSIS
  4557.     Function Sqr(Expr : Any numeric type) : The same type
  4558.  
  4559.     DESCRIPTION
  4560.     This function returns the square of the value, i.e.
  4561.     Expr * Expr.
  4562.  
  4563.     EXAMPLE
  4564.  
  4565.     Program ShowSqr;
  4566.     var
  4567.         Value : Real;
  4568.     begin
  4569.         Write('Please enter a value: ');
  4570.         Readln(Value);
  4571.         Writeln(Value:0:3, ' squared is ', Sqr(Value):0:3);
  4572.     end.
  4573.  
  4574.     INPUTS
  4575.  
  4576.     Expr : Any numeric expression
  4577.  
  4578.     RESULTS
  4579.     The square of the expression, (Expr * Expr), in the
  4580.     same type.
  4581.  
  4582.     BUGS
  4583.  
  4584.     SEE ALSO
  4585.     Sqrt
  4586.  
  4587. PCQ/Sqrt                PCQ/Sqrt
  4588.  
  4589.     NAME
  4590.     Sqrt - return the square root of an expression
  4591.  
  4592.     SYNOPSIS
  4593.     Function Sqrt(Expr : Real) : Real;
  4594.  
  4595.     DESCRIPTION
  4596.     The Sqrt function returns the approximate square root
  4597.     of the specified expression, i.e. Sqrt(Expr) * Sqrt(Expr)
  4598.     is close to Expr.
  4599.  
  4600.     EXAMPLE
  4601.  
  4602.     Program ShowSqrt;
  4603.     var
  4604.         Value : Real;
  4605.     begin
  4606.         Write('Please enter a value: ');
  4607.         Readln(Value);
  4608.         Writeln('The square root of ', Value:0:3,
  4609.             ' is ', Sqrt(Value):0:3);
  4610.     end.
  4611.  
  4612.     INPUTS
  4613.  
  4614.     Expr : Any Real type expression
  4615.  
  4616.     RESULTS
  4617.     An approximation of the square root of the expression
  4618.  
  4619.     BUGS
  4620.  
  4621.     SEE ALSO
  4622.     Sqr
  4623.  
  4624. Utils/DateTools/StampDesc        Utils/DateTools/StampDesc
  4625.  
  4626.     NAME
  4627.     StampDesc - convert a DateStampRec into a DateDescription
  4628.  
  4629.     SYNOPSIS
  4630.     Procedure StampDesc(DS : DateStampRec;
  4631.                 VAR DD : DateDescription);
  4632.  
  4633.     DESCRIPTION
  4634.     This routine converts a date and time from the DateStampRec
  4635.     format into a DateDescription, which is easier to use but
  4636.     much larger.  The DateDescription is layed out as follows:
  4637.  
  4638.         DaysOfTheWeek = (Sunday, Monday, Tuesday, Wednesday,
  4639.                 Thursday, Friday, Saturday);
  4640.  
  4641.         DateDescription = record
  4642.         Day    : Byte;         { Day of month, 1..31 }
  4643.         Month    : Byte;         { Month, 1..12 }
  4644.         Year    : Short;     { Year, 1978... }
  4645.         DOW    : DaysOfTheWeek; { Sunday .. Saturday }
  4646.         Hour    : Byte;         { 0..23.  0 = 12 AM, 12 = Noon }
  4647.         Minute    : Byte;         { 0..59 }
  4648.         Second    : Byte;         { 0..59 }
  4649.         end;
  4650.  
  4651.     If you have the time in a TimeVal rather than a DateStampRec,
  4652.     you can use the GetDescription routine to convert it.
  4653.  
  4654.     EXAMPLE
  4655.  
  4656.     Program ShowTime;
  4657.     {$I "Include:Utils/DateTools.i"}
  4658.     {$I "Include:Libraries/DOS.i"}
  4659.     var
  4660.         MyStamp : DateStampRec;
  4661.         MyDate  : DateDescription;
  4662.     begin
  4663.         DateStamp(MyStamp);
  4664.         StampDesc(MyStamp,MyDate);
  4665.         with MyDate do
  4666.         Writeln('It is ', Minutes, ' after ', Hour);
  4667.     end.
  4668.  
  4669.     INPUTS
  4670.  
  4671.     DS    : An AmigaDOS DateStampRec, initialized with a date
  4672.         and time
  4673.     DD    : A DateDescription record
  4674.  
  4675.     RESULTS
  4676.     None
  4677.  
  4678.     BUGS
  4679.  
  4680.     SEE ALSO
  4681.     DateStamp, GetDescription, TimeDesc
  4682.  
  4683.  
  4684. Utils/StringLib/strcat            Utils/StringLib/strcat
  4685.  
  4686.     NAME
  4687.     strcat - concatenate two strings
  4688.  
  4689.     SYNOPSIS
  4690.     Procedure strcat(Str1, Str2 : String);
  4691.  
  4692.     DESCRIPTION
  4693.     This routine attaches Str2 on the end of Str1.  Str1 must
  4694.     have enough room for the entire resulting string, which
  4695.     will be null-terminated.
  4696.  
  4697.     EXAMPLE
  4698.  
  4699.     Program Attach;
  4700.     {$I "Include:Utils/StringLib.i"}
  4701.     var
  4702.         Str1, Str2 : String;
  4703.     begin
  4704.         Str1 := AllocString(256);
  4705.         Str2 := AllocString(256);
  4706.         Write('Enter the first string: ');
  4707.         ReadLn(Str1);
  4708.         Write('Enter the second string: ');
  4709.         Readln(Str2);
  4710.         strcat(Str1, Str2);
  4711.         Writeln('Str1 is now ', Str1);
  4712.         Writeln('Str1 is still ', Str2);
  4713.     end.
  4714.  
  4715.     INPUTS
  4716.  
  4717.     Str1  : The base string.  The second string will be
  4718.         attached to the end of this one, so Str1 must
  4719.         have enough space allocated for both.
  4720.     Str2  : The second string, which will be attached to the
  4721.         end of the first.  Str2 itself will not be
  4722.         affected.
  4723.  
  4724.     RESULTS
  4725.     None
  4726.  
  4727.     BUGS
  4728.  
  4729.     SEE ALSO
  4730.     strncat, strcpy
  4731.  
  4732.  
  4733. Utils/StringLib/strcmp            Utils/StringLib/strcmp
  4734.  
  4735.     NAME
  4736.     strcmp - compare two strings, returning relationship
  4737.  
  4738.     SYNOPSIS
  4739.     Function strcmp(Str1, Str2 : String) : Integer;
  4740.  
  4741.     DESCRIPTION
  4742.     This function returns an Integer whose relationship with
  4743.     zero is the same as the relationship of Str1 to Str2.  In
  4744.     other words, if the return value is less than zero, Str1
  4745.     is less than Str2.  If the return value is equal to zero,
  4746.     Str1 is equal to Str2.  If the return value is greater
  4747.     than zero, Str1 is greater than Str2.
  4748.  
  4749.     EXAMPLE
  4750.  
  4751.     Program Comparem;
  4752.     {$I "Include:Utils/StringLib.i"}
  4753.     var
  4754.         Str1, Str2 : String;
  4755.     begin
  4756.         Str1 := AllocString(256);
  4757.         Str2 := AllocString(256);
  4758.         Write('Enter the first string: ');
  4759.         ReadLn(Str1);
  4760.         Write('Enter the second string: ');
  4761.         ReadLn(Str2);
  4762.         Writeln('strcmp returns ', strcmp(Str1,Str2));
  4763.     end.
  4764.  
  4765.     INPUTS
  4766.  
  4767.     Str1,Str2 : The strings to compare
  4768.  
  4769.     RESULTS
  4770.     -MaxInt to -1 if Str1 < Str2, or
  4771.     0 if Str1 = Str2, or
  4772.     1 to MaxInt if Str1 > Str2
  4773.  
  4774.     BUGS
  4775.  
  4776.     SEE ALSO
  4777.     streq, strieq, strneq, strnieq, stricmp, strncmp,
  4778.     strnicmp, SameName
  4779.  
  4780.  
  4781. Utils/StringLib/strcpy            Utils/StringLib/strcpy
  4782.  
  4783.     NAME
  4784.     strcpy - copy one string into another
  4785.  
  4786.     SYNOPSIS
  4787.     Procedure strcpy(Dest, Source : String);
  4788.  
  4789.     DESCRIPTION
  4790.     This routine copies the string Source into the string
  4791.     Dest.  Both strings must already be allocated.  Note
  4792.     that this is different from "Dest := Source", which
  4793.     just copies a pointer to the same area of memory - this
  4794.     procedure actually copies all the characters over to
  4795.     a second memory area.
  4796.  
  4797.     EXAMPLE
  4798.  
  4799.     Program MakeTwo;
  4800.     {$I "Include:Utils/StringLib.i"}
  4801.     var
  4802.         Str1, Str2 : String;
  4803.     begin
  4804.         Str1 := AllocString(256);
  4805.         Str2 := AllocString(256);
  4806.         Write('Enter a string: ');
  4807.         Readln(Str1);
  4808.         strcpy(Str2,Str1);
  4809.         Writeln('You entered "', Str2, '"');
  4810.     end.
  4811.  
  4812.     INPUTS
  4813.  
  4814.     Dest   : The string buffer that will recieve characters
  4815.     Source : The string to be copied
  4816.  
  4817.     RESULTS
  4818.     None
  4819.  
  4820.     BUGS
  4821.  
  4822.     SEE ALSO
  4823.     strncpy, strcat, strncat, strdup
  4824.  
  4825. Utils/StringLib/strdup            Utils/StringLib/strdup
  4826.  
  4827.     NAME
  4828.     strdup - duplicate a string
  4829.  
  4830.     SYNOPSIS
  4831.     Function strdup(Str : String) : String;
  4832.  
  4833.     DESCRIPTION
  4834.     This function allocates an area of memory large enough
  4835.     to hold Str, copies Str into it, and returns a pointer
  4836.     to the new string.
  4837.  
  4838.     Understanding this function goes a long way toward
  4839.     understanding PCQ strings in general.  Consider the
  4840.     three following statements:
  4841.  
  4842.         Str1 := Str2;
  4843.         strcpy(Str1,Str2);
  4844.         Str1 := strdup(Str2);
  4845.  
  4846.     They each do very different things.  The first one points
  4847.     Str1 at the same area of memory as Str2 points to - any
  4848.     changes you make to Str1 show up in Str2 as well.  The
  4849.     second statement copies the contents of Str2 into Str1 -
  4850.     Str1 must already point to an allocated area of memory
  4851.     at least as long as Str2.  The third one makes a completely
  4852.     new copy of Str2.  It works just like the following
  4853.     statements:
  4854.  
  4855.         Str1 := AllocString(strlen(Str2) + 1);
  4856.         strcpy(Str1,Str2);
  4857.  
  4858.     EXAMPLE
  4859.  
  4860.     Program CopyTwo;
  4861.     {$I "Include:Utils/StringLib.i"}
  4862.     var
  4863.         Str1, Str2 : String;
  4864.         i          : Integer;
  4865.     begin
  4866.         Str1 := AllocString(256);
  4867.         Write('Enter a string: ');
  4868.         Readln(Str1);
  4869.         Str2 := strdup(Str1);
  4870.         for i := 0 to strlen(Str1) do
  4871.         Str1[i] := toupper(Str1[i]);
  4872.         Writeln('Str1 is now ', Str1);
  4873.         Writeln('Str2 is now ', Str2);
  4874.     end.
  4875.  
  4876.     INPUTS
  4877.  
  4878.     Str   : The string that will be duplicated.
  4879.  
  4880.     RESULTS
  4881.     A pointer to a string matching Str, or possibly Nil if
  4882.     the program could not allocate the memory and you have
  4883.     set up the appropriate HeapError.
  4884.  
  4885.     BUGS
  4886.  
  4887.     SEE ALSO
  4888.     AllocString, strcpy
  4889.  
  4890.  
  4891. Utils/StringLib/streq            Utils/StringLib/streq
  4892.  
  4893.     NAME
  4894.     streq - compare two strings for equality
  4895.  
  4896.     SYNOPSIS
  4897.     Function streq(Str1, Str2 : String) : Boolean;
  4898.  
  4899.     DESCRIPTION
  4900.     The streq function compares two strings, and returns
  4901.     TRUE if they are equal and FALSE otherwise.  Of all the
  4902.     string comparison functions, it is the fastest.
  4903.  
  4904.     EXAMPLE
  4905.  
  4906.     Program Comparem;
  4907.     {$I "Include:Utils/StringLib.i"}
  4908.     var
  4909.         Str1, Str2 : String;
  4910.     begin
  4911.         Str1 := AllocString(256);
  4912.         Str2 := AllocString(256);
  4913.         Write('Enter the first string: ');
  4914.         ReadLn(Str1);
  4915.         Write('Enter the second string: ');
  4916.         ReadLn(Str2);
  4917.         if streq(Str1,Str2) then
  4918.         Writeln('The strings are equal')
  4919.         else
  4920.         Writeln('The strings are not equal');
  4921.     end.
  4922.  
  4923.     INPUTS
  4924.  
  4925.     Str1 and Str2 : The two strings to compare
  4926.  
  4927.     RESULTS
  4928.     TRUE if the strings are equal, or
  4929.     FALSE otherwise
  4930.  
  4931.     BUGS
  4932.  
  4933.     SEE ALSO
  4934.     strieq, strneq, strnieq, strcmp, stricmp, strncmp,
  4935.     strnicmp, SameName
  4936.  
  4937.  
  4938. Utils/StringLib/stricmp            Utils/StringLib/stricmp
  4939.  
  4940.     NAME
  4941.     stricmp - return the relationship ignoring case
  4942.  
  4943.     SYNOPSIS
  4944.     Function stricmp(Str1, Str2 : String) : Integer;
  4945.  
  4946.     DESCRIPTION
  4947.     This function compares two strings, ignoring any
  4948.     differences in case, and returns an Integer whose
  4949.     relationship to zero is the same as the relationship
  4950.     of Str1 to Str2.
  4951.  
  4952.     EXAMPLE
  4953.  
  4954.     Program Comparem;
  4955.     {$I "Include:Utils/StringLib.i"}
  4956.     var
  4957.         Str1, Str2 : String;
  4958.     begin
  4959.         Str1 := AllocString(256);
  4960.         Str2 := AllocString(256);
  4961.         Write('Enter the first string: ');
  4962.         ReadLn(Str1);
  4963.         Write('Enter the second string: ');
  4964.         ReadLn(Str2);
  4965.         Writeln('strieq returns ', strieq(Str1,Str2));
  4966.     end.
  4967.  
  4968.     INPUTS
  4969.  
  4970.     Str1,Str2 : The two strings to compare
  4971.  
  4972.     RESULTS
  4973.     -MaxInt to -1 if Str1 < Str2, or
  4974.     0 if Str1 = Str2, or
  4975.     1 to MaxInt if Str1 > Str2
  4976.  
  4977.     BUGS
  4978.  
  4979.     SEE ALSO
  4980.     streq, strieq, strneq, strnieq, strcmp, strncmp,
  4981.     strnicmp, SameName
  4982.  
  4983.  
  4984. Utils/StringLib/strieq            Utils/StringLib/strieq
  4985.  
  4986.     NAME
  4987.     strieq - compare the strings ignoring case
  4988.  
  4989.     SYNOPSIS
  4990.     Function strieq(Str1, Str2 : String) : Boolean;
  4991.  
  4992.     DESCRIPTION
  4993.     This function compares the two strings, and returns TRUE
  4994.     if they are equal.  It is case insensitive, which means
  4995.     that it considers, for example, "String" and "STRING"
  4996.     equal.
  4997.  
  4998.     This function is much slower than streq, so it should
  4999.     only be used where you really need to ignore case.
  5000.  
  5001.     EXAMPLE
  5002.  
  5003.     Program Comparem;
  5004.     {$I "Include:Utils/StringLib.i"}
  5005.     var
  5006.         Str1, Str2 : String;
  5007.     begin
  5008.         Str1 := AllocString(256);
  5009.         Str2 := AllocString(256);
  5010.         Write('Enter the first string: ');
  5011.         ReadLn(Str1);
  5012.         Write('Enter the second string: ');
  5013.         ReadLn(Str2);
  5014.         if strieq(Str1,Str2) then
  5015.         Writeln('The strings are equal')
  5016.         else
  5017.         Writeln('The strings are not equal');
  5018.     end.
  5019.  
  5020.     INPUTS
  5021.  
  5022.     Str1,Str2 : The strings to compare
  5023.  
  5024.     RESULTS
  5025.     TRUE if the strings are equal, ignoring case, or
  5026.     FALSE otherwise
  5027.  
  5028.     BUGS
  5029.  
  5030.     SEE ALSO
  5031.     streq, strneq, strnieq, strcmp, stricmp, strncmp,
  5032.     strnicmp, SameName
  5033.  
  5034.  
  5035. Utils/StringLib/strlen            Utils/StringLib/strlen
  5036.  
  5037.     NAME
  5038.     strlen - return the length of a string
  5039.  
  5040.     SYNOPSIS
  5041.     Function strlen(Str : String) : Integer;
  5042.  
  5043.     DESCRIPTION
  5044.     This function returns the number of characters in the
  5045.     string.  Note that a string requires strlen(Str) + 1
  5046.     bytes of memory for storage, because it also has to
  5047.     store the trailing zero byte.
  5048.  
  5049.     EXAMPLE
  5050.  
  5051.     Program Countem;
  5052.     {$I "Include:Utils/StringLib.i"}
  5053.     var
  5054.         Str : String;
  5055.     begin
  5056.         Str := AllocString(256);
  5057.         Write('Enter a string: ');
  5058.         Readln(Str);
  5059.         Writeln('That string is ', strlen(Str),
  5060.             ' characters long.');
  5061.     end.
  5062.  
  5063.     INPUTS
  5064.  
  5065.     Str   : The string to measure
  5066.  
  5067.     RESULTS
  5068.     The number of characters in the string
  5069.  
  5070.     BUGS
  5071.  
  5072.     SEE ALSO
  5073.  
  5074.  
  5075. Utils/StringLib/strncat            Utils/StringLib/strncat
  5076.  
  5077.     NAME
  5078.     strncat - concatenate at most n characters
  5079.  
  5080.     SYNOPSIS
  5081.     Procedure strncat(Str1, Str2 : String; n : Short);
  5082.  
  5083.     DESCRIPTION
  5084.     This routine attaches Str2 on the end of Str1, but will
  5085.     attach at most n characters.  This helps you ensure that
  5086.     the resulting string does not overrun Str1's memory
  5087.     area.  The result, whether it is truncated or not, will
  5088.     be null-terminated.
  5089.  
  5090.     EXAMPLE
  5091.  
  5092.     Program Attach;
  5093.     {$I "Include:Utils/StringLib.i"}
  5094.     var
  5095.         Str1, Str2 : String;
  5096.         n          : Short;
  5097.     begin
  5098.         Str1 := AllocString(256);
  5099.         Str2 := AllocString(256);
  5100.         Write('Enter a string: ');
  5101.         Readln(Str1);
  5102.         Write('Enter a second string: ');
  5103.         Readln(Str2);
  5104.         Write('Enter a number: ');
  5105.         Readln(n);
  5106.         strncat(Str1, Str2, n);
  5107.         Writeln('Str1 is now: "', Str1, '"');
  5108.     end.
  5109.  
  5110.     INPUTS
  5111.  
  5112.     Str1  : The destination string, which will have Str2
  5113.         attached to the end of it.  It must have at
  5114.         least n characters left in its allocated space.
  5115.     Str2  : The string that will be copied on the end of
  5116.         Str1.  It is unaffected by the operation.
  5117.     n     : The maximum number of characters that can be
  5118.         copied.
  5119.  
  5120.     RESULTS
  5121.     None
  5122.  
  5123.     BUGS
  5124.  
  5125.     SEE ALSO
  5126.     strcat, strcpy, strncpy
  5127.  
  5128.  
  5129. Utils/StringLib/strncmp            Utils/StringLib/strncmp
  5130.  
  5131.     NAME
  5132.     strncmp - return relationship of first n characters
  5133.  
  5134.     SYNOPSIS
  5135.     Function strncmp(Str1,Str2 : String; n : Short) : Integer;
  5136.  
  5137.     DESCRIPTION
  5138.     This function compares the first n characters in Str1 and
  5139.     Str2, and returns an Integer that is greater than zero if
  5140.     the first n characters of Str1 are greater alphabetically
  5141.     than those of Str2, zero if they are equal, or less than
  5142.     zero if the first n characters of Str1 are less than those
  5143.     of Str2.
  5144.  
  5145.     EXAMPLE
  5146.  
  5147.     Program Comparem;
  5148.     {$I "Include:Utils/StringLib.i"}
  5149.     var
  5150.         Str1, Str2 : String;
  5151.         n          : Integer;
  5152.     begin
  5153.         Str1 := AllocString(256);
  5154.         Str2 := AllocString(256);
  5155.         Write('Enter the first string: ');
  5156.         ReadLn(Str1);
  5157.         Write('Enter the second string: ');
  5158.         ReadLn(Str2);
  5159.         Write('Enter a the number to compare: ');
  5160.         Readln(n);
  5161.         Writeln('strncmp returns ', strncmp(Str1,Str2));
  5162.     end.
  5163.  
  5164.     INPUTS
  5165.  
  5166.     Str1, Str2 : The strings to compare
  5167.     n          : The number of characters to compare at most
  5168.  
  5169.     RESULTS
  5170.     -MaxInt to -1 if the first n characters of Str1 are less
  5171.     than those of Str2, or
  5172.     0 if they are equal, or
  5173.     1 to MaxInt if they are greater.
  5174.  
  5175.     BUGS
  5176.  
  5177.     SEE ALSO
  5178.     streq, strieq, strneq, strnieq, strcmp, stricmp, strnicmp,
  5179.     SameName
  5180.  
  5181.  
  5182. Utils/StringLib/strncpy            Utils/StringLib/strncpy
  5183.  
  5184.     NAME
  5185.     strncpy - copy at most n characters from Source to Dest
  5186.  
  5187.     SYNOPSIS
  5188.     Procedure strncpy(Dest, Source : String; n : Short);
  5189.  
  5190.     DESCRIPTION
  5191.     This routine copies Source into Dest, but if there are
  5192.     more than n characters in Source, Dest is truncated to
  5193.     n characters.  Dest will always be null-terminated.
  5194.  
  5195.     EXAMPLE
  5196.  
  5197.     Program CopyIt;
  5198.     {$I "Include:Utils/StringLib.i"}
  5199.     var
  5200.         Str1, Str2 : String;
  5201.         n          : Integer;
  5202.     begin
  5203.         Str1 := AllocString(256);
  5204.         Str2 := AllocString(256);
  5205.         Write('Enter a string: ');
  5206.         ReadLn(Str1);
  5207.         Write('Enter the number of characters to copy: ');
  5208.         Readln(n);
  5209.         strncpy(Str2,Str1,n);
  5210.         Writeln('Result is ', Str2);
  5211.     end.
  5212.  
  5213.     INPUTS
  5214.  
  5215.     Dest   : The string buffer to copy into.  It must already
  5216.          be allocated.
  5217.     Source : The string to be copied.
  5218.     n      : The maximum number of characters to copy.
  5219.  
  5220.     RESULTS
  5221.     None
  5222.  
  5223.     BUGS
  5224.  
  5225.     SEE ALSO
  5226.     strcpy, strcat, strncat
  5227.  
  5228.  
  5229. Utils/StringLib/strneq            Utils/StringLib/strneq
  5230.  
  5231.     NAME
  5232.     strneq - check whether string prefixes are equal
  5233.  
  5234.     SYNOPSIS
  5235.     Function strneq(Str1, Str2 : String; n : Short) : Boolean;
  5236.  
  5237.     DESCRIPTION
  5238.     This function determines whether the two strings are
  5239.     equal for the first n characters at most.  If either
  5240.     string is less than n characters long, the function
  5241.     will return TRUE if both strings are equal and the
  5242.     same length.
  5243.  
  5244.     EXAMPLE
  5245.  
  5246.     Program Comparem;
  5247.     {$I "Include:Utils/StringLib.i"}
  5248.     var
  5249.         Str1, Str2 : String;
  5250.         n           : Integer;
  5251.     begin
  5252.         Str1 := AllocString(256);
  5253.         Str2 := AllocString(256);
  5254.         Write('Enter the first string: ');
  5255.         ReadLn(Str1);
  5256.         Write('Enter the second string: ');
  5257.         ReadLn(Str2);
  5258.         Write('Enter a length: ');
  5259.         Readln(n);
  5260.         if strneq(Str1,Str2,n) then
  5261.         Writeln('The strings are equal up to ',n)
  5262.         else
  5263.         Writeln('The strings are not equal up to ',n);
  5264.     end.
  5265.  
  5266.     INPUTS
  5267.  
  5268.     Str1,Str2 : The strings to compare
  5269.     n         : The number of characters to compare at most
  5270.  
  5271.     RESULTS
  5272.     TRUE if the first n characters of the strings are equal,
  5273.          or if the strings are equal and less than n characters
  5274.          length, or
  5275.     FALSE otherwise
  5276.  
  5277.     BUGS
  5278.  
  5279.     SEE ALSO
  5280.     streq, strieq, strnieq, strcmp, stricmp, strncmp,
  5281.     strnicmp, SameName
  5282.  
  5283.  
  5284. Utils/StringLib/strnicmp        Utils/StringLib/strnicmp
  5285.  
  5286.     NAME
  5287.     strnicmp - return alphabetical relationship ignoring case
  5288.  
  5289.     SYNOPSIS
  5290.     Function strnicmp(Str1, Str2 : String; n : Short) : Integer;
  5291.  
  5292.     DESCRIPTION
  5293.     This function compares the first n characters of two
  5294.     strings, ignoring case, and returns an Integer indicating
  5295.     their relative alphabetical position.  If the returned
  5296.     value is less than zero, then the prefix of Str1 is less
  5297.     than that of Str2.  If it is zero, the prefixes are equal.
  5298.     If it is greater than zero, the prefix of Str1 is greater
  5299.     than that of Str2.
  5300.  
  5301.     EXAMPLE
  5302.  
  5303.     Program Comparem;
  5304.     {$I "Include:Utils/StringLib.i"}
  5305.     var
  5306.         Str1, Str2 : String;
  5307.         n          : Integer;
  5308.     begin
  5309.         Str1 := AllocString(256);
  5310.         Str2 := AllocString(256);
  5311.         Write('Enter the first string: ');
  5312.         ReadLn(Str1);
  5313.         Write('Enter the second string: ');
  5314.         ReadLn(Str2);
  5315.         Write('Enter the number of characters to compare: ');
  5316.         Readln(n);
  5317.         Writeln('strnicmp returns ', strnicmp(Str1,Str2,n));
  5318.     end.
  5319.  
  5320.     INPUTS
  5321.  
  5322.     Str1,Str2 : The string to be compared.
  5323.     n         : The maximum number of characters to compare.
  5324.  
  5325.     RESULTS
  5326.     -MaxInt to -1 if the first n characters of Str1 are less
  5327.     than those of Str2, ignoring case, or
  5328.     0 if the prefixes are equal, or
  5329.     1 to MaxInt if the prefix of Str1 is greater than that
  5330.     of Str2.
  5331.  
  5332.     BUGS
  5333.  
  5334.     SEE ALSO
  5335.     streq, strieq, strneq, strnieq, strcmp, stricmp, strncmp,
  5336.     SameName
  5337.  
  5338.  
  5339. Utils/StringLib/strnieq            Utils/StringLib/strnieq
  5340.  
  5341.     NAME
  5342.     strnieq - Compares up to n characters ignoring case
  5343.  
  5344.     SYNOPSIS
  5345.     Function strnieq(Str1,Str2 : String; n : Short) : Boolean;
  5346.  
  5347.     DESCRIPTION
  5348.     This function compares at most n characters of the two
  5349.     strings ignoring case.
  5350.  
  5351.     EXAMPLE
  5352.  
  5353.     Program Comparem;
  5354.     {$I "Include:Utils/StringLib.i"}
  5355.     var
  5356.         Str1, Str2 : String;
  5357.         n          : Integer;
  5358.     begin
  5359.         Str1 := AllocString(256);
  5360.         Str2 := AllocString(256);
  5361.         Write('Enter the first string: ');
  5362.         ReadLn(Str1);
  5363.         Write('Enter the second string: ');
  5364.         ReadLn(Str2);
  5365.         Write('Enter the number of characters to compare: ');
  5366.         ReadLn(n);
  5367.         if strnieq(Str1,Str2,n) then
  5368.         Writeln('The strings are equal')
  5369.         else
  5370.         Writeln('The strings are not equal');
  5371.     end.
  5372.  
  5373.     INPUTS
  5374.  
  5375.     Str1,Str2 : The two strings to compare
  5376.     n         : The maximum number of characters to compare
  5377.  
  5378.     RESULTS
  5379.     TRUE if the first n characters are equal, ignoring case,
  5380.          or if the strings are equal and both less than n
  5381.          characters long, or
  5382.     FALSE otherwise
  5383.  
  5384.     BUGS
  5385.  
  5386.     SEE ALSO
  5387.     streq, strieq, strneq, strcmp, stricmp, strncmp,
  5388.     strnicmp, SameName
  5389.  
  5390.  
  5391. Utils/StringLib/strpos            Utils/StringLib/strpos
  5392.  
  5393.     NAME
  5394.     strpos - find the first occurence of a character
  5395.  
  5396.     SYNOPSIS
  5397.     Function strpos(Str : String; Ch : Char) : Integer;
  5398.  
  5399.     DESCRIPTION
  5400.     This routine search for the first (leftmost) occurence
  5401.     of the character Ch in the string Str.  If it finds it,
  5402.     it returns the index, from 0 to strlen(Str).  If the
  5403.     character does not occur in the string, it returns -1.
  5404.  
  5405.     EXAMPLE
  5406.  
  5407.     Program FindChar;
  5408.     {$I "Include:Utils/StringLib.i"}
  5409.     var
  5410.         Str : String;
  5411.         i   : Integer;
  5412.     begin
  5413.         Str := AllocString(256);
  5414.         Write('Enter a string: ');
  5415.         Readln(Str);
  5416.         i := strpos(Str, 'e');
  5417.         if i = -1 then
  5418.         Writeln('The letter "e" does not occur')
  5419.         else
  5420.         Writeln('The letter "e" occurs in position ', i);
  5421.     end.
  5422.  
  5423.     INPUTS
  5424.  
  5425.     Str   : The string to search through - it will not be
  5426.         modified.
  5427.     Ch    : The character to search for.
  5428.  
  5429.     RESULTS
  5430.     -1 if the character could not be found, or
  5431.     the index of the leftmost occurence otherwise.
  5432.  
  5433.     BUGS
  5434.  
  5435.     SEE ALSO
  5436.     strrpos
  5437.  
  5438. Utils/StringLib/strrpos            Utils/StringLib/strrpos
  5439.  
  5440.     NAME
  5441.     strrpos - find the rightmost occurence of a character
  5442.  
  5443.     SYNOPSIS
  5444.     Function strrpos(Str : String; Ch : Char) : Integer;
  5445.  
  5446.     DESCRIPTION
  5447.     This function returns the index of the rightmost
  5448.     occurrence of the character Ch in the string Str.  If
  5449.     the character does not occur in the string, the
  5450.     function returns -1.
  5451.  
  5452.     EXAMPLE
  5453.  
  5454.     Program Rightmost;
  5455.     {$I "Include:Utils/StringLib.i"}
  5456.     var
  5457.         Str : String;
  5458.         Ch  : Char;
  5459.         Pos : Integer;
  5460.     begin
  5461.         Str := AllocString(256);
  5462.         Write('Enter a string: ');
  5463.         Readln(Str);
  5464.         Write('Enter a character: ');
  5465.         Readln(Ch);
  5466.         Pos := strrpos(Str,Ch);
  5467.         if Pos = -1 then
  5468.         Writeln('"', Ch, '" does not occur in "', Str, '"')
  5469.         else
  5470.         Writeln(Ch, ' last occurs at position ', Pos);
  5471.     end.
  5472.  
  5473.     INPUTS
  5474.  
  5475.     Str   : The string to be examined.  It will not be modified.
  5476.     Ch    : The character for which to search.
  5477.  
  5478.     RESULTS
  5479.     -1 if the character does not occur in the string, or
  5480.     the index of the rightmost occurence.
  5481.  
  5482.     BUGS
  5483.  
  5484.     SEE ALSO
  5485.     strpos
  5486.  
  5487.  
  5488. PCQ/Succ                PCQ/Succ
  5489.  
  5490.     NAME
  5491.     Succ - return the next ordinal value
  5492.  
  5493.     SYNOPSIS
  5494.     Function Succ(Expr : Any ordinal type) : The same type;
  5495.  
  5496.     DESCRIPTION
  5497.     Succ returns the successor to an ordinal value, i.e.
  5498.     the value plus 1.  If the value is already at its maximum
  5499.     value, in an enumerated type for example, the returned
  5500.     value has no meaning.
  5501.  
  5502.     EXAMPLE
  5503.  
  5504.     Program ShowSucc;
  5505.     var
  5506.         i : (sunday,monday,tuesday,wednesday,
  5507.          thursday,friday,saturday);
  5508.     begin
  5509.         i := sunday;
  5510.         while i < saturday do
  5511.         i := Succ(i);
  5512.     end.
  5513.  
  5514.     INPUTS
  5515.  
  5516.     Expr  : Any ordinal expression
  5517.  
  5518.     RESULTS
  5519.     A value of the same type
  5520.  
  5521.     BUGS
  5522.  
  5523.     SEE ALSO
  5524.     Pred, Inc
  5525.  
  5526.  
  5527. Utils/DoubleBuffer/SwapBuffers        Utils/DoubleBuffer/SwapBuffers
  5528.  
  5529.     NAME
  5530.     SwapBuffers - swap the drawing and displaying BitMaps
  5531.  
  5532.     SYNOPSIS
  5533.     Procedure SwapBuffers(w : WindowPtr);
  5534.  
  5535.     DESCRIPTION
  5536.     When you have drawn something into a Window opened using
  5537.     OpenDoubleBuffer, you need to call SwapBuffers in order
  5538.     to display it.  SwapBuffers points the Screen's BitMap
  5539.     at the BitMap into which you have been drawing, and points
  5540.     the RastPort's at the BitMap that was being displayed.  It
  5541.     then calls ScrollVPort to update the graphics system.
  5542.  
  5543.     EXAMPLE
  5544.     See Examples/3d.p
  5545.  
  5546.     INPUTS
  5547.  
  5548.     w     : A pointer to a Window opened with OpenDoubleBuffer
  5549.  
  5550.     RESULTS
  5551.     None
  5552.  
  5553.     BUGS
  5554.  
  5555.     SEE ALSO
  5556.     OpenDoubleBuffer, CloseDoubleBuffer
  5557.  
  5558.  
  5559. PCQ/Tan                    PCQ/Tan
  5560.  
  5561.     NAME
  5562.     Tan - computes the tangent of the specified angle in radians
  5563.  
  5564.     SYNOPSIS
  5565.     Function Tan(Radians : Real) : Real;
  5566.  
  5567.     DESCRIPTION
  5568.     This function computes the tangent of the angle, which must
  5569.     be specified in radians.  The tangent function is not defined
  5570.     at odd multiples of PI/2, so neither is this function.
  5571.  
  5572.     If you are using the $N+ option, this function is computed by
  5573.     the mathtrans.library.  Otherwise, it is computed by internal
  5574.     PCQ routines.
  5575.  
  5576.     EXAMPLE
  5577.  
  5578.     Program ShowTan;
  5579.     var
  5580.         Angle : Real;
  5581.     begin
  5582.         Write('Enter an angle in radians: ');
  5583.         Readln(Angle);
  5584.         Writeln('The tangent of ', Angle:0:3, ' is ',
  5585.                 Tan(Angle):0:3);
  5586.     end.
  5587.  
  5588.     INPUTS
  5589.  
  5590.     Radians : The radian measure of the angle
  5591.  
  5592.     RESULTS
  5593.     The tangent of the specified angle
  5594.  
  5595.     BUGS
  5596.  
  5597.     SEE ALSO
  5598.     Sin, Cos, ArcTan
  5599.  
  5600. Utils/CRT/TextBackground        Utils/CRT/TextBackground
  5601.  
  5602.     NAME
  5603.     TextBackground - set the current background color
  5604.  
  5605.     SYNOPSIS
  5606.     Procedure TextBackground(CRT : Address; Pen : Byte);
  5607.  
  5608.     DESCRIPTION
  5609.     This routine sets the background pen number for
  5610.     subsequent text writes.  The actual color depends
  5611.     on the screen's colormap, so you might want to use
  5612.     SetRGB4 to make sure you get the colors you're
  5613.     looking for.
  5614.  
  5615.     EXAMPLE
  5616.  
  5617.     Procedure HighLight(CRT : Address; msg : String);
  5618.     begin
  5619.         TextBackground(CRT, 3);
  5620.         WriteString(CRT, msg);
  5621.         TextBackground(CRT, 0);
  5622.     end;
  5623.  
  5624.     INPUTS
  5625.  
  5626.     CRT   : A pointer to a valid CRT information block as
  5627.         returned by AttachConsole.
  5628.     Pen   : The new background pen number
  5629.  
  5630.     RESULTS
  5631.     None
  5632.  
  5633.     BUGS
  5634.  
  5635.     SEE ALSO
  5636.     AttachConsole, TextColor, WriteString
  5637.  
  5638.  
  5639. Utils/CRT/TextColor            Utils/CRT/TextColor
  5640.  
  5641.     NAME
  5642.     TextColor - set the foreground color for text drawing
  5643.  
  5644.     SYNOPSIS
  5645.     Procedure TextColor(CRT : Address; Pen : Byte);
  5646.  
  5647.     DESCRIPTION
  5648.     This routine sets the foreground pen color for the
  5649.     text.  The resulting color depends on the colormap
  5650.     in use, so to get specific results you should use
  5651.     the SetRGB4 function to define the pen colors
  5652.     exactly.
  5653.  
  5654.     EXAMPLE
  5655.  
  5656.     Procedure ColorWrite(CRT : Address; Msg : String);
  5657.     var
  5658.         Buffer : Array [0..1] of Char;
  5659.         Pen    : Byte;
  5660.         Pos    : Short;
  5661.     begin
  5662.         Buffer[1] := Chr(0);
  5663.         Pos := 0;
  5664.         while Msg[Pos] <> 0 do begin
  5665.         Buffer[0] := Msg[Pos];
  5666.         WriteString(CRT, String(@Buffer));
  5667.         TextColor(CRT, Pos);
  5668.         Inc(Pos);
  5669.         end;
  5670.     end;
  5671.  
  5672.     INPUTS
  5673.  
  5674.     CRT   : A pointer to a valid CRT information block, as
  5675.         returned by the AttachConsole function.
  5676.     Pen   : The new pen number
  5677.  
  5678.     RESULTS
  5679.     None
  5680.  
  5681.     BUGS
  5682.  
  5683.     SEE ALSO
  5684.     AttachConsole, TextBackground, WriteString
  5685.  
  5686.  
  5687. Utils/DateTools/TimeDesc        Utils/DateTools/TimeDesc
  5688.  
  5689.     NAME
  5690.     TimeDesc - fill a DateDescription with the current date/time
  5691.  
  5692.     SYNOPSIS
  5693.     Procedure TimeDesc(VAR DD : DateDescription);
  5694.  
  5695.     DESCRIPTION
  5696.     TimeDesc fills in a DateDescription record with the current
  5697.     system date and time.  A DateDescription record is defined
  5698.     as follows:
  5699.  
  5700.         DaysOfTheWeek = (Sunday, Monday, Tuesday, Wednesday,
  5701.                 Thursday, Friday, Saturday);
  5702.  
  5703.         DateDescription = record
  5704.         Day    : Byte;         { Day of month, 1..31 }
  5705.         Month    : Byte;         { Month, 1..12 }
  5706.         Year    : Short;     { Year, 1978... }
  5707.         DOW    : DaysOfTheWeek; { Sunday .. Saturday }
  5708.         Hour    : Byte;         { 0..23.  0 = 12 AM, 12 = Noon }
  5709.         Minute    : Byte;         { 0..59 }
  5710.         Second    : Byte;         { 0..59 }
  5711.         end;
  5712.  
  5713.     EXAMPLE
  5714.  
  5715.     Program DayOfWeek;
  5716.     {$I "Include:Utils/DateTools.i"}
  5717.     var
  5718.         MyDate : DateDescription;
  5719.     begin
  5720.         TimeDesc(MyDate);
  5721.         Writeln('It is ', DayNames[MyDate.DOW]);
  5722.     end.
  5723.  
  5724.     INPUTS
  5725.  
  5726.     DD    : A DateDescription record
  5727.  
  5728.     RESULTS
  5729.     None
  5730.  
  5731.     BUGS
  5732.  
  5733.     SEE ALSO
  5734.     GetDescription, StampDesc
  5735.  
  5736.  
  5737. Utils/StringLib/tolower            Utils/StringLib/tolower
  5738.  
  5739.     NAME
  5740.     tolower - convert an upper case character to lower case
  5741.  
  5742.     SYNOPSIS
  5743.     Function tolower(c : Char) : Char;
  5744.  
  5745.     DESCRIPTION
  5746.     This function converts characters in the range A..Z to
  5747.     their corresponding lower case characters in the range
  5748.     a..z.  If the character is not an upper case letter,
  5749.     no action is taken.
  5750.  
  5751.     EXAMPLE
  5752.  
  5753.     Program LowerLine;
  5754.     {$I "Include:Utils/StringLib.i"}
  5755.     var
  5756.         Line : String;
  5757.         i    : Integer;
  5758.     begin
  5759.         Line := AllocString(256);
  5760.         Write('Enter a line: ');
  5761.         Readln(Line);
  5762.         for i := 0 to strlen(Line) do
  5763.         Line[i] := tolower(Line[i]);
  5764.         Writeln('In lower case, that is: ', Line);
  5765.     end.
  5766.  
  5767.     INPUTS
  5768.  
  5769.     c     : The character to convert
  5770.  
  5771.     RESULTS
  5772.     If the input character is in the range A..Z, this
  5773.     function returns its corresponding lower case character.
  5774.     Otherwise, it returns the character unchanged.
  5775.  
  5776.     BUGS
  5777.  
  5778.     SEE ALSO
  5779.     toupper, islower
  5780.  
  5781.  
  5782. Utils/StringLib/toupper            Utils/StringLib/toupper
  5783.  
  5784.     NAME
  5785.     toupper - convert a character to uppercase
  5786.  
  5787.     SYNOPSIS
  5788.     Function toupper(c : Char) : Char;
  5789.  
  5790.     DESCRIPTION
  5791.     This function converts a character in the range a..z to
  5792.     its upper case equivalent.  If the character is outside
  5793.     of that range, it returns the character unchanged.
  5794.  
  5795.     EXAMPLE
  5796.  
  5797.     Program UpperLine;
  5798.     {$I "Include:Utils/StringLib.i"}
  5799.     var
  5800.         Line : String;
  5801.         i    : Integer;
  5802.     begin
  5803.         Line := AllocString(256);
  5804.         Write('Enter a line: ');
  5805.         Readln(Line);
  5806.         for i := 0 to strlen(Line) do
  5807.         Line[i] := toupper(Line[i]);
  5808.         Writeln('In upper case, that is: ', Line);
  5809.     end.
  5810.  
  5811.     INPUTS
  5812.  
  5813.     c     : The character to convert
  5814.  
  5815.     RESULTS
  5816.     If c is in the range a..z, toupper() returns the
  5817.     corresponding character in the range A..Z.  Otherwise,
  5818.     it returns the character unchanged.
  5819.  
  5820.     BUGS
  5821.  
  5822.     SEE ALSO
  5823.     tolower, isupper
  5824.  
  5825.  
  5826. PCQ/Trap                PCQ/Trap
  5827.  
  5828.     NAME
  5829.     Trap - issue a 68000 TRAP instruction
  5830.  
  5831.     SYNOPSIS
  5832.     Procedure Trap(TrapNum : Integer);
  5833.  
  5834.     DESCRIPTION
  5835.     This routine inserts a 68000 TRAP instruction into your
  5836.     code.  In some cases (you'll have to experiment) the
  5837.     trap will act as a breakpoint for a debugger.
  5838.  
  5839.     EXAMPLE
  5840.  
  5841.     Program TryTrap;
  5842.     begin
  5843.         Trap(4); { Will GURU if not in a debugger }
  5844.     end.
  5845.  
  5846.     INPUTS
  5847.  
  5848.     TrapNum : The trap number to generate
  5849.  
  5850.     RESULTS
  5851.     None
  5852.  
  5853.     BUGS
  5854.  
  5855.     SEE ALSO
  5856.  
  5857.  
  5858. PCQ/Trunc                PCQ/Trunc
  5859.  
  5860.     NAME
  5861.     Trunc - convert a Real value into an Integer
  5862.  
  5863.     SYNOPSIS
  5864.     Function Trunc(Expr : Real) : Integer;
  5865.  
  5866.     DESCRIPTION
  5867.     The Trunc function returns the whole number portion
  5868.     of a Real expression.  In other words, it rounds the
  5869.     Real value down and returns the Integer part.
  5870.  
  5871.     This routine is somewhat faster than the Round
  5872.     function.
  5873.  
  5874.     Note that this function is automatically invoked by
  5875.     the compiler to    convert Real values to Integers,
  5876.     whenever that is appropriate.
  5877.  
  5878.     EXAMPLE
  5879.  
  5880.     Program ShowTrunc;
  5881.     var
  5882.         FloatValue : Real;
  5883.     begin
  5884.         Write('Please enter a Real value: ');
  5885.         Readln(FloatValue);
  5886.         Writeln(FloatValue:0:3, ' becomes ', Trunc(FloatValue));
  5887.     end.
  5888.  
  5889.     INPUTS
  5890.  
  5891.     Expr  : Any Real type expression
  5892.  
  5893.     RESULTS
  5894.     The whole number portion of Expr, i.e. Expr with the
  5895.     fractional digits truncated.
  5896.  
  5897.     BUGS
  5898.  
  5899.     SEE ALSO
  5900.     Round, Float
  5901.  
  5902.  
  5903. Utils/CRC16/UpdCRC            Utils/CRC16/UpdCRC
  5904.  
  5905.     NAME
  5906.     UpdCRC - Update a CRC code for the next byte of data
  5907.  
  5908.     SYNOPSIS
  5909.     Function UpdCRC(cp : Byte; crc : Word) : Word;
  5910.  
  5911.     DESCRIPTION
  5912.     UpdCRC takes a previous 16-bit CRC value and updates
  5913.     it according to the next character.  The CRC is
  5914.     calculated by the fast table-driven method
  5915.     compatible with ZMODEM, but incompatible with Kermit
  5916.     and XMODEM.
  5917.  
  5918.     This routine was written by Stephen Satchell and Chuck
  5919.     Forsberg.
  5920.  
  5921.     EXAMPLE
  5922.  
  5923.     Program CRC;
  5924.     {$I "Include:Utils/CRC16.p"}
  5925.     var
  5926.         InFile : Text;
  5927.         Code   : Word;
  5928.     begin
  5929.         if reopen(CommandLine, InFile) then begin
  5930.         Code := 0;
  5931.         while not eof(InFile) do begin
  5932.             Code := UpdCRC(InFile^, Code);
  5933.             Get(InFile);
  5934.         end;
  5935.         Close(InFile);
  5936.         Writeln('The CRC is ', Code);
  5937.         end else
  5938.         Writeln('Could not open ', CommandLine);
  5939.     end.
  5940.  
  5941.     INPUTS
  5942.     cp    : The character to add to the CRC value
  5943.     crc    : The previous crc value
  5944.  
  5945.     RESULTS
  5946.     The updated CRC value
  5947.  
  5948.     SEE ALSO
  5949.     CRCCheck
  5950.  
  5951. Utils/Random/UseSeed            Utils/Random/UseSeed
  5952.  
  5953.     NAME
  5954.     UseSeed - set the seed value for the random number routines
  5955.  
  5956.     SYNOPSIS
  5957.     Procedure UseSeed(Seed : Integer);
  5958.  
  5959.     DESCRIPTION
  5960.     This routine allows you to directly set the random number
  5961.     seeds.  Normally you would call SelfSeed instead, but this
  5962.     routine lets you get predictable results from the supposedly
  5963.     random routines, since for a given seed value they will always
  5964.     produce the same sequence of numbers.
  5965.  
  5966.     EXAMPLE
  5967.  
  5968.     Program Swami;
  5969.     {$I "Include:Utils/Random.i"}
  5970.     begin
  5971.         UseSeed(1991);
  5972.         Writeln('I would guess ... 481204');
  5973.         Writeln(RangeRandom(Pred(MaxInt)));
  5974.     end.
  5975.  
  5976.     INPUTS
  5977.  
  5978.     Seed  : The seed value to use for RealRandom and RangeRandom
  5979.  
  5980.     RESULTS
  5981.     None
  5982.  
  5983.     BUGS
  5984.  
  5985.     SEE ALSO
  5986.     SelfSeed, RangeRandom, RealRandom
  5987.  
  5988.  
  5989. PCQ/VA_Arg                PCQ/VA_Arg
  5990.  
  5991.     NAME
  5992.     VA_Arg - return the next unnamed parameter
  5993.  
  5994.     SYNOPSIS
  5995.     Function VA_Arg(VAR ArgPtr : Address;
  5996.             Simple Type Spec) : Simple Type;
  5997.  
  5998.     DESCRIPTION
  5999.     The VA_Arg routine retrieves the next unnamed parameter
  6000.     from the stack.  You should first call VA_Start to
  6001.     initialize ArgPtr, an Address variable, then call this
  6002.     routine to get each of the parameters.  The type returned
  6003.     by this function is the simple type specified as the
  6004.     second argument.
  6005.  
  6006.     EXAMPLE
  6007.  
  6008.     Program Unnamed;
  6009.     {$C+ use C calling conventions }
  6010.         Procedure WriteAll(Num : Short; ... );
  6011.         var
  6012.         ArgPtr : Address;
  6013.         i      : Short;
  6014.         begin
  6015.         VA_Start(ArgPtr);
  6016.         for i := 1 to Num do
  6017.             Writeln(VA_Arg(ArgPtr,Integer));
  6018.         end;
  6019.     begin
  6020.         WriteAll(1,45);
  6021.         WriteAll(3,56,12,12345);
  6022.     end.
  6023.  
  6024.     INPUTS
  6025.  
  6026.     ArgPtr         : A variable of type Address that will be
  6027.                used to point to the next argument.
  6028.     Simple Type Spec : The type specification of a simple
  6029.                type.
  6030.  
  6031.     RESULTS
  6032.     The value from the stack, of the type specified as the
  6033.     second parameter.
  6034.  
  6035.     BUGS
  6036.  
  6037.     SEE ALSO
  6038.     VA_Start
  6039.  
  6040.  
  6041. PCQ/VA_Start                PCQ/VA_Start
  6042.  
  6043.     NAME
  6044.     VA_Start - initialize an argument pointer
  6045.  
  6046.     SYNOPSIS
  6047.     Procedure VA_Start(VAR ArgPtr : Address);
  6048.  
  6049.     DESCRIPTION
  6050.     The VA_Start procedure initializes ArgPtr to point to the
  6051.     first of the routine's unnamed parameters.  It must be
  6052.     called before any calls to VA_Arg.
  6053.  
  6054.     EXAMPLE
  6055.  
  6056.     Program Unnamed;
  6057.     {$C+ use C calling conventions }
  6058.         Procedure WriteAll(Num : Short; ... );
  6059.         var
  6060.         ArgPtr : Address;
  6061.         i      : Short;
  6062.         begin
  6063.         VA_Start(ArgPtr);
  6064.         for i := 1 to Num do
  6065.             Writeln(VA_Arg(ArgPtr,Integer));
  6066.         end;
  6067.     begin
  6068.         WriteAll(1,45);
  6069.         WriteAll(3,56,12,12345);
  6070.     end.
  6071.  
  6072.     INPUTS
  6073.  
  6074.     ArgPtr         : A variable of type Address that will be
  6075.                used to point to the next argument.
  6076.  
  6077.     RESULTS
  6078.     None
  6079.  
  6080.     BUGS
  6081.  
  6082.     SEE ALSO
  6083.     VA_Arg
  6084.  
  6085. Utils/TimerUtils/WaitTimer        Utils/TimerUtils/WaitTimer
  6086.  
  6087.     NAME
  6088.     WaitTimer - wait for a given amount of time
  6089.  
  6090.     SYNOPSIS
  6091.     Procedure WaitTimer(WhichTimer   : TimeRequestPtr;
  6092.                 Seconds,
  6093.                 MicroSeconds : Integer);
  6094.  
  6095.     DESCRIPTION
  6096.     This routine waits for at least the given number of
  6097.     seconds and microseconds, then returns.  If you want
  6098.     to continue processing while you wait, use SetTimer
  6099.     instead.
  6100.  
  6101.     EXAMPLE
  6102.     See Examples/TimerTest.p
  6103.  
  6104.     INPUTS
  6105.  
  6106.     WhichTimer   : A pointer to the TimeRequest record returned
  6107.                by CreateTimer
  6108.     Seconds         : The number of seconds to wait
  6109.     MicroSeconds : The number of microseconds to wait
  6110.  
  6111.     RESULTS
  6112.     None
  6113.  
  6114.     BUGS
  6115.  
  6116.     SEE ALSO
  6117.     CreateTimer, SetTimer, Delay
  6118.  
  6119.  
  6120. Utils/CRT/WhereX            Utils/CRT/WhereX
  6121.  
  6122.     NAME
  6123.     WhereX - returns the current cursor column
  6124.  
  6125.     SYNOPSIS
  6126.     Function WhereX(CRT : Address) : Short;
  6127.  
  6128.     DESCRIPTION
  6129.     This routine returns the cursor's current column position,
  6130.     expressed in character coordinates (not pixels).
  6131.  
  6132.     EXAMPLE
  6133.  
  6134.     Procedure VerticalLine(CRT : Address);
  6135.     var
  6136.         y : Short;
  6137.     begin
  6138.         for y := 1 to MaxY(CRT) do begin
  6139.         GotoXY(WhereX(CRT),y);
  6140.         WriteString(CRT, "|");
  6141.         end;
  6142.     end;
  6143.  
  6144.     INPUTS
  6145.  
  6146.     CRT   : A pointer to a valid CRT information block as
  6147.         returned by AttachConsole
  6148.  
  6149.     RESULTS
  6150.     The current cursor column in character coordinates
  6151.  
  6152.     BUGS
  6153.  
  6154.     SEE ALSO
  6155.     AttachConsole, GotoXY, MaxX, MaxY, WhereY
  6156.  
  6157.  
  6158. Utils/CRT/WhereY            Utils/CRT/WhereY
  6159.  
  6160.     NAME
  6161.     WhereY - returns the current text row
  6162.  
  6163.     SYNOPSIS
  6164.     Function WhereY(CRT : Address) : Short;
  6165.  
  6166.     DESCRIPTION
  6167.     WhereY returns the cursor row in character coordinates,
  6168.     not pixels.
  6169.  
  6170.     EXAMPLE
  6171.  
  6172.     Procedure Filling(CRT : Address);
  6173.     var
  6174.         Offset : Short;
  6175.     begin
  6176.         Offset := 1;
  6177.         while Offset <= (MaxX(CRT) div 2) do begin
  6178.         GotoXY(CRT, Offset, WhereY(CRT));
  6179.         WriteString(CRT, "-");
  6180.         GotoXY(CRT, MaxX(CRT) - Offset, WhereY(CRT));
  6181.         WriteString(CRT, "-");
  6182.         Inc(Offset);
  6183.         end;
  6184.     end;
  6185.  
  6186.     INPUTS
  6187.  
  6188.     CRT   : A pointer to a valid CRT information block as
  6189.         returned by the AttachConsole function.
  6190.  
  6191.     RESULTS
  6192.     The current cursor row in character coordinates
  6193.  
  6194.     BUGS
  6195.  
  6196.     SEE ALSO
  6197.     AttachConsole, WhereX, MaxX, MaxY, GotoXY
  6198.  
  6199.  
  6200. PCQ/Write                PCQ/Write
  6201.  
  6202.     NAME
  6203.     Write - send data to a PCQ file
  6204.  
  6205.     SYNOPSIS
  6206.     Procedure Write([VAR OutputFile,] Arguments );
  6207.  
  6208.     Each argument can take the form: e:m:n, where e is an
  6209.     expression and m and n are integer expressions.
  6210.  
  6211.     DESCRIPTION
  6212.     The standard procedure Write outputs data to the
  6213.     specified PCQ file, or to the standard output file
  6214.     Output if no file is specified.
  6215.  
  6216.     If OutputFile is a typed file, the data is written as
  6217.     a direct binary representation, just as it exists in
  6218.     memory.  In that case, the extra values m and n in
  6219.     the argument definition above are not allowed.
  6220.  
  6221.     If the output file is a Text file, the data is first
  6222.     converted to a character representation before it is
  6223.     written.  The results of the conversion depend on the
  6224.     type of the expression e.
  6225.  
  6226.     If e is an Integer, Word, Short or Byte type, the
  6227.     number is converted into its decimal representation,
  6228.     preceded by a minus sign if appropriate.  If the
  6229.     character representation is less than m characters
  6230.     long, the field is filled with spaces.  The parameter
  6231.     n is not allowed.
  6232.  
  6233.     If e is a Real value, the integer part of the value
  6234.     is converted to a character representation and printed
  6235.     according to the rules for an Integer.  If the parameter
  6236.     n is greater than zero, a decimal point is written and
  6237.     n fractional digits follow.
  6238.  
  6239.     If e is a String, the characters in the string up to,
  6240.     but not including, the final null byte are written.  If
  6241.     there are less than m characters in the string, spaces
  6242.     are written before the string to fill out the field.  The
  6243.     parameter n is not allowed.
  6244.  
  6245.     If e is an Array of Char, the entire array is written
  6246.     to the file, possibly preceded by enough space characters
  6247.     to fill out the field.  Again the parameter n is not
  6248.     allowed.
  6249.  
  6250.     If e is a Char type, the single character is written,
  6251.     possibly preceded by m-1 space characters.  The parameter
  6252.     n is not allowed.
  6253.  
  6254.     If e is a Boolean type, the string TRUE or the string
  6255.     FALSE is written, preceded by spaces as necessary to fill
  6256.     out the field.  The parameter n is not allowed.
  6257.  
  6258.     No other types can be written to a text file.
  6259.  
  6260.     If an error occurs during the write, IOResult will be set
  6261.     to a non-zero value.  If IOResult is not zero when you
  6262.     call Write, no output will occur.
  6263.  
  6264.     EXAMPLE
  6265.  
  6266.     Program ShowWrite;
  6267.     begin
  6268.         Write(56);          (* Writes '56'         *)
  6269.         Write(Output,56:4); (* Writes '  56'       *)
  6270.         Write(98.6:5:4);    (* Writes '   98.6000' *)
  6271.         Write(45 > 32);     (* Writes 'TRUE'       *)
  6272.         Write(32 > 45:8);   (* Writes '   FALSE'   *)
  6273.     end.
  6274.  
  6275.     INPUTS
  6276.  
  6277.     OutputFile : The destination file, which must have been
  6278.              opened for output using Rewrite or Open.
  6279.     Arguments  : Any number of expressions.  If the output
  6280.              file is a typed file, these expressions
  6281.              must each match the file type, and cannot
  6282.              use field width specifiers.  If the file
  6283.              is a Text file, they can be any of the
  6284.              types mentioned above, and can have at
  6285.              least one field width specifier.
  6286.  
  6287.     RESULTS
  6288.     None
  6289.  
  6290.     BUGS
  6291.  
  6292.     SEE ALSO
  6293.     Writeln, Read, Readln, Rewrite, Open, Put
  6294.  
  6295.  
  6296. PCQ/Writeln                PCQ/Writeln
  6297.  
  6298.     NAME
  6299.     Writeln - write arguments, then append a newline character
  6300.  
  6301.     SYNOPSIS
  6302.     Procedure Writeln([VAR OutputFile : Text;] Arguments );
  6303.  
  6304.     DESCRIPTION
  6305.     Writeln outputs values to a PCQ file like Write, but with
  6306.     two differences: it only works with Text files, and it
  6307.     appends a newline character after writing all of the
  6308.     arguments.
  6309.  
  6310.     Writeln only works on Text files because typed files,
  6311.     which are unlimited sequences of a single type, don't
  6312.     have lines.
  6313.  
  6314.     The newline character on the Amiga is a line feed, or
  6315.     Chr(10), but since on other machines it can be quite
  6316.     different (on MS-DOS machines, for example, it is a
  6317.     carraige return/line feed pair), you should use this
  6318.     routine rather than writing line feeds directly.
  6319.  
  6320.     EXAMPLE
  6321.  
  6322.     Program ShowWriteln;
  6323.     begin
  6324.         Writeln(50:3, 100.0:5:2); { Writes ' 50  100.00' }
  6325.     end.
  6326.  
  6327.     INPUTS
  6328.  
  6329.     OutputFile : A PCQ Text file, already open for output.  If
  6330.              OutputFile is not supplied, PCQ used the
  6331.              standard output file Output.
  6332.     Arguments  : A series of arguments exactly like those of
  6333.              Write, which will be written the same way.
  6334.  
  6335.     RESULTS
  6336.     None
  6337.  
  6338.     BUGS
  6339.  
  6340.     SEE ALSO
  6341.     Write, Read, Readln, Rewrite, Open, Put
  6342.  
  6343.