mf_fopen.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{smcl}
{* *! version 1.0.0  15jun2005}{...}
{cmd:help mata fopen()}
{hline}
{* index file processing}{...}
{* index fopen()}{...}
{* index _fopen()}{...}
{* index fclose()}{...}
{* index _fclose()}{...}
{* index fget()}{...}
{* index _fget()}{...}
{* index fgetnl()}{...}
{* index _fgetnl()}{...}
{* index fread()}{...}
{* index _fread()}{...}
{* index fput()}{...}
{* index _fput()}{...}
{* index fwrite()}{...}
{* index _fwrite()}{...}
{* index fgetmatrix()}{...}
{* index _fgetmatrix()}{...}
{* index fputmatrix()}{...}
{* index _fputmatrix()}{...}
{* index fstatus()}{...}
{* index ftell()}{...}
{* index _ftell()}{...}
{* index fseek()}{...}
{* index _fseek()}{...}
{* index ftruncate()}{...}
{* index _ftruncate()}{...}

{title:Title}

{p 4 4 2}
{bf:[M-5] fopen() -- File I/O}


{title:Syntax}

{p 8 8 2}
{it:real scalar}{bind:   }
{cmd:fopen(}{it:string scalar fn}{cmd:,}
{it:mode}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:   }
{cmd:fopen(}{it:string scalar fn}{cmd:,}
{it:mode}{cmd:,}
{it:public}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:  }
{cmd:_fopen(}{it:string scalar fn}{cmd:,}
{it:mode}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:  }
{cmd:_fopen(}{it:string scalar fn}{cmd:,}
{it:mode}{cmd:,}
{it:public}{cmd:)}


{p 4 4 2}
where 
{p_end}
{p 16 18 2}
{it:mode}:  {it:string scalar} containing "{cmd:r}", "{cmd:w}", "{cmd:rw}", or
"{cmd:a}"

{p 14 18 2}
{it:public}:  optional {it:real scalar} containing zero or non zero


{p 4 4 2}
In what follows, {it:fh} is the value returned by {cmd:fopen()} or 
{cmd:_fopen()}:

{p 8 8 2}
{it:void}{bind:          }
{cmd:fclose(}{it:fh}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:  }
{cmd:_fclose(}{it:fh}{cmd:)}


{p 8 8 2}
{it:string scalar}{bind: }
{cmd:fget(}{it:fh}{cmd:)}

{p 8 8 2}
{it:string scalar}
{cmd:_fget(}{it:fh}{cmd:)}

{p 8 8 2}
{it:string scalar}{bind: }
{cmd:fgetnl(}{it:fh}{cmd:)}

{p 8 8 2}
{it:string scalar}
{cmd:_fgetnl(}{it:fh}{cmd:)}


{p 8 8 2}
{it:string scalar}{bind: }
{cmd:fread(}{it:fh}{cmd:,}
{it:real scalar len}{cmd:)}

{p 8 8 2}
{it:string scalar}
{cmd:_fread(}{it:fh}{cmd:,}
{it:real scalar len}{cmd:)}


{p 8 8 2}
{it:void}{bind:          }
{cmd:fput(}{it:fh}{cmd:,}
{it:string scalar s}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:  }
{cmd:_fput(}{it:fh}{cmd:,}
{it:string scalar s}{cmd:)}


{p 8 8 2}
{it:void}{bind:          }
{cmd:fwrite(}{it:fh}{cmd:,}
{it:string scalar s}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:  }
{cmd:_fwrite(}{it:fh}{cmd:,}
{it:string scalar s}{cmd:)}


{p 8 8 2}
{it:matrix}{bind:        }
{cmd:fgetmatrix(}{it:fh}{cmd:)}

{p 8 8 2}
{it:matrix}{bind:       }
{cmd:_fgetmatrix(}{it:fh}{cmd:)}

{p 8 8 2}
{it:void}{bind:          }
{cmd:fputmatrix(}{it:fh}{cmd:,}
{it:transmorphic matrix X}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:  }
{cmd:_fputmatrix(}{it:fh}{cmd:,}
{it:transmorphic matrix X}{cmd:)}


{p 8 8 2}
{it:real scalar}{bind:   }
{cmd:fstatus(}{it:fh}{cmd:)}


{p 8 8 2}
{it:real scalar}{bind:   }
{cmd:ftell(}{it:fh}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:  }
{cmd:_ftell(}{it:fh}{cmd:)}

{p 8 8 2}
{it:void}{bind:          }
{cmd:fseek(}{it:fh}{cmd:,}
{it:real scalar offset}{cmd:,}
{it:real scalar whence}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:  }
{cmd:_fseek(}{it:fh}{cmd:,}
{it:real scalar offset}{cmd:,}
{it:real scalar whence}{cmd:)}

{p 22 23 2}
({it:whence} is coded -1, 0, or 1, meaning from start of file, from 
current position, or from end of file; {it:offset} is signed:  positive
values mean after {it:whence} and negative values mean before)


{p 8 8 2}
{it:void}{bind:          }
{cmd:ftruncate(}{it:fh}{cmd:)}

