This file describes the functionality of release 1.0 of IPC forth. Running Rdforth --------------- Usage: "rdforth first_screen_number last_screen_number [screen_file_name]" Rdforth reads the range of screens starting at 'first_screen_number' to 'last_screen_number' from a forth data file, stripping trailing blanks from each line and writing the resulting text on standard out. If the 'screen_file_name' is present, then it is used as the file name. If it is not present then 'forth.data' is used as the file name. Running Wrforth --------------- Usage: "wrforth first_screen_number last_screen_number [screen_file_name]" Wrforth reads text from standard in and writes the text to the range of screens starting at 'first_screen_number' to 'last_screen_number' in a forth data file. If the 'screen_file_name' is present, then it is used as the forth data file name. If it is not present then 'forth.data' is used as the forth data file name. Running IPC Forth ----------------- Usage: "forth [-D number_of_disk_buffers] [-d dictionary_size] [-f screen_file_name] [-p printer_file_name] [-s string_stack_size] [-t terminal_input_buffer_size] [-u number_of_user_variables]" IPC forth is normally invoked by just "forth". If desired, one or more of the following options may be included on the invocation line (in any order): option comment -------------------------------- --------------------------- -D number_of_disk_buffers default number is 3 -d dictionary_size default size is 20 k-bytes -f screen_file_name default is "forth.data" -p printer_file_name default is "/dev/lp" -s string_stack_size default size is 1000 bytes -t terminal_input_buffer_size default size is 260 bytes -u number_of_user_variables default number is 31 IPC forth will display a summary of the above if invoked with any confusing (to IPC forth) invocation. To exit from IPC forth, use the 'Stop' key. General Comments About IPC Forth -------------------------------- This version of forth is derived in part from the fig-FORTH model (release 1, with compiler security and variable length names) provided by the: Forth Interest Group P.O. Box 1105 San Carlos, CA. 94070 Further distribution must include the above notice. The computation stack, numbers, and addresses are 32 bits wide. Double numbers are 64 bits wide. 8-bit numbers or characters are still 8 bits wide. The words 'w@', 'w!' and 'w,' are provided to do 16-bit operations if they are necessary. The 68000 requires fetches of 16 or 32 bits to be done from an even address. This requires that all data structures be padded if necessary to an even number of bytes. The words 'even' and '?align' may be useful. All pre-defined word names are in lower case. The hexadecimal digits 'A' through 'F' are still in upper case. New word names may be in upper or lower case as desired; IPC forth does not do any case folding. The memory areas for the dictionary (and computation stack), the terminal input buffer, the string stack, and the disk buffers are not guarenteed to be contiguous or in any particular order. fig-FORTH words missing from IPC forth 1.0 ------------------------------------------ +- not needed because multiply and divide are machine code +origin the boot-up parameters are now settable from 'C' ;code implemented in the 68000 assembler (68kasm) cold not implemented; stop and restart forth d+- not needed because multiply and divide are machine code dlist not implemented; see 'vlist' dr0 not implemented dr1 not implemented enclose not implemented; see '(skip)' and '(enclose)' mon not implemented; not a word move not implemented; see 'cmove' next implemented in the 68000 assembler (68kasm) pop not implemented; not a word push not implemented; not a word put not implemented; not a word task not defined; can be defined if desired by the user width not implemented; width is always 31 Words in IPC forth 1.0 ---------------------- ! n addr --- Store 32 bits of 'n' at 'address'. !csp --- Save the stack position in the variable 'csp'. Used as part of the compiler security. # d1 --- d2 Generate from a double number 'd1', the next ascii character which is placed in an output string. Result 'd2' is the quotient after division by base, and is maintained for further processing. Used between '<#' and '#>'. See '#s'. #> d --- addr count Terminates numeric output conversion by dropping 'd', leaving the text address and character count suitable for 'type'. #s d1 --- d2 Generates ascii text in the text output buffer, by the use of '#', until a zero double number 'd2' results. Used between '<#' and "#>'. " --- p If compiling, emplace an in-line string to be moved to the top of the string stack at execution time. If not compiling, put the following string until the next '"' onto the top of the string stack. $. --- Output the top string on the string stack, removing it from the string stack. $.s --- Output non-destructively all of the strings on the string stack. $@ addr --- Fetch the string at 'addr' to the top of the string stack. $sp --- addr Leave the address of the variable that contains the string stack pointer. $sp! --- Empty the string stack. $sp@ --- string_stack_pointer Leave the contents of the string stack pointer on the computation stack. $stack_empty? --- Output an error message if the string stack is empty. $stack_end --- string_stack_ending_address Leave the ending address of the string stack on the computation stack. $stack_size --- string_stack_size Leave the size of the string stack on the computation stack. $stack_start --- string_stack_starting_address Leave the starting address of the string stack on the computation stack. ' --- addr p Used in the form: ' nnnn Leaves the parameter field address of dictionary word 'nnnn'. As a compiler directive, executes in a colon-definition to compile the address of a literal. If the word is not found after a search of the 'context' and 'current' vocabularies, an appropriate error message is given. 'abort --- addr Leaves the address of the variable that initially contains the address of the forth 'abort' routine. By storing the CFA of a user defined word here, the user will get control any time '(abort)' is called (such as when 'warning' has a value of -1). 'number --- addr Leaves the address of the variable that contains the address of the forth number parsing routine. It is initialized to the CFA of '[number]'. This may someday be useful for adding floating point numbers to the IPC forth system. ( --- p Used in the form: ( cccc) Ignore a comment that will be delimited by a right parenthesis on the same line. May occur during execution or in a colon-definition. A blank after the leading parenthesis is required. (Will also handle a zero-length comment correctly) (") --- The run-time procedure compiled by '"' which moves the following in-line (null-terminated) string to the top of the string stack. (.") --- The run-time procedure compiled by '."' which transmits the following in-line text to the selected output device. ($drop) --- Drop the top string from the string stack with no error checking. (+loop) n --- The run-time procedure compiled by '+loop' which increments the loop index by 'n' and tests for loop completion. (;code) --- The run-time procedure, compiled by ';code', that rewrites the code field of the most recently defined word to point to the following machine code sequence. (abort) Executes the word whose code field address is in ''abort' after an error when the variable 'warning' is -1. This word normally executes 'abort', but may be altered (with care) to a user's alternative procedure. See ''abort'. (creat) path mode --- error_code Attempts to create the file named by the path name pointed to by 'path' using the parameter 'mode'. This is an IPC OS tie-in word. The error code is the value returned by the HP-UX 'creat' call. (do) limit index --- The run-time procedure compiled by 'do' which moves the loop control parameters to the return stack. (enclose) addr1 c --- addr1 n1 n2 From the text address 'addr1' and a delimiting character 'c' determines the byte offset to the first delimiter 'n1', and the byte offset to the first character not included 'n2'. This word will not process past an ascii 'null', treating it as an unconditional delimiter. (find) addr1 addr2 --- pfa b tf (ok) addr1 addr2 --- ff (bad) Searches the dictionary starting at the name field address 'addr2', matching to the text at 'addr1'. Returns the parameter field address, the length byte of the name field, and a boolean 'true' for a good match. If no match is found, only a boolean 'false' is left. (line) n1 n2 --- addr count Convert the line number 'n1' and the screen 'n2' to the disk buffer address containing the data. A count of 64 indicates the full line text length. (loop) --- The run-time procedure compiled by 'loop' which increments the loop index and tests for loop completion. (number) d1 addr1 --- d2 addr2 Convert the ascii text beginning at 'addr1'+1 with regard to the current numeric base. The new value is accumulated into double number 'd1', being left as 'd2'. 'Addr2' is the address of the first unconvertable digit. Used by 'number'. (open) path oflag mode --- error_code Attempts to open the file named by the path name pointed to by 'path' using the parameters 'oflag' and 'mode' (both of which must always be provided, even if they are not used). This is an IPC OS tie-in word. The error code is the value returned by the HP-UX 'open' call. (skip) addr1 c --- addr1 n From the text address 'addr1' and a delimiting character 'c', determines the byte offset to the first non-delimiter character 'n'. This word will not work reliably if 'c' is an ascii 'null' (if c has a value of 0). (unlink) path --- error_code Attempts to unlink the file named by the path name pointed to by 'path'. This is an IPC OS tie-in word. The error code is the value returned by the HP-UX 'unlink' call. (word) c --- Like 'word', but does not ignore leading occurrances of the delimiter character 'c'. * n1 n2 --- prod Leave the signed product of the two signed numbers 'n1' and 'n2' as 'prod'. */ n1 n2 n3 --- n4 Leave the ratio 'n4 = n1*n2/n3' where all are signed numbers. Retention of an intermediate 63 bit product permits greater accuracy than would be available with the sequence: n1 n2 * n3 / */mod n1 n2 n3 --- n4 n5 Leave the quotient 'n5' and the remainder 'n4' of the operation 'n1*n2/n3'. A 63 bit intermediate product is used as for '*/'. + n1 n2 --- sum Leave the sum of 'n1' and 'n2'. +! n addr --- Add 'n' to the value at address 'addr'. +buf addr1 --- addr2 f Advance the disk buffer address 'addr1' to the address of the next buffer 'addr2'. Boolean 'f' is false when 'addr2' is the buffer presently pointed to by the variable 'prev'. +loop n1 --- (run-time) p addr n2 --- (compile) Used in a colon-definition in the form: do ... n1 +loop At run-time, '+loop' selectively controls branching back to the corresponding 'do' based on 'n1', the loop index, and the loop limit. The signed increment 'n1' is added to the index and the total compared to the limit. The branch back to 'do' occurs until the new index is equal to or greater than the limit (n1>0), or until the new index is equal to or less than the limit (n1<0). Upon exiting the loop, the parameters are discarded and execution continues ahead. At compile time, '+loop' compiles the run-time word '(+loop)' and the branch offset computed from 'here' to the address left on the stack by 'do'. 'N2' is used for compile time error checking. , n --- Store 'n' into the next available dictionary memory cell, advancing the dictionary pointer. - n1 n2 --- diff Leave the difference of 'n1' minus 'n2' as 'diff'. --- --- p This word is provided so that files created by the 'rdforth' program can be read in by the 'inf' word (see 'inf'). It does nothing. --> --- p Continue interpretation with the next disk screen. -dup n1 --- n1 (if zero) n1 --- n1 n1 (if non-zero) Reproduce 'n1' only if it is non-zero. This is usually used to copy a value just before 'if', to eliminate the need for an 'else' part to drop it. -find --- pfa b tf (found) --- ff (not found) Accepts the next text input word (delimited by blanks) in the input stream to 'here', and searches the 'context' and 'current' vocabularies for a matching entry. If found, the dictionary entry's parameter field address, its length byte, and a boolean true is left. Otherwise, only a boolean false is left. -move addr n1 --- Moves 'c/l' characters from 'addr' to line 'n1' in the current screen. -trailing addr n1 --- addr n2 Adjusts the character count 'n1' of a text string beginning at 'addr' to suppress the output of trailing blanks. I. e. the characters at 'addr'+'n1' to 'addr'+'n2' are blanks. . n --- Print a number from a signed 32 bit two's complement value, converted according to the numeric base. A trailing blank follows. ." --- p Used in the form: ." cccc" Compiles an in-line string 'cccc' (delimited by the trailing '"') with an execution procedure to transmit the text to the selected output device. If executed outside a definition, '."' will immediately print the text until the final '"'. The maximum number of characters is 250. .line line scr --- Print on the terminal device, a line of text from the disk by its line and screen number. Trailing blanks are suppressed. .r n1 n2 --- Print the number 'n1' right aligned in a field whose width is 'n2'. No following blank is printed. .s --- Non-destructively display all of the numbers on the stack. / n1 n2 --- quot Leave the signed quotient of 'n1' divided by 'n2'. /mod n1 n2 --- rem quot Leave the remainder and signed quotient of 'n1' divided by 'n2'. The remainder has the sign of the dividend. 0 --- 0 Leave the constant 0 on the stack. 0< n --- f Leave a true flag if the number 'n' is less than zero (negative), otherwise leave a false flag. 0= n --- f Leave a true flag if the number 'n' is equal to zero, otherwise leave a false flag. 0branch f --- The run-time procedure to conditionally branch. If 'f' is false (zero), the following in-line parameter is added to the interpretive pointer to branch ahead or back. Compiled by 'if', 'until', and 'while'. 1 --- 1 Leave the constant 1 on the stack. 1+ n1 --- n2 Leave the result of adding 1 to 'n1' in 'n2'. 2 --- 2 Leave the constant 2 on the stack. 2+ n1 --- n2 Leave the result of adding 2 to 'n1' in 'n2'. 3 --- 3 Leave the constant 3 on the stack. 4 --- 4 Leave the constant 4 on the stack. 4+ n1 --- n2 Leave the result of adding 4 to 'n1' in 'n2'. : --- p Used in the form called a colon-definition: : cccc ... ; Creates a dictionary entry defining 'cccc' as equivalent to the following sequence of forth word definitions until the next ';' or ';code'. The compiling process is done by the text interpreter as long as the variable 'state' is non-zero. Other details are that the 'context' vocabulary is set to the 'current' vocabulary and that words with the precedence bit are executed rather than being compiled. In this document, a word with the precedent bit set is indicated by a 'p' near the right margin. :: --- Defines a nameless word that is executed once and discarded. It is handy for loops and conditionals which can't ordinarily be done from the keyboard. For example: :: 100 0 do i . loop ; ; --- p Terminate a colon-definition and stop further compilation. Compiles the run-time routine ';s'. See ':'. ;s --- Stops interpretation of a screen. ';s' is also the run-time word compiled at the end of a colon-definition which returns execution to the calling procedure. < n1 n2 --- f Leave a true flag if 'n1' is less than 'n2'; otherwise leave a false flag. <# Setup for pictured numeric output formatting using the words '#', '#s', and 'sign'. The conversion is done on a double number producing text at PAD. << n1 --- n2 Leaves the result of doing a logical left shift (by one) on 'n1' as 'n2'. ... ; Each time 'cccc' is executed, '' part for 'nnnn'. When 'nnnn' is later executed, it has the address of its parameter area on the stack and executes the words after the 'does>' in 'cccc'. '' allow runtime procedures to be written in high-level code rather than in assembler code. = n1 n2 --- f Leave a true flag if 'n1' equals 'n2'; otherwise leave a false flag. > n1 n2 --- f Leave a true flag if 'n1' is greater than 'n2'; otherwise leave a false flag. >> n1 --- n2 Leave the result of doing a logical right shift (by one) on 'n1' as 'n2'. >r n --- Remove a number from the computation stack and place as the most accessable on the return stack. Use should be balanced with 'r>' in the same definition. ? addr --- Print the value contained at the address 'addr' in free format according to the current base. ?align --- Allots an extra byte if needed to align a data structure to an even boundary. Typically used after an 'allot' (see 'allot'). ?comp --- (no error) --- in blk (error) Issue an error message if not compiling. ?csp --- (no error) --- in blk (error) Issue an error message if the stack position differs from the value saved in the variable 'csp'. ?error f n --- (no error) --- in blk (error) Issue error message 'n' if the boolean flag 'f' is true. ?exec --- (no error) --- in blk (error) Issue an error message if not executing. ?loading --- (no error) --- in blk (error) Issue an error message if not loading. ?pairs n1 n2 --- (no error) --- in blk (error) Issue an error message if 'n1' does not equal 'n2'. The message indicates that compiled conditionals do not match. ?stack --- (no error) --- in blk (error) Issue an error message if the stack is out of bounds. ?terminal --- f Returns a non-zero flag 'f' if the "Break" or "^C" keys were hit since the last use of '?terminal'. @ addr --- n Leave the 32 bit contents 'n' of address 'addr'. [ p Used in a colon-definition in the form: : xxx [ words ] more ; Suspend compilation. The words after '[' are executed, not compiled. This allows calculation or compilation execeptions before resuming compilation with ']'. See 'literal' and ']'. [compile] p Used in a colon-definition in the form: : xxx [compile] forth ; '[compile]' will force the compilation of an immediate definition, that would otherwise execute during compilation. The above example will select the 'forth' vocabulary when 'xxx' executes, rather than at compile time. [number] addr --- d Convert a character string left at 'addr' with a preceeding count, to a signed double number 'd', using the current numeric base. If a decimal point is encountered in the text, its position will be given in the variable 'dpl', but no other effect occurs. If numeric conversion is not possible, an error message will be given. This word is called 'number' by fig-FORTH, but was changed when 'number' was made redirectable. \ --- p Starts a comment to the end of the line. Works from the keyboard or with text on screens. ] Resume compilation, to the completion of a colon-definition. See '['. a>> n1 --- n2 Leaves the result of doing an arithmetic right shift (by one) on 'n1' as 'n2'. abort Clear the stacks and enter the execution state. Return control to the operator's terminal, printing a message. If the input file descriptor is non-zero, closes the old file descriptor and resets the input file descriptor to 0 (see 'input_fd'). abs n --- u Leave the absolute value of 'n' as 'u'. addr_empty? addr --- Outputs an error message if 'addr' is at or beyond the beginning of the string stack. addr_full? addr --- Outputs an error message if 'addr' is beyond the end of the string stack. after_string addr1 --- addr2 Leaves the address 'addr2' of the first byte after the null-terminated string at 'addr1'. again --- (run-time) addr n --- (compiling) Used in a colon-definition in the form: begin ... again At run-time, 'again' forces execution to return to the corresponding 'begin'. There is no effect on the stack. Execution cannot leave this loop (unless 'r> drop' is executed one level below). At compile time, 'again' compiles 'branch' with an offset from 'here' to 'addr'. 'N' is used for compile-time error checking. allot n --- Add the signed number 'n' to the dictionary pointer 'dp'. May be used to reserve dictionary space. 'N' is in terms of bytes. and n1 n2 --- n3 Leave the bitwise logical and of 'n1' and 'n2' as 'n3'. b/buf --- 1024 This constant leaves the number of bytes per disk buffer, the byte count read from the disk by 'block'. b/scr --- 1 This constant leaves the number of blocks per editing screen. By convention, an editing screen is 1024 bytes organized as 16 lines of 64 characters each. back addr --- Calculate the backward branch offset from 'here' to 'addr' and compile into the next available dictionary memory address. base --- addr A user variable containing the current number base used for input and output conversion. begin --- (run-time) p --- addr n (compiling) Occurs in a colon-definition in the form: begin ... until begin ... again begin ... while ... repeat At run-time, 'begin' marks the start of a sequence that may be repetitively executed. It serves as a return point from the corresponding 'until', 'again', or 'repeat'. When executing 'until', a return to 'begin' will occur if the top of the stack is false; for 'again' and 'repeat' a return to 'begin' always occurs. At compile time 'begin' leaves its return address 'addr' and 'n' for compiler error checking. bl --- c A constant that leaves the ascii value for "blank". blanks addr count --- Fill 'count' bytes beginning at 'addr' with blanks. blk --- addr A user variable containing the block number being interpreted. If zero, input is being taken from the terminal input buffer. block n --- addr Leave the memory address of the block buffer containing block 'n'. If the block is not already in memory, it is transferred from disk to which ever buffer was least recently written. If the block occupying that buffer has been marked as updated, it is rewritten to disk before block 'n' is read into the buffer. See also 'buffer', 'r/w', 'update', and 'flush'. block-read buffer_address block_number --- f Reads 1024 bytes (one block) from the disk file descriptor (see 'disk_fd'). The boolean flag 'f' has a value of false (zero) if no error occurred, and true (one) if an error occurred. block-write buffer_address block_number --- f Writes 1024 bytes (one block) to the disk file descriptor (see 'disk_fd'). The boolean flag 'f' has a value of false (zero) if no error occurred, and true (one) if an error occurred. branch --- The run-time procedure to unconditionally branch. An in-line offset is added to the interpretive pointer to branch ahead or back. 'Branch' is compiled by 'else', 'again', and 'repeat'. buffer n --- addr Obtain the next memory buffer, assigning it to block 'n'. If the contents of the buffer is marked as updated, it is written to the disk. The block is not read from the disk. The address 'addr' left is the first byte within the buffer for data storage. c! b addr --- Store 8 bits of 'b' at 'addr'. c, b --- Store 8 bits of 'b' into the next available dictionary byte, advancing the dictionary pointer. This should be used with caution, since the 68000 requires that 16 or 32 bit quantities must be stored at even addresses. This forces all data structures to be padded to an even number of bytes. c/l --- 64 This constant leaves the number of characters per line in an editing screen. c@ addr --- b Leave the 8 bit contents of memory at 'addr' in the least significant 8 bits of 'b'. The most significant 24 bits of 'b' will be set to 0. cfa pfa --- cfa Convert the parameter field address 'pfa' of a definition to its code field address 'cfa'. clear n1 --- Fills screen 'n1' with blanks. close fildes --- error_code Attempts to close the file descriptor 'fildes'. This is an IPC OS tie-in word. The error code is the value returned by the HP-UX 'close' call. cmove from to count --- Move 'count' bytes beginning at address 'from' to address 'to'. The contents of address 'from' is moved first proceeding toward higher memory. compile --- When the word containing 'compile' executes, the execution address of the word following 'compile' is copied (compiled) into the dictionary. This allows specific compilation situations to be handled in addition to simply compiling an execution address (which the interpreter already does). constant n --- A defining word used in the form: n constant cccc to create word 'cccc', with its parameter field containing 'n'. When 'cccc' is later executed, it will push the value of 'n' to the stack. context --- addr A user variable containing a pointer to the vocabulary within which dictionary searches will first begin. copy n1 n2 --- Copies screen 'n1' to screen 'n2'. count addr1 --- addr2 n Leave the byte address 'addr2' and the byte count 'n' of a message text beginning at address 'addr1'. It is presumed that the first byte at 'addr1' contains the text byte count and the actual text starts with the second byte. Typically 'count' is followed by 'type'. cr --- Transmit a line feed to the selected output device. See 'output_fd'. creat mode --- error_code Attempts to create the file whose path name is the top string on the string stack using 'mode'. The path name is removed from the string stack. This is an IPC OS tie-in word. The error code is the result of the HP-UX 'creat' call. create --- A defining word used in the form: create cccc by such words as 'code' and 'constant' to create a dictionary header for a forth definition. The code field contains the address of the word's parameter field. The new word is created in the 'current' vocabulary. csp --- addr A user variable temporarily storing the stack pointer position, for compilation error checking. current --- addr Leaves the address 'addr' of the variable that contains the vocabulary into which succeeding definitions will be linked. d+ d1 d2 --- dsum Leave the double number sum of two double numbers. d. d --- Print a signed double number from a 64 bit two's complement value 'd'. The high-order 32 bits are most accessable on the stack. Conversion is performed according to the current numeric base. A blank follows. d.r d n --- Print a signed double number 'd' right aligned in a field 'n' characters wide. dabs d --- ud Leave the absolute value 'ud' of the double number 'd'. decimal --- Set the current numeric base to decimal. definitions --- Used in the form: cccc definitions Set the 'current' vocabulary to the 'context' vocabulary. In the example, executing vocabulary name 'cccc' made it the 'context' vocabulary and executing 'definitions' made both 'current' and 'context' specify vocabulary 'cccc'. digit c n1 --- n2 tf (ok) c n1 --- ff (bad) Converts the ascii character 'c' (using base 'n1') to its binary equivalent 'n2', accompanied by a 'true' flag. If the conversion is invalid, leaves only a 'false' flag. disk_fd --- addr Leaves the address of the variable that contains the file descriptor for the file that holds the forth 'blocks' (also called 'screens'). The 'block_read' and 'block_write' words use this file descriptor to read and write 1024-byte blocks. To change the file that forth uses for block storage, open the file and store the resulting file descriptor in 'disk_fd'. dl n1 --- Delete line 'n1' of the current editing screen. Following lines will be moved up. dliteral d --- d (executing) p d --- (compiling) If compiling, compile a stack double number into a literal. Later execution of the definition containing the literal will push it to the stack. If executing, the number will remain on the stack. dminus d1 --- d2 Convert 'd1' to its double number two's complement. do n1 n2 --- (executing) p addr n --- (compiling) Occurs in a colon-definition in the form: do ... loop do ... +loop At run time, 'do' begins a sequence with repetetive execution controlled by a loop limit 'n1' and an index with initial value 'n2'. 'Do' removes these from the stack. Upon reaching 'loop' the index is incremented by one. Until the new index equals or exceeds the limit, execution loops back to just after 'do'; otherwise the loop parameters are discarded and execution continues ahead. Both 'n1' and 'n2' are determined at run-time and may be the result of other operations. Within a loop 'i' will copy the current value of the index to the stack. See 'i', 'loop', '+loop', and 'leave'. When compiling within the colon-definition, 'do' compiles '(do)', leaving the following address 'addr' and 'n' for later error checking. does> --- pfa (run-time) --- (compiling) A word which defines the run-time action within a high-level defining word. 'Does>' alters the code field and first parameter of the new word to execute the sequence of compiled word addresses following 'does>'. Used in combination with '' part executes it begins with the address of the first parameter of the new word on the stack. This allows interpretation using this area or its contents. Typical uses include the forth assembler, multi-dimensional arrays, and compiler generation. done --- Flush any changed screens in the disk buffers and turn on the " ok" prompt (see 'okflag'). dp --- addr A user variable, the dictionary pointer, which contains the address of the next free memory above the dictionary. The value may be read by 'here' and altered by 'allot'. dpl --- addr A user variable containing the number of digits to the right of the decimal point on double integer input. It may also be used to hold the output column location of a decimal point, in user generated formatting. The default value on single number input is -1. drop n --- Drop the number 'n' from the stack. dump starting_address number_of_bytes --- List the address, the byte at that address, and the character representation of the byte at that address starting at 'starting_address' for 'number_of_bytes' bytes. dup n --- n n Duplicate the top value 'n' on the stack. edit n1 --- Turn off the " ok" prompt (see 'okflag') and list screen 'n1'. This word is intended to make editing of screens easier, but a full screen editor now available starting on screen 100 of the "forth.data" file is much easier to use. el n1 --- Fill line 'n1' of the current editing screen with blanks. else --- (run-time) p addr1 n1 --- addr2 n2 (compiling) Occurs within a colon-definition in the form: if ... else ... endif At run-time, 'else' executes after the true part following 'if'. 'Else' forces execution to skip over the following false part and resumes execution after the 'endif'. It has no stack effect. At compile-time 'else' emplaces 'branch' reserving a branch offset, leaving the address 'addr2' and 'n2' for error testing. 'Else' also resolves the pending forward branch from 'if' by calculating the offset from 'addr1' to 'here' and storing at 'addr1'. emit c -- Transmit ascii character 'c' to the selected output device. The variable 'out' is not affected by 'emit'. See 'output_fd'. empty-buffers --- Mark all block buffers as empty. Updated blocks are not written to the disk. end p This is an alias or duplicate definition for 'until'. endif --- (run-time) p addr n --- (compiling) Occurs in a colon-definition in the form: if ... endif if ... else ... endif At run-time, 'endif' serves only as the destination of a forward branch from 'if' or 'else'. It marks the conclusion of the conditional structure. 'Then' is another name for 'endif'. At compile-time, 'endif' computes the forward branch offset from 'addr' to 'here' and stores it at 'addr'. 'N' is used for error tests. erase addr n --- Clear a region of memory to zero from 'addr' over 'n' bytes. errno --- error_number Leave the value of the HP-UX variable 'errno' on the stack. This is an IPC OS tie-in word. error line --- in blk Execute error notification and restart of system. 'Warning' is first examined. If 1, the text of line 'n', relative to screen 4 of the disk file is output. This line number may be positive or negative, and may be beyond just screen 4. If 'warning' is zero, 'n' is just output as a message number. If 'warning' is -1, the definition '(abort)' is executed, which executes the word whose code field address is contained in ''abort'. The user may cautiously modify this execution by altering ''abort'. IPC forth saves the contents of 'in' and 'blk' to assist in determining the location of the error. If the input file descriptor is non-zero, it also closes the old input file descriptor, and resets the input file descriptor to 0 (see 'input_fd'). Final action is the execution of 'quit'. even n1 --- n2 Leaves the next even number 'n2' greater than or equal to 'n1'. execute addr --- Execute the definition whose code field address 'addr' is on the stack. The code field address is also called the compilation address. expect addr count --- Transfer characters from the terminal to address 'addr', until a "return" or the count of characters have been received. One or more nulls are added at the end of the text. false? f1 --- f2 Reverse the sense of conditional flag 'f1' to 'f2'. fence --- addr A user variable containing an address below which 'forget'ing is trapped. To forget below this point the user must alter the contents of 'fence'. fill addr quan b --- Fill memory at address 'addr' with the specified quantity 'quan' of bytes 'b'. first --- addr A constant that leaves the address of the first (lowest) block buffer. fld --- addr A user variable for control of number output field width. Currently unused. flush --- Writes out all disk buffers that are marked as modified. forget --- Executed in the form: forget cccc Deletes the definition named 'cccc' from the dictionary along with all entries physically following it. An error message will occur if the 'current' and 'context' vocabularies are not the same. forth --- p The name of the primary vocabulary. Execution makes 'forth' the 'context' vocabulary. Until additional user vocabularies are defined, new user definitions become part of 'forth'. 'Forth' is immediate, so it will execute during the creation of a colon-definition, to select this vocabulary at compile time. here --- addr Leave the address of the next available dictionary location. hex --- Set the numeric conversion base to sixteen (hexadecimal). hld --- addr A user variable that holds the address of the latest character of text during numeric output conversion. hold c --- Used between '<#' and '#>' to insert an ascii character 'c' into a pictured numeric output string. i --- n Used within a 'do'-'loop' structure to copy the loop index to the stack. id. addr --- Print a definition's name from its name field address. if f --- (run-time) p --- addr n (compiling) Occurs in a colon-definition in the form: if (true-part) ... endif if (true-part) ... else (false-part) ... endif At run-time, 'if' selects execution based on a boolean flag 'f'. If 'f' is true (non-zero), execution continues ahead through the true part. If 'f' is false (zero), execution skips till just after the 'else' to execute the false part. After either part, execution resumes after the 'endif'. 'Else' and its false part are optional; if they are missing, false execution skips to just after the 'endif'. At compile-time 'if' compiles '0branch' and reserves space for an offset at 'addr'. 'Addr' and 'n' are used later for resolution of the offset and error testing. immediate --- Mark the most recently made definition so that when encountered at compile time, it will be executed rather than being compiled. i. e. the prececedent bit in its header is set. this method allows definitions to handle unusual compiling situations, rather than build them into the fundamental compiler. The user may force compilation of an immediate definition by preceding it with '[compile]'. in --- addr A user variable containing the byte offset within the current input text buffer (terminal or disk) from which the next text will be accepted. 'Word' uses and moves the value of 'in'. in_char_addr --- addr Leave the address of the next character in the input stream. index from to --- Print the first line of each screen over the range 'from', 'to'. This is used to view the comment lines of an area of text on disk screens. inf --- (no error) --- in blk (error) Attempt to set the input file descriptor (see 'input_fd') to the file whose path name is the top string on the string stack. The path name is removed from the string stack. If the attempt fails an error message is generated. If the attempt succeeds then input will be taken from the file rather than the keyboard until the end-of-file is reached or until an error occurs. input_fd --- addr Leave the address of the variable that contains the input file descriptor. The input words (such as 'key' and 'expect') read characters from this file descriptor. If a file is opened and the resulting file descriptor is placed in this variable (see 'inf'), then the characters in that file will be used instead of the standard input (a file descriptor of 0). If an error occurs or the read reaches the end of the file, then this variable is set back to 0. interpret The outer text interpreter which sequentially executes or compiles text from the input stream (terminal or disk) depending on 'state'. If the word name cannot be found after a search of 'context' and then 'current' it is converted to a number according to the current base. That also failing, an error message echoing the name with a "?" will be given. Text input will be taken according to the convention for 'word'. If a decimal point is found as part of a number, a double number value will be left. The decimal point has no other purpose than to force this action. See 'number'. ioctl fildes request arg -- error_code Attempt to do an ioctl to the file descriptor 'fildes' with parameters 'request' and 'arg'. This is an IPC OS tie-in word. The error code is the value returned by the HP-UX 'ioctl' call. key --- c Read a key in raw mode. If the read returns without a key and the input file descriptor (see 'input_fd') was non-zero, closes the input file descriptor and sets the input file descriptor to 0 (see 'inf'). If the read returns without a key and the input file_descriptor was zero, terminates IPC forth (this allows IPC forth to be run from a script by redirecting standard in). l --- List the current screen. latest --- addr Leave the name field address of the topmost word in the 'current' vocabulary. leave --- Force termination of a 'do'-'loop' structure at the next opportunity by setting the loop index equal to the current value of the index. The index itself remains unchanged, and execution proceeds normally until 'loop' or '+loop' is encountered. lfa pfa --- lfa Convert the parameter field address of a dictionary definition to its link field address. limit --- addr A constant leaving the address just above the highest memory available for a disk buffer. line ln --- addr Leave the address 'addr' of line 'ln' of the current screen. list n --- Display the ascii text of screen 'n' on the selected output device. 'Scr' contains the screen number during and after this process. lit --- n Within a colon-definition, 'lit' is automatically compiled before each 32 bit literal number encountered in input text. Later execution of 'lit' causes the contents of the next dictionary address to be pushed to the stack. literal n --- p If compiling, then compile the stack value 'n' as a 32 bit literal. This definition is immediate so that it will execute during a colon definition. The intended use is: : xxx [ calculate ] literal ; Compilation is suspended for the compile time calculation of a value. Compilation is resumed and 'literal' compiles this value. load n --- Begin interpretation of screen 'n'. Loading will terminate at the end of the screen or at ';s'. See ';s' and '-->'. loads starting_screen_number number_of_screens --- Load 'number_of_screens' screens starting at 'starting_screen_number'. loop --- (run-time) p addr n --- (compiling) Occurs in a colon-definition in the form: do ... loop At run-time, 'loop' selectively controls branching back to the corresponding 'do' based on the loop index and limit. The loop index is incremented by one and compared to the limit. The branch back to 'do' occurs until the index equals or exceeds the limit; at that time, the parameters are discarded and execution continues ahead. At compile-time, 'loop' compiles '(loop)' and uses 'addr' to calculate an offset to 'do'. 'N' is used for error testing. lseek fildes offset whence --- error_code Attempt to do a fseek to the file descriptor 'fildes' with parameters 'offset' and 'whence'. This is an IPC OS tie-in word. The error code is the value returned by the HP-UX 'lseek' call. m* n1 n2 --- d A mixed magnitude math operation which leaves the double number signed product 'd' of two signed numbers 'n1' and 'n2'. m/ d n1 --- n2 n3 A mixed magnitude math operator which leaves the signed remainder 'n2' and signed quotient 'n3', from a double number dividend 'd' and divisor 'n1'. The remainder takes its sign from the dividend. m/mod ud1 u2 --- u3 ud4 An unsigned mixed magnitude math operation which leaves a double quotient 'ud4' and remainder 'u3', from a double dividend 'ud1' and single divisor 'u2'. max n1 n2 --- max Leave the greater of the two numbers 'n1' and 'n2' as 'max'. mcopy n1 n2 n3 --- Copy 'n1' screens starting at screen 'n2' to the screens starting at 'n3'. message n --- Print on the selected output device the text of line 'n' relative to screen 4 of the "screen" file. 'N' may be positive or negative. 'Message' may be used to print incidental text such as report headers. If 'warning' is zero, the message will simply be printed as a number (The "screen" file is asummed to be unavailable). min n1 n2 --- min Leave the smaller of the two numbers 'n1' and 'n2' as 'min'. minus n1 --- n2 Leave the two's complement of 'n1' as 'n2'. mod n1 n2 --- mod Leave the remainder of 'n1' divided by 'n2' as 'mod', with the same sign as 'n1'. next_screen --- next_screen_number Leave the number of the screen following the one that 'next_screen' is used on. nfa pfa --- nfa Convert the parameter field address of a definition to its name field address. not n1 --- n2 Leave the result of doing a one's complement on 'n1' as 'n2'. number Execute the word whose code field address is stored in ''number'. See ''number'. offset --- addr Leave the address of the variable that contains the offset to disk drives. The variable exists, but should always remain set to 0. okflag --- addr Leave the address of the variable that contains the 'ok' flag. If 'okflag' contains a value of 1 then an " ok" will be output after the interpreter has finished interpreting a line from the input file descriptor (see 'input_fd'). If 'okflag' contains a value of 0 then no prompt will be output. open oflag mode --- error_code Attempt to open the file whose path name is the top string on the string stack using 'oflag' and 'mode'. The path name is removed from the string stack. This is an IPC OS tie-in word. The error code is the result of the 'open' HP-UX call. or n1 n2 --- or Leave the bit-wise logical or of 'n1' and 'n2' as 'or'. out --- addr Leave the address of the variable that contains the offset in the output stream. The variable exists, but is not used. output_fd --- addr Leave the address of the variable that contains the output file descriptor. The output words (such as 'emit', 'cr', and 'type') write characters to this file descriptor. If a file is opened and the resulting file descriptor is placed in this variable, then any characters that would normally be output to the display will instead be written to that file. If an error occurs in one of the output words then this variable is set back to 1 (the standard output file descriptor). over n1 n2 --- n1 n2 n1 Copy the second stack value, placing it as the new top. p n1 --- Put the text following the p until the end of the line into line 'n1' of the current screen. pad --- addr Leave the address of the text output buffer, which is a fixed offset above 'here'. pfa nfa --- pfa Convert the name field address of a compiled definition to its parameter field address. prev --- addr A variable containing the address of the disk buffer most recently referenced. The 'update' command marks this buffer to be later written to disk. printer_fd --- addr Leave the address of the variable that contains the printer file descriptor. To redirect output to the printer, store the file descriptor contained in this variable into the variable 'output_fd'. When output to the display is desired again, store a 1 into the variable 'output_fd'. query --- Input 80 characters of text (or until a "return") from the input file descriptor. Text is positioned at the address contained in 'tib' with 'in' set to zero. quit --- Clear the return stack, stop compilation, and return control to the operator's terminal. No message is given. r --- n Copy the top of the return stack to the computation stack. r# --- addr A user variable which may contain the location of an editing cursor, or other file related function. r/w addr blk f --- The fig-FORTH standard disk read-write linkage. 'Addr' specifies the source or destination block buffer, 'blk' is the sequential number of the referenced block; and 'f' is a flag for write (f=0) or read (f=1). 'R/w' determines the location on mass storage, performs the read/write and performs any error checking. r> --- n Remove the top value from the return stack and leave it on the computation stack. See '>r' and 'r'. r0 --- addr A user variable containing the initial location of the return stack. See 'rp!'. read fildes buf nbyte --- error_code Attempt to do a read from the file descriptor 'fildes' with parameters 'buf' and 'nbyte'. This is an IPC OS tie-in word. The error code is the value returned by the HP-UX 'read' call. repeat --- (run-time) p addr n --- (compiling) Used within a colon-definition in the form: begin ... while ... repeat At run-time, 'repeat' forces an unconditional branch back to just after the corresponding 'begin'. At compile-time, 'repeat' compiles 'branch' and the offset from 'here' to 'addr'. 'N' is used for error checking. rl n1 --- Replace line 'n1' of the current editing screen with the text at 'pad'. room --- Displays the number of bytes of dictionary space left. rot n1 n2 n3 --- n2 n3 n1 Rotate the top three values on the stack, bringing the third to the top. rp! --- A procedure to initialize the return stack pointer from user variable 'r0'. s->d n --- d Sign extend a single number 'n' to form a double number 'd'. s0 --- addr A user variable that contains the initial value for the stack pointer. See 'sp!'. scr --- addr A user variable containing the screen number most recently referenced by 'list'. sign n d --- d Store an ascii "-" sign just before a converted numeric output string in the text output buffer when 'n' is negative. 'N' is discarded, but double number 'd' is maintained. Must be used between '<#' and '#>'. skipleading c --- Skip over leading occurances of the delimiter character 'c' in the input stream. sl n1 --- Spread the text on the current editing screen at line 'n1'. Line 15 of the current editing screen is lost. smudge --- Used during word definition to toggle the "smudge bit" in a definition's name field. This prevents an uncompleted definition from being found during dictionary searches until compiling is completed without error. sp! --- Initialize the stack pointer from 's0'. sp@ --- addr Leave the address of the top of the stack as it was before 'sp@' was executed on the top of the stack. space --- Transmit an ascii blank to the output device. spaces n --- Transmit 'n' ascii blanks to the output device. state --- addr A user variable containing the compilation state. A non-zero value indicates compilation. strlen addr --- addr length Leave the address 'addr' and the length 'length' of the null-terminated text at 'addr'. The length does not include the null. swap n1 n2 --- n2 n1 Exchange the top two values on the stack. text c --- Accept text up to the first occurrence of the character 'c' and move it to 'pad'. then p An alias for 'endif'. tib --- addr A user variable containing the address of the terminal input buffer. toggle addr b --- Complement the contents of 'addr' by the bit pattern 'b'. traverse addr1 n --- addr2 Move across a variable length name field. 'Addr1' is the address of either the length byte or the last letter. If 'n' is 1, the motion is toward high memory; if 'n' is -1, the motion is toward low memory. The 'addr2' resulting is the address of the other end of the name. triad scr --- Display on the selected output device the three screens which include that numbered 'scr', beginning with a screen divisible by three with a remainder of one. Output is suitable for source text records, and includes a reference line at the bottom taken from line 15 of screen 4. type addr count --- Transmit 'count' characters from 'addr' to the output file descriptor (see 'output_fd'). Does not affect the value of 'out'. u* u1 u2 --- ud Leave the unsigned double number product 'ud' of the two unsigned numbers 'u1' and 'u2'. u. u1 --- Print an unsigned 32 bit number, converted according to the current numeric base. A trailing blank follows. u/ ud u1 --- u2 u3 Leave the unsigned remainder 'u2' and the unsigned quotient 'u3' from the unsigned double dividend 'ud' and the unsigned divisor 'u1'. u< u1 u2 --- f Leave a true flag if unsigned number 'u1' is less than unsigned number 'u2'; otherwise leave a false flag. unlink --- error_code Attempt to unlink the file whose path name is the top string on the string stack. The path name is removed from the string stack. This is an IPC OS tie-in word. The error code is the result of the 'unlink' HP-UX call. until f --- (run-time) p addr n --- (compile) Occurs within a colon-definition in the form: begin ... until At run-time, 'until' controls the conditional branch back to the corresponding 'begin'. If 'f' is false, execution returns to just after 'begin'; if true, execution continues ahead. At compile-time, 'until' compiles '(0branch)' and an offset from 'here' to 'addr'. 'N' is used for error tests. update --- Mark the most recently referenced block (pointed to by 'prev') as altered. The block will subsequently be transferred to disk should its buffer be required for storage of a different block. use --- addr A variable containing the address of the block buffer to use next. user n --- A defining word used in the form: n user cccc which creates a user variable 'cccc'. The parameter field of 'cccc' contains 'n' as a fixed offset relative to the start of the user variable area. When 'cccc' is later executed, it places the sum of its offset and the user area base address on the stack as the storage address of that particular variable. variable n --- A defining word used in the form: n variable cccc When 'variable' is executed, it creates the definition 'cccc' with its parameter field initialized to 'n'. When 'cccc' is later executed, the address of its parameter field (containing 'n') is left on the stack, so that a fetch or store may access this location. voc-link --- addr A user variable containing the address of a field in the definition of the most recently created vocabulary. All vocabulary names are linked by these fields to allow control for forgetting through multiple vocabularies. vocabulary --- A defining word used in the form: vocabulary cccc to create a vocabulary definition 'cccc'. Subsequent use of 'cccc' will make it the 'context' vocabulary which is searched first by 'interpret'. The sequence "cccc definitions" will also make 'cccc' the 'current' vocabulary into which new definitions are placed. 'Cccc' is so chained as to include all definitions of the vocabulary in which 'cccc' is itself defined. All vocabularies ultimately chain to 'forth'. By convention, vocabulary names are to be declared 'immediate'. See 'voc-link'. vlist --- List the names of the definitions in the 'context' vocabulary. The "Break" key will terminate the listing. w! n addr --- Store the least significant 16 bits of 'n' at 'addr'. w, n --- Store the least significant 16 bits of 'n' into the next available dictionary word, advancing the dictionary pointer. w@ addr --- n Leave the contents of the word at 'addr' in the least significant 16 bits of 'n'. The rest of 'n' is set to 0. warning --- addr A user variable containing a value controlling messages. If 'warning' is 1 a screen file is assummed to be present, and screen 4 of the screen file is the base location for messages. If 'warning' is 0, it is assummed that no screen file is available, and messages will be presented by number. If 'warning' is -1, '(abort)' is executed. See 'message' and 'error'. while f --- (run-time) p addr1 n1 --- addr1 n1 addr2 n2 (compiling) Occurs in a colon-definition in the form: begin ... while (true-part) ... repeat At run-time, 'while' selects conditional execution based on the boolean flag 'f'. If 'f' is true (non-zero), 'while' continues execution of the true part through to 'repeat', which then branches back to 'begin'. If 'f' is false (zero), execution skips to just after repeat, exiting the structure. At compile time, 'while' emplaces '(0branch)' and leaves 'addr2' of the reserved offset. The stack values will be resolved by 'repeat'. word c --- Read the next text characters from the input stream being interpreted, until a delimiter 'c' is found, storing the packed character string beginning at the dictionary buffer 'here'. 'Word' leaves the character count in the first byte followed by the characters, and ends with two or more blanks. Leading occurances of 'c' are ignored. If 'blk' is zero, input is taken from the terminal input buffer, otherwise from the disk block whose number is stored in 'blk'. See 'blk', 'in'. write fildes buf nbyte --- error_code Attempt to do a write to the file descriptor 'fildes' with parameters 'buf' and 'nbyte'. This is an IPC OS tie-in word. The error code is the value returned by the HP-UX 'write' call. x --- p This is the pseudonym for the dictionary entry for a name of one character of ascii null. It is the execution procedure to terminate interpretation of a line of text from the terminal or within a disk buffer, as both buffers always have a null at the end. xor n1 n2 --- xor Leave the bitwise logical exclusive-or of 'n1' and 'n2' as 'xor'.