GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/files/language/forst/glossary.lst

File List | 1993-10-23 | 7.9 KB | 227 lines

                  GLOSSARY OF NON-STANDARD ForST WORDS


SYSTEM:  use this word when you wish to exit ForST.


Strings and TOS:  TOS was written in C, and expects all strings to be
  uncounted and null-terminated.  The one curious exception is the
  command line used in EXEC, which is both counted and (usually) null-
  terminated.


File words:  where appropriate, the order of parameter passing has been
  made consistent with standard usage in Unix/C.  Occasional deviations
  are intended to be more intuitive to Forth users.  Their detailed
  workings are in the assembly file FILES.S.

Low-level words:  as with C, these use system file handles as descriptors.
They should be used cautiously, and best with a book on the ST in hand.

CHDIR:  (^path--result).  Result of 0 if OK.

CHMOD:  (^filename,flag,attribute--result).  Result = negative if an
  error, otherwise the new attribute.

CLOSE:  (handle--)

DELETE:  (^filename--).  Result of 0 = OK.

EXEC:  (^environment string,^command_line,^filename,mode--)
  Execute a file.  Except in inter-application communication, ^envstr
  should be the address of a zero byte; ^command line is the address
  of a COUNTED string and is copied into the base page of the new file
  when it is loaded; the mode is normally 0.

FDUP:  (non-standard_handle,standard_handle--result).  Result of 0 is OK.

FMAKE: (mode,^name--handle)

GETDTA:  (--address).  Get the current data transfer address.

