DosClose

Description

Closes a handle to a file, pipe, or device.

Syntax

#define INCL_DOSFILEMGR
#include <os2.h>

HFILE     hFile;  /* The handle returned by a previous call to DosCreateNPipe, 
                     DosCreatePipe, DosDupHandle, or DosOpen. */
APIRET    ulrc;   /* Return Code. */

ulrc = DosClose(hFile);

Parameters

hFile (HFILE) - input

The handle returned by a previous call to DosCreateNPipe, DosCreatePipe, DosDupHandle, or DosOpen.

Return Code

ulrc (APIRET) - returns

DosClose returns one of the following values:

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

Remarks

Issuing DosClose with the handle to a file closes a handle to a file, pipe, or device.

If additional handles to a file were created with DosDupHandle, DosClose must be issued for the duplicate handles before the directory is updated, and information in internal buffers is written to the medium.

Closing a device handle causes the device to be notified of the close, if appropriate.

Named-Pipe Considerations

DosClose closes a named pipe by handle. When all handles that refer to one end of a pipe are closed, the pipe is considered broken.

If the client end closes, no other process can reopen the pipe until the serving end issues DosDisConnectNPipe, followed by DosConnectNPipe.

If the server end closes when the pipe is already broken, the pipe is immediately deallocated; otherwise, it is not deallocated until the last client handle is closed.

Example Code

This example opens, or creates and opens, a file named "DOSTEST.DAT", writes to it, reads from it, and finally closes it.

#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  ulBytesRead    = 0;   /* Number of bytes read by DosRead */
   ULONG  ulWrote        = 0;   /* Number of bytes written by DosWrite */
   ULONG  ulLocal        = 0;   /* File pointer position after DosSetFilePtr */
   UCHAR  uchFileName[20]  = "dostest.dat",  /* Name of file */
          uchFileData[100] = " ";            /* Data to write to file */
   APIRET rc             = NO_ERROR;         /* Return code */

   /* Open the file dostest.dat. Use an existing file or create a new */
   /* one if it doesn't exist.                                      */
   rc = DosOpen(uchFileName,                    /* File path name */
                &hfFileHandle,                  /* File handle */
                &ulAction,                      /* Action taken */
                100L,                           /* File primary allocation */
                FILE_ARCHIVED | FILE_NORMAL,    /* File attribute */
                OPEN_ACTION_CREATE_IF_NEW |
                OPEN_ACTION_OPEN_IF_EXISTS,     /* Open function type */
                OPEN_FLAGS_NOINHERIT |
                OPEN_SHARE_DENYNONE  |
                OPEN_ACCESS_READWRITE,          /* Open mode of the file */
                0L);                            /* No extended attribute */

   if (rc != NO_ERROR) {
      printf("DosOpen error: return code = %u\n", rc);
      return 1;
   } else {
     printf ("DosOpen: Action taken = %ld\n", ulAction);
   } /* endif */

   /* Write a string to the file */
   strcpy (uchFileData, "testing...\n1...\n2...\n3\n");
   rc = DosWrite (hfFileHandle,              /* File handle */
                  (PVOID) uchFileData,       /* String to be written */
                  sizeof (uchFileData),      /* Size of string to be written */
                  &ulWrote);                 /* Bytes actually written */

   if (rc != NO_ERROR) {
      printf("DosWrite error: return code = %u\n", rc);
      return 1;
   } else {
      printf ("DosWrite: Bytes written = %u\n", ulWrote);
   } /* endif */

   /* Move the file pointer back to the beginning of the file */
   rc = DosSetFilePtr (hfFileHandle,           /* File Handle */
                       0L,                     /* Offset */
                       FILE_BEGIN,             /* Move from BOF */
                       &ulLocal);              /* New location address */
   if (rc != NO_ERROR) {
      printf("DosSetFilePtr error: return code = %u\n", rc);
      return 1;
   }

   /* Read the first 100 bytes of the file */
   rc = DosRead (hfFileHandle,                /* File Handle */
                 uchFileData,                 /* String to be read */
                 100L,                        /* Length of string to be read */
                 &ulBytesRead);               /* Bytes actually read */

   if (rc != NO_ERROR) {
      printf("DosRead error: return code = %u\n", rc);
      return 1;
   } else {
      printf ("DosRead: Bytes read = %u\n%s\n", ulBytesRead, uchFileData);
   } /* endif */

   rc = DosClose(hfFileHandle);                /* Close the file */

   if (rc != NO_ERROR) {
      printf("DosClose error: return code = %u\n", rc);
      return 1;
   }
   return NO_ERROR;
}

Related Functions

• DosConnectNPipe
• DosCreateNPipe
• DosDisConnectNPipe
• DosDupHandle
• DosOpen
• DosResetBuffer