Applications and Geodes: 4.4 General System Utilities: Shutting the System Down

| Up: GEOS SDK TechDocs | Up | Prev: 4.3 System Statistics and Utilities | Next: 5 The Error-Checking Version 
DosExec(), SysShutdown()

There are two ways for a geode to shut down GEOS. The first, DosExec() , shuts the system down to run a program under DOS, returning after the DOS program has finished--unless a task-switch driver is in use, in which case the system will create a new task and cause the task-switcher to switch to the new task. The second, SysShutdown() , forces the system to shut itself down completely. Neither of these routines is commonly used by anything other than the kernel, GeoManager, special "launcher" programs, or the UI. Their use by other libraries or applications is discouraged unless absolutely necessary.

DosExec() takes several parameters including the pathname of the DOS program to be run, arguments for the program, an optional disk handle of the disk that contains the program to be run, the optional directory and disk handle in which the program should be executed, and a record of DosExecFlags . If the return value is nonzero, an error occurred in loading the DOS program, and you can use ThreadGetError() to check what error occurred. Note that DosExec() always returns. Applications should not rely on DosExec() shutting the system down; if a task switcher is present, GEOS will be swapped out rather than shut down.

SysShutdown() causes GEOS to exit in one of several ways. This routine should be passed a shutdown mode. If the mode is SST_CLEAN, SST_RESTART, SST_SUSPEND, or SST_CLEAN_FORCED, the routine will return; otherwise, it will not return and the shutdown will commence. If SST_CLEAN is passed, the shutdown may be aborted after SysShutdown() returns. You can have SysShutdown() cause GEOS to reboot itself after shutting down (as the Preferences Manager application does for certain preferences settings), but this starts GEOS fresh. This routine is very rarely used by anything other than the UI, the kernel, or the Preferences Manager application.

If something else (typically the UI or task switcher) shuts the system down, objects that register for shutdown notification will receive MSG_META_CONFIRM_SHUTDOWN . The application should call SysShutdown() with the mode SST_CONFIRM_START; this allows the object to have exclusive rights for asking the user to confirm the shutdown (when the object is finished with the user interaction, it can call SysShutdown() with SST_CONFIRM_END to release exclusive access). This is useful if your application or library has an ongoing operation and wants to verify the shutdown with the user.

| Up: GEOS SDK TechDocs | Up | Prev: 4.3 System Statistics and Utilities | Next: 5 The Error-Checking Version