View source for DosProtectWrite

==Description==
Writes a specified number of bytes from a buffer to the specified file.

==Syntax==
<PRE>
#define INCL_DOSFILEMGR
#include <os2.h>

HFILE     hFile;               /*  File handle from DosOpen. */
PVOID     pBuffer;             /*  Address of the buffer that contains the data to write. */
ULONG     cbWrite;             /*  Number of bytes to write. */
PULONG    pcbActual;           /*  Address of the variable to receive the number of bytes actually written. */
FHLOCK    fhFileHandleLockID;  /*  The filehandle lockid obtained from DosProtectOpen. */
APIRET    ulrc;                /*  Return Code. */

ulrc = DosProtectWrite(hFile, pBuffer, cbWrite, pcbActual, fhFileHandleLockID);
</PRE>

==Parameters==
;hFile (HFILE) - input : File handle from DosOpen.
;pBuffer (PVOID) - input : Address of the buffer that contains the data to write.
;cbWrite (ULONG) - input : Number of bytes to write.
;pcbActual (PULONG) - output :  Address of the variable to receive the number of bytes actually written.
;fhFileHandleLockID (FHLOCK) - input : The filehandle lockid obtained from DosProtectOpen.

==Return Code==
 ulrc (APIRET) - returns
DosProtectWrite returns one of the following values:
* 0 NO_ERROR
* 5 ERROR_ACCESS_DENIED
* 6 ERROR_INVALID_HANDLE
* 19 ERROR_WRITE_PROTECT
* 26 ERROR_NOT_DOS_DISK
* 29 ERROR_WRITE_FAULT
* 33 ERROR_LOCK_VIOLATION
* 109 ERROR_BROKEN_PIPE

==Remarks==
DosProtectWrite begins to write at the current file-pointer position. The file pointer is automatically moved by read and write operations. It can be moved to a desired position by issuing DosProtectSetFilePtr.

If the specified file has been opened using the write-through flag, DosProtectWrite writes the data to the disk before returning. Upon return to the caller, pcbActual contains the number of bytes actually written.

If there is not enough space on the disk or diskette to write all of the bytes specified by cbWrite then DosProtectWrite does not write any bytes. Upon return to the caller, pcbActual contains zero.

A value of zero for cbWrite is not considered an error. No data transfer occurs, and there is no effect on the file or the file pointer.

If the file is read-only, the write operation to the file is not performed.

If you issue DosProtectOpen with the Direct Open flag set to 1 in the fsOpenMode parameter, you have direct access to an entire disk or diskette volume, independent of the file system. You must lock the logical volume before accessing it, and you must unlock the logical volume when you are finished accessing it. Issue DosDevIOCtl for Category 8, DSK_LOCKDRIVE to lock the logical volume, and for Category 8, DSK_UNLOCKDRIVE to unlock the logical volume. While the logical volume is locked, no other process can access it.

===Named-Pipe Considerations===
DosProtectWrite also is used to write bytes or messages to a named pipe.

Each write operation to a message pipe writes a message whose size is the length of the write operation. DosProtectWrite automatically encodes message lengths in the pipe, so applications need not encode this information in the buffer being written.

Write operations in blocking mode always write all requested bytes before returning.

In nonblocking mode, DosProtectWrite returns either with all bytes written or none written. DosProtectWrite returns with no bytes written when it would have to divide the message into blocks in order to complete the request. This can occur when there is not enough space left in the pipe, or when the pipe is currently being written to by another client. If this occurs, DosProtectWrite returns immediately with a value of zero for pcbActual indicating that no bytes were written.

For a byte pipe, if the number of bytes to be written exceeds the space available in the pipe, DosProtectWrite writes as many bytes as it can, and returns with the number of bytes actually written in pcbActual.

An attempt to write to a pipe whose other end has been closed returns ERROR_BROKEN_PIPE. 

==Example Code==
This example opens or creates and opens a file named "DOSPROT.DAT", writes to it, reads from it, and finally closes it using DosProtect functions.
<PRE>
#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;
   ULONG  ulAction       = 0;
   ULONG  ulBytesRead    = 0;
   ULONG  ulWrote        = 0;
   ULONG  ulLocal        = 0;
   UCHAR  uchFileName[20]  = "dosprot.dat",
          uchFileData[100] = " ";
   FHLOCK FileHandleLock = 0;        /* File handle lock   */
   APIRET rc             = NO_ERROR; /* Return code */

   /* Open the file test.dat.  Make it read/write, open it */
   /* if it already exists and create it if it is new.     */
   rc = DosProtectOpen(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   */
                &FileHandleLock);               /* File handle lock id     */
   if (rc != NO_ERROR) {
      printf("DosProtectOpen error: return code = %u\n", rc);
      return 1;
   } else {
     printf ("DosProtectOpen: Action taken = %u\n", ulAction);
   } /* endif */

   /* Write a string to the file */
   strcpy (uchFileData, "testing...\n3...\n2...\n1\n");

   rc = DosProtectWrite (hfFileHandle,       /* File handle                  */
                  (PVOID) uchFileData,       /* String to be written         */
                  sizeof (uchFileData),      /* Size of string to be written */
                  &ulWrote,                  /* Bytes actually written       */
                  FileHandleLock);           /* File handle lock id          */
   if (rc != NO_ERROR) {
      printf("DosProtectWrite error: return code = %u\n", rc);
      return 1;
   } else {
      printf ("DosProtectWrite: Bytes written = %u\n", ulWrote);
   } /* endif */

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

   /* Read the first 100 bytes of the file */
   rc = DosProtectRead (hfFileHandle,         /* File Handle                 */
                 uchFileData,                 /* String to be read           */
                 100L,                        /* Length of string to be read */
                 &ulBytesRead,                /* Bytes actually read         */
                 FileHandleLock);             /* File handle lock id         */
   if (rc != NO_ERROR) {
      printf("DosProtectRead error: return code = %u\n", rc);
      return 1;
   } else {
      printf("DosProtectRead: Bytes read = %u\n%s\n", ulBytesRead, uchFileData);
   } /* endif */

   rc = DosProtectClose(hfFileHandle, FileHandleLock);   /* Close the file */
   if (rc != NO_ERROR) {
      printf("DosProtectClose error: return code = %u\n", rc);
      return 1;
    }
   return NO_ERROR;
}
</PRE>

==Related Functions==
* [[DosProtectOpen]]
* [[DosProtectRead]]
* [[DosProtectSetFilePtr]]

[[Category:Dos]]