> Wimp.Errors New Calls --------- Wimp_ReportError UpCall handling Service_WimpReportError (&57) Reporting Errors ---------------- There are two ways of trapping errors in Arthur: * set up an error handler using OS_ChangeEnvironment * set bit 17 of all SWI numbers called: they return V set and R0->error Only applications are allowed to set error handlers - transients and *command decoding routines must use the second method. 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 ' appears in the title bar Exit: R1 = 1 ==> 'OK' was selected = 2 ==> 'Cancel' was selected Note that the escape key can be used as a synonym for clicking the mouse on whichever of the icons was highlighted. 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. UpCall Handling --------------- 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 ' 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! Service_WimpReportError ----------------------- 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 - when he does so, the window will close and the output will continue inside the task window.