Win32Forth

Getting Help

This is a public domain product supported by hobbyists; we're not professional software writers, and this isn't professional software (although we try pretty hard). Always remember the warranty. If you're reporting a problem, be polite, informative and patient. Someone will normally get back to you within a day or two. Self-help will be needed, so read on.

Classes of error

There are several classes of error that you can make in Win32Forth. They are:

Programmer error (sometimes called "stupid mistake"), Win32Forth error message (closely associated with "Programmer error") and Win32Forth system error (rare). Here's some simple help that might help you form tearing your hair out.

Handling errors in Win32Forth

As an extended ANS system, Win32Forth implements the exception wordset (which you are strongly recommended to read, if only to understand the need for errors in the first place) from the ANS specification. These words allow the programmer to trap errors, and to continue execution based on the error value returned.

Commonly, though, the error is unanticipated, and the system has a global error handler that catches errors, prints a default error message and resets the system to allow programmer input. Where possible, Win32Forth tries to use the defined ANS error numbers, but not all errors can be trapped by the system, so many are unused at present. For instance, it's very difficult to trap stack overflow; Win32Forth will simply terminate in this case. Frustrating, but unavoidable. The tables below document the used error numbers.

Suppressing Warnings

Warnings are useful to tell you of potential problems, but on the other hand if you know about the potential problem you may want to suppress them

Redefinition Warnings

The display of these warnings is controlled by the variable WARNING which can be turned on and off with the words ON and OFF.

System Word Warnings

The display of these warnings is controlled by the value SYS-WARNING? which can be set and reset with SYS-WARNING-ON and SYS-WARNING-OFF respectively. The word  \IN-SYSTEM-OK  suppresses the warnings for remainder of the current line and then restores the previous state of SYS-WARNING? even if an error occurs. It DOES NOT make it OK to use system words in a TURNKEYed application.

Stack Change Warnings

These warnings are suppressed with NOSTACK and turned back on with CHECKSTACK or its alias NOSTACK1CHECKSTACK can also be used to suppress the warning for the current line if it's used after values are added to the stack.

Deprecated Word Warnings

The display of these warnings is controlled by the value DPR-WARNING? which can be set and reset with DPR-WARNING-ON and DPR-WARNING-OFF respectively.


Error messages

These announce themselves like so:

Error(n): <name> <text> in file <filename> at line <n>

or

Warning:(n) <name> <text> in file <filename> at line <n>

Errors entered at the console do not have the "in file <filename> at line <n>" text appended; it only appears if the line in error was included from a source file. The source line is marked with one or more carets (^) to indicate the position of the error, or the word in error, and the error or warning message is printed underneath. The examples use <this bold fixed font> to indicate user entered data into the console, and <this normal fixed font> to indicate the output from Win32Forth. Here are a few examples;

: dup 123 ;
  ^^^
Warning(-4100): DUP is redefined ok
: x y ;
    ^
Error(-13): Y is undefined ok

Error Descriptions

Error(-n): <name> text

Summary: A summary of the error or warning above.

Example: The examples use <this bold fixed font> to indicate user entered data into the console, and <this normal fixed font> to indicate the output from Win32Forth.

10 value
        ^
Error(-16): requires a name

Resolution: The resolution (if there is one).


ANS Error Messages

THROW error number Message text
-1 no message
-2 <message from ABORT">
-4 stack underflow
-13 is undefined
-14 is compilation only
-16 requires a name
-22 control structure mismatch
-38 file not found
-45 floating point stack underflow
-58 unmatched interpreted conditionals

Extended System Error Messages

THROW error number Message text
-260 is not a DEFER
-262 is not a VALUE
-270 out of memory
-271 memory allocation failed
-272 memory release failed
-280 create-file failed
-281 read-file failed
-282 write-file failed
-290 is interpretation only
-300 locals defined twice
-301 too many locals
-302 missing }
-310 procedure not found
-311 <Windows error message>
-320 stack changed
-330 can't use EXIT in a method
-331 can't use DOES> in a method
-332 method must end with ;M

Warning Messages

THROW error number Message text
-4100 is redefined
-4101 is a system word in an application word
-4102 is an application word set to a system word
-4103 stack depth increased
-4104 is a deprecated word
-4105 has a hash value that is already recognised by this class."
-4106 is an application word whose runtime is in a system word."

