|R1||New address, or 0 to read|
|R2||Value of R12 when code is called|
|R3||Pointer to buffer if appropriate or 0 to read|
|R3||Previous buffer pointer|
The purpose of this call is to install a handler.
This is a single routine which performs the actions of OS_Control, OS_SetEnv, OS_CallBack, OS_BreakCtrl and OS_UnusedSWI. In fact all of those routines use this call and are only kept for backwards compatibility, so you should use this call in preference.
Note, OS_ChangeEnvironment vectors through ChangeEnvironmentV. A routine linked into this vector can stop the change from happening by setting R1 to zero and passing the call on.
If you set up any handlers, you must provide Error, Exit and UpCall handlers so that you can restore all handlers on any kind of program exit (even X SWIs can generate serious errors).
Handlers are specific to the current task and are swapped automatically by the Wimp when it switches tasks.
Consult the documentation for each individual handler to determine what extra buffer pointer (R3), if any, is required.