Reviewed and revised April 2024
(1) xcall ERRMSG {,errarg}
(2) xcall ERRMSG, msg, errnum
Parameters
errarg (Structure) [in]
A structure mapped as shown below specifying your application-defined error code and message
MAP1 ERRARG
MAP2 err'id,S,6 ! (this field is ignored)
MAP2 err'cde,B,2 ! app-defined error #
MAP2 err'msg,S,50 ! app-defined error message
msg (String) [out]
Receives the standard language-dependent error message corresponding to the ASB error code in errnum. Messages are defined in SYS:ERRMSG.xxx where xxx is the extension defined in the current Language Definition File.
errnum (Unsigned Int) [in]
ASB error code. You can retrieve this via the err(0) function.
ERRMSG is a handy way to handle ASB error trap reporting. Add the subroutine to your ASB error trap, and it can display a standardized message at the bottom of the screen (listing information about the error) and log the error to file, and/or retrieve the text associated with the current error. The routine must be set up as an alias to DERR in miame.ini as follows:
ALIAS=ERRMSG:DERR
DERR is a Debug plc routine which is similar to ERRMSG. It is not documented here since we prefer that you use ERRMSG. If you are already using DERR, feel free to continue, but note that it expects four arguments, rather than the 0-2 that ERRMSG expects.
If 0 or 1 argument is passed and an ASB error has occurred, then ERRMSG ignores the errarg argument (if passed) and displays a three line message at the bottom of the screen relating to the ASB error, which looks something like this:
* ERROR MESSAGE * TSKAAA Illegal record number
Error 31 in Line 360 of MYPROG Last File: 5 (ERRMSG.TMP)
Press ESC to Abort
You may also call the ERRMSG directly (i.e. absent any ASB error) to report application-defined errors. In that case, you must include the errarg parameter, assigning your own values to the fields. For example, consider the following code:
125 err'cde = 142
130 err'msg = "Something bad has happened!"
135 xcall ERRMSG,ERRARG
This would display the following message (where "MYPROG" is the current program name):
* ERROR MESSAGE * TSKAAA Something bad has happened!
Error 142 in Line 135 of MYPROG
Press RETURN to Continue or Retry
In either of the above cases, the subroutine will also log a similar message to the text file bas:baserr.log.
If two arguments are passed (as in the second sample format above) then it simply retrieves the ASB error message associated with the specified error number. This can be useful for creating your own error message display within an error trap, since when error trapping is enabled, BASIC no longer displays the error message. (It only supplies you with the error number, last line number, and last channel number, via the ERR(0), ERR(1), and ERR(2) functions.)
ERRMSG (i.e., DERR) uses a Windows-style message box if GUI support is available.