DosShutdown

From EDM2
Jump to: navigation, search

Locks out changes to all file systems, and writes system buffers to the disk in preparation for turning off power to the system.

Syntax

DosShutdown(ulShutDownValue)

Parameters

ulShutDownValue (ULONG) - input 
Flag indicating the shutdown value.
Possible values are described in the following list:
0 Perform full system shutdown and file-system lock.
1 Perform buffer and cache flushing to make system quiescent.

Return Code

ulrc (APIRET) - returns
DosShutdown returns one of the following values:
  • 0 NO_ERROR
  • 87 ERROR_INVALID_PARAMETER
  • 274 ERROR_ALREADY_SHUTDOWN

Remarks

When ulShutDownValue equals 0, the full system is shut down and the file-system is locked. In this case, DosShutdown can take several minutes to complete its operation; the time depends on the amount of data in the buffers.

If other functions that change file-system data are issued while the system is shut down, either the return code ERROR_ALREADY_SHUTDOWN is set, or the other function calls are blocked permanently.

Allocated memory cannot be increased once DosShutdown has been issued. This means that in low-memory situations, some functions may fail because of a lack of memory. This is of particular importance to the process issuing DosShutdown. All memory that the calling process will ever need should be allocated before DosShutdown is issued. This includes implicit memory allocations that system functions make on behalf of DosShutdown.

When DosShutdown has completed successfully, the system can be powered-off or restarted.

When ulShutDownValue equals 1, the system is quiescent (no threads of execution are active) at the end of this function request, but the file-systems are not locked, and processing can resume at a later time.

Example Code

This example prepares the file system for the shutdown of the system. Refer to the WinShutdownSystem function to perform a complete OS/2 shutdown.

 #define INCL_DOSFILEMGR
 #define INCL_DOSERRORS
 #include <os2.h>
 #include <stdio.h>
 
 int main(VOID)
   {
    APIRET  rc = NO_ERROR;    /* Return code */
 
    rc = DosShutdown(0L);
 
    if (rc != NO_ERROR) {
        printf("DosShutdown error: return code = %u\n",rc);
        return 1;
    } else {
        printf("The file system has been prepared for shutdown.\n");
    }  /* endif */
 
    return NO_ERROR;
    }