Application and Runtime Error Messages

THROW error number Message text
9998 Windows exception trapped

 


Error(-1): <no message>

Summary: ANS error number. This error number you will never see. It's generated by ABORT (or -1 THROW) and is handled silently by the system.

Resolution: This error needs to be CATCHed if you wish to handle it.


Error(-2): <name> <message from ABORT">

Summary: ANS error number. This error message is generated by ABORT", and the message text is from that.

Example:

: X S" Rubbish File Name" OPEN-FILE ABORT" Rubbish file didn't open!" ;  ok
x
^
Error(-2): X Rubbish file didn't open!

Resolution: These are application errors, not Win32Forth system errors; hopefully, the message text is clear enough so that you can fix the problem. If it's not, then you need to refer to the application's documentation for this error (if it exists) or contact the author if you can't understand or fix the problem yourself.


Error(-4): <name> stack underflow

Summary: ANS error number. The word <name> caused the data stack to underflow; the top of the stack would have pointed to an entry before the start of the stack.

Example:

10 drop drop
        ^^^^
Error(-4): DROP stack underflow

Resolution: Definite programmer error. Best advice is to use the debugger, and watch the stack contents carefully. It may be that the word in the message is OK, just that there weren't enough stack entries for it because of some previous words, or it may be that the word itself declares it consumes x stack entries, but in fact consumes >x.


Error(-13): <name> is undefined

Summary: ANS error number. The word <name> doesn't exist in the current vocabulary search order.

Example:

: x 10 make-csr ;
       ^^^^
Error(-13): MAKE-CSR is undefined

Resolution: Definite programmer error. Have you typed it correctly? Have you checked it exists, but in some vocabulary that's not in the search order? If you're sure you typed it correctly, think the word is something like MAKE but you're not sure, or can't remember if you defined it or not, try these steps.

words mak
----------- HASHED -----------------------------------------------
MAKECURSOR:
----------- FORTH ------------------------------------------------
MAKELONG MAKE-CURSOR MAKEPATHRELATIVETO MAKEABSOLUTEPATH MAKEDEFER
------------------------------------------------------------------
order
Context: FORTH FORTH ROOT
Current: FORTH ok

Words will be defined in the current vocabulary (in this case, FORTH), and will be searched for in the context vocabularies (FORTH and ROOT). Use ONLY ALSO and PREVIOUS with specific vocabularies to modify the search order.


Error(-14): <name> is compilation only

Summary: ANS error number. The word <name> can't be used except in a : colon definition.

Example:

10 0 do i . loop
     ^^
Error(-14): DO is compilation only

Resolution: Definite programmer error. Some words just can't be used while interpreting; they include

IF ELSE THEN ENDIF DO I J K LOOP +LOOP LEAVE UNLOOP BEGIN WHILE REPEAT UNTIL CASE OF ENDOF ENDCASE

and possibly others. Put the words you want to test in a definition, and execute that.

: test 10 0 do i . loop ; ok
test 0 1 2 3 4 5 6 7 8 9 ok

Error(-16): <name> requires a name

Summary: ANS error number. The word <name> is a parsing word; it needs a name to create.

Example:

10 value
        ^
Error(-16): requires a name

Resolution: Definite programmer error. Some words that require a name to create are

CREATE VALUE VARIABLE DEFER VOCABULARY

and possibly others.


Error(-22): <name> control structure mismatch

Summary: ANS error number. The named control structure word is in the wrong place.

Example:

: notright if 10 then 20 else 30 ;
                         ^^^^
Error(-22): ELSE control structure mismatch

Resolution: The example above is a typical example of thinking in C or PASCAL instead of Forth; it's a

<flag> IF <things to do if true> ELSE <things to do if false> THEN

construction. Other control words (like LOOP and ENDCASE without a preceding DO or CASE respectively) cause the same error. Also note that a control structure must be complete in the word in which it's defined. You can't start an IF in one word and have the matching THEN in another. Also see error -320; you might make this mistake;

: notright if dup if 10 else 20 then ;
                                     ^
Error(-320): ; stack changed