MALLOC:  (#bytes--result).  Allocate memory from the heap.
  Result is 0 on error, else the address of the start of the allocated
  memory.
  If -1 is passed as #bytes, the result is the total amount of available
  memory, and none will be allocated.

MFREE:  (^start--result).  Release the memory allocated by MALLOC.  Result
  is 0 if OK.

OPEN:  (^filename,mode--handle).  Handle returned is 32-bit negative
  for an error, $ffff for CON:, $fffe for AUX:, $fffd for PRN: or a
  positive handle for a disk file.

RENAME: (^oldname,^newname--result).  Result of 0 = OK

READ:  (handle,^buffer,#chars--#read)

SEEK:  (handle,seekmode,offset--posit).
  Seekmode:  0 = offset relative to file start
             1 = offset relative to present position
            -1 = offset relative to end of file.

SETBLK:  (^start,#bytes--result).  Reserve part of memory for an
  application.  Result is 0 if OK.

SETDTA:  (^buffer--).  Set the data transfer address.

SETDRV:  (#drive--)  0 = A drive, 1 = B, etc

SFIRST:  (^filename,attrib--result).  Find the first file which matches
  the file name (which may include wild chars). Result is 0 if file found.

SNEXT:  (--result).  Find the next file which matches.  Result as before.

WRITE:  (^buffer,handle,#chars--#written)


High-level file words which use some of the above words:

These words use ^file as the address of a ForST file descriptor,
which holds information like the file handle, file mode, #chars read or
written, etc.  A buffer is allocated dynamically from the heap, using
MALLOC.

FCLOSE:  (^file--).  Close this file.

FOPEN:  (^file,mode,^name--).  Open a file for buffered I/O.

FTELL:  (^file--result).  Report the active position in the presently
  open file.

GETC:  (^file--char).  The char is -1 if eof or other error.

LOAD <filename>: Interpret and/or compile text from an ASCII file.

LSEEK:  (^file,mode,offset--).  Seek to a position of an open buffered
  file (see SEEK above).

PUTC:  (char,^file--).  Write a char to a buffered file.

RUN <filename> <parameters>: Run a file with command line parameters.

SAVE <filename>: save the present ForST memory as an executable file.


Other operating system words (in assembly files GEMDOS.S and BIOS.S).

AUXIN:  (--char).  Read a char from the serial port.

BIOS, XBIOS, XBDOS:  Access to operating system traps (care!).

CONIN:  (--char).  There is no echo to the screen.

CONOUT:  (char--).  Used by EMIT to write to screen.

CONSTAT:  (--result).  Result is 0 if no chars available.
  PRTSTAT and AUXINSTAT are similar.

LOGBASE:  (--address).  Return the address of the screen RAM currently
  being used for output (may not be visible at the time).

PHYSBASE:  (--address).  Return the address of the physical screen RAM.

PRTOUT:  (char--).  Write a char to the printer, with a 30 sec timeout.

SCRDMP:  (--).  Make a hard-copy dump of the screen.  The printer MUST
  be an Atari (mine isn't).

SETPRT:  (config--)  Config = $08 for Atari printer, $0c for Epson.


VT52 terminal emulator words:

CURSON, CURSOFF:  turn cursor on or off

KLINE:  remove current line from the screen.

ILINE:  insert a new line with cursor at the left.

KRIGHT:  clear line from cursor position.  Cursor is unchanged.

KDOWN:  clear from cursor to end of screen.

SCURSUP:  scroll the screen upwards.

VDIPB, AESPB:  parameter blocks for GEM VDI and AES screen management.


Control of separated headers:

HIDE <wordname>:  remove the header of a specific word, leaving its
  code or data intact.

FROM <wordname>:  mark the start of a range of headers.  This will usually
  be a dummy name, such as MODULE (see below).

KEEP <wordname>:  select a header for preservation.

PUBLIC:  remove headers, starting with that marked by FROM, and retain
  only those headers specified with KEEP.

  Example:
      FROM MODULE  KEEP INPUT  KEEP OUTPUT  PUBLIC


Other words:

ADDRIN, ADDROUT, PTSIN, PTSOUT:  buffers for GEM.

CALL:  compile a call to the following word (avoids possible macro code
  expansion).

CALLS, MACROS:  change the mode of compilation.  After CALLS, no macro
  code expansion and optimisation can take place.

CELL+, CELL-:  synonyms for 4+ and 4-.

COMP,:  compile the compilation record corresponding to the next
  word in the input stream (see the ForST file VECTORS.S).

DATA, RETURN, CP, HP:  system variables (see assembly file VARS.S)

DELAY:  used as DELAY <wordname> in the definition of an immediate word.
 <wordname> is a DEFERed or VECTORed word and, when the immediate word
 is used in another definition, the contents of the compilation record
 of <wordname> are used to direct compilation (cf COMPILE).  By this
 stage, the compilation record should have been initialised by:
   HEAD <actioname> IS <wordname>

DELIM:  A variable used to hold the character presently being used
  by REPLACE.  The default delimiter is ']', which probably has the
  greatest flexibility, but '"' may be preferred.

FLIP:  interchanges bytes 0 and 1 of the top stack value.

REPLACE:  define a text macro, to replace the next token in the input
  stream with a character string delimited by the character in DELIM.
  Example:  ASCII " DELIM !  REPLACE BUMP R> 1+ DUP >R ."
  BUMP can then be used as a substitute for R> 1+ DUP >R .
  Nesting of REPLACE strings is permitted, but the current limit on the
  degree of input nesting (including file nesting) is 7.  It can be
  increased if the size of IOSTACK (in assembly file VARS.S) is increased,
  and there is a check for stack overflow (mainly to guard against
  accidental text macro recursion.  Try it!).

ROR, ROL:  rotate the carry bit after another operation (like ASR) which
  may have affected it.  Reliable only with macro code expansions.

SYSTEM:  leave ForST for the calling program (or desktop).

START:  a dummy word to mark a point close to the start of headers.

THERE:  return address of free header space (cf HERE)

VECTOR:  define a word (analogous to DEFER).  VECTOR gives compile-time
  binding: DEFER gives run-time binding.  VECTOR is used in the system
  vectors.

VECTORS:  base address of the system vectors (see assembly file SHELL.S).

WFLIP:  interchanges halves of top stack value.

XKEY:  extended keyboard input, with the key location in the second byte
  and the usual char in the first byte.  Can be used to determine a press
  of a function key.