Note: When writing message pipes the application is limited to 64K messages. As well, these messages cannot span 64k boundaries due to the current design of the thunk layer in read or write routines. If the message is not written in an aligned manner, the subsequent read will not be able to handle the messages properly. If a 64k or less message is written to a pipe from an aligned buffer, the read will handle this properly.
DosWrite 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 DosSetFilePtr.
If the specified file has been opened using the write-through flag, DosWrite 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 DosWrite 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 DosOpen 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
DosWrite 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. DosWrite 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, DosWrite returns either with all bytes written or none written. DosWrite 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, DosWrite 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, DosWrite 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 or, if the other end was closed without reading all pending data, ERROR_DISCARDED.
Clients of named pipes created with the NP_ACCESS_OUTBOUND access mode cannot use the DosWrite function. If the named pipe's client uses the DosWrite function, the function returns error code ERROR_ACCESS_DENIED.