Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosSetFHandState(hf, fsState)
HFILE hf;          /* file handle      */
USHORT fsState;    /* file-state flags */
 
The DosSetFHandState function modifies a file's inheritance, fail-on-error,
and write-through flags. These flags are originally set by using the
DosOpen function when the file is opened.
 
The DosSetFHandState function is a family API function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hf         Identifies the handle of the file to be set. This handle must
           have been created previously by using the DosOpen function.
 
fsState    Specifies the state of the file-handle. This parameter can be one
           or more of the following values:
 
           Value                     Meaning
           ─────────────────────────────────────────────────────────────────
           OPEN_FLAGS_FAIL_ON_ERROR  Any function that uses the file handle
                                     returns immediately with an error value
                                     if there is an I/O error──for example,
                                     if the drive door is open or a sector
                                     is missing. If this value is not
                                     specified, the system passes the error
                                     to the system critical-error handler,
                                     which then reports the error to the
                                     user with a hard-error pop-up message.
                                     The fail-on-error flag is not inherited
                                     by child processes.
 
                                     The fail-on-error flag applies to all
                                     functions that use the file handle,
                                     with the exception of the DosDevIOCtl
                                     function.
 
           OPEN_FLAGS_NOINHERIT      The file handle is not available to any
                                     child process started by the current
                                     process. If this value is not
                                     specified, any child process started by
                                     the current process can use the file
                                     handle.
 
           OPEN_FLAGS_WRITE_THROUGH  This flag applies to functions, such as
                                     DosWrite, that write data to the file.
                                     If this value is specified, the system
                                     writes data to the device before the
                                     given function returns. Otherwise, the
                                     system may store the data in an
                                     internal file buffer and write the data
                                     to the device only when the buffer is
                                     full or the file is closed.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_INVALID_HANDLE
     ERROR_INVALID_PARAMETER
 
Restrictions
 
In real mode, the following restriction applies to the DosSetFHandState
function:
 
♦  Only the OPEN_FLAGS_NOINHERIT flag can be set. It must not be set if the
   application will be used under MS-DOS 2.x.
 
See Also
 
DosDevIOCtl, DosDupHandle, DosOpen, DosQFHandState, DosSetFileMode,
DosWrite
 
                                      ♦