DosReadAsync

Bindings:  C, MASM 

This call asynchronously transfers the specified number of bytes from a 
file, pipe, or device to a buffer. 

 DosReadAsync      (FileHandle, RamSemaphore, ReturnCode, BufferArea, 
                   BufferLength, BytesRead) 
 

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

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

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

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

 BufferLength (USHORT) - input 
    Length, in bytes, to be read. 

 BytesRead (PUSHORT) - output 
    Address of the number of bytes read. 

 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 

 The requested number of bytes may not be read. If the value in BytesRead 
 is zero, the process tried to read from the end of the file. 

 A BufferLength value of zero is not considered an error.  In the case 
 where BufferLength is zero, the system treats the request as a null 
 operation. 

 The file pointer is moved to the desired position by reading, writing, or 
 issuing DosChgFilePtr. 

 A call to DosReadAsync may return before the read is complete. To wait 
 for an asynchronous read to complete, RamSemaphore must be set by the 
 application before the DosReadAsync call is made. The application issues 
 DosSemSet to set the semaphore, calls  DosReadAsync, and then issues 
 DosSemWait, to wait to be signaled by the system that the asynchronous 
 read is complete. When RamSemaphore is cleared and the read operation is 
 complete, ReturnCode can be checked. 

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

 
 Named Pipe Considerations 

 A named pipe is read as one of the following: 

 o A byte pipe in byte read mode 
 o A message pipe in message read mode 
 o A message pipe in byte read mode. 
 

 A byte pipe must be in byte read mode to be read; an error is returned if 
 it is in message read mode. All currently available data, up to the size 
 requested, is returned. 

 When a message pipe is read in message read mode, a read that is larger 
 than the next available message returns only that message and BytesRead 
 is set to indicate the size of the message returned. 

 A read that is smaller than the next available message returns with the 
 number of bytes requested and an ERROR_MORE_DATA return code. When 
 resuming the reading of a message after ERROR_MORE_DATA is returned, a 
 read always blocks until the next piece (or rest) of the message can be 
 transferred. DosPeekNmPipe may be used to determine how many bytes are 
 left in the message. 

 A message pipe in byte read mode is read as if it were a byte stream, 
 skipping over message headers.  This is like reading a byte pipe in byte 
 read mode. 

 When blocking mode is set for a named pipe, a read blocks until data is 
 available.  In this case, the read never returns with BytesRead = 0 
 except at EOF.  In message read mode, messages are always read in their 
 entirety, except in the case where the message is bigger than the size of 
 the read. 

 Non-blocking mode allows a return with BytesRead = 0 only when trying to 
 read at the start of a message and no message is available.