Opening a File

Before doing any I/O operations to a file, you must first open the file using the mmioOpen function. The mmioOpen function returns a file handle which you use to identify the open file when calling other file I/O functions. The mmioOpen function has the following syntax:

HMMIO mmioOpen(szFileName, lpmmioinfo, dwFlags)

The szFileName parameter points to a null-terminated string containing the pathname of the file to open.

The lpmmioinfo parameter is a far pointer to an MMIOINFO structure containing additional parameters. For basic file I/O services, this parameter should be NULL.

The dwFlags parameter specifies options for opening the file. The most commonly used flags for basic file I/O are MMIO_READ, MMIO_WRITE, and MMIO_CREATE.

The return value is a file handle of type HMMIO. Use this file handle to identify the open file when calling other file I/O functions. If the file cannot be opened, the return value is NULL.

Warning:

An HMMIO file handle is not a MS-DOS file handle. Do not use HMMIO file handles with MS-DOS, Windows, or C run-time file I/O functions.

There are options you can use with the mmioOpen function for operations beyond basic file I/O. By specifying an MMIOINFO structure with the lpmmioinfo param-eter, you can open memory files, specify a custom I/O procedure, or supply a buffer for buffered I/O. These topics are discussed later in this chapter. First, this chapter discusses the most basic use of mmioOpen—opening files for basic unbuffered file I/O.

Summary: Opening a File

To open a file for basic I/O operations, set the lpmmioinfo parameter of mmioOpen to NULL. For example, the following code fragment opens a file named “C:\SAMPLES\SAMPLE1.TXT” for reading, and checks the return value for errors:

HMMIO hFile;
.
.
.
if ((hFile = mmioOpen("C:\\SAMPLES\\SAMPLE1.TXT", NULL, MMIO_READ)) != NULL)
        /* File opened successfully */

else
        /* File cannot be opened */

Options for Opening a File

When you open a file, you must specify whether you are opening the file for reading, writing, or both reading and writing. In addition, you can specify other options, such as to create or delete a new file. Use the dwFlags parameter of mmioOpen to specify options for opening a file.

Summary: Basic Options

The following table lists the basic options for opening a file using mmioOpen:

The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are read/write privilege flags. These flags are mutually exclusive—specify only one when opening a file. If you don't specify one of these flags, mmioOpen opens the file for reading only.

The MMIO_CREATE and MMIO_DELETE flags are also mutually exclusive. You can specify one of the read/write privilege flags with the MMIO_CREATE flag. You can't specify any additional flags with the MMIO_DELETE flag.

See “Performing Buffered File I/O,” later in this chapter, for information on using the MMIO_ALLOCBUF flag.

Summary: Sharing Options

In addition to the basic options for opening a file, there are sharing options you can use for opening MS-DOS files so they can be opened and accessed by more than one process. The following table lists the sharing options for opening a file using mmioOpen.

The sharing options are rarely used by applications, and are provided only because they are available through MS-DOS. They are not available for memory files or for files opened using custom I/O procedures. For more information on sharing options, see the Microsoft MS-DOS Programmer's Reference or the Microsoft MS-DOS Encyclopedia.

Note:

MS-DOS sharing options only work if the MS-DOS share command is used before the file is opened.