DosResetBuffer

From EDM2
(Redirected from OS2 API:CPI:DosResetBuffer)
Jump to: navigation, search

Description

Writes the buffers for the specified file to the device.

Syntax

#define INCL_DOSFILEMGR
#include <os2.h>

HFILE   hFile;  /*  The handle of the file whose buffers are to be written to the disk. */
APIRET  ulrc;   /*  Return Code. */

ulrc = DosResetBuffer(hFile);

Parameters

hFile (HFILE) - input 
The handle of the file whose buffers are to be written to the disk.
If hFile has a value of 0xFFFFFFFF, all of the buffers for all of the file handles of the process are written to the disk.

Return Code

ulrc (APIRET) - returns

DosResetBuffer returns one of the following values:

  • 0 NO_ERROR
  • 2 ERROR_FILE_NOT_FOUND
  • 5 ERROR_ACCESS_DENIED
  • 6 ERROR_INVALID_HANDLE

Remarks

When DosResetBuffer is issued for a file handle, the contents of the file's buffers are written to the disk, and the file's directory entry is updated as if the file had been closed; however, the file remains open.

DosResetBuffer should be issued with caution. When files are on diskettes, issuing DosResetBuffer could have the undesirable effect of requiring the user to insert and remove a large number of diskettes.

Named-Pipe Considerations

Issuing DosResetBuffer for a named pipe results in an operation that is similar to forcing the buffer cache to the disk. The request blocks the calling process at one end of the pipe until all written data has been read at the other end.

Example Code

This example writes to a file named "DOSMAN.DAT", resets the buffer, and changes the size of the file.

#define INCL_DOSFILEMGR          /* File Manager values */
#define INCL_DOSERRORS           /* DOS Error values    */
#include <os2.h>
#include <stdio.h>
#include <string.h>

int main(VOID) {
   HFILE  hfFileHandle   = 0L;     /* Handle for file being manipulated */
   ULONG  ulAction       = 0;      /* Action taken by DosOpen */
   ULONG  ulWrote        = 0;      /* Number of bytes written by DosWrite */
   UCHAR  uchFileName[20]  = "dosman.dat",     /* Name of file */
          uchFileData[4]   = "DATA";            /* Data to write to file */
   APIRET rc             = NO_ERROR;            /* Return code */

   /* Open the file dosman.dat.  Use an existing file or create a new */
   /* one if it doesn't exist.                                      */
   rc = DosOpen(uchFileName, &hfFileHandle, &ulAction, 4L,
                FILE_ARCHIVED | FILE_NORMAL,
                OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS,
                OPEN_FLAGS_NOINHERIT | OPEN_SHARE_DENYNONE  |
                OPEN_ACCESS_READWRITE, 0L);
   if (rc != NO_ERROR) {
      printf("DosOpen error: return code = %u\n", rc);
      return 1;
   }

   rc = DosWrite (hfFileHandle, (PVOID) uchFileData,
                  sizeof (uchFileData), &ulWrote);
   if (rc != NO_ERROR) {
      printf("DosWrite error: return code = %u\n", rc);
      return 1;
   }

   rc = DosResetBuffer (hfFileHandle);
   if (rc != NO_ERROR) {
      printf("DosResetBuffer error: return code = %u\n", rc);
      return 1;
   } /* endif */

   rc = DosSetFileSize (hfFileHandle, 8L);    /* Change file size */
   if (rc != NO_ERROR) {
      printf("DosSetFileSize error: return code = %u\n", rc);
      return 1;
   }

   return NO_ERROR;
}

Related Functions