{p 8 8 2}
{it:real scalar}{bind:  }
{cmd:_ftruncate(}{it:fh}{cmd:)}


{title:Description}

{p 4 4 2}
These functions read and write files.  First,
open the file and get back a file handle ({it:fh}).  The file handle, which is
nothing more than an integer, is how you reference the file in the calls to
other file I/O functions.  When you are finished, close the file.

{p 4 4 2}
Most file I/O functions come in two flavors: without and with an 
underscore in front of the name, such as {cmd:fopen()} and {cmd:_fopen()}, 
and {cmd:fwrite()} and {cmd:_fwrite()}.

{p 4 4 2}
In functions without a leading underscore, errors cause execution to be
aborted.  For instance, you attempt to open a file for read and the file does
not exist.  Execution stops.  Or, having successfully opened a file, you
attempt to write into it and the disk is full.  Execution stops.  When
execution stops, the appropriate error message is presented.

{p 4 4 2}
In functions with the leading underscore, execution continues and no error
message is displayed; it is your responsibility (1) to verify that things went
well and (2) to take the appropriate action if they did not.  Concerning (1),
some underscore functions return a status value; others require that you call
{cmd:fstatus()} to obtain the status information.

{p 4 4 2}
You can mix and match use of underscore and nonunderscore functions, 
using, say, {cmd:_fopen()} to open a file and {cmd:fread()} to read it, or 
{cmd:fopen()} to open and {cmd:_fwrite()} to write.


{title:Remarks}

{p 4 4 2}
Remarks are presented under the headings

	{bf:Opening and closing files}
	{bf:Reading from a file}
	{bf:Writing to a file}
	{bf:Reading and writing in the same file}
	{bf:Reading and writing matrices}
	{bf:Repositioning in a file}
	{bf:Truncating a file}
	{bf:Error codes}


{title:Opening and closing files}

{p 4 4 2}
Functions 

{p 9 9 2}
{cmd:fopen(}{it:string scalar fn}{cmd:,}
{it:string scalar mode}{cmd:)}

{p 8 8 2}
{cmd:_fopen(}{it:string scalar fn}{cmd:,}
{it:string scalar mode}{cmd:)}

{p 9 9 2}
{cmd:fopen(}{it:string scalar fn}{cmd:,}
{it:string scalar mode}{cmd:,}
{it:real scalar public}{cmd:)}

{p 8 8 2}
{cmd:_fopen(}{it:string scalar fn}{cmd:,}
{it:string scalar mode}{cmd:,}
{it:real scalar public}{cmd:)}

