Wimp_ReportError
UpCall handling
Service_WimpReportError (&57)
There are two ways of trapping errors in Arthur:
When running under the Wimp, the following SWI should be used to report errors to the user:
Wimp_ReportError
Entry: R0 --> error block
+0 error number (1 word)
+4 error string (0-terminated)
R1 = flags
bit 0 set ==> provide 'OK' box in error window
bit 1 set ==> provide 'Cancel' box
bit 2 set ==> highlight 'Cancel' box (otherwise highlight 'OK')
bit 3 set ==> don't wait for confirmation if this is a 'text' error
bit 4 set ==> omit 'Error from ' message in title bar
bit 5 set ==> return with R1=0 immediately if buttons not clicked
the error window is also left open
bit 6 set ==> select OK/Cancel depending on R1, close error window
bits 7..31 reserved (must be 0)
R2 --> application name (less than 20 characters)
the string 'Error from <application>' appears in the title bar
Exit: R1 = 1 ==> 'OK' was selected
If the application receives an error it is not expecting, it should provide the user with a choice of 'OK' or 'Cancel'. If OK is selected, it should return to its polling loop, whereas if Cancel is selected, it should exit (by calling Wimp_CloseDown followed by OS_Exit).
See 'Wimp.Misc' for a description of what happens if a command window is open when Wimp_ReportError is called, and 'Wimp.Desktop' for a fuller description of how errors should be dealt with by a Wimp application.
One feature of ADFS which was not fully exploited in Arthur 1.20 is the ability to refer to disc names rather than drive numbers, so that multiple discs can be used with only one disc drive.
When a disc is referred to that is not currently in any of the drives, ADFS generates an 'UpCall', which can be intercepted by other software in the machine. The new Window Manager intercepts this call (if active), and uses Wimp_ReportError to prompt the user to insert the appropriate disc. The user can then select 'OK' or 'Cancel' to look for the disc again or to give up.
UpCall interface:
In: R0 = 1 or 2 (MediaNotPresent / MediaNotKnown)
R1 = filing system number (8 for adfs)
R2 = pointer to disc name
R3 = device number (-1 for adfs)
R4 = iteration number (0 initially)
R5 = retry timeout (centiseconds) - &FFFFFFFF for no retries
R6 = pointer to media type (eg. 'disc' for adfs)
Out: R0 = 0 ==> try again
R0 = -1 ==> give up
The UpCall interface allows the filing system to give a 'retry time limit' after which it would be reasonable for the upcall handler to return so that the filing system could try again to look for the disc. This time limit is set to about 10 centiseconds if the disc drives support the 'disc changed' feature, so the presence of a disc in a drive can be checked quickly, but otherwise is set to a very large value (&FFFFFFFF).
The upcall handler should wait either until the user selects 'OK' or until the timeout limit is reached, and then return with R0=0 (or -1 if 'Cancel' is selected). At this point the filing system will re-scan its drives to try to find the required disc - if it is not found, the same upcall is called again (with R4 incremented); if found, the following upcall is issued:
R0 = 4 (MediaSearchEnd)
The Wimp's upcall handler uses bits 5 and 6 of R1 when calling Wimp_ReportError as follows:
Upcall: R0 = 1 or 2 (MediaNotPresent / MediaNotKnown)
error title is 'Message from <filing system name>'
read filing system name as follows:
R0 = FSControl_ReadFSName (33)
R1 = fs number
R2 = buffer start
R3 = buffer length
SWI OS_FSControl
error message is "Please insert disc ':xxxx'" (r6 -> 'disc' on entry)
R0 -> error message
R1 = bits 0,1 set (OK and Cancel buttons present)
bit 4 set (omit 'Error from ' in title bar)
bit 5 set (return immediately if user hasn't selected anything)
R2 -> error box title
SWI Wimp_ReportError
if R1=0, call reporterror again until timeout reached
then return with R0=0 (retry)
if R1=1, return with R0=0 (retry) - user clicked 'OK'
if R1=2, return with R0=-1 (give up) - user clicked 'Cancel'
Upcall: R0 = 4 (MediaSearchEnd)
R1 = bit 0 set (select OK)
bit 6 set (select OK/Cancel (OK here) and close error window)
SWI Wimp_ReportError
The upshot of all this is that with the right kind of disc drives (ie. the ones fitted to the original A300 series machines) you simply have to stick the right disc in the drive and off it goes on its own, without you having to click the OK button!
Because the UpCall handlers etc. may wish to call Wimp_ReportError at 'odd' times, it is necessary to provide a facility to allow programs such as the Task Window module to get out of the way when Wimp_ReportError is called.
The Wimp therefore issues the following service call before and after opening the ReportError window, which is trapped by ArcEdit task windows and the Vdu module:
R0 = 0 or 1 (window closing / opening)
R1 = Service_WimpReportError (&57)
A module such as the Vdu module should trap the service call and work out if any of its windows are active (only one window can be active at any one moment in time). If so, it should mark the window as 'suspended' (if R0=1 and the window was active) or 'active' (if R0=0 and the window was suspended).
This allows the user to access discs by name from within the task window, whereupon the Wimp's error window will inform him to insert the correct disc