home *** CD-ROM | disk | FTP | other *** search
/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / MISC / FPC355_3.ZIP / FPCHLP.ZIP / SEQREAD.HLP < prev    next >
Encoding:
Text File  |  1989-09-21  |  12.5 KB  |  315 lines
  1. \ SEQREAD.HLP   Sequential read and load file           by Tom Zimmer
  2.  
  3. WITHPATH        ( -- f1 )
  4.         A flag telling F-PC whether it should include the PATH in the file
  5.         variable created when loading a file.
  6.  
  7. IBLEN           ( -- n1 )
  8.         The input buffer length value specifies how much may be read into
  9.         the input buffer at one time (on a buffer refill). This value is
  10.         adjusted by BUFSIZE-INIT in BUFSET.SEQ to a size correct for your
  11.         computers performance at Forth boot time. IBLEN will typically
  12.         range from about 4k for a 4.7 MHZ 8088 machine up to 27k for a
  13.         16MHZ 80386 machine. The value of IBLEN is limited even on very
  14.         fast machines to IBLIMIT located in BUFSET.SEQ. IBLEN will at times
  15.         get adjusted down to a very small value (256 bytes) when returning
  16.         from a nested load. This is done to minimize re-reads of the entire
  17.         load file when you are likely to be only reading a single line from
  18.         the load file and then going off to load another file. The value
  19.         IBFULL holds the actual full buffer size when restoring IBLEN at
  20.         the beginning of each load.
  21.  
  22. IBFULL          ( -- n1 )
  23.         The full buffer size value is used to restore IBLEN at the
  24.         beginning of each file load. See IBLEN for more details.
  25.  
  26. SCREENCHAR      ( -- n1 )
  27.         A value used by the editor to indicate the cursor position on the
  28.         line. This value also gets set by the error handler when a compile
  29.         error occurs.
  30.  
  31. DELIMITER       ( -- c1 )
  32.         Lineread delimiter, normally $0A (linfeed), but can be set to
  33.         other values when reading records that are delimited by some
  34.         symbol other than a linefeed.
  35.  
  36. OBLEN           ( -- n1 )
  37.         The output buffer length value, specifys how much can be placed in
  38.         the output buffer by LINEREAD. This value can be adjusted to a
  39.         smaller value, to force a shorter maximum read of a file. For
  40.         example if OBLEN is set to 64, you can read Forth block files with
  41.         LINEREAD, one line at a time.  Be sure to preserve the value of
  42.         OBLEN so it can be restored to its original value. WARNING setting
  43.         the value OBLEN to something greater than its original value will
  44.         cause a system crash. See IBLEN for additional details.
  45.  
  46. INSTART         ( -- n1 )
  47.         This value specifys where in the input buffer to start scanning for
  48.         the next line read by LINEREAD. INSTART will always be in the range
  49.         zero to IBLEN.  See also IBLEN.
  50.  
  51. INLENGTH        ( -- n1 )
  52.         The input text length value specifys how much text ramains in the
  53.         input buffer. When INLENGTH falls below OBLEN a buffer refill from
  54.         the file is performed. See also IBLEN.
  55.  
  56. INBSEG          ( -- n1 )
  57.         The input buffer segment value contains the physical starting
  58.         segment in memory of the LINEREAD input buffer. See also IBLEN.
  59.  
  60. TOTALLINES      ( -- a1 )
  61.         The total lines VARIABLE holds the total number of lines read with
  62.         LINEREAD since TOTALLINES was reset to zero. Useful in keeping
  63.         track of how many lines of code you are working on.
  64.  
  65. OUTBUF          ( -- a1 )
  66.         The line output buffer array in CODE space. Holds the lines read by
  67.         LINEREAD. Returns a1 the address of a counted string of characters.
  68.         See also IBLEN and OBLEN.
  69.  
  70. MAXNEST         ( -- n1 )
  71.         This constant holds the total sum in bytes of the handle control
  72.         blocks used in the handle stack. Normally set to (7 times B/HCB).
  73.  
  74. HNDLS           ( -- a1 )
  75.         An array of handles. Returns the address of the first handle in the
  76.         handle stack.
  77.  
  78. FILEPOINTER     ( -- a1 )
  79.         A double variable holding the byte offset into the current file for
  80.         the next disk read when filling the input buffer.
  81.  
  82. LOADING         ( -- a1 )
  83.         A variable. Holds a flag TRUE if we are we in the process of
  84.         loading a file?
  85.  
  86. CONHNDL         ( -- a1 )
  87.         A system handle pre-initialized to contain the DOS handle number
  88.         for the CONSOLE output device, handle value 1. Can be re-directed
  89.         to other places, but normally isn't.
  90.  
  91. PRNHNDL         ( -- a1 )
  92.         A system handle pre-initialized to contain the DOS handle number
  93.         for the PRN print device, handle value 4. This handle can easily
  94.         be redirected to a file if desired with PFILE and PCLOSE.
  95.  
  96. (CONSOLE)       ( c1 --- )
  97.         Write character c1 to the console output device. Normally the
  98.         display console.
  99.  
  100. (TYPE)          ( a1 n1 --- )
  101.         Write the string of characters specified by a1, n1 to the console
  102.         output device. Normally the display console.
  103.  
  104. (PRINT)         ( c1 --- )
  105.         Write the character c1 to the PRN output device. Normally the local
  106.         printer.
  107.  
  108. (EXTYPE)        ( seg a1 n1 --- )
  109.         Write the string of characters specified by a1, n1 in segment seg
  110.         to the console output device. Normally the display console.
  111.  
  112. LOADSTAT        ( -- )
  113.         A defered word that normally contains a function to display the
  114.         status line at hte top of the screen. This function is called
  115.         periodically while loading files, to let the user know what is
  116.         going on.
  117.  
  118. SEQHANDLE+      ( --- a1 )
  119.         Returns address a1, the address of the next unused handle above the
  120.         current handle. Used occasionally when a VERY TERMPORARY handle is
  121.         needed for filename manipulation.
  122.  
  123. .SEQHANDLE      ( --- )
  124.         Display the filename in the current file handle.
  125.  
  126. CURPOINTER      ( handle --- double-current )
  127.         Get the double-current file offset pointer of the file open on
  128.         handle.
  129.  
  130. SAVEPOINTER     ( --- )
  131.         Save the current file offset pointer in FILEPOINTER for use later
  132.         in filling the input buffer.
  133.  
  134. GET_ALINE       ( --- )
  135.         Parse a line of text from the input buffer and place it in the
  136.         output buffer OUTBUF. See also IBLEN and OBLEN.
  137.  
  138. FILEPOINTER+    ( --- )
  139.         Increment the current file pointer by the length of the line
  140.         in outbuf.
  141.  
  142. FILLBUF         ( -- )
  143.         Re-fills the input buffer to capacity from the currently open file
  144.         specified by the handle in the value SEQHANDLE.
  145.  
  146. ?FILLBUFF       ( --- )
  147.         Re-fill the input buffer by calling FILLBUF if INLENGTH is less
  148.         than OBLEN.
  149.  
  150. LINEREAD        ( --- a1 )
  151.         Read a line from the current file, returning the address a1,
  152.         the address of the next line. See also IBLEN, OBLEN & GET_ALINE.
  153.  
  154. (DOERROR)       ( a1 n1 --- )
  155.         Display the file, line, and offset into the line where an error
  156.         has occured, then QUIT.
  157.  
  158. DOERROR         ( a1 n1 -- )
  159.         A defered word used to handle errors that occur while loading.
  160.         A1 and n1 specify a message string to be displayed while handling
  161.         the error.
  162.  
  163. DEFBASE         ( -- n1 )
  164.         A value that holds the numeric base to be used when restoring the
  165.         base when an error occurs. See also HEXBASE, DECIMALBASE & NOBASE.
  166.  
  167. HEXBASE         ( --- )
  168.         Set HEX as the default base. When an error occurs, the base will be
  169.         set to hexdecimal.
  170.  
  171. DECIMALBASE     ( --- )
  172.         Set DECIMAL as the default base. When an error occurs, the base
  173.         will be switched back to DECIMAL.
  174.  
  175. NOBASE          ( --- )
  176.         Set NO default base, the base will not be changed when an error
  177.         occurs.
  178.  
  179. .BASE           ( --- )
  180.         Display the current base in decimal.
  181.  
  182. ?BASE_RESTORE   ( f1 --- )
  183.         Conditionally restore the base to DEFBASE if f1 is TRUE and DEFBASE
  184.         is not zero.
  185.  
  186. (?SERROR)       ( a1 n1 f1 --- )
  187.         If f1 is true, then print message a1, n1 and show the
  188.         line in the current file where the error occured using DOERROR.
  189.  
  190. ?SEQRANGE       ( --- )
  191.         Verify the value of seqhandle points to a handle in the HNDLS
  192.         array, abort if it doesn't.
  193.  
  194. SEQUP           ( --- )
  195.         Step up to the next handle in the HNDLS handle stack.
  196.  
  197. SEQINIT         ( --- )
  198.         Clear the the handle stack. Set SEQHANDLE to the first handle in
  199.         HNDLS. Allocate the input buffer and set INBSEG. Initialize CONHNDL
  200.         and PRNHNDL to their default display and printer devices.
  201.  
  202. IBRESET         ( --- )
  203.         Reset the input buffer to empty. The next LINEREAD will force a
  204.         physical file read from disk. This word emptys the buffer, but does
  205.         not effect the positon in the file where the read will occur, so if
  206.         you want to force a read from the start of a file, you need to do
  207.         use the MOVEPOINTER command in addition to this word.
  208.  
  209. $HOPEN          ( a1 --- f1 )
  210.         Open the file specified by the counted string a1. Return
  211.         boolean f1 false if the open was succesful. Also clears the input
  212.         buffer to empty using IBRESET.
  213.  
  214. GETFILE         ( --- <a1> f1 )
  215.         A defered word that returns a flag true, followed by a1 the address
  216.         of a file, or returns f1 false alone.  This word provides the
  217.         interface to the F-PC popup file selection tool.
  218.  
  219. FILE>TIB        ( a1 --- )
  220.         Given a counted string a1, put it in the terminal input buffer to
  221.         be the next word obtained by BL WORD.
  222.  
  223. GFL             ( --- )
  224.         test the terminal input buffer to see if there is any "un-gotten"
  225.         text there. If there is text in TIB, then leave. If there is no
  226.         more text in TIB, then try to prompt for file using GETFILE, and if
  227.         a file is returned, put it in TIB.
  228.  
  229. SEEK            ( d1 --- )
  230.         Seek (move pointer) to position d1 in the current open file
  231.         specified in value SEQHANDLE.
  232.  
  233. LISTVAR         ( --- f1 )
  234.         List value, if this value is on, then lines of the
  235.         current load file will be displayed while being loaded.
  236.  
  237. SHOWLINES       ( --- )
  238.         Turn on listing of lines while loading.
  239.  
  240. HIDELINES       ( --- )
  241.         Turn off listing of lines while loading.
  242.  
  243. CRLF>BL'S       ( a1 --- a1 )
  244.         Test the last two characters of the counted string a1, and change
  245.         them to blanks if they are CRLF (carraige return & linefeed).
  246.  
  247. SETTIB          ( a1 --- )
  248.         Set TIB to point to the counted string a1.
  249.  
  250. .LOADLINE       ( a1 --- a1 )
  251.         Display the counted string a1, preceeded by a CR and a line number
  252.         from LOADLINE.
  253.  
  254. ?.LOADLINE      ( a1 --- a1 )
  255.         If the value LISTVAR is true. then perform .LOADLINE .
  256.  
  257. LENGTH.CHECK    ( a1 --- a1 f1 )
  258.         Test the counted string a1 to see if it has a length of zero. also
  259.         check INLENGTH to see if it is zero. If both are zero, then return
  260.         f1 as false meaning we are at the end of the file.
  261.  
  262. FILLTIB         ( --- )
  263.         read a line from the current open file, and set the terminal input
  264.         buffer to point to it.
  265.  
  266. SEQDOWN         ( --- )
  267.         Step down one handle in the handle stack. closes the current
  268.         file, and selects the next lower file. Also fills TIB with a line
  269.         from the file.
  270.  
  271. CLOSE           ( --- )
  272.         A pseudonym for SEQDOWN. See also SEQDOWN.
  273.  
  274. CLOSEALL        ( --- )
  275.         Close all open file handles in the HNDLS handle stack.
  276.  
  277. <LOAD>          ( --- )
  278.         Load the current file starting at the current file offset.
  279.  
  280. LOADER          ( --- )
  281.         A defered word that loads the current file. Normally defers to
  282.         <LOAD>.
  283.  
  284. >LINE           ( n1 --- )
  285.         Step to line n1 in the current file such that the next LINEREAD
  286.         will read line n1.
  287.  
  288. ?LOADED,        ( -- f1 )
  289.         A value that specifys whether LOADED, will create a variable in the
  290.         FILES vocabulary for the currently open file. When ?LOADED, is true
  291.         a variable is created. When ?LOADED, is false, no variable is
  292.         created, and ?LOADED, is set to true.  This value is used to allof
  293.         F-PC to load its .CFG configuration file without creating a FILES
  294.         variable for it.
  295.  
  296. LOADED,         ( --- )
  297.         Compile the name of the current file as a variable in the FILES
  298.         vocabulary. Also links the variable into a list of variables that
  299.         represent the files that have been loaded. See also ?LOADED,
  300.  
  301. <FLOAD>         ( --- )
  302.         Primitive word that loads the current open file.
  303.  
  304. CHARREAD        ( --- c1 )
  305.         Read a character c1 from the current open file.
  306.  
  307. OK              ( --- )
  308.         Load all of the current file from the beginning.
  309.  
  310.  
  311. \S              ( n1 --- )
  312.         Stop loading the current file with the line that contains
  313.         this word.
  314.  
  315.