file.hlp

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

{smcl}
{* 11feb2005}{...}
{cmd:help file}
{hline}

{p2colset 5 17 19 2}{...}
{p2col :{hi:[P] file} {hline 2}}Read and write ASCII text and binary files{p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 19 2}
{cmd:file} {cmd:open}
{space 1}{it:handle}
{cmd:using} {it:filename}{cmd:,}
{c -(}{cmdab:r:ead}|{cmdab:w:rite}|{cmdab:r:ead} {cmdab:w:rite}{c )-}
[
[{cmdab:t:ext}|{cmdab:b:inary}]
[{cmd:replace}|{cmd:append}]
{cmd:all}
]

{p 8 19 2}
{cmd:file} {cmdab:r:ead} {space 1}{it:handle} [{it:specs}]

{p 8 19 2}
{cmd:file} {cmdab:w:rite} {it:handle} [{it:specs}]

{p 8 19 2}
{cmd:file} {cmd:seek} {space 1}{it:handle}
{c -(}{cmdab:q:uery}|{cmd:tof}|{cmd:eof}|{it:#}{c )-}

{p 8 19 2}
{cmd:file} {cmd:set} {space 2}{it:handle}
{cmd:byteorder}
{c -(}{cmd:hilo}|{cmd:lohi}|{cmd:1}|{cmd:2}{c )-}

{p 8 19 2}
{cmd:file} {cmd:close}
{c -(}{it:handle}|{cmd:_all}{c )-}

{p 8 19 2}
{cmd:file} {cmdab:q:uery}

{pstd}
where {it:specs} for ASCII {cmd:text} output is

	{cmd:"}{it:string}{cmd:"} or {cmd:`"}{it:string}{cmd:"'}
	{cmd:(}{it:exp}{cmd:)}{col 40}(note that parentheses are required)
	{cmd:%}{it:fmt} {cmd:(}{it:exp}{cmd:)}{col 40}(see {helpb format} about {cmd:%}{it:fmt})
	{cmd:_skip(}{it:#}{cmd:)}
	{cmdab:_col:umn(}{it:#}{cmd:)}
	{cmdab:_n:ewline}[{cmd:(}{it:#}{cmd:)}]
	{cmd:_char(}{it:#}{cmd:)}{col 40}(0 {ul:<} {it:#} {ul:<} 255)
	{cmd:_tab}[{cmd:(}{it:#}{cmd:)}]
	{cmd:_page}[{cmd:(}{it:#}{cmd:)}]
	{cmd:_dup(}{it:#}{cmd:)}

{pstd}
{it:specs} for ASCII {cmd:text} input is {it:localmacroname},

{pstd}
{it:specs} for {cmd:binary} output is

	{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}
and {it:specs} for {cmd:binary} input is

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


{title:Description}

{pstd}
{cmd:file} is a programmer's command and should not be confused with
{helpb insheet}, {helpb infile}, and {helpb infix}, which are the usual ways
data are brought into Stata.  {cmd:file} allows programmers to read and write
both ASCII text and binary files, so {cmd:file} could be used to write a
program to input data in some complicated situation, but that would be an
undertaking.

{pstd}
Files are referenced by a file {it:handle}.  When you open a file, you
specify the file handle you want to use; for example, in

	{cmd:. file open myfile using example.txt, write}

{pstd}
{cmd:myfile} is the file handle for the file named {cmd:example.txt}.  From
that point on, you refer to the file by its handle.  Thus

	{cmd:. file write myfile "this is a test" _n}

{pstd}
would write the line "this is a test" (without the quotes) followed by a
newline into the file, and

	{cmd:. file close myfile}

{pstd}
would then close the file.  You may have multiple files open at the same time,
and you may access them in any order.


{title:Options}

{phang}
{cmd:read}, {cmd:write}, and {cmd:read write} are required; they specify
    how the file is to be opened.  If the file is opened {cmd:read},
    you can subsequently use {cmd:file} {cmd:read} but not {cmd:file}
    {cmd:write}; if the file is opened {cmd:write}, you can subsequently use
    {cmd:file} {cmd:write} but not {cmd:file} {cmd:read}.  If the file
    is opened {cmd:read} {cmd:write}, you can subsequently use both.

{pmore}
    {cmd:read} {cmd:write} is more flexible, but most programmers open
    files purely {cmd:read} or purely {cmd:write} because that is all that is
    necessary; it is safer, and it is faster.

{pmore}
    When a file is opened {cmd:read}, the file must already exist, or an
    error message will be issued.  The file is positioned at the top
    (tof), so the first {cmd:file} {cmd:read} reads at the beginning of the
    file.  Both local files and files over the net may be opened for
    {cmd:read}.

{pmore}
    When a file is opened {cmd:write}, and the options {cmd:replace} or
    {cmd:append} are not specified, the file must not exist, or an error
    message will be issued.  The file is positioned at the top (tof), so the
    first {cmd:file} {cmd:write} writes at the beginning of the file.  Net
    files may not be opened for {cmd:write}.

{pmore}
    When a file is opened {cmd:write} and option {cmd:replace} is also
    specified, it does not matter whether the file already exists; the
    existing file, if any, is erased before hand.

{pmore}
    When a file is opened {cmd:write} and option {cmd:append} is also
    specified, it also does not matter whether the file already exists; the
    file will be reopened or created if necessary.  The file will be
    positioned at the append point, meaning that if the file existed, the
    first {cmd:file} {cmd:write} will write at the first byte past the end of
    the previous file; if there was no previous file, {cmd:file} {cmd:write}
    begins writing at the first byte in the file.  {cmd:file} {cmd:seek} may
    not be used with {cmd:write} {cmd:append} files.

{pmore}
    When a file is opened {cmd:read} {cmd:write}, it also does not matter
    whether the file exists.  If the file exists, it is reopened.  If the
    file does not exist, a new file is created.  Regardless, the file will be
    positioned at the top of file.  You can use {cmd:file} {cmd:seek} to
    seek to the end of the file or wherever else you desire.  Net files may
    not be opened for {cmd:read} {cmd:write}.

{pmore}
    Before opening a file, you can determine whether it exists using
    {cmd:confirm} {cmd:file}; see {helpb confirm}.

{phang}
{cmd:text} and {cmd:binary} determine how the file is to be treated once it is
    opened.  {cmd:text} means ASCII text files, and that is the default.
    In ASCII {cmd:text}, files are
    assumed to be composed of lines of characters, with each line ending
    in a line-end character.  The character varies across operating systems,
    being linefeed under Unix, carriage return under Macintosh, and carriage
    return/line feed under Windows.  {cmd:file} understands all the ways lines
    might end when reading and assumes lines are to end in the usual way for
    the computer being used when writing.

{pmore}
    The alternative to {cmd:text} is {cmd:binary}, meaning that the file is
    to be viewed merely as a stream of bytes.  In binary files, there is an
    issue of byte order; consider the number 1 written as a 2-byte integer.
    On some computers (called hilo), it is written as {bind:"00 01"} and on
    other computers (called lohi), it is written as {bind:"01 00"} (with the
    least significant byte written first).  There are similar issues for 4-byte
    integers, 4-byte floats, and 8-byte floats.

{pmore}
    {cmd:file} assumes that the bytes are ordered in the way natural to the
    computer being used.  {cmd:file} {cmd:set} can be used to vary this
    assumption.  {cmd:file} {cmd:set} can be issued immediately after the
    {cmd:file} {cmd:open}, or later, or repeatedly.

{phang}
    {cmd:replace} and {cmd:append} are only allowed when the file is opened for
    {cmd:write} (which does not include {cmd:read} {cmd:write}).  They
    determine what is to be done if the file already exists.  The default is
    to issue an error message and not open the file.  See the description of
    the options {cmd:read}, {cmd:write}, and {cmd:read} {cmd:write} above for
    more details.

{phang}
    {cmd:all} is allowed when the file is opened for {cmd:write} or for
    {cmd:read} {cmd:write}.  It specifies that, if the file needs to be
    created, the permissions on the file are to be set so that it is readable
    by everybody.


{title:ASCII text output specifications}

{phang}
{cmd:"}{it:string}{cmd:"} and {cmd:`"}{it:string}{cmd:"'} write {it:string}
    into the file, without the surrounding quotes.

{phang}
{cmd:(}{it:exp}{cmd:)} evaluates the expression {it:exp} and writes the result
    in the file.  If the result is numeric, it is written with a {cmd:%10.0g}
    format, but with leading and trailing spaces removed.  If {it:exp}
    evaluates to a string, the resulting string is written, with no extra
    leading or trailing blanks.

{phang}
{cmd:%}{it:fmt} {cmd:(}{it:exp}{cmd:)} evaluates expression {it:exp} and
    writes the result with the specified {cmd:%}{it:fmt}.  If {it:exp}
    evaluates to a string, {cmd:%}{it:fmt} must be a string format, and,
    correspondingly, if {it:exp} evaluates to a real, a numeric format must be
    specified.  Do not confuse Stata's standard display formats with the
    binary formats {cmd:%b} and {cmd:%z} described elsewhere in this help
    file.  {cmd:file} {cmd:write} in this case allows Stata's display formats
    described in {helpb format} and also allows the centering extensions (e.g.,
    {cmd:% 20s}) described in {bind:{cmd:[P] display}}.

{phang}
{cmd:_skip(}{it:#}{cmd:)} inserts {it:#} blanks into the file.  If
{it:#}{ul:<}0, nothing is written; {it:#}{ul:<}0 is not considered an error.

{phang}
{cmd:_column(}{it:#}{cmd:)} writes a sufficient number of blanks to skip
    forward to column {it:#} of the line; if {it:#} refers to a prior
    column, nothing is displayed.  The first column of a line is numbered 1.
    Referring to a column less than 1 is not considered an error; nothing is
    displayed in that case.

{phang}
{cmd:_newline}[{cmd:(}{it:#}{cmd:)}], which may be abbreviated
    {cmd:_n}[{cmd:(}{it:#}{cmd:)}], outputs one end-of-line character if
    {it:#} is not specified, or outputs the specified number of end-of-line
    characters.  The end-of-line character varies according to your operating
    system, being line feed under Unix, carriage return under Macintosh, and
    the two characters carriage return/line feed under Windows.  If
    {it:#}{ul:<}0, no end-of-line character is output.

{phang}
{cmd:_char(}{it:#}{cmd:)} outputs one character, being the one
    given by the ASCII code {it:#} specified.  {it:#} must be between 0 and
    255, inclusive.

{phang}
{cmd:_tab}[{cmd:(}{it:#}{cmd:)}] outputs one tab character if {it:#} is not
    specified, or outputs the specified number of tab characters.  Coding
    {cmd:_tab} is equivalent to coding {cmd:_char(9)}.

{phang}
{cmd:_page}[{cmd:(}{it:#}{cmd:)}] outputs one pagefeed character if
    {it:#} is not specified, or outputs the specified number of pagefeed
    characters.  Coding {cmd:_page} is equivalent to coding {cmd:_char(12)}.
    The pagefeed character is often called control-L.

{phang}
{cmd:_dup(}{it:#}{cmd:)} specified that the next directive is to be executed
    (duplicated) {it:#} times.  {it:#} must be greater than or equal to 0.
    If {it:#} is equal to zero, the next element is not displayed.


{title:Remarks}

{pstd}
Remarks are presented under the headings

	{bf:{help file##1.1:1.1 Use of file}}
	{bf:{help file##1.2:1.2 Use of file with tempfiles}}

	{bf:{help file##2.1:2.1.Writing ASCII text files}}
	{bf:{help file##2.2:2.2 Reading ASCII text files}}
{phang2}{bf:{help file##2.3:2.3 Use of seek when reading and writing ASCII text files}}

	{bf:{help file##3.1:3.1 Reading and writing binary files}}
	{bf:{help file##3.2:3.2 Writing binary files}}
	{bf:{help file##3.3:3.3 Reading binary files}}
{phang2}{bf:{help file##3.4:3.4 Use of seek when reading and writing binary files}}

{p 8 24 2}{bf:{help file##A1:Appendix A1:  Useful commands and functions for use with file}}{p_end}
{p 8 24 2}{bf:{help file##A2:Appendix A2:  Actions of binary output formats with out-of-range values}}

{phang2}{bf:{help file##sr:Saved results}}


{marker 1.1}{...}
{title:1.1 Use of file}

{pstd}
{cmd:file} provides low-level access to file I/O.  You open the file, use
{cmd:file} {cmd:read} or {cmd:file} {cmd:write} repeatedly to read or write
the file, and then close the file using {cmd:file} {cmd:close}:

	{cmd:file open} ...
	...
	{cmd:file read}  or  {cmd:file write} ...
	...
	{cmd:file read}  or  {cmd:file write} ...
	...
	{cmd:file close} ...

{pstd}
Do not forget to close the file.  Open files tie up system resources.
In addition, in the case of files opened for write, the contents of the