DosWriteAsync

From EDM2
Jump to: navigation, search

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

Syntax

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

Parameters

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.

Return Code

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.

Bindings

C

#define INCL_DOSFILEMGR

USHORT  rc = DosWriteAsync(FileHandle, RamSemaphore, ReturnCode,
                             BufferArea, BufferLength, BytesWritten);

HFILE   FileHandle;    /* File handle */
PULONG  RamSemaphore;  /* RAM semaphore */
PUSHORT ReturnCode;    /* I/O operation return code (returned) */
PVOID   BufferArea;    /* User buffer */
USHORT  BufferLength;  /* Buffer length */
PUSHORT BytesWritten;  /* Bytes written (returned) */

USHORT  rc;            /* return code */

MASM

EXTRN  DosWriteAsync:FAR
INCL_DOSFILEMGR     EQU 1

PUSH   WORD    FileHandle    ;File handle
PUSH@  DWORD   RamSemaphore  ;Ram semaphore
PUSH@  WORD    ReturnCode    ;I/O operation return code (returned)
PUSH@  OTHER   BufferArea    ;User buffer
PUSH   WORD    BufferLength  ;Buffer length
PUSH@  WORD    BytesWritten  ;Bytes written (returned)
CALL   DosWriteAsync

Returns WORD