There's a missing THEN in the definition; Win32Forth only knows that there's something wrong right at the end, but can't tell what it is, hence the peculiar message. (Reason: W32F uses the data stack as a control flow stack while compiling these words, and as a consequence can't tell that the value is a control value, rather than a regular data value.)


Error(-38): <name> file not found

Summary: ANS error number. For words that expect a filename, the file couldn't be found in the search path.

Example:

fload files2.f
      ^^^^^^^^
Error(-38): files2.f file not found

Resolution: Make sure the file you require is in the search path. The .FPATH command will show you the list of directories that will be searched.

.fpath .;S:\FORTH\CVSVER;SRC;SRC\LIB;RES;DEMOS;SRC\CONSOLE;HTM ok

Paths can be added with the FPATH+ command.


Error(-45): <name> floating point stack underflow

Summary: ANS error number. The word <name> caused the floating point stack to underflow; the top of the floating point stack would have pointed to an entry before the start of the floating point stack.

Example:

10e0 fdrop fdrop
           ^^^^^
Error(-45): FDROP floating point stack underflow

Resolution: Definite programmer error. The problem might be that the base is set to HEX which causes the number to be treated as an integer (e is a valid hexadecimal digit) or double, and thus go on the data stack. Best advice is to use the debugger, and watch the stack contents carefully. It may be that the word in the message is OK, just that there weren't enough stack entries for it because of some previous words, or it may be that the word itself declares it consumes x stack entries, but in fact consumes >x.


Error(-58): <name> Unmatched Interpreted conditionals

Summary: ANS error number. The word <name> caused the interpreter to encounter an interpreted conditional structure which was not concluded before the input stream (including any necessary REFILLs) is exhausted. When the source code is loaded from a file then the error occurs at the end of the last line of the file. When inputting from the command line this error does not occur; instead all input is ignored until the correct ending interpreted conditional is encountered. <name> normally indicates a word that calls EVALUATE, either directly or indirectly. It is possible for this error to only occur on some occassions since different values of the test supplied to [IF] or #IF cause different parts of the input stream to be scanned for the matching conditional(s).

Example:


^
Error(-58): Unmatched Interpreted conditionals!!!  in file C:\PROGRAM FILES\WIN32FORTH\
TEST.F at line 98

Resolution: Definite programmer error. The problem is either a missing [THEN]or #THEN (or their synonyms [ENDIF] or #ENDIF) or the [] and # forms are intermixed (although they perform the same actions #THEN will not match with [IF] or vice versa).


Error(-260): <name> is not a DEFER

Summary: Extended error number. The word IS can only set the value of a DEFERed word.

Example:

0 value z2  ok
' dup is z2
         ^
Error(-260): Z2 is not a DEFER

Resolution: If the name is a VALUE or a 2VALUE , use TO or +TO to set a value.


Error(-262): <name> is not a VALUE

Summary: Extended error number. The word TO or +TO can only set the value of a VALUE word.

Example:

2 constant z2  ok
5 to z2
         ^
Error(-260): Z2 is not a VALUE

Resolution: If the name is a DEFER , use IS to set a value. You cannot TO a CONSTANT or a VARIABLE .


Error(-270): <name> <memory pool> out of memory

Summary: Extended error number. An ALLOT or , has caused the named memory pool to be exhausted.

Example:

200000000 allot
          ^^^^^
Error(-270): ALLOT APP out of memory

Resolution: There is a limit to each of the predefined memory pools. The .FREE word shows the areas and their size;

.free
Section Address       Total      Used      Free
------- --------- --------- --------- ---------
LOCALS  1473C0h       4,096         0     4,096
*PROCS  4135F8h      12,288     4,070     8,218
CODE    401000h      40,960    12,144    28,816
APP     40B000h   1,024,000   188,760   835,240
SYS     505000h     512,000   271,608   240,392
* areas are inline
Malloc/Pointer: 1,046,504 ok

Each of the pools is defined when the kernel is compiled. If your program requires large memory areas, then consider using ALLOCATE instead of ALLOT. You may wish to meta-compile a new kernel with larger named memory pools. On the other hand, this could be a programming error, if all you're doing is allocating a few small buffers.


Error(-271): <name> memory allocation failed