{p 4 4 2}
open a file.  
The file may be on a local disk, a network disk, or even on the 
web (such as http://www.stata.com/index.html). 
{it:fn} specifies the filename, and {it:mode} specifies how the file is to
opened:

	{it:mode}     meaning
	{hline 61}
	"{cmd:r}"      Open for reading; file must exist and be readable.
                 File may be "{cmd:http://...}" file.
		 File will be positioned at the beginning.

	"{cmd:w}"      Open for writing; file must not exist and the 
                 directory be writable.
                 File may not be "{cmd:http://...}" file.
		 File will be positioned at the beginning.

        "{cmd:rw}"     open for reading and writing; file must either 
                 exist and be writable or not exist and directory be
                 writable.
                 File may not be "{cmd:http://...}" file.
		 File will be positioned at the beginning (new file) 
		 or at the end (existing file).

        "{cmd:a}"      open for appending; file must either exist and be 
                 writable or not exist and directory be writable.
                 File may not be "{cmd:http://...}" file.
		 File will be positioned at the end.
	{hline 61}

{p 4 4 2}
Other values for {it:mode} cause {cmd:fopen()} and {cmd:_fopen()} to 
abort with an invalid-mode error.

{p 4 4 2}
Optional third argument {it:public} specifies whether the file, if it is 
being created, should be given permissions so that everyone can read it, 
or if it instead should be given the normal permissions.
Not specifying {it:public}, or specifying {it:public} as 0, gives the 
file the normal permissions.  Specifying {it:public} as nonzero makes the 
file publicly readable.  {it:public} is relevant only when the file is 
being created, i.e., is being opened {cmd:"w"}, or being opened {cmd:"rw"} and
not previously existing.

{p 4 4 2}
{cmd:fopen()} returns a file handle; the file is opened or execution is
aborted.

{p 4 4 2}
{cmd:_fopen()} returns a file handle or returns a negative number.
If a negative number is returned, the file is not open, and the number
indicates the reason.  In the case of {cmd:_fopen()}, there are a few 
likely possibilities

      negative
	value    meaning
	{hline 61}
	 -601    file not found
	 -602    file already exists
	 -603    file could not be opened
	 -608    file is read-only
	 -691    I/O error
	{hline 61}

{p 4 4 2}
and there are lots of other possibilities.
For instance, perhaps you attempted to open a file on the web (say
http://www.newurl.org/upinfo.doc) and the URL was not found, or the server
refused to send back the file, etc.  See {bf:Error codes} below for a complete
list of codes.

{p 4 4 2}
After opening the file, you use the other file I/O commands to read and write
it, and then you close the file using {cmd:fclose()} or {cmd:_fclose()}.
{cmd:fclose()} returns nothing; if the file cannot be closed, execution is
aborted.  {cmd:_fclose} returns 0 if successful, or a negative number
otherwise.  In the case of {cmd:_fclose()}, the likely possibilities are

      negative
	value    meaning
	{hline 61}
         -691    filesystem I/O error
	{hline 61}


{title:Reading from a file}

{p 4 4 2}
You may read from a file opened "{cmd:r}" or "{cmd:rw}".
The commands to read are

{p 9 8 2}
{cmd:fget(}{it:fh}{cmd:)}

{p 9 8 2}
{cmd:fgetnl(}{it:fh}{cmd:)}

{p 9 8 2}
{cmd:fread(}{it:fh}{cmd:,}
{it:real scalar len}{cmd:)}

{p 4 4 2}
and, of course, 

{p 8 8 2}
{cmd:_fget(}{it:fh}{cmd:)}

{p 8 8 2}
{cmd:_fgetnl(}{it:fh}{cmd:)}

{p 8 8 2}
{cmd:_fread(}{it:fh}{cmd:,}
{it:real scalar len}{cmd:)}

{p 4 4 2}
All functions, with or without an underscore, require a file handle be
specified, and all the functions return a string scalar or they return
{cmd:J(0,0,"")}, a 0 {it:x} 0 string matrix.  They return {cmd:J(0,0,"")} 
on end of
file and, in the case of the underscore functions, when the read was not
successful for other reasons.  When using the underscore functions, you use
{cmd:fstatus()} to obtain the status code; see {bf:Error codes} below.
The underscore read functions are rarely used because the only reason a 
read can fail is due to I/O error, and there is not much that can be done 
about that except abort, which is exactly what the nonunderscore functions
do.

{p 4 4 2}
{cmd:fget(}{it:fh}{cmd:)} is for reading ASCII files; the next line from the
file is returned, without end-of-line characters.
(If the line is longer then 32,768 characters, the first 32,768 characters 
are returned.)

{p 4 4 2}
{cmd:fgetnl(}{it:fh}{cmd:)} is much the same as {cmd:fget()}, except that the
newline characters are not removed from the returned result.
(If the line is longer then 32,768 characters, the first 32,768 characters 
are returned.)

{p 4 4 2}
{cmd:fread(}{it:fh}{cmd:,} {it:len}{cmd:)} is usually used for reading binary
files and returns the next {it:len} characters (bytes) from the file or, if
there are fewer than that remaining to be read, however many remain.
({it:len} may not exceed 2,147,483,647 on 32-bit computers and
9,007,199,254,740,991 (sic) on 64-bit computers; memory shortages for storing
the result will arise long before these limits are reached on most computers.)

{p 4 4 2}
The following code reads and displays a file:

	{cmd}fh = fopen(filename, "r")
	while ((line=fget(fh))!=J(0,0,"")) {
		printf("%s\n", line) 
	}
	fclose(fh){txt}


{title:Writing to a file}

{p 4 4 2}
You may write to a file opened "{cmd:w}", "{cmd:rw}", or "{cmd:a}".
The functions are 

{p 9 8 2}
{cmd:fput(}{it:fh}{cmd:,}
{it:string scalar s}{cmd:)}

{p 9 8 2}
{cmd:fwrite(}{it:fh}{cmd:,}
{it:string scalar s}{cmd:)}

{p 4 4 2}
and, of course, 

{p 8 8 2}
{cmd:_fput(}{it:fh}{cmd:,}
{it:string scalar s}{cmd:)}

{p 8 8 2}
{cmd:_fwrite(}{it:fh}{cmd:,}
{it:string scalar s}{cmd:)}

{p 4 4 2}
{it: fh} specifies the file handle, and {it:s} specifies the string to be
written.  {cmd:fput()} writes {it:s} followed by the newline characters
appropriate for your operating system.  {cmd:fwrite()} writes {it:s} alone.

{p 4 4 2}
{cmd:fput()} and {cmd:fwrite()} return nothing; {cmd:_fput()} and 
{cmd:_fwrite()} return a real scalar equal to 0 if all went well, or a 
negative error code; see {bf:Error codes} below.

{p 4 4 2}
The following code copies text from one file to another:

	{cmd}fh_in  = fopen(inputname, "r")
	fh_out = fopen(outputname, "w")
	while ((line=fget(fh_in))!=J(0,0,"")) {
		fput(fh_out, line)
	}
	fclose(fh_out)
	fclose(fh_in){txt}

{p 4 4 2}
The following code reads a file (binary or text) and changes every 
occurrence of "a" to "b":

	{cmd}fh_in  = fopen(inputname, "r")
	fh_out = fopen(outputname, "w")
	while ((c=fread(fh_in, 1))!=J(0,0,"")) {
		fwrite(fh, (c=="a" ? "b" : c))
	}
	fclose(fh_out)
	fclose(fh_in){txt}