mmioSetBuffer
The mmioSetBuffer function enables or disables buffered I/O, or changes the buffer or buffer size, for a file that was opened using mmioOpen.
Syntax
#define INCL_MMIOOS2 #include <os2.h> USHORT mmioSetBuffer(HMMIO hmmio, PCHAR pchBuffer, LONG cBytes, USHORT usFlags);
Parameters
- pchBuffer (PCHAR) - input
- A pointer to the caller-supplied buffer to use for buffered I/O. It can be NULL if the caller wants **mmioSetBuffer** to allocate the buffer, or wants buffered I/O to be disabled.
- cBytes (LONG) - input
- The size of the caller-supplied buffer, or (if pchBuffer is NULL) the size of the buffer that the caller wants **mmioSetBuffer** to allocate.
- usFlags (USHORT) - input
- Reserved for future use and must be set to zero.
Return Value
- rc (USHORT) - returns
- Return codes indicating success or type of failure:
- MMIO_SUCCESS: If the function succeeds, 0 is returned.
- MMIOERR_INVALID_HANDLE: The handle passed was not correct.
- MMIOERR_UNBUFFERED: Tried to disable a buffer already disabled.
- MMIOERR_INVALID_BUFFER_LENGTH: The buffer length is invalid.
- MMIOERR_CANNOTWRITE: The buffer could not be written to disk. It might be full.
- MMIOERR_READ_FAILED: Set Buffer failed during a read operation.
- MMIOERR_SEEK_FAILED: Set Buffer failed during a seek operation.
- MMIOERR_WRITE_FAILED: Set Buffer failed during a write operation.
- MMIOERR_OUTOFMEMORY: A buffer was expected but not allocated.
Remarks
The behavior of **mmioSetBuffer** depends on the combination of the pchBuffer and cBytes (referred to as cchBuffer in some contexts) parameters:
- **Disable Buffering**: If pchBuffer is NULL and cBytes is 0, buffered I/O is disabled.
- **Reallocate Buffer**: If pchBuffer is NULL, cBytes is non-zero, and buffering was already enabled (with a buffer allocated by mmioOpen or a previous call to **mmioSetBuffer**), the function reallocates the buffer to the new size. Data is preserved unless the buffer is shrunk beyond the current file position.
- **Enable/Allocate Buffer**: If pchBuffer is NULL, cBytes is non-zero, and buffering was previously disabled, the function allocates a new buffer of cBytes length and enables buffered I/O.
- **User-Provided Buffer**: If pchBuffer is not NULL and cBytes is non-zero, the specified memory block is used as the I/O buffer.
Example Code
The following code illustrates how to disable buffering for an open MMIO file.
HMMIO hmmio1;
LONG cchBuffer;
PCHAR pchBuffer;
USHORT usFlags = 0;
USHORT rc;
...
/* Set parameters to NULL and 0 to disable buffering */
pchBuffer = NULL;
cchBuffer = 0L;
rc = mmioSetBuffer(hmmio1, pchBuffer, cchBuffer, usFlags);
if (rc)
{
/* error */
}
else
{
/* Buffered I/O is now disabled */
}
...