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.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs