MagiC
Semaphores in MagiC
Smart redraw in MagiC
Shutdown is to be understood as a mechanism that allows the system to be run down in a controlled manner. In a multitasking environment it is actually no longer permissible to simply switch off the computer after use; a reset with the reset button should be taboo as well. Rather one must ensure that all programs have been terminated properly and all files closed correctly before the current to the computer is turned off. If this is ignored, then data losses may well result.
For this reason UNIX systems or the Apple Macintosh, for instance, have a Shutdown mechanism; such a one was also introduced by Atari in MultiTOS and is also available in MagiC (as of Version 3.0).
Shutdown is activated normally via the menu entry 'File/Shutdown' on the desktop, with the key combination [[Control]-[Alternate]-[Delete], or by a resolution change. During the Shutdown, no programs can be launched.
See also: Shutdown in MultiTOS Shutdown in MagiC Shutdown at the receiver Shutdown at the initiator shel_write
Under MultiTOS, programs must do the following to support the Shutdown mechanism:
Call shel_write (with sh_wdoex= 9), to inform the
AES that they understand the AP_TERM message
Terminate on receipt of an AP_TERM message, or send AP_TFAIL
Note: MultiTOS sends the AP_TERM message here only to those processes that explicitly understand AP_TERM. As hardly any programs exist at present that dismiss a corresponding shel_write, an implementation such as this in MagiC would not give the desired result. Hence a different procedure was chosen, in which the AP_TERM message is sent to all running applications.
See also: Shutdown in MagiC shel_write Shutdown at the receiver Shutdown at the initiator
Under MagiC the Shutdown works a follows: all running programs receive an AP_TERM message signalling that they should terminate themselves. If there are still programs in memory after a certain time, then SHUTDOWN outputs an error-message. In the file SHUTDOWN.INF one can specify program names (without a suffix such as '.prg' or '.app') that are uncritical and should not lead to an error-message from SHUTDOWN.
In addition to this the following points have to be heeded:
If [Control]-[Alternate]-[Delete] is to be used to terminate
the system, one must ensure that the screen is not locked, i.e. that a
program is not currently processing a dialog box or alert on the
screen, for instance. Furthermore a suitable shell (such as MAGXDESK,
Thing or Jinnee) must have been loaded, i.e. no program may be loaded
in 'single-mode' or in the 'Shell not resident' mode (say with
[Alternate]-double-click).
f the screen is locked, then only the writeback-demon will be
terminated, i.e. the cache written back. Only after the screen is
released (i.e. after closing of the dialog or alert box) can the
Shutdown be performed.
Should the system have crashed in such a way that no Shutdown is
possible any more, then [Control]-[Alternate]-[Delete] should be
performed for a second time; a warm start will be carried out without
programs being terminated
If 'single-mode' is active or the shell is not loaded, then again
only the writeback-demon will be terminated and the cache written
back. For a complete Shutdown the running program has to be terminated
so that the shell is active again. The Shutdown then must be
performed via the 'File/Shutdown' menu entry.
In MagiC 4, the Shutdown mechanism was revised as follow: The AES now sends a SHUT_COMPLETED message with msg[3] = 0 (i.e. 'Shutdown terminated unsuccessfully') and msg[4] = -1 (invalid ap_id) if there are still programs running in the system that do not understand AP_TERM explicitly. With that, a program that only masters the MultiTOS specification will break off the Shutdown. SHUTDOWN.PRG, on the other hand, was adapted to the new specification, and functions as previously, i.e. gives all programs still running a timeout and then outputs the names of all reluctant applications.
In addition, the application #0 is no longer passed arbitrary data in msg[4,5,6,7] on [Control]-[Alternate]-[Delete], but the following message:
msg[3] = -1 msg[4,6,7] = 0 msg[5] = AP_TERM
See also:
Shutdown in MultiTOS shel_write Shutdown at the receiver Shutdown at the initiator
First one should point out that the Shutdown mechanism in MultiTOS differs from that in MagiC: Atari's MultiTOS sends an AP_TERM message only to those applications that have explicitly informed the AES with shel_write (opcode 9) that they understand the AP_TERM message; on the other hand MagiC sends the mssage to all active applications.
The Shutdown will be seen by the AES as successful only when all programs explicitly understanding AP_TERM have terminated themselves. If an application should intimate that it cannot terminate itself, then the Shutdown will be broken off. For these reasons, every program receiving an AP_TERM message has principally only two options:
msg[0] = AP_TFAIL; msg[1] = err; shel_write(10, 0, 0, (char *) msg, NULL);
If the application reacts differently on the other hand, i.e. ignores the AP_TERM message, then the behaviour of the system depends on whether it was informed that the AP_TERM message is understood. In plain language:
If the application explicitly understands AP_TERM then
the system starts from the assumption that the application cannot
accept any messages at the time. The Shutdown is not interrupted, but
lasts until the caller (generally the program SHUTDOWN) terminates the
Shutdown. SHUTDOWN uses a timeout for this of 3 seconds, i.e. if 3 seconds
after the start of the Shutdown programs are still active that
understand AP_TERM, the program will break off the Shutdown process.
If the application does not explicitly understand
AP_TERM, then the system tells the initiator of the Shutdown (generally
SHUTDOWN.PRG) that the Shutdown process has been successful. Only
because the SHUTDOWN.PRG is so indulgent with old programs, it tests
whether any applications are still active, and outputs a message if
so. One can specify in the file SHUTDOWN.INF the programs that should
not lead to an error-message, i.e. that need not be terminated.
Note: If the Shutdown was started with [Alternate]-[Control]-[Delete], then at first only the writeback-demon and the application with the ID 0 receives an AP_TERM message; -1 is entered as sender for this. Application 0 (generally the desktop) then terminates itself and then starts the Shutdown program.
See also:
Shutdown at the initiator shel_write Shutdown in MagiC Shutdown in MultiTOS
Shutdown and resolution change are taken on in MagiC by the program SHUTDOWN, which is called with the following parameters:
SHUTDOWN.PRG dev txt
For this dev = -1 if a Shutdown without a resolution change is to be performed, else = the device number of the VDI screen driver. txt is the text height for the AES; generally this should be 0.
A Shutdown is started with ret = shel_write(4, TRUE, 0, NULL, NULL). Here a return value of 0 signals that a Shutdown is not possible, because a Shutdown is already running, for instance. A resolution change is performed with ret = shel_write(5, dev, 0, NULL, NULL); here dev is the VDI device driver. Alternatively, one can specify a Falcon resolution mode in xdv with shel_write(5, xdv, 1, NULL, NULL).
These calls are all MultiTOS-conform. In addition, as of MagiC 3 the following call exists: ret = shel_write(5, dev, 100+txt, NULL, NULL). With this one can set the text height for the AES. One cannot pass a Falcon resolution with this mode, so dev is the device number of the VDI screen driver.
The device number depends on the system in use and the VDI. With a 'naked' ST or TT030 (without graphics card) the following allocations apply:
| 1 | Default resolution | |
| 2 | ST-Low | (320*200*16) |
| 3 | ST-Medium | (640*200*4) |
| 4 | ST-High | (640*400*2) |
| 6 | TT-Medium | (640*480*16) |
| 8 | TT-High | (1280*960*2) |
| 9 | TT-Low | (320*480*256) |
When using a graphics card, or on a Macintosh, the device numbers are found as usual in the ASSIGN.SYS file in the root directory of the boot drive.
After a successful shel_write call the system will be in the Shutdown mode and no more programs can be launched. On successful completion of the Shutdown or a resolution change the initiator receives the following message:
| msg[0] = | SHUT_COMPLETED |
| msg[3] = | 1 - Shutdown successful |
or with a resolution change:
| msg[0] = | RESCH_COMPLETED |
| msg[3] = | 1 - Resolution change successful |
Successful as far as the system is concerned means that all progams that understand AP_TERM have terminated themselves. If the Shutdown should be broken off nevertheless, then this can be done by using ret = shel_write(4, FALSE, 0, NULL, NULL). Otherwises a resolution change will be performed irrevocably when the initiator has terminated itself. On the other hand the Shutdown will be broken off when the initiator terminates.
If a program has refused a Shutdown with AP_TFAIL, then the initiator receives the following message:
| msg[0] = | SHUT_COMPLETED |
| msg[3] = | 0 - Break off Shutdown |
| msg[4] = | ap_id of the application that has refused |
| msg[5] = | Error-code of this application |
bzw. beim Auflösungswechsel
| msg[0] = | RESCH_COMPLETED |
| msg[3] = | 0 - Resolution change broken off |
| msg[4] = | ap_id of the application that has refused |
| msg[5] = | Error-code of this application |
In this case the system has already terminated the Shutdown or resolution change, i.e. the initiator cannot do anything any more.
Note: Because it is possible that the Shutdown process is never reported by the system as complete or broken off (the RESCH_COMPLETED or SHUT_COMPLETED message is never sent), the initiator should forsee a timeout while waiting for the message. In that case the Shutdown must be broken off explicitly. With appl_search the initiator can test whether there are still programs active that do not understand AP_TERM explicitly.
See also:
Shutdown at the receiver shel_write Shutdown in MultiTOS Shutdown in MagiC
MagiC
Semaphores in MagiC
Smart redraw in MagiC