mmioAdvance

This function fills and empties the contents of an I/O buffer of a file set up for direct I/O buffer manipulation by mmioGetInfo.

Syntax

#define INCL_MMIOOS2
#include <os2.h>

HMMIO       hmmio;      /*  Open file handle. */
PMMIOINFO   pmmioinfo;  /*  Pointer to MMIOINFO. */
USHORT      usFlags;    /*  Flags. */
USHORT      rc;         /*  Return codes. */

rc = mmioAdvance(hmmio, pmmioinfo, usFlags);

Parameters

hmmio (HMMIO) - input

The open file handle returned by mmioOpen.

pmmioinfo (PMMIOINFO) - input

A pointer to the MMIOINFO data structure that was filled in by mmioGetInfo.

usFlags (USHORT) - input

Specifies options for the operation. Contains one or more of the following flags:

• MMIO_READ: The buffer is refilled from the file. Use this when you have finished reading data from the I/O buffer and want the buffer to be refilled.
• MMIO_WRITE: The buffer is written to the file and not refilled. Use this when you have written to the end of the buffer and need it to be emptied (or expanded for a memory file).

Return Value

rc (USHORT) - returns

Return codes indicating success or type of failure:

• MMIO_SUCCESS: Function succeeds (0).
• MMIOERR_UNBUFFERED: File not opened for buffered I/O.
• MMIOERR_INVALID_HANDLE: Invalid handle.
• MMIOERR_INVALID_PARAMETER: Invalid parameter.
• MMIOERR_READ_ONLY_FILE: Write-advance requested for a read-only file.
• MMIOERR_WRITE_ONLY_FILE: Read-advance requested for a write-only file.
• ... (See Remarks for additional specific error cases like SEKK_FAILED, READ_FAILED, etc.)

Remarks

The `mmioAdvance` function does not change the current file position relative to the data. That is, `pchNext` of the MMIOINFO structure will correspond to the same data position before and after the call—the data pointed to by `pchNext` is simply moved to the beginning of the buffer.

• **Reading**: After a call with `MMIO_READ`, there will be at least $n$ bytes available between `pchNext` and `pchEndRead`, where $n$ is the lesser of the buffer size or remaining file data.
• **Writing**: After a call with `MMIO_WRITE`, there will be at least $n$ bytes of free space between `pchNext` and `pchEndWrite`.
• **Dirty Buffers**: If you have written to the buffer, you **must** set the `MMIO_DIRTY` flag in the `ulFlags` field of MMIOINFO before calling `mmioAdvance`. Otherwise, the data will not be committed to disk.
• **Pointer Updates**: The `pchNext`, `pchEndRead`, and `pchEndWrite` fields are automatically updated to reflect the new state of the I/O buffer.

Example Code

The following code illustrates how to advance the I/O buffer.

   HMMIO hmmio1;
   MMIOINFO mmioinfo;
   USHORT usFlags;
   USHORT rc;
   ...

   /* Fill usFlags with MMIO_READ or MMIO_WRITE as needed */
   rc = mmioAdvance(hmmio1, &mmioinfo, usFlags);
   if (rc) {
     /* Handle error */
   } else {
     /* Continue processing buffer */
   }

Related Functions

• mmioGetInfo
• mmioSetInfo