file.hlp

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

file probably will not be fully written until you close the file.

{pstd}
Typing {cmd:file} {cmd:close} {cmd:_all} will close all open files, and the
{helpb clear} command closes all files as well.  These commands, however,
should not be included in programs you write; they are included to allow the
user to reset Stata when programmers have been sloppy.

{pstd}
If you use file handles obtained from {helpb tempname}, the file will be
automatically closed when the ado-file terminates:

	{cmd:tempname myfile}
	{cmd:file open `myfile' using} ...

{pstd}
This is the only case where it is appropriate not to close the file.  Use of
temporary names for filehandles offers considerable advantages because
programs can be stopped because of errors or because the user presses Break.


{marker 1.2}{...}
{title:1.2 Use of file with tempfiles}

{pstd}
In the rare event that you {cmd:file} {cmd:open} a {helpb tempfile}, you must
obtain the handle from {helpb tempname}.  Temporary files are automatically
deleted when the ado- or do-file ends.  If the file is erased before it is
closed, significant problems are possible.  Using a tempname will guarantee
that the file is properly closed beforehand:

	{cmd:tempname myfile}
	{cmd:tempfile tfile}
	{cmd:file open `myfile' using "`tfile'"} ...


{marker 2.1}{...}
{title:2.1 Writing ASCII text files}

{pstd}
This is easy to do:

{phang2}{cmd:file open} {it:handle} {cmd:using} {it:filename}{cmd:, write text}
	{cmd:file write} {it:handle} ...
	...
	{cmd:file close} {it:handle}

{pstd}
The syntax of {cmd:file} {cmd:write} is very similar to that of
{helpb display}.  The significant difference is that expressions must be
bound in parentheses.  In {cmd:display}, you can code

	{cmd:display 2+2}

{pstd}
but using {cmd:file} {cmd:write}, you must code

	{cmd:file write} {it:handle} {cmd:(2+2)}

{pstd}
The other important difference between {cmd:file} {cmd:write} and
{cmd:display} is that {cmd:display} assumes you want the end-of-line character
output at the end of each {cmd:display} (and {cmd:display} provides
{cmd:_continue} for use when you do not want this), but {cmd:file} {cmd:write}
assumes you want an end-of-line character only when you specify it.  Thus
rather than coding "{cmd:file write} {it:handle} {cmd:(2+2)}", you probably
want to code

{phang2}{cmd:file write} {it:handle} {cmd:(2+2)} {cmd:_n}

{pstd}
Since Stata outputs end-of-line characters only where you specify, coding

{phang2}{cmd:file write} {it:handle} {cmd:"first part is " (2+2)} {cmd:_n}

{pstd}
has the same effect as coding

{phang2}{cmd:file write} {it:handle} {cmd:"first part is "}{p_end}
{phang2}{cmd:file write} {it:handle} {cmd:(2+2)} {cmd:_n}

{pstd}
or even

{phang2}{cmd:file write} {it:handle} {cmd:"first part is "}{p_end}
{phang2}{cmd:file write} {it:handle} {cmd:(2+2)}{p_end}
{phang2}{cmd:file write} {it:handle} {cmd:_n}

{pstd}
There is no limit to the line length that {cmd:file} {cmd:write} can write
since, as far as {cmd:file} {cmd:write} is concerned, {cmd:_n} is just
another character.  The {cmd:_col(}{it:#}{cmd:)} directive, however, will lose
count if you write lines of more than 2,147,483,646 characters
({cmd:_col(}{it:#}{cmd:)} skips forward to the specified column).  In general,
we recommend you do not write lines longer than 67,783 characters because
reading lines longer than that is more difficult using {cmd:file} {cmd:read}.

{pstd}
We say that {cmd:_n} is just another character, but we should say character or
characters.  {cmd:_n} outputs the appropriate end-of-line character for your
operating system, meaning the two-characters carriage return followed by
line feed under Windows, the one character carriage return under Macintosh,
and line feed under Unix.


{marker 2.2}{...}
{title:2.2 Reading ASCII text files}

{pstd}
The commands for reading text files are similar to those for writing them:

{phang2}{cmd:file open} {it:handle} {cmd:using} {it:filename}{cmd:, read text}{p_end}
{phang2}{cmd:file read} {it:handle} {it:localmacroname}
	...
	{cmd:file close} {it:handle}

{pstd}
The {cmd:file} {cmd:read} command has exactly one syntax:

{phang2}{cmd:file read} {it:handle} {it:localmacroname}

{pstd}
One line is read from the file, and it is put in {it:localmacroname}.
For instance, to read a line from the file myfile and put it in the local macro
line, you code

	{cmd:file read myfile line}

{pstd}
Thereafter in your code, you can refer to {cmd:`line'} to obtain the contents
of the line just read.  The following program will do a reasonable job of
displaying the contents of file, putting line numbers in front of the lines:

	{cmd:program define ltype}
		{cmd:version {ccl stata_version}}
		{cmd:local 0 `"using `0'"'}
		{cmd:syntax using/}
		{cmd:tempname fh}
		{cmd:local linenum = 0}
		{cmd:file open `fh' using `"`using'"', read}
		{cmd:file read `fh' line}
		{cmd:while r(eof)==0 {c -(}}
			{cmd:local linenum = `linenum' + 1}
			{cmd:display %4.0f `linenum' _asis `"  `macval(line)'"'}
			{cmd:file read `fh' line}
		{cmd:{c )-}}
		{cmd:file close `fh'}
	{cmd:end}

{pstd}
In the program above, notice our use of {helpb tempname} to obtain a temporary
name for the file handle.  Doing that, we ensure that the file will be closed
even if the user presses Break while our program is displaying lines, and so
never executes "{cmd:file close `fh'}".  In fact, our
"{cmd:file close `fh'}" line is unnecessary.

{pstd}
Also note our use of {cmd:r(eof)} to determine when the file ends.  {cmd:file}
{cmd:read} sets {cmd:r(eof)} to contain 0 before end-of-file and 1 once
end-of-file is encountered; see {bf:Saved results}, below.

{pstd}
As an aside, the {cmd:_asis} was included in the {cmd:display} in case the
file contained braces or SMCL commands.  These would be interpreted,
and we wanted to suppress that interpretation so that {cmd:ltype} would
display lines exactly as stored; see {helpb smcl}.  We also used the 
{cmd:macval()} macro function to obtain what was in {cmd:`line'} without
recursively expanding the contents of line.


{marker 2.3}{...}
{title:2.3 Use of seek when reading and writing ASCII text files}

{pstd}
You may use {cmd:file} {cmd:seek} when reading or writing text files, although,
in fact, it is seldomly used, except with {cmd:read} {cmd:write} files and,
even then, seldomly used with ASCII text files.

{pstd}
See {bf:{help file##3.4:3.4 Use of seek when reading and writing binary files}}
below for a complete description of {cmd:file} {cmd:seek}{hline 2}{cmd:seek}
works the same way with both text and binary files{hline 2}and then bear the
following in mind:

{p 8 11 2}
o{space 2}The {it:#} in "{cmd:file} {cmd:seek} {it:handle} {it:#}" refers
 to byte position, not line number.  "{cmd:file} {cmd:seek} {it:handle}
 {cmd:5}" means to seek to the fifth byte of the file, not the fifth line.

{p 8 11 2}
o{space 2}When calculating byte offsets by hand, remember that the end-of-line
 character is 1 byte under Macintosh and Unix but 2 bytes under Windows.

{p 8 11 2}
o{space 2}Rewriting a line of an ASCII text file works as expected only if
 the new and old lines are of the same length.


{marker 3.1}{...}
{title:3.1 Reading and writing binary files}

{pstd}
Consider whether you wish to read this section.  There are lots of potential
pitfalls associated with binary files, and, at least in theory, a poorly
written binary-I/O program can cause Stata to crash.

{pstd}
Binary files are made up of binary elements, of which Stata can understand:

    Element                                          corresponding format
    {hline 69}
    single- and multiple-character strings           {cmd:%1s} and {cmd:%}{it:#}{cmd:s}
    signed and unsigned 1-byte binary integers       {cmd:%1b}, {cmd:%1bs}, and {cmd:%1bu}
    signed and unsigned 2-byte binary integers       {cmd:%2b}, {cmd:%2bs}, and {cmd:%2bu}
    signed and unsigned 4-byte binary integers       {cmd:%4b}, {cmd:%4bs}, and {cmd:%4bu}
    4-byte IEEE floating point numbers               {cmd:%4z}
    8-byte IEEE floating point numbers               {cmd:%8z}
    {hline 69}

{pstd}
The differences between all these types are only of interpretation.  For
instance, the decimal number 72, stored as a 1-byte binary integer, also
represents the character H.  If a file contained the 1-byte integer 72 and you
were to read the byte using the format {cmd:%1s}, you would get back the
character "H", and if a file contained the character "H" and you were to read
the byte using the format {cmd:%1bu}, you would get back the number 72.  72
and H are indistinguishable in that they represent the same bit pattern.
Whether that bit pattern represents 72 or H depends on the format you use,
which is to say, the interpretation you give to the field.

{pstd}
Similar equivalence relations hold between the other elements.
A binary file is nothing more than a sequence of unsigned 1-byte integers
where those integers are sometimes given different interpretations or grouped
and given an interpretation and in fact, all you need is the format {cmd:%1bu}
and you could read or write anything.  The other formats, however, make
programming more convenient.

                                                                    missing
    format  length   type               minimum         maximum     values?
    {hline 71}
    {cmd:%1bu}      1    unsigned int               0             255       no
    {cmd:%1bs}      1    signed int              -127             127       no
    {cmd:%1b}       1    Stata int               -127             100       yes

    {cmd:%2bu}      2    unsigned int               0          65,474       no
    {cmd:%2bs}      2    signed int           -32,767          32,767       no
    {cmd:%2b}       2    Stata int            -32,767          32,740       yes

    {cmd:%4bu}      4    unsigned int             647   4,294,967,296       no
    {cmd:%4bs}      4    signed int    -2,147,483,647   2,147,483,647       no
    {cmd:%4b}       4    Stata int     -2,147,483,647   2,147,483,620       yes

    {cmd:%4z}       4    float                 -10^38           10^38       yes
    {cmd:%8z}       8    float                -10^307           10^307      yes
    {hline 71}

{pstd}
When you write a binary file, you must decide on the format you will use
for every element you will write.  When you read a binary file, you must
know ahead of time the format that was used for each of the elements.


{marker 3.2}{...}
{title:3.2 Writing binary files}

{pstd}
As with ASCII text files, you open the file, write repeatedly, and then close
the file:

{phang2}{cmd:file open} {it:handle} {cmd:using} {it:filename}{cmd:, write binary}{p_end}
	{cmd:file write} {it:handle} ...
	...
	{cmd:file close} {it:handle}

{pstd}
The {cmd:file} {cmd:write} command may be composed of the following elements:

	{cmd:%}{c -(}{cmd:8}|{cmd:4}{c )-}{cmd:z}        {cmd:(}{it:exp}{cmd:)}
	{cmd:%}{c -(}{cmd:4}|{cmd:2}|{cmd:1}{c )-}{cmd:b}[{cmd:s}|{cmd:u}] {cmd:(}{it:exp}{cmd:)}
	{cmd:%}{it:#}{cmd:s}            {cmd:"}{it:text}{cmd:"}{col 40}(1 {ul:<} {it:#} {ul:<} 67,783)
	{cmd:%}{it:#}{cmd:s}            {cmd:`"}{it:text}{cmd:"'}
	{cmd:%}{it:#}{cmd:s}            {cmd:(}{it:exp}{cmd:)}

{pstd}
For instance, to write "test file" followed by 2, 2+2, and 3*2 represented in
various of its forms, you could code

{phang2}{cmd:. file write} {it:handle} {cmd:%9s "test file" %8z (2) %4b (2+2) %1bu (3*2)}

{pstd}
or

{phang2}{cmd:. file write} {it:handle} {cmd:%9s "test file"}{p_end}
{phang2}{cmd:. file write} {it:handle} {cmd:%8z (2) %4b (2+2) %1bu (3+2)}

{pstd}
or even

{phang2}{cmd:. file write} {it:handle} {cmd:%9s "test file" }{p_end}
{phang2}{cmd:. file write} {it:handle} {cmd:%8z (2) }{p_end}
{phang2}{cmd:. file write} {it:handle} {cmd:%4b (2+2) %1bu (3*2)}

{pstd}
etc.

{pstd}
You write strings using the {cmd:%}{it:#}{cmd:s} format and numbers using the
{cmd:%b} or {cmd:%z} formats.  Concerning strings, the {it:#} in
{cmd:%}{it:#}{cmd:s} should be greater than or equal to the length of the
string to be written.  If {it:#} is too small, only that many characters of
the string will be written.  Thus

{phang2}{cmd:. file write} {it:handle} {cmd:%4s "test file"}

{pstd}
would write "test" into the file and leave the file positioned at the fifth