DosReadAsync

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

This function has been eliminated since OS/2 2.0.

Syntax

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

Parameters

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.

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

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:

• A byte pipe in byte read mode
• A message pipe in message read mode
• 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.

Example Code

C Binding

#define INCL_DOSFILEMGR

USHORT  rc = DosReadAsync(FileHandle, RamSemaphore, ReturnCode, BufferArea,
                             BufferLength, BytesRead);

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

USHORT           rc;            /* return code */

MASM Binding

EXTRN  DosReadAsync: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 (returned)
PUSH   WORD    BufferLength  ;Buffer length
PUSH@  WORD    BytesRead     ;Bytes read (returned)
CALL   DosReadAsync

Returns WORD