misc

"Misc.Compatibility words"

* just print OK, also fine for copy-and-paste in terminal

    ok [] no special info, see general notes 
  FORTH/BASE misc   ordinary primitive 

    /* more fig-forth */
    * COLD ( -- )

cold abort - reinitialize everything and go to QUIT routine

... this routine is implemented as a warm-boot in pfe.
 : WARM FENCE @ (FORGET) INCLUDE-FILE ?DUP IF COUNT INCLUDED THEN QUIT ;

  FORTH/BASE misc   ordinary primitive 
    LIT [] no special info, see general notes 
  FORTH/BASE misc   ordinary primitive 
    * .LINE ( line# block# -- )

  FORTH/BASE misc   ordinary primitive 

    /** basic system variables ( OUT DP HLD R0 S0 ) */
    OUT [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
    DP [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
    HLD [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
    R0 [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
    S0 [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 

    /* words without pedigree */
    * UD.R ( 2val r -- )

  FORTH/BASE misc   ordinary primitive 
    * UD. ( 2val -- )

see also UD.R

  FORTH/BASE misc   ordinary primitive 
    * ID. ( nfa -- )

print the name-field pointed to by the nfa-argument.

a synonym for .NAME - but this word is more portable due its

heritage from fig-forth. 



in fig-forth the name-field is effectivly a bstring with some flags,

so the nfa's count has to be masked out, e.g. 
 : .NAME COUNT 32 AND TYPE ;


in other pfe configurations, the name might not contain the flags it

it just a counted string - and there may be even more possibility.
 : .NAME COUNT TYPE ;


you should more and more convert your code to use the sequence

NAME>STRING TYPE

  FORTH/BASE misc   ordinary primitive 
    .NAME [] no special info, see general notes 
  FORTH/BASE misc   forthword synonym 
    * -ROLL ( xn ... x2 x1 n -- x1 xn ... x2 )

the inverse of ROLL

  FORTH/BASE misc   ordinary primitive 
    * RANDOM ( n1 -- n2 )

returns random number with 0 <= n2 < n1)
 : RANDOM ?DUP IF _random SWAP MOD ELSE _random THEN ;

  FORTH/BASE misc   ordinary primitive 
    * SRAND ( n -- )

  FORTH/BASE misc   ordinary primitive 
    *  (UNDER+)  ( n1 n2 -- n1+n2 n2 )

quicker than
 : (UNDER+) TUCK + SWAP ; or : (UNDER+) DUP UNDER+ ;

  FORTH/BASE misc   ordinary primitive 
    * UNDER+ ( n1 x n2 -- n1+n2 x ) TF

    quicker than
 : UNDER+  ROT + SWAP ;

  FORTH/BASE misc   obsolete forthword 

    /* more local variables */
    * +TO ( val [name] -- )

add the val to the named VALUE or LOCALS| value

  FORTH/BASE misc   compiling primitive 

    /* data structures */
    * BUILD-ARRAY ( n1 n2 ... nX X --- n )

writes X, n1, ... nX into the dictionary - 

returns product n1 * n2 * ... * nX 

  FORTH/BASE misc   ordinary primitive 
    * ACCESS-ARRAY ( i1 i2 ... iX addr1 --- addr2 n )

see BUILD-ARRAY

  FORTH/BASE misc   ordinary primitive 

    * .STATUS ( -- )

display internal variables 
 : .STATUS .VERSION .CVERSION .MEMORY .SEARCHPATHS .DICTVARS .REGSUSED ;

  FORTH/BASE misc   ordinary primitive 
    SHOW-STATUS [] no special info, see general notes 
  FORTH/BASE misc   forthword synonym 

    /* NOTE: the newer "TO"-implementation is able to set DVaLs */
    UPPER-CASE? [] no special info, see general notes 
  FORTH/BASE misc   loader code P4_DVaL 
 /* will be bool-VaL */
    LOWER-CASE [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
 /* fixme: deleted somewhen */
    LOWER-CASE-FN? [] no special info, see general notes 
  FORTH/BASE misc   loader code P4_DVaL 
 /* will be bool-VaL */
    LOWER-CASE-FN [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
 /* fixme: delete somewhen */
    REDEFINED-MSG? [] no special info, see general notes 
  FORTH/BASE misc   loader code P4_DVaL 
 /* will be bool-VaL */
    REDEFINED-MSG [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
 /* fixme: delete somewhen */
    QUOTED-PARSE? [] no special info, see general notes 
  FORTH/BASE misc   loader code P4_DVaL 
  /* will be bool-VaL */
  
    * SOURCE-LINE ( -- n )

if SOURCE is from EVALUATE (or QUERY ) then

the result is 0 else the line-numbers start from 1 

  FORTH/BASE misc   ordinary primitive 
    * SOURCE-NAME ( -- str-ptr str-len )

if SOURCE is from INCLUDE then the result is the filename,

otherwise a generic name for the SOURCE-ID is given.

  FORTH/BASE misc   ordinary primitive 
    * TH'POCKET ( n -- addr u )

returns the specified pocket as a S" string reference

  FORTH/BASE misc   ordinary primitive 
    * POCKET-PAD ( -- addr )

Returns the next pocket.

A pocket has usually the size of a maxstring, see ENVIRONMENT /STRING

(but can be configured to be different, mostly when MAXPATH > /STRING )

Note that a pocket is a temporary and forth internal functions do

sometimes call POCKET-PAD too, especially when building filenames

and getting a literal (but temporary) string from the keyboard.

Functions are not expected to hold references to this transient

area any longer than building a name and calling another word with it.
Usage of a pocket pad is a good way to make local temporary buffers

superfluous that are only used to construct a temporary string that 

usually gets swallowed by another function.
 depracated code:
   create temp-buffer 255 allot
   : make-temp ( str buf ) 
          temp-buffer place  " .tmp" count temp-buffer append 
          temp-buffer count make-file ;
 replace with this:
   : make-temp ( str buf )
        pocket-pad >r    
        r place  " .tmp" count r append
        r> count make-file
   ;

  FORTH/BASE misc   ordinary primitive 
    P4_OCoN ("/CELL",		sizeof (p4cell)),
    WSIZE [] no special info, see general notes 
  FORTH/BASE misc   forthword synonym 
    * W@ ( addr -- w-val )

fetch a 2byte-val from address

  FORTH/BASE misc   ordinary primitive 
    * W! ( w-val addr -- )

store a 2byte-val at addressed 2byte-value

  FORTH/BASE misc   ordinary primitive 
    * W+! ( w-val addr -- )

add a 2byte-val to addressed 2byte-value

  FORTH/BASE misc   ordinary primitive 
    * WL-HASH ( c-addr n1 -- n2 )

calc hash-code for selection of thread

in a threaded-vocabulary

  FORTH/BASE misc   ordinary primitive 
    * TOPMOST ( wid -- a-addr )

that last valid word in the specified vocabulary

  FORTH/BASE misc   ordinary primitive 
     /** the variable accessed with LATEST */

    * LS.WORDS ( -- )

see WORDS

  FORTH/BASE misc   ordinary primitive 
    * LS.PRIMITIVES ( -- )

see WORDS

  FORTH/BASE misc   ordinary primitive 
    * LS.COLON-DEFS ( -- )

see WORDS

  FORTH/BASE misc   ordinary primitive 
    * LS.DOES-DEFS ( -- )

see WORDS

  FORTH/BASE misc   ordinary primitive 
    * LS.CONSTANTS ( -- )

see WORDS

  FORTH/BASE misc   ordinary primitive 
    * LS.VARIABLES ( -- )

see WORDS

  FORTH/BASE misc   ordinary primitive 
    * LS.VOCABULARIES ( -- )

see WORDS

  FORTH/BASE misc   ordinary primitive 
    * LS.MARKERS ( -- )

see WORDS

  FORTH/BASE misc   ordinary primitive 

    * TAB ( n -- )

jump to next column divisible by n 

  FORTH/BASE misc   ordinary primitive 
    * BACKSPACE ( -- )

reverse of SPACE

  FORTH/BASE misc   ordinary primitive 
    * ?STOP ( -- flag )

check for 'q' pressed

- see ?CR

  FORTH/BASE misc   ordinary primitive 
    * START?CR ( -- )

initialized for more-like effect

- see ?CR

  FORTH/BASE misc   ordinary primitive 
    * ?CR ( -- flag )

like CR , stop 25 lines past START?CR

  FORTH/BASE misc   ordinary primitive 
    * CLOSE-ALL-FILES ( -- )

  FORTH/BASE misc   ordinary primitive 
    * .MEMORY ( -- )

  FORTH/BASE misc   ordinary primitive 
    
    /** vectorized i/o variables, see STANDARD-I/O */
    *EMIT* [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
    *EXPECT* [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
    *KEY* [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
    *TYPE* [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
    * (EMIT) ( val -- )

like EMIT and always to screen 

- the routine to be put into *EMIT*

  FORTH/BASE misc   ordinary primitive 
    * (EXPECT) ( . -- . )

like EXPECT and always from screen

- the routine to be put into *EXPECT*

  FORTH/BASE misc   ordinary primitive 
    * (KEY) ( -- ... )

like KEY and always from screen

- the routine to be put into *KEY*

  FORTH/BASE misc   ordinary primitive 
    * (TYPE) ( val -- )

like TYPE and always to screen 

- the routine to be put into *TYPE*

  FORTH/BASE misc   ordinary primitive 
    * STANDARD-I/O ( -- )

initialize *TYPE* , *EMIT* , *EXPECT* and *KEY*

to point directly to the screen I/O routines, 
 

namely (TYPE) , (EMIT) , (EXPECT) , (KEY) 

  FORTH/BASE misc   ordinary primitive 

    /* show online help: */
    * HELP ( name -- )

will load the help module in the background and hand over the 

parsed name to (HELP) to be resolved. If no (HELP) word

can be loaded, nothing will happen.

  FORTH/BASE misc   ordinary primitive 
    * EDIT-BLOCKFILE ( name -- )

will load the edit module in the background and look for a word

called EDIT-BLOCK that could be used to edit the blockfile.

If no EDIT-BLOCKFILE word can be loaded, nothing will happen.

Otherwise, OPEN-BLOCKFILE is called followed by 0 EDIT-BLOCK

to start editing the file at the first block.

  FORTH/BASE misc   ordinary primitive 
  /** the application to be called, options like ARGC ARGV */
    APPLICATION [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 

    /** task system hooks */
    * ARGC ( -- n )

  FORTH/BASE misc   ordinary primitive 
    * ARGV ( n -- addr u )

  FORTH/BASE misc   ordinary primitive 
    EXITCODE [] no special info, see general notes 
  FORTH/BASE misc   threadstate variable 
     /** ( -- fid ) - the standard file-handles of the task */

STDIN [] no special info, see general notes 
  FORTH/BASE misc   loader code P4_DVaL

	
    STDOUT [] no special info, see general notes 
  FORTH/BASE misc   loader code P4_DVaL

	
    STDERR [] no special info, see general notes 
  FORTH/BASE misc   loader code P4_DVaL 	

    * EXPAND-FN ( addr1 u1 addr2 -- addr2 cnt2 )

  FORTH/BASE misc   ordinary primitive 
    LOAD" [] no special info, see general notes 
  FORTH/BASE misc   compiling primitive 
#ifndef NO_SYSTEM
    * SYSTEM ( addr u -- ret-val )

run a shell command  (note: embedded systems have no shell)

  FORTH/BASE misc   ordinary primitive 
    SYSTEM" [] no special info, see general notes 
  FORTH/BASE misc   compiling primitive 
#endif /* NO_SYSTEM */
    * RAISE ( n -- )

send a SIGNAL to self

  FORTH/BASE misc   ordinary primitive 
    * SIGNAL ( xt1 n -- xt2 )

install signal handler

- return old signal handler

  FORTH/BASE misc   ordinary primitive 

/* almost usable everywhere */
    * CREATE: ( 'name' -- )

this creates a name with the VARIABLE runtime.

Note that this is the FIG-implemenation of CREATE whereas in

ANS-Forth mode we have a CREATE identical to FIG-style <BUILDS
 : CREATE: BL WORD $HEADER DOVAR A, ;

  FORTH/BASE misc   ordinary primitive 
    * BUFFER: ( size 'name' -- )

this creates a name with the VARIABLE runtime and ALLOTs memory
 : BUFFER: BL WORD $HEADER DOVAR A, ALLOT ;

  FORTH/BASE misc   ordinary primitive 

/* quite useful, esp. for non-locals code */
    * R'@                 ( -- x )( R: x y -- x y )

 The second element on the return stack.
 : R'@   S" 2R@ DROP " EVALUATE ; IMMEDIATE

  FORTH/BASE misc   compiling primitive 
    * R'! ( x R: a b -- R: x b )

store the value into the next-under value in the returnstack.

used to interpret the returnstack to hold two LOCALS| values.

see R'@ for inverse operation

  FORTH/BASE misc   compiling primitive 
    R"@ [] no special info, see general notes 
  FORTH/BASE misc   compiling primitive 
    R"! [] no special info, see general notes 
  FORTH/BASE misc   compiling primitive 
    * R! ( x R: a -- R: x )

store the value as the topmost value in the returnstack.

see R@ for inverse operation ( R'@ / R"@ / 2R@ / 2R!)

  FORTH/BASE misc   compiling primitive 
    * 2R! ( x y R: a b -- R: x y )

store the value as the topmost value in the returnstack.

see 2R@ for inverse operation ( R'@ / R"@ / 2R@ / 2R!)

  FORTH/BASE misc   compiling primitive 
    * DUP>R ( val -- val )

shortcut, see R>DROP


 note again that the following will fail:
 : DUP>R DUP >R ;

  FORTH/BASE misc   compiling primitive 
    * R>DROP ( -- )

shortcut (e.g. in CSI-Forth)


 note that the access to R is configuration dependent - only in

a traditional fig-forth each NEST will be one cell wide - in case that

there are no LOCALS| of course. And remember, the word above reads

like the sequence R> and DROP but that is not quite true.
 : R>DROP R> DROP ; ( is bad - correct might be )  : R>DROP R> R> DROP >R ;

  FORTH/BASE misc   compiling primitive 
    * 2R>2DROP ( -- )

this is two times R>DROP but a bit quicker.

it is however really quick compared to the sequence 2R> and 2DROP

  FORTH/BASE misc   compiling primitive 
    * CLEARSTACK ( -- )

reset the parameter stack to be empty
 : CLEARSTACK  S0 SP! ;

  FORTH/BASE misc   ordinary primitive 

    EXTENSIONS
    +UNDER [] no special info, see general notes 
  FORTH/EXTENSIONS misc   ordinary primitive 

/* smart */
    * EXECUTES ( n [word] -- )

stores the execution token of following word into

the callback pointer for the specified function-key 

  FORTH/EXTENSIONS misc   ordinary primitive 

    ENVIRONMENT
    ENVIRONMENT RAND_MAX [] no special info, see general notes 
  ENVIRONMENT misc   ordinary constant