This is an old version from the tos.hyp. The new is on GitHub!

HomeMagiCSemaphores in MagiCSmart redraw in MagiC

11.14 General remarks about shutdown

Shutdownis 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).

Shutdownis 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

11.14.1 Shutdown in MultiTOS

Under MultiTOS, programs must do the following to support the Shutdown mechanism:

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

11.14.2 Shutdown in MagiC

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:

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

11.14.3 Shutdown as seen by the application

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:

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:

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

11.14.4 Shutdown as seen by the initiator

Shutdownand 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" ignore} 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


HomeMagiCSemaphores in MagiCSmart redraw in MagiC