Monster Media 1994 #1

home *** CD-ROM | disk | FTP | other *** search

/ Monster Media 1994 #1 / monster.zip / monster / PROG_GEN / FORTH_86.ZIP / GLOSSARY.4TH < prev next >

Wrap

Text File | 1993-12-24 | 54KB | 1,881 lines

4th_86 version 4.01 GLOSSARY page 1 ============================================= This is not a complete glossary. Only the words which differ from more conventional FORTHs are described. The glossary provided with the demo version is further reduced in content to include only the most commonly useable words. ** NOTE ** there is no difference between upper and lower case. Some of the words below are in upper -- some in lower -- this just depends on how they were defined. The system recognises upper and lower as equivalent when searching the dictionary. ============================================== $! (string store) Purpose: Moves the string at the source address on the NOS to the destination address on the TOS ' (tick or "defadr") Purpose: Gets the definition address to the TOS of the word immediately following ' in the input stream. '' (tick-tick or "datadr") Purpose: Gets the contents of the 4th and 5th bytes of the definition whose address immediately follows '' in the input stream. This is used with the words BLOCK, CONST, etc 5 BLOCK ABC '' ABC .H would define the block ABC and then print its actual memor address. ABC .H would also print the actual address of ABC -- but there are times (eg in cross-compile) when words such as ABC can not be executed per-se and the address has to be found with tick-tick. Note that tick-tick is two apostrophes -- not a double quote 4th_86 version 4.01 GLOSSARY page 2 +! (plus store) Purpose: Add NOS to contents of address at TOS and store at the same address. -1* (negate) Purpose: Compute the 2's complement of the TOS examples FF Hex => FF01 Hex 0 Hex => 0 Hex 2 Hex => FFFE Hex FFFF Hex => 0001 Hex -2 => 2 ->L (rightshift logical) Purpose: Logical shift right the value at NOS by the number of bytes on TOS ." (dot-quote) Purpose: Writes a styring of characters to the console device. The TOS contains the address of the string. The first byte of the string contains the length of the string. Note that defining the string by " ...string.." automatically leaves the address of the string on the TOS. If the system is in high mode (ie compile) then the string is stored in the definition being compiled. If the system is in low mode (ie execute) then the string is stored in STRING and its address is retorned on TOS. .B ( dot-bee) Purpose: Prints the TOS as a binary number with a leading space. .C (dot-see) Purpose: Writes the ASCII character on the TOS to the console output device .CL (dot-see-el) Same as .L but writes numerical value in a colour defined by the current contents of GCOLR. 4th_86 version 4.01 GLOSSARY page 3 . (dot) Purpose: Prints the TOS as a five digit decimal number with a leading space .H (dot-aitch) Purpose: Prints the TOS as a four digit hexadecimal number with a leading space. .HB (dot-aitch-bee) Purpose: Prints the TOS as a two digit hexadecimal number with a leading space .L ( dot-ell ) Purpose: While this prints the TOS as a five digit decimal number WITHOUT a leading space -- its purpose is to send ANSI control parameters to the screen. .Q ( dot-Q ) Purpose: Prints the TOS as an octal number with a leading space. 0= (equal to zero) Purpose: To test if the TOS is zero Returns 0 for FALSE and 1 for TRUE Can also be used to negate flag on TOS (see below) 0> (positive) Purpose: Test if TOS is greater than zero. Returns 0 (false) if TOS is less than or equal to zero. Note that 0< is not implemented as such. It can be simulated with 0> and 0= : 0< 0> 0= ; 1+ (increment by one ) Purpose: Increments the TOS by one 4th_86 version 4.01 GLOSSARY page 4 1- ( decrement by one ) Purpose: Decrements the TOS by one 16DM Purpose: Dumps 16 lines of memory starting at the address on TOS. example 8000H DM will return the following memory dump and will ALSO leave on the TOS the address 8100 Hex ready for another 16DM ( see also DM and 8DM) 8000 01E83281 887B747F 3E01E829 81407C74 *..2..{t.>..).@|t* 8010 7F3E01E8 CEF50000 0000E8C7 F5000080 *.>..............* 8020 3FE8C0F5 00000040 E8B9F500 002041E8 *?......@..... A.* 8030 B2F5CDCC CC3DE8FD 80EF014A 01FF7FBF *.....=.....J....* 8040 02EF013E 01E8EE80 6576D002 91015A80 *...>....ev....Z.* 8050 EF014A01 0080E102 EF013E01 E8D780F8 *..J.......>.....* 8060 7FCC012D 053E01E8 CC808B76 5C803E01 *...-.>.....v\.>.* 8070 E871F5FC FFFFFFE8 BC80D175 7080AB75 *.q.........up..u* 8080 13773E01 5A5B0AC0 B000F512 073C0A73 *.w>.Z[.......<.s* 8090 03E90200 B0008807 4BFECA74 03E9E8FF *........K..t....* 80A0 7303E90B 0043C607 01BA0800 03DAFE07 *s....C..........* 80B0 E95180E8 80801808 18081808 18083608 *.Q............6.* 80C0 FA013608 FA011808 3B080802 18084008 *..6.....;.....@.* 80D0 08026576 3680D002 9101BD81 C4011808 *..ev6...........* 80E0 FB049101 EE801D08 27080802 36806576 *........'...6.ev* 80F0 76010000 803FCA76 91010881 2F800180 *v....?.v..../...* 2+ (increment by two) Purpose: Increments the TOS by two 8/ (divide by eight) Purpose: Divides the TOS by eight 8DM Purpose: Dumps 9 lines of memory starting at the address on TOS. (see 16DM) : (colon) Purpose: Identifies the beginning of a high level definition. A warning message will be given depending on the state of the system variable REDEFINE (see later) 4th_86 version 4.01 GLOSSARY page 5 :ENTER (colon enter) Purpose: Allows the user to now use high level (Forth) words if currently using low level (assembly) words. :EXIT (colon exit) Purpose: Allows the user to now use low level words (assembly) if currently using high level (Forth) words. ; (semi-colon) Purpose: Terminates any definition and when executed returns control to the threader. The words can be either high level (Forth) or low level (assembly). ;NOTHREAD (semi-nothread) Purpose: Terminates only code definitions and when executed does not return control to the threader. Normally used when defining assembly language subroutines ending in RET or equivalent. ;PUSH (semi-push) ?DUP Purpose: Copies the TOS to the NOS if and only if the TOS is non-zero. ABS (absolute value of) Purpose: Get the absolute value of the TOS If the TOS is a signed negative number then its positive value will be returned. example FFFF Hex => 0001 Hex 7FFF Hex => 7FFF Hex ASM Purpose: If the word being defined is a code definition which is a subroutine with an assembly language return (or equivalent), then the word ASM should be used after the definition terminator and will cause the dictionary entry flags to be set accordingly. This allows the interpreter to avoid execution of the flagged word in immediate mode example CODE FRED ........ RET, ;NOTHREAD ASM 4th_86 version 4.01 GLOSSARY page 6 B! (byte store) Purpose: Stores NOS as one byte at address on TOS example 00EFH 534EH B! will store the byte value EF Hex at the address 534E Hex B@ (byte fetch) Purpose: Fetch to the TOS the byte value whose address is on the TOS example assuming we have a word value 2435 Hex stored at address 3705 Hex (for example by an MASM DW 2435 statement) then 3705H B@ will return 35 Hex on the TOS ( ie the low byte of the word 2435) BEGIN ... END Purpose: Provides loop control over the execution of the code between the BEGIN and END. The code is executed repeatedly until the TOS has a true value when the END is executed. Note that the code is always executed at least one time. ( see alse END[ ) example : print_ten 0 ( initialise loop counter) begin 1+ dup . ( increment counter and print it) dup 10 = ( TOS=1 ( true) if done ) end drop ( loop counter) ; BLOAD Shells to DOS and calls the batch file ASMBL.BAT which then calls MASM, LINK, and EXE2BIN in sequence. It will then load the BIN file into 4th_86. The source file must have a suffix ASM [ eg TEST.ASM ] but the command is BLOAD TEST Before shelling to DOS the command will check the date of the corresponding BIN and ASM files. It will also check the value of HEAD against the origin at which any existing BIN file was assembled. Only if the BIN file is "out of date" or non existent or assembled at the wrong origin will the assembly be executed. 4th_86 version 4.01 GLOSSARY page 7 Note that if the command is issued from text mode 3 -- the same mode and video page will be returned to on EXIT from DOS. If however the command is issued from a graphics mode and page - return is not necessarily to the same mode or video page. This is because the exit to DOS is into video page 0 - and DOS text will over-write; and leave garbage display on graphics page0. In the demonstration version -- which uses page0 only -- return is always to text mode 3 page 0. In the registered version, an exit to DOS will return to the mode it was initiated from -- and if this was a video mode, to page 1. BLOCK Purpose: Reserves a block of contiguous memory where the size of the block is defined by the value on TOS and the name of the block is the next word. When the name of the block is executed, the address of the block associated with it is placed on the TOS. example Reserve 25 bytes of memory and name it BUFFER 25 BLOCK BUFFER The address of the buffer is determined automatically at the top end of memory. If we assume the address is D912 Hex, then BUFFER .H will print D912 on the console BR Purpose: Unconditional branch for direct threaded code. BRKOFF Disables the control-break function of DOS by redirecting the ctrl-brk interrupt vector to an IRET. The original vectored address is saved for restoring with BRKON. Gives error message if BRKOFF is already in effect. BRKOFF is normally implemented on initialisation of 4th_86. BRKON Makes the ctrl-brk key functional so that endless loops can be exited. Dumps the user back to DOS however. 4th_86 version 4.01 GLOSSARY page 8 BRZ Purpose: Used to transfer control within direct threaded code if the TOS is zero. If the test is true then the address immediately following the BRZ is loaded into the Forth PC and control is passed to the THREADer. If the test is false, control will continue with the word immediately following the branch address of BRZ example ...... TEST 0= BRZ ' SUBR CONT ... will branch to the routine SUBR if the word TEST returns a TRUE value -- otherwise will continue with the word CONT BS Purpose: to send a backspace chracter to the screen BSWAP Purpose: swap the bytes in the word at TOS BYE Purpose: the normal exit from 4th_86 back to DOS. Closes all files and resets the EGA card to normal text mode. CASE .. ENDCASE .. OF .. ENDOF Purpose: Provides for selected code to be executed based on the contents of TOS. The construct CASE .. ENDCASE defines the scope of the case statement. The construcet OF .. ENDOF is used inside the CASE .. ENDCASE to define the code to be executed if the NOS equals the TOS. If NOS = TOS then both values are removed and the code between OF .. ENDOF is executed. and control then passes to the code following ENDCASE. If NOS is not equal to TOS then TOS is removed and control continues following ENDOF -- which usually is another OF .. ENDOF construct. See also the words OF[ .. ] and THRU example : FRED case 23 of " TOS was 23" ." endof 32 of " TOS was 32" ." endof " TOS was neither 23 nor 32" ." drop (TOS value on entry) endcase ; 4th_86 version 4.01 GLOSSARY page 9 CGAM Purpose: Initialise multi-function graphics card in 640x200 2 color CGA graphics mode -- and clear video buffer. (see also NEGAM EGAM NCGAM NORM NNORM) CIRCLE Purpose: Draws a circle at centre X Y of radius R and color C Input -- X Y R C <= TOS This is based on an algorithm in July '83 Dobbs Journal. Larger circles will be drawn with a coarser dot pattern than will smaller circles. The aspect ratio is corrected so that a true circle is produced in the EGA high-res mode. Other modes may produce a flattened circle. Note that the card must be initialised first with either EGAM or CGAM. CLOSE Purpose: Closes a file that has previously been opened. The TOS contains the file handle number of the file to be closed. If all files should be closed then the TOS should contain a zero. No error code will be returned. CLS Purpose: to clear the screen as in DOS command. CODE Purpose: Identifies the beginning of an in-line low level definition. Only 8080 mnemonics are implemented at this stage. example CODE SWAP H POP, D POP, H PUSH, D PUSH, ; defines an assembly routine for SWAP 8086 code can be assembled with MASM and loaded using GLOAD. 4th_86 version 4.01 GLOSSARY page 10 CONST Purpose: Defines a constant whose value is on TOS and whose name folllows CONST. When the name is executed, the value associated with that name is placed on TOS. Only single precision integers may be used as the value of a constant. COS Purpose to return on TOS the cosine of the angle curently there. Angle must be in radians given as a floating point number. CRLF Purpose: Prints a carriage return and line feed on the console CROSS-COMPILE Purpose: All user definitions following CROSS-COMPILE are compiled in a special segment of memory starting at offset 100H. They can not be executed. The purpose is to create a standalone executable COM file. See some of the xxx.DEM files for illustration. CSP@ Return the value of the Control Stack Pointer ( carried in register DI CSP! Store the value on TOS in register DI (Control Stack Pointer) CSPUSH Push code segment register on the stack DATE Displays the date in Day Month Year format DAYTE Returns the date month and year as three parameters on the stack 4th_86 version 4.01 GLOSSARY page 11 D4PIX Purpose: Draws a "nybble" -- 4 consecutive pixels all the same color -- at the specified co-ordinates. This is implemented for speed of drawing where a coarse pattern is acceptable. The format is X Y C D4PIX where X and Y are the co-ordinates and C is the color D>R Purpose: to convert degrees to radians. Degrees must be given as a floating point number. DATA[ Purpose: Defines a block of memory with the values between DATA[ and ] with the name of the block following ] For further details see manual DBOX Purpose: Draws a filled box. The format is X1 Y1 X2 Y2 C DBOX x1,y1 ------------------ | | | | | | | | ------------------ x2,y2 C is the color DLINE Purpose: Draws a line starting from the end of the previous line drawn. To move the starting point to a new position, use DLINE with a colour value equal to the background colour. The format is X Y C DLINE where X and Y are the end co-ordinates and C is the color 4th_86 version 4.01 GLOSSARY page 12 DD (dump definition) Purpose: The word DD decompiles any Forth word. example DD QUIT will decompile the word QUIT see manual for fuller details, including DDH and DDL DDICT (dump dictionary) Purpose: The word DDICT has no arguments and dispalys each dictionary entry of all the dictionaries (which are linked to each other). see manual for fuller details DDS (destructive display stack) Purpose: Displays to the console device all the stack entries currently on the stack, in hexadecimal -- and leaves the stack empty. If the stack is empty when DDS is executed, then the message STACK EMPTY is printed. If the stack has underflowed (ie too many entries DROPped), then printed on the console is the message: STACK UNDERFLOW ... RESETTING STACK. DEBUG Purpose: The word DEBUG toggles the debug facility on and off. The debug facility allows the operator to view the stack while executing words interactively. see manual for fuller details DEFINE Purpose: Builds a new entry into the dictionary ( but does NOT of itself allow building the code in the definition area) The TOS is used as the flag byte. The word being defined follows DEFINE. If the word is already in the dictionary, then a message is displayed asking whether the word should be redefined. DEPTH Purpose: Brings to the TOS the total number of entries on the stack 4th_86 version 4.01 GLOSSARY page 13 DIR Purpose: Display the directory of current drive The format is: DIR or DIR B: etc The current drive can be changed with A: --- D: The subdirectory can be changed with CD Paths are implemented - DIR C:\FORTH\DOCS DM Purpose: Dumps one line of memory starting at the address on TOS. (see 16DM) DO Purpose: Provides iterative loop control over the code between the DO and the LOOP. The structure may be nested up to three levels, DOUBLE Purpose: To convert a single precision number to double precision. DPIX Purpose: Draws a pixel at the specified co-ordinates The format is X Y C DPIX where X and Y are the co-ordinates and C is the color DROP Removes the value currently on TOS and throws it away. DS Purpose: Displays to the console device all the stack entries currently on the stack, in hexadecimal -- and leaves the stack unchanged. If the stack is empty when DS is executed, then the message STACK EMPTY is printed. If the stack has underflowed (ie too many entries DROPped), then printed on the console is the message: STACK UNDERFLOW ... RESETTING STACK. 4th_86 version 4.01 GLOSSARY page 14 DUP Duplicates the value currently on TOS DUP@ Combination of DUP followed by @ DUPB@ Combination of DUP followed by B@ DZHALTOFF Purpose: turns off display of divide by zero error messages DZHALTON Purpose: turns on display of divide by zero error messages DZINST Purpose: Installs divide by zero error handler. Both DZINST and DZREST attempt to be reasonably intelligent about whether the original handler is present or not -- even if 4th-86 is exited to DOS and re-initiated. DZREST Purpose: Restores original DOS divide by zero error handler EDIT Purpose: To shell into DOS and run the chosen DOS editor file. The file EDITR.BAT must be configured to call your specific DOS editor. The file to be used is previously specified with the word USING Note that if the command is issued from text mode 3 -- the same mode and video page will be returned to on EXIT from DOS. If however the command is issued from a graphics mode and page - return is not necessarily to the same mode or video page. This is because the exit to DOS is into video page 0 - and DOS text will over-write; and leave garbage display on graphics page0. In the demonstration version -- which uses page0 only -- return is always to text mode 3 page 0. In the registered version, an exit to DOS will return to the mode it was initiated from -- and if this was a video mode, to page 1. 4th_86 version 4.01 GLOSSARY page 15 EGAM Purpose: Initialise multi-function graphics card in 640x350 16 color EGA graphics mode -- and clear video buffer. (see also NEGAM CGAM NCGAM NORM NNORM)EGAM ELAPSED Same as TD ELSE see IF ... ELSE .. THEN END see BEGIN ... END END[ (end left bracket) Purpose: Used instead of END in BEGIN .. END construct. Instead of using the TOS as a boolean value like END this uses the TOS to compare against the list between END[ and its matching ] If the TOS matches any of the values in the brackets, then a true condition exists and the loop is exited. example Given the address of text on TOS, search for the first occurrence of an alphanumeric character "A" through "Z". "0" through "9" : FINDAN ( find first occurrence of alphanumeric) BEGIN 1+ ( bump pointer) DUPB@ ( get character) END[ "A" THRU "Z" "0" THRU "9" ] ; ENDIF see IFTRUE ... OTHERWISE ... ENDIF ENDOF see CASE ... ENDCASE .. OF ... ENDOF ENDWHILE see REPEAT ... WHILE ... ENDWHILE 4th_86 version 4.01 GLOSSARY page 16 ERMSG Purpose: Provides a common exit back to the command line interpreter whenever an error is detected. When executed, TOS contains the number of addresses on the stack which point to strings containing parts of an error message. The addresses should be placed on the stack such that the first message to be printed is deeper into the stack. EXEC Purpose: Executes Forth words which may be defined to be "immediate" words or entered interactively through the console in low mode or execute mode. The TOS contains the address of the word to execute. EXIT Purpose: Provides an abnormal exit from a DO .. LOOP or DO .. +LOOP structure. When executed, the flow of control will be transferred to the statement imediately following LOOP or +LOOP. F* F+ F- F-1* F. F/ F< F= F> FABS Floating point operators similar to fixed point single precision FCIRCLE1 Purpose: Draws a filled circle at centre X Y of radius R and color C Input -- X Y R C <= TOS The fill is done by drawing circles of continuously decreasing radius. Note that the card must be initialised first with either EGAM or CGAM. FCIRCLE2 Purpose: Draws a filled circle at centre X Y of radius R and color C Input -- X Y R C <= TOS The fill is done by drawing horizontal lines between the boundaries of the circumference. Note that the card must be initialised first with either EGAM or CGAM. 4th_86 version 4.01 GLOSSARY page 17 FILES Displays a table of file handles and names with indications of those that are open and closed. FILL Purpose: Fills memory starting at the address on TOS for a count of NOS with the value at 3OS. example 11H 20H 8000H FILL FIND Purpose: Tries to find a word in a specified dictionary. Returns either zero (if the word did not exist in the dictionary) or the address of the dictionary entry of the word. The TOS contains the address of the dictionary where the search is to be started, and the NOS contains the address of the string representing the word to find. FLOAD Purpose: To load a Forth source file from disk. Format is FLOAD FILENAME An alternative is " FILENAME" LOAD FLOAT Converts a double precision number to floating point format FMEM Purpose: Similar to FILL, but uses an end address instead of a count value. Fills memory starting at the address on TOS and ending at the adress on NOS with the value at 3OS. example 11H 8020H 8000H FMEM FORGET format FORGET xxxx. Removes the word xxx from dictionary -- along with ALL the words which were defined after it. Code belonging to the forgotten words will be over-written as new words are entered. 4th_86 version 4.01 GLOSSARY page 18 FSAVE Purpose: To allow the current state of the running 4th_86 -- including all new words loaded -- to be saved under a specified name xxxx ==> use FSAVE xxxx ( see also SAVESYS) GCOLR A variable which controls the colour of all characters printed with the word GCOUT ( or digits via .CL ) GCOUT Prints ascii character on TOS in colour determined by value on variable GCOLR. GETCHR Purpose: When executed the TOS contains the next character entered at the console. GETCLI Purpose: Returns the tail of the command line that invoked a 4th_86 program. The TOS contains the address of a 128 byte buffer which will receive the command line. When GETCLI is executed, the command line will be moved into the buffer with the first byte containing the length of the text read from the command line. GETLIN Purpose: Returns a line of text entered at the console. The TOS contains the address of the buffer which should receive the text with the first byte of the buffer containing the maximum length of the string to be collected. When GETLIN is executed, the second byte of the buffer will contain the actual number of bytes read from the console with the text beginning at the third byte of the buffer. GETLOC Purpose: Fetch to the TOS the address of the next location available for entering code into the current definition being defined. GETMODE Purpose: Return on TOS the active display page, and on NOS the number of columns (high byte) and the display mode (low byte) 4th_86 version 4.01 GLOSSARY page 19 GETSTS Purpose: When executed the TOS contains a 1 if a character was detected at the console, or a zero if no chartacter was detected. GETXY Purpose: To read the cursor location x,y GOTOXY Purpose: To specify the cursor location. : FRED 11 12 gotoxy " test" ." ; will print the word 'test' at the [ decimal ] x,y co-ordinates 11,12 GTDFA Purpose: Searches the current dictionary for the word following GTDFA. If found, the definition address is returned to TOS. GVAL (get numeric value) Purpose: Evaluates a character string as a numeric string and converts it into a binary number. The TOS on entry is the address of the character string. On exit, the TOS is a flag: zero - returned value is single precision one - returned value is double precision The NOS is the low order two bytes of the double precision, or floating point value, and the 3OS is the high order two bytes. If the value is single precision as denoted by TOS, then 3OS must be DROPped. HEAD! Purpose: Stores a word in the definition currently being defined. The word on TOS is stored at the address in HEAD. The contents of HEAD are then incremented by two bytes. HEADB! Purpose: Identical to HEAD! but stores a byte value instead of a word value, and only increments HEAD by one. HELP Loads the file TUTORIAL.TXT [ into high memory ] as default, and initiates a colored split-screen window tutorial. See also TUTLOAD 4th_86 version 4.01 GLOSSARY page 20 HLINE Purpose: Draws a horizontal line of specified color. The format is X1 X2 Y C DLINE where X1,Y and X2,Y are the end co-ordinates and C is the color I Innermost loop variable in DO ... LOOP construct IF .. ELSE .. THEN Purpose: Provides conditional execution of the code between IF and ELSE or ELSE and THEN. IFTRUE .. OTHERWISE .. ENDIF Purpose: A construct for conditionally ignoring segmentgs of the input stream. It is an immediate definition and is executed when encountered, even in high mode. IFTRUE ( evaluate the TOS) .... ( execute code if TOS is true (non zero)) OTHERWISE .... ( execute code if TOS is false (zero)) ENDIF IF[ Purpose: Used instead of IF in IF .. THEN or IF .. ELSE .. THEN constructs. Similar in concept to END[ and OF[ ILOAD Purpose: To allow a system image saved with ISAVE to be reloaded for further work to be done. IMMEDIATE Purpose: If the word being defined should not be compiled into a definition, but executed whenever detected, then the word IMMEDIATE should be used after the definition terminator ( see ASM ) 4th_86 version 4.01 GLOSSARY page 21 INSRT Purpose: Removes the TOS, called n, and removes the NOS, called x. The resultant stack contains two less stack elements. x is inserted into the stack indexed by n. EXAMPLES 1 2 3 4 5 1 => 1 2 3 4 5 1 2 3 4 5 2 => 1 2 3 5 4 1 2 3 4 5 3 => 1 2 5 3 4 1 2 3 4 5 4 => 1 5 2 3 4 NOTE THAT 1 insrt => nop => 1 xtrct 2 insrt => swap => 2 xtrct INT3 Provided 4th_86 has been entered from within a debugger shell [ for example by typing DEBUG 4TH86DEM.COM and then typing G at the DEBUG.COM prompt ]; INT3 will exit from 4TH_86 into the debugger that was used. To return to 4th_86 again -- make sure the CS: and DS: segment values have not been altered -- and then start operation at offset 200H [ the address of THREAD ]. The relevant DEBUG.COM command is G=200 4th_86 contains enough FORTH debugging facilities to make the use of a DOS debugger shell un-necessary. It can however be useful for stepping through assembly code -- or examining memory over a range of segments. Note also that unless screen-swapping is implemented; the original 4th_86 screen display will be lost as you use DEBUG.COM. INTEGER Purpose: To convert a floating point number to a double precision integer value. ISAVE Purpose: To allow the current state of a partially meta-compiled system to be saved under a specified name xxxx ==> use FSAVE xxxx J Innermost level plus one loop variable in DO ... LOOP construct 4th_86 version 4.01 GLOSSARY page 22 LINK Purpose: replaces one definition with another -- provided both definitions are already existent. example LINK EGAM CGAM will cause all references to EGAM to instead use CGAM. See UNLINK LOAD An alternative to FLOAD. Whereas we would usually say FLOAD filename It is possible to achieve the same result by typing " filename" LOAD LUM A system variable which keeps track of a pointer to the data storage area. As words like BLOCK and CONST are used, memory storage is allocated automatically and the pointer stored in LUM decreases. MON1 Purpose: A call is made to the operating system and no value is returned. The TOS contains the function code and NOS contains any address requirted by the function. MON2 Purpose: A call is made to the operating system and a value is returned on TOS. The stack values on entry are as for MON1 MOVE (data move) Purpose: Move the number of bytes on the TOS to the address on NOS from the address on 3OS NCGAM Purpose: Initialise multi-function graphics card in 640x200 2 color CGA graphics mode -- but do NOT clear video buffer. (see also NEGAM CGAM EGAM NORM NNORM) 4th_86 version 4.01 GLOSSARY page 23 NEGAM Purpose: Initialise multi-function graphics card in 640x350 16 color EGA graphics mode -- but do NOT clear video buffer. (see also EGAM CGAM NCGAM NORM NNORM) NORM Purpose: Initialise multi-function graphics card in 80x25 color text mode -- and clear video buffer. (see also NEGAM CGAM NCGAM NORM NNORM) NNORM Purpose: Initialise multi-function graphics card in 80x25 color text mode -- but do NOT clear video buffer. (see also NEGAM CGAM NCGAM NORM NNORM) NUMBER Purpose: Evaluates a numeric string found in the input stream as a binary number and stores it into the current definition. The number may be eithert single or double precision. OMIT Purpose: To remove unwanted words from the dictionary - either for security - or to save space. Normally a file called OMITFILE is prepared containing a full list of all the words to be omitted. The code itself is not removed -- nor any threading from other WORDS to the code. Only the dictionary entry is removed. The gap created is closed up by moving the remaining dictionary entries up. OPEN Purpose: Opens a file for either input or output. The TOS contains a 1 for input or a 2 for output. The NOS contains the address of the ASCIIZ filename including any DOS paths, which is to be opened. If the file is opened for output, no data can be written to it. If the file is opened for output, any previous file will be deleted and a new file opened. PAGE0 Switches video display to page 0 of current mode. Will work in both text mode 3 and graphics modes 4 or 10, Note that mode must be set first with one of NORM, EGAM, or CGAM. The Demonstration 4th_86 is configured to work entirely in page0 as a default. 4th_86 version 4.01 GLOSSARY page 24 PAGE1 Switches video display to page 1 of current mode. Will work in both text mode 3 and graphics modes 4 or 10, Note that mode must be set first with one of NORM, EGAM, or CGAM. The Demonstration 4th_86 is configured to work entirely in page0 as a default. The command PAGE1 will have no effect. PAT Purpose: Allows one word in a definition to be changed to another word. The format is address PAT word where address is the patch address, and word is the dictionary name of the word to store at address. PATCH Purpose: Alters a constant value in the definitions. PATCH uses the TOS as the value to patch at the word which follows PATCH example suppose the constant LENGTH was defined with a value of 100, and later a value of 200 was needed. 200 PATCH LENGTH will do this PDICT Purpose: The dictionary entry of a single word is displayed example PDICT DUP will display the entry for DUP PI A constant which puts the floating point value of PI on TOS. PI/2 A constant which puts the floating point value of PI/2 on TOS. 4th_86 version 4.01 GLOSSARY page 25 PICK Purpose: Copy the TOSth element of the stack to TOS. The TOS is not counted as part of the stack. examples (all values in hex) 43 55 12 3e 4 => 43 55 12 3e 43 43 55 12 3e 3 => 43 55 12 3e 55 43 55 12 3e 2 => 43 55 12 3e 12 43 55 12 3e 1 => 43 55 12 3e 3e 1 PICK => DUP 2 PICK => OVER POKE Purpose: Move the NOS into the TOSth place. The TOS and NOS are not included in the poke count examples (all values in hex) 43 55 12 3e 3 => 3e 55 1 43 55 12 3e 2 => 43 3e 12 43 55 12 3e 1 => 43 55 3e 43 55 12 3e 0 => 43 55 12 PRINTLOAD Purpose: Controls whether a file being FLOADed is printed at the console or not OFF PRINTLOAD -- don't show file ON PRINTLOAD -- show file as it loads PRINTLOC Purpose: Controls whether a file being FLOADed has the compile location of each line displayed on the console. R>D Purpose: to convert radians to degrees. Radians must be given as a floating point number. READ Purpose: Inputs data sequentially from a previously opened file. The TOS contains the file handle number of the already opened file to read from. The NOS contains the address of the buffer to read the data into. The 3OS contains the maximum number of bytes to read. When the input data has been moved into the buffer, or when an error occurs, then the TOS contains an error code and the NOS contains the actual number of bytes read into the buffer. 4th_86 version 4.01 GLOSSARY page 26 RECROSS Purpose: Allows cross-compile mode to be re-entered after it has been left by using UNCROSS. RECURSE Purpose: Allows a word being defined to thread back to its own definition. : SERIES 5 > if dup . 1- recurse else drop then ; The command 123 SERIES will print the numbers from 123 down through 6 Note that the following will not work : SERIES 5 > if dup . 1- recurse then drop ; because EVERY recursive execution of SERIES results in DROP being executed -- producing stack underflow. We only require DROP executed once. REDEFINE Purpose: Normally when a definition is created that has the same name as another definition, 4th_86 prompts with a warning message and queries for continuing or aborting. This feature is disabled by the command ON REDEFINE and is restored by OFF REDEFINE REDIT Purpose: Equivalent to sequence EDIT RELOAD ; RELOAD purpose: Same function as FLOAD -- but the name of the file to be FLOADed does not have to be specified. It is the same name which has previously been defined by USING -- ie the same as the name used by EDIT and REDIT. REPEAT .. WHILE .. ENDWHILE Purpose: Provides loop control over the code between REPEAT and ENDWHILE. The code following the ENDWHILE is executed when the WHILE is executed and the TOS is false, otherwise the code between the REPEAT .. ENDWHILE will be executed. The construct is the same as the BEGIN .. END structure except that the exit test is made at the top of the loop instead of the bottom of the loop. 4th_86 version 4.01 GLOSSARY page 27 RETURN Purpose: Provides an immediate exit from a high level definition. It can be used anywhere in a word except within a DO .. LOOP construct. When executed it is similar to encountering the word ; SAVESYS Purpose: To allow the current state of the running 4th_86 -- including all new words loaded -- to be saved under the name 4th_86.COM. (see also FSAVE) No parameters needed --- just type SAVESYS at any time. Any existing 4th_86.COM will be over-written. SECDELAY Causes a time delay of xx seconds where xx is the number on TOS. As the delay progresses a countdown is displayed on screen. SHL8 Purpose: Move the low byte of TOS to the high byte SHR8 Purpose: Move the high byte of TOS to the low byte SINGLE Purpose: To convert a double precision number to single precision. SIZE Purpose: Returns on TOS the number of bytes in the definition of the word which follows SIZE STATUS Purpose: Provides the user information concerning the space available in the dictionary and the definition tables. If in cross mode, the code and data start and stop addresses are also displayed 4th_86 version 4.01 GLOSSARY page 28 STRCAT Purpose: to concatenate two strings. The format is Addr1 Addr2 STRCAT The string at address2 will be added to the end of the string at address1, and the concatenated result stored at addr1 NOTE - the allocated space for string1 must be great enough to accomodate the concatenated result. If in doubt -- copy string 1 to a larger buffer area. For example - if we define data[ " This is " " " ] st1 data[ " a test " ] st2 Then ST1 ST2 STRCAT ST1 ." will print " This is a test". whereas data[ " This is " ] st1 data[ " a test " ] st2 requires data[ " " ] st3 ST! ST3 $! ST3 ST2 STRCAT ST3 ." ST1 ST3 $! ST3 ST2 STRCAT ST3 ." STRCMP Purpose: to compare two strings for a specified number of bytes. Returns 0 for mis-match and 1 for match The format is Addr1 Addr2 Count STRCMP Note --- : FRED " abcdef" " abcde" 3 STRCMP ; will give a mis-match because the first byte of each string is the string-length byte. String one is 6 bytes long whereas string 2 is 5 bytes. : FRED " abcdef" 1+ " abcde" 1+ 3 STRCMP ; will step over the count byte, and give a match. STRING SWAP SYNONYM 4th_86 version 4.01 GLOSSARY page 29 SYS Purpose: Causes the user to shell out to DOS. Return to 4th_86 is achieved by typing EXIT (not a Forth word -- a DOS command) Note that if the command is issued from text mode 3 -- the same mode and video page will be returned to on EXIT from DOS. If however the command is issued from a graphics mode and page - return is not necessarily to the same mode or video page. This is because the exit to DOS is into video page 0 - and DOS text will over-write; and leave garbage display on graphics page0. In the demonstration version -- which uses page0 only -- return is always to text mode 3 page 0. In the registered version, an exit to DOS will return to the mode it was initiated from -- and if this was a video mode, to page 1. SYSCLOSE Purpose: Closes a file. The TOS contains the file handle number of the already opened file to be closed, or zero if all files should be closed. SYSOPEN Purpose: Opens a file for either input or output. The TOS contains the access code (1=input 2=output) and the NOS contains the address of the filename which should be opened. Upon exit, the TOS contains the DOS file handle number SYSRBYTE Purpose: Writes one byte to a file. The TOS contains the file handle number of the already opened file to be written to. The NOS contains the byte to be written. SYSREAD Purpose: Reads a block from a file to a buffer. The TOS contains the file handle number of the already opened file to be read from. The NOS contains the address of the buffer to read into. The 3OS contains the number of bytes to read. Upon exit from SYSREAD the TOS contains the actual number of bytes read. SYSWBYTE Purpose: Writes one byte to a file. The TOS contains the file handle number of the already opened file to be written to. The NOS contains the byte to be written. 4th_86 version 4.01 GLOSSARY page 30 SYSWRITE Purpose: Writes a block from a buffer to a file. The TOS contains the file handle number of the already opened file to be written into. The NOS contains the address of the buffer to write from. The 3OS contains the number of bytes to write. TAB TAG TCOLON TD (time and delay) Purpose: displays the time in hours, minutes, seconds, tenths. Also displays the time elapsed since the previous reference to TD TDLOCK THEN see IF .. ELSE .. THEN THREAD TIME Same as TM TM (time) Purpose: displays the time in hours, minutes, seconds, tenths. TRACE TRACEL TRACEOFF TUTLOAD TYME Returns the hours minutes and seconds as parameters on the stack 4th_86 version 4.01 GLOSSARY page 31 TYPE (type file) Purpose: To display on the screen the contents of a disk text file. The format is TYPE FILENAME or TYPE B:\FORTH\FILENAME The current drive can be changed with A: --- D: U> UNCROSS UNLINK Purpose: Removes the latest patch established with LINK. If more than one pair of words have been LINKed, only the latest one can be UNLINKed. The others are un-recoverable. UNPAT UNSPLIT USING Purpose: Defines the file name to be subsequently used by the words EDIT REDIT RELOAD. Format USING filename VAL VLINE Purpose: Draws a vertical line of specified color. The format is X Y1 Y2 C HLINE where X,Y1 and X,Y2 are the end co-ordinates and C is the color WORD Purpose: Fetches a word from the input stream and stores it in ATOM, returning the address of ATOM on TOS. A word is defined in the input stream as ANY sequence of ASCII printable characters delineated by at least one space or blank. 4th_86 version 4.01 GLOSSARY page 32 WRITE Purpose: Outputs data sequentially to a previously opened file. The TOS contains the file handle number of the already opened file to write to. The NOS contains the address of the buffer to write the data from. The 3OS contains the number of bytes to write. When the input data has been moved into the buffer, or when an error occurs, then the TOS contains an error code. XTRCT Purpose: Removes the TOS called n and extracts (moves) the stack element indexed by n to the TOS example 1 2 3 4 5 1 => 1 2 3 4 5 1 2 3 4 5 2 => 1 2 3 5 4 1 2 3 4 5 3 => 1 2 4 5 3 1 2 3 4 5 4 => 1 3 4 5 2 1 2 3 4 5 5 => 2 3 4 5 1 [COMPILE] Purpose: Stores the definition address of a word declared to be immediate by the word IMMEDIATE into the current definition. Format [COMPILE] xxxxx where xxxxx is the word [[ Purpose: Toggles from execute mode to compile mode ]] | ( 7C Hex ascii ) Purpose: used before a label in CODE definitions. │ ( graphics character 83 Hex ) Purpose: Can be used in 4th_86 source files which are FLOADed as a comment character. It is ignored by 4th_86 ( actually converted to a space 20 Hex.) The intended application is at the left margin to format the display of IF │ IF │ │ │ ELSE │ │ │ THEN │ THEN