DosWriteAsync

Bindings:  C, MASM 

This call asynchronously transfers the specified number of bytes from a 
buffer to a file. 

 DosWriteAsync     (FileHandle, RamSemaphore, ReturnCode, BufferArea, 
                   BufferLength, BytesWritten) 
 

 FileHandle (HFILE) - input 
    File handle obtained from DosOpen. 

 RamSemaphore (PULONG) - input 
    Address used by the system to signal the caller that the write 
    operation is complete. 

 ReturnCode (PUSHORT) - output 
    Address of the I/O error return code. 

 BufferArea (PVOID) - input 
    Address of the output buffer. 

 BufferLength (USHORT) - input 
    Number of bytes to be written. 

 BytesWritten (PUSHORT) - output 
    Address of the number of bytes written. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    5         ERROR_ACCESS_DENIED 
    6         ERROR_INVALID_HANDLE 
    26        ERROR_NOT_DOS_DISK 
    33        ERROR_LOCK_VIOLATION 
    89        ERROR_NO_PROC_SLOTS 
    109       ERROR_BROKEN_PIPE 
 
 Remarks 

 A BufferLength value of 0 is not considered an error.  No data transfer 
 occurs.  There is no effect on the file or the file pointer. 

 A call to DosWriteAsync may return before the write is complete. To wait 
 for the asynchronous write to complete, RamSemaphore must be set by the 
 application before the DosWriteAsync call is made.  The application 
 issues DosSemSet to set the semaphore, calls DosWriteAsync, and then 
 issues DosSemWait to wait for the clearing of the semaphore, which 
 signals the write is complete. 

 When RamSemaphore is cleared, BytesWritten identifies the number of bytes 
 written.  If BytesWritten is different from BufferLength, it usually 
 indicates insufficient disk space. 

 The program must not modify the contents of BufferArea or look at the 
 values returned in ReturnCode or BytesWritten until after RamSemaphore is 
 cleared. 

 Buffers that are multiples in size of the hardware's base physical unit 
 for data, written to the file on these base boundaries, are written 
 directly to the device.  (The base physical unit is defined as the 
 smallest block that can be physically written to the device.)  Other 
 buffer sizes force at least some I/O to go through an internal system 
 buffer (if the file handle state bit indicates that internal buffers may 
 be used) and reduce the efficiency of I/O operation. 

 The read/write pointer is moved by I/O operations. It can also be moved 
 to a desired position by calling DosChgFilePtr. The value of the pointer 
 is updated by the File Level Request Router before the I/O request is 
 queued to the device driver. 

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

 Note:  If it is necessary to make a DosWriteAsync request from within a 
        segment that has I/O privilege, DosCallback may be used to invoke 
        a privilege level 3 segment, which makes the actual DosWriteAsync 
        request. 

 
 Named Pipe Considerations 

 DosWriteAsync is also used to write bytes and messages to named pipes. 

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

 Writes in blocking mode always write all requested bytes before 
 returning. In non-blocking mode, if the message size is bigger than the 
 buffer size, the write blocks . If the message size is smaller than the 
 pipe, but not enough space is left in the pipe, DosWriteAsync returns 
 immediately with a value of zero, indicating no bytes were written. 

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

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