Summary: Extended error number. A request for system memory failed, probably due to the size requested.

Example:

123456789012 malloc
             ^^^^^^
Error(-271): MALLOC memory allocation failed

Resolution: MALLOC requests memory from the operating system. There's lots of it. Are you sure you need that much? .MALLOCS will show you the number and size of already allocated memory; on most systems, you should be able to get several hundred megabytes without a problem.

.mallocs
Abs-Addr Rel-Addr       Bytes HeapAddr Type
-------- --------    -------- -------- ----
00C50020 00C50030   1,024,000 00140000
0014C0E0 0014C0F0       8,192 00140000
0014BE60 0014BE70         332 00140000
00149EB8 00149EC8       8,060 00140000
001473B0 001473C0       4,096 00140000
00146C68 00146C78       1,824 00140000
-------- --------    -------- -------- ----
Total allocated 1,046,504
ok

Error(-272): <name> memory release failed

Summary: Extended error number. Memory released failed; probably due to an invalid pointer.

Example:

: x release ; ok
0 x
  ^
Error(-272): X memory release failed

Resolution: Probably a bad pointer, not one you got from an ALLOCATE or MALLOC. You can only RELEASE memory in the REL-ADDR column below; it's the value returned by a MALLOC.

.mallocs
Abs-Addr Rel-Addr       Bytes HeapAddr Type
-------- --------    -------- -------- ----
00C50020 00C50030   1,024,000 00140000
0014C0E0 0014C0F0       8,192 00140000
0014BE60 0014BE70         332 00140000
00149EB8 00149EC8       8,060 00140000
001473B0 001473C0       4,096 00140000
00146C68 00146C78       1,824 00140000
-------- --------    -------- -------- ----
Total allocated 1,046,504
ok

Error(-280): <name> create-file failed

Summary: Extended error number. Currently only used by FSAVE-FILE; probably indicates a bad file name.

Example:

0x40000 300 c" .. def^$??" fsave-file
                           ^^^^^^^^^^
Error(-280): FSAVE-FILE create-file failed

Resolution: Try following Windows standards for naming files -- or perhaps you're trying to write to an existing file or to a directory you don't have permission to access.


Error(-281): <name> read-file failed

Summary: Extended error number. Currently only used by REFILL. Very unusual error.

Example:

Resolution: An I/O error of some description was encountered while reading the source for a program. Probably indicates there's something wrong with the file, the disk or the file handle; I/O errors during read are unusual. Have you closed a file handle you didn't own? Is it a pipe that's disconnected?


Error(-282): <name> write-file failed

Summary: Extended error number. Currently only used by FSAVE-FILE; probably indicates a full file system, or a file system I/O error.

Example:

0x40000 300 c" .. def^$??" fsave-file
                           ^^^^^^^^^^
Error(-280): FSAVE-FILE write-file failed

Resolution: Your disk might be full; or (if the file is a pipe) perhaps the pipe is broken.


Error(-290): is interpretation only

Summary: Extended error number. Reserved; not currently used.

Example:

Resolution:


Error(-300): { locals defined twice

Summary: Extended error number. Locals can only be defined once.

Example:

: x { a b -- c } { d } ;
                 ^
Error(-300): { locals defined twice

Resolution: Did you really mean this? Perhaps you used { } for locals, and also specified LOCALS| . They're mutually exclusive


Error(-301): <name> too many locals

Summary: Extended error number.

Example:

: x { a b c d e f g h i j k l m n o p } ;
                              ^
Error(-301): M too many locals

Resolution: 12 is the maximum number of locals. Perhaps you forgot the closing }, or need to factor your word better.


Error(-302): missing }

Summary: Extended error number. Locals started with { require a closing }.

Example:

fload test

^
Error(-302): missing } in file <directory>\TEST.F at line 3

