DosShutdown (OS/2 1.x): Difference between revisions

Latest revision as of 07:01, 26 January 2020

This call locks out changes to all file systems and forces system buffers to disk in preparation for system power off.

Syntax

DosShutdown (Reserved)

Parameters

Reserved (ULONG) - input: Double-word whose value must be zero.

Return Code

rc (USHORT) - return

Return code description is:

0 NO_ERROR

274 ERROR_ALREADY_SHUTDOWN

87 ERROR_INVALID_PARAMETER

Remarks

DosShutdown may take several minutes to complete depending on the amount of data buffered.

Other API function calls that change file system data called while the system is shutdown will either return the error ERROR_ALREADY_SHUTDOWN or block permanently.

It should be noted that it will not be possible to increase memory overcommit once the DosShutdown has been called. This means that in low memory situations some functions may fail due to a lack of memory. This is of particular importance to the process calling DosShutdown. All memory that the calling process will ever need should be allocated before calling DosShutdown. This includes implicit memory allocation that may be done on behalf of the caller by system functions.

When DosShutdown returns successfully, it is safe to power the system off or to reboot it.

Bindings

C

#define INCL_DOSFILEMGR

USHORT  rc = DosShutdown(Reserved);

ULONG   Reserved;      /* Reserved, must be set to zero */
USHORT  rc;            /* return code */

MASM

EXTRN  DosShutdown:FAR
INCL_DOSFILEMGR     EQU 1

PUSH   DWORD   Reserved      ;Reserved, must be set to zero
CALL   DosShutdown

Returns WORD

@@ Line 1: / Line 1: @@
-==Description==
 This call locks out changes to all file systems and forces system buffers to disk in preparation for system power off.
 ==Syntax==
-<PRE>
+  DosShutdown (Reserved)
-  DosShutdown
-    (Reserved)
-</PRE>
 ==Parameters==
-; Reserved (ULONG) - input : Double-word whose value must be zero.
+;Reserved (ULONG) - input: Double-word whose value must be zero.
 ==Return Code==
- rc (USHORT) - return
+;rc (USHORT) - return:Return code description is:
+::0 NO_ERROR
-Return code description is:
+::274 ERROR_ALREADY_SHUTDOWN
+::87 ERROR_INVALID_PARAMETER
-* 0          NO_ERROR
-* 274        ERROR_ALREADY_SHUTDOWN
-* 87         ERROR_INVALID_PARAMETER
 ==Remarks==
@@ Line 27: / Line 20: @@
 It should be noted that it will not be possible to increase memory overcommit once the DosShutdown has been called. This means that in low memory situations some functions may fail due to a lack of memory. This is of particular importance to the process calling DosShutdown. All memory that the calling process will ever need should be allocated before calling DosShutdown. This includes implicit memory allocation that may be done on behalf of the caller by system functions.
 When DosShutdown returns successfully, it is safe to power the system off or to reboot it.
-==Example Code==
+==Bindings==
-===C Binding===
+===C===
 <PRE>
 #define INCL_DOSFILEMGR
@@ Line 36: / Line 29: @@
 USHORT  rc = DosShutdown(Reserved);
-ULONG            Reserved;      /* Reserved, must be set to zero */
+ULONG   Reserved;      /* Reserved, must be set to zero */
+USHORT  rc;            /* return code */
-USHORT           rc;            /* return code */
 </PRE>
-===MASM Binding===
+===MASM===
 <PRE>
 EXTRN  DosShutdown:FAR
@@ Line 51: / Line 43: @@
 Returns WORD
 </PRE>
-==Related Functions==
-*
-[[Category:The OS/2 API Project]]
+[[Category:Dos16]]