Reference » Service classes » MFile » open

Elgrint::MFile::open(MString,MFileMode) method

Declaration (see MFile.h):

void open(const MString& pathname, MFileMode fm = fmRead);

Description

Associates the object with the specified file/stream and opens it for reading and/or editing.

Parameters:

Name Type Def value Description
pathname MString

Case sensitive pathname of a file/stream to open/create (local, FTP, or HTTP/HTTPS).

Details: For HTTP/HTTPS the pathname is actually a URL (web address), which may not describe an actual file. For example, "http:www.miranor.co.il/elgrint" opens a stream based on the file "http:www.miranor.co.il/elgrint/index.html", even though "index.html" wasn't specified, because that is how HTTP works. This also means that there is no such thing as "file not found" in HTTP, unless the server itself was not found. If the server is found and successfully connected to, and the specified pathname is invalid, a file is still successfully opened (no exception is generated), but that file usually contains the 404 error page rather than useful text.

fm MFileMode fmRead

The purpose for which the file is opened: reading, appending, or overwriting.

Details:

  • fmRead - the file is opened only for reading (operator<< will generate exception 2001 in this mode). If the file doesn't exist, exception 2002 is generated
  • fmAppend - the file is opened for adding new data to the end of the file. If the file doesn't exist, a new empty file is created. This mode works only with local files (exception 2001 for online files)
  • fmOverwrite - a new empty file is created (any existing file is destroyed) and opened for writing. For local files, both writing and reading can be done in this mode. For online files, reading (operator>>) generates exception 2001
  • Any other value of fm is equivalent to fmRead

Details

If this file is already open (isOpen returns true), then it is automatically closed (see close), and the new file is opened instead (even if it is the same file).

On success, the file is opened and the file pointer is set to the initial position (see getPos): beginning of the file for fmRead and fmOverwrite (getPos returns 0), and end of the file for fmAppend (isEOF returns true). Of course, for fmOverwrite (or any empty file) the beginning of the file is the same as the end of the file.

The function can fail for many reasons with exceptions 2000 (out of memory), 2002 (file not found), 2003 (similar file already exists), 2004 (access denied), 2005 (out of resources), 2006 (lost connection on reading), and 2007 (lost connection on writing). See these exceptions for more information. If pathname is an online pathname, and connection to the server fails, exception 2040 is generated as well. The file remains closed on any error and all subsequent operations (except open) are silently ignored until the file is reopened. This means that: a) You can use isOpen to check for any error, and b) you don't have to check for errors after every operation (which is convenient).

See MFile for a usage example.

Remarks

Let us know

Please Contact us to report any errors on this page, or to suggest any improvements.

Miranor Home | About Miranor | About Elgrint | Create account | Login | Account settings | Contact Us | Privacy Policy | Site map

© Copyright 2014 by Miranor. All rights reserved. By using this site you agree to the Terms of Use.

Page last updated on August 10th, 2014.