Resolution: Only occurs when including a file, if the end of the file is encountered during the { definition. The file in this case looked like this;

: x { a b c

Error(-310): <name> procedure not found

Summary: Extended error number. The CALL couldn't find the Windows procedure.

Example:

call Allocconsole
     ^^^^^^^^^^^^
Error(-310): Allocconsole procedure not found

Resolution: Did you spell the procedure name correctly? They're CaseSensitive names. Have you declared the library that contains the procedure? Check if you've done so. Use the words .PROCS and .LIBS to identify the procedures and libraries loaded.

.procs alloc
Location ProcName    Prm ProcEP   LibName
-------- --------    --- -------- --------
00414208 GlobalAlloc  -  7C58DB7D KERNEL32.DLL
00420E98 GlobalLock   1  7C58E043 KERNEL32.DLL
0040F1FC VirtualAlloc 4  7C58E845 KERNEL32.DLL
0040D5AC HeapReAlloc  4
0040D574 HeapAlloc    3  77FCC0EF KERNEL32.DLL
0040BF98 AllocConsole 0
Displayed 6 of 248 procedures defined
.libs
Location Handle   Name
-------- -------- -----------
00437490 71710000 COMCTL32.DLL
00432034 77A50000 OLE32.DLL
00420508 76B30000 COMDLG32.DLL
004114E8 782F0000 SHELL32.DLL
004114D0 7C2D0000 ADVAPI32.DLL
004114BC 77F40000 GDI32.DLL
00411368 00940000 WINCON.DLL
0040E81C 70A70000 SHLWAPI.DLL
0040D15C 7C570000 KERNEL32.DLL
0040BD88 77E10000 USER32.DLL
0040BAEC 10000000 W32FCONSOLE.DLL

Error(-311): <name> <Windows error message>

Summary: Extended error number. Some Windows error occurred; the text explains what.

Example:

fsave win32for.exe
Entry point at 2A84h (402A84h)
Segment Origin    Size   Alloc
------- --------- ------ -------
CODE    401000h    12120   40960
APP     40B000h   188600 1024000
SYSTEM  505000h   271836  512000
------- --------- ------ -------
Total             472556
Building image win32for.exe
File 'win32for.exe' :
      ^^^^^^^^^^^^
Error(-311): win32for.exe The process cannot access the file because
it is being used by another process. Windows DLL error

Resolution: Fix it! Some are pretty straightforward; the example shows that FSAVEing the running process doesn't work. Others are tougher.


Error(-320): <name> stack changed

Summary: Extended error number. Compilation error.

Example:

: x if 20 else 30 ;
                  ^
Error(-320): ; stack changed

Resolution: You've added or removed something from the stack while compiling a : or CODE definition. The example has a missing THEN ; see also Error(-22) for another example.


Error(-330): <name> can't use EXIT in a method

Summary: Extended error number. Due to the internal structure of classes and methods, EXIT or anything that compiles the equivalent is not permitted.

Example:

:class x <super object ok
:m draw: { a b }
dup 0= if exit then ;m
          ^^^^
Error(-330): EXIT can't use EXIT in a method

Resolution: Well, rewrite the code; it might be all the better for it.


Error(-331): <name> can't use DOES> in a method

Summary: Extended error number. Due to the internal structure of classes and methods, DOES> or anything that compiles the equivalent is not permitted.

Example:

:class x <super object ok
:m draw: { a b }
dup 0= does> @ ;m
       ^^^^^
Error(-331): DOES> can't use DOES> in a method

Resolution: What exactly would you want with a DOES> in a method? This DOES> not compute.


Error(-332): <name> method must end with ;M

Summary: Extended error number. Well, they just must, OK? Methods aren't ordinary words.

Example:

:class x <super object ok
:m draw: { a b }
dup 0= @ ;
         ^
Error(-332): ; method must end with ;M

Resolution: Replace ; with ;M


Warning(-4100): <name> is redefined

Summary: Warning. There are two or more definitions of <name> in the same vocabulary. The last definition is the one in force.

Example:

: y 1 2 3 ; ok
: y 4 5 6 ;
  ^
Warning(-4100): Y is redefined ok

Resolution: Did you mean to define the same word twice in the same vocabulary? If so, and this is annoying you, then turn off warnings with WARNING OFF.


Warning(-4101): <name> is a system word in an application word

Summary: Warning. The word you are defining is in the normal application area; but the <name> is in the system area, and might not be available if the application is TURNKEYed.

Example:

: xx .procs ;
     ^^^^^^
Warning(-4101): .PROCS is a system word in an application word

Resolution: If you understand this, and it's annoying you, then turn off warnings with SYS-WARNING-OFF. Otherwise, realise that your application might fail if it is TURNKEYed.


Warning(-4102): <name> is an application word set to a system word

Summary: Warning. The word you are setting is in the normal application area; but the <name> is in the system area, and might not be available if the application is TURNKEYed.

Example:

defer x ok
' .procs is x
            ^
Warning(-4102): X is an application word set to a system word

Resolution: If you understand this, and it's annoying you, then turn off warnings with SYS-WARNING-OFF. Otherwise, realise that your application might fail if it is TURNKEYed.


Warning(-4103): <name> stack depth increased

Summary: Warning. When loading a file, one or more lines have left a value on the stack. This is possibly an error, but might be OK for you. See about suppressing warning messages for more details on stack changes.

Example:

fload test
1 2
^
Warning(-4103): stack depth increased in file <directory>\TEST.F at line 5
Stack: [2] 1 2
ok..

Resolution: Depends; check out whether it's OK for this to happen.


Warning(-4104): is a deprecated word

Summary: Warning. The word you are using is marked as deprecated. Such words will be removed form Win32Forth in the future.For more information take a look at the source of the deprecated word.

Example:

foo ; DEPRECATED  ok
: foo1 foo ;
       ^^^
Warning(-4104): FOO is a deprecated word  ok

Resolution: If you understand this, and it's annoying you, then turn off warnings with DPR-WARNING-OFF. Otherwise, realise that your application might not work with new Win32Forth Versions in the future.


Warning(-4105): has a hash value that is already recognised by this class

Summary: Warning. There are two or more methods in the same class, or an ancestor. The last method is the one in force.

Example:

:m getPeriodY: ." Executing GetPeriodY" ;m ok
:m setperiods: ." Executing SetPeriods" ;m
   ^^^^^^^^^^^
Warning(-4105): SETPERIODS: has a hash value that is already recognised by this class.  ok

Resolution: Hashing method names is not perfect, so very occassionally clashes may occur. Try renaming the method. If the method that the new method clashes with is in an ancestor, and is not needed by this class then you can ignore the warning. If so, and this is annoying you, then turn off warnings with WARNING OFF.


Warning(-4106): <name> is an application word whose runtime is in a system word

Summary: Warning. The word <name> you are defining is in the normal application area; but the DOES> part of the defining word is in the system area, and might not be available if the application is TURNKEYed.

Example:

: MyConstant create , does> @ ; ok
' MyConstant Foo
            ^
Warning(-4106): Foo is an application word whose runtime is in a system word

Resolution: If you understand this, and it's annoying you, then turn off warnings with SYS-WARNING-OFF. Otherwise, realise that your application might fail if it is TURNKEYed.


Error(9998): <name> Windows exception trapped

Summary: Application/run time error number.

Example:

0 0 /

EXCEPTION 0xC0000094 INT_DIVIDE_BY_ZERO
Version: 6.09.14 Build: 17
Registers:
Eax:      00000000
Ebx: TOS  00000000 top of stack
Ecx:      00127FB0
Edx: USER 00000000 user area
Edi:      00000000
Esi: IP   0040B100 Forth ip
Esp: SP@  00126F78 stack ptr
Ebp: RP@  0012FF8C rstack ptr
Eip: PC   00401C12 machine ip
Backtracking: _INTERPRET+20 CONSOLE-STATUSBAR-INTERPRET+0 QUERY-INTERPRET+2 CATCH+14
Data stack: 0 0 1 2
Primitive /MOD loaded from: SRC\KERNEL\FKERNEL.F at line: 1207
Invoking word _INTERPRET loaded from: SRC\KERNEL\FKERNEL.F at line: 4579
fails at word / loaded from: SRC\KERNEL\FKERNEL.F at line: 1233

Press any key to exit...
     ^
Error(9998): / Windows exception trapped

Resolution: Wow, you expect us to fix all your problems? If you really can't debug this one (and some of them can be difficult), please send the mini-dump shown above to us here: and we'll try our best. Please, please, please include the mini-dump and any other supporting material, such as the code that caused the error.


Document $Id: p-gethelp.htm,v 1.6 2006/08/03 13:08:21 georgeahubert Exp $