file.hlp

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

				file read `hdl' %8z `val'
				matrix `mname'[`i',`j'] = `val'
			{c )-}
		{c )-}
		file close `hdl'
	end

{pstd}
We simply read back the value we recorded and then {cmd:file} {cmd:set} it.
We cannot directly {cmd:file} {cmd:set} {it:handle} {cmd:byteorder}
{cmd:`val'} because {cmd:`val'} is a scalar and the syntax for {cmd:file}
{cmd:set} {cmd:byteorder} is

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

{pstd}
That is, {cmd:file} {cmd:set} is willing to see a number ({cmd:1} and
{cmd:hilo} means the same thing, as do {cmd:2} and {cmd:lohi}), but that
number must be a literal (the character {it:1} or {it:2}), so we had to copy
{cmd:`val'} into a macro before we could use it.  Once we set the byte order,
however, we could from then on depend on {cmd:file} to reorder the bytes for
us should that be necessary.

{pstd}
In the third version of {cmd:mymatout}, we added a signature.  In the
modification below, we read the signature using a {cmd:%14s} format.
Strings are copied into local macros and we must specify the name of the local
macro following the format:

	program define {cmd:mymatin3}
		version {ccl stata_version}
		gettoken mname 0 : 0
		syntax using/

		tempname hdl
		file open `hdl' using `"`using'"', read binary

  /* new */     {cmd:file read `hdl' %14s signature}
  /* new */     {cmd:if "`signature'" != "mymatout 1.0.0" {c -(}}
  /* new */             {cmd:disp as err "file not mymatout 1.0.0"}
  /* new */             {cmd:exit 610}
  /* new */     {cmd:{c )-}}

		tempname val
		file read `hdl' %1b `val'
		local border = `val'
		file set `hdl' byteorder `border'

		file read `hdl' %2b `val'
		local r = `val'
		file read `hdl' %2b `val'
		local c = `val'

		matrix `mname' = J(`r', `c', 0)
		forvalues i=1(1)`r' {c -(}
			forvalues j=1(1)`c' {c -(}
				file read `hdl' %8z `val'
				matrix `mname'[`i',`j'] = `val'
			{c )-}
		{c )-}
		file close `hdl'
	end

{pstd}
In the fourth and final version, we wrote the row and column names.  You will
remember that we wrote the names by first preceding them by a 4-byte integer
recording their width:

	program define {cmd:mymatin4}
		version {ccl stata_version}
		gettoken mname 0 : 0
		syntax using/

		tempname hdl
		file open `hdl' using `"`using'"', read binary

		file read `hdl' %14s signature
  /* changed */ if "`signature'" != "mymatout 1.0.{cmd:1}" {c -(}
  /* changed */         disp as err "file not mymatout 1.0.{cmd:1}"
			exit 610
		{c )-}

		tempname val
		file read `hdl' %1b `val'
		local border = `val'
		file set `hdl' byteorder `border'

		file read `hdl' %2b `val'
		local r = `val'
		file read `hdl' %2b `val'
		local c = `val'

		matrix `mname' = J(`r', `c', 0)

  /* new */     {cmd:file read `hdl' %4b `val'}
  /* new */     {cmd:local len = `val'}
  /* new */     {cmd:file read `hdl' %`len's names}
  /* new */     {cmd:matrix rownames `mname' = `names'}

  /* new */     {cmd:file read `hdl' %4b `val'}
  /* new */     {cmd:local len = `val'}
  /* new */     {cmd:file read `hdl' %`len's names}
  /* new */     {cmd:matrix colnames `mname' = `names'}

		forvalues i=1(1)`r' {c -(}
			forvalues j=1(1)`c' {c -(}
				file read `hdl' %8z `val'
				matrix `mname'[`i',`j'] = `val'
			{c )-}
		{c )-}
		file close `hdl'
	end


{marker 3.4}{...}
{title:3.4 Use of seek when reading and writing binary files}

{pstd}
99% of all I/O programs are written without using {cmd:file} {cmd:seek}.
{cmd:file} {cmd:seek} changes your location in the file.  Ordinarily, you
start at the beginning of the file and proceed sequentially through the bytes.
{cmd:file} {cmd:seek} lets you back up or skip ahead.

{pstd}
{cmd:file} {cmd:seek} {it:handle} {cmd:query} actually does not change your
location in the file; it merely returns in scalar {cmd:r(loc)} the
current position, with the first byte in the file being numbered 0, the second
1, and so on.  In fact, all the {cmd:file} {cmd:seek} commands return
{cmd:r(loc)}, but {cmd:file} {cmd:seek} {cmd:query} is unique because that is
all it does.

{pstd}
{cmd:file} {cmd:seek} {it:handle} {cmd:tof} moves to the beginning (top) of
the file.  This is useful with {cmd:read} files when you want to read the file
again, but you can seek to tof even with {cmd:write} files and, of course,
with {cmd:read} {cmd:write} files, too.  (Concerning {cmd:read} files, we
emphasize that you can seek to top, or any point, before or after the
end-of-file condition is raised.)

{pstd}
{cmd:file} {cmd:seek} {it:handle} {cmd:eof} moves to the end of the file.
This is only useful with {cmd:write} files (or {cmd:read} {cmd:write} files),
but may be used with {cmd:read} files, too.

{pstd}
{cmd:file} {cmd:seek} {it:handle} {it:#} moves to the specified position.
{it:#} is measured in bytes from the beginning of the file and is in the
same units as reported in {cmd:r(loc)}.  {cmd:file} {cmd:seek} {it:handle}
{cmd:0} is equivalent to {cmd:file} {cmd:seek} {it:handle} {cmd:tof}.

{hline}
{p 4 4 4}
    {it:Technical note:}
    When a file is opened {cmd:write} {cmd:append}, you may not use
    {cmd:file} {cmd:seek}.  If you need to seek in the file, open the file
    {cmd:read} {cmd:write} instead.
{p_end}
{hline}


{marker A1}{...}
{title:Appendix A1:  Useful commands and functions for use with file}

{p 5 9 2}
    1.  When opening a file {cmd:read write} or {cmd:write append},
	{cmd:file}'s actions differ depending upon whether the file
	already exists.  {helpb confirm:confirm file} can tell you
	whether a file exists; use it before opening the file.

{p 5 9 2}
    2.  To obtain the length of strings when writing binary files, use the
	{help macro:macro extended function} {cmd:length}:

	    {cmd:local length : length local mystr}
	    {cmd:file write} {it:handle} {cmd:%`length's `"`mystr'"'}

{p 9 9 2}
	{cmd:length} was added to Stata at the same time as {cmd:file} and
	so is not yet documented in the manuals.  The syntax of the function
	is

{p 12 16 2}{cmd:local} {it:macname} {cmd::} {cmd:length} {c -(}{cmd:local}|{cmd:global}{c )-} {it:macname}

{p 9 9 2}
	Note, to obtain the length of local macro mystr and store it in local
	macro len, you do NOT type {cmd:local len : length "`mystr'"}; you
	type

{p 12 16 2}{cmd:local len : length local mystr}

{p 5 9 2}
    3.  To write portable binary files, we recommend writing in natural
	byte order and recording the byte order in the file.  Then the
	file can be read by reading the byte order and setting it:

	    Writing:
		{cmd:file write handle %1b (byteorder())}

	    Reading:
		{cmd:tempname mysca}
		{cmd:file read handle %1b `mysca'}
		{cmd:local b_order = `mysca'}
		{cmd:file set handle byteorder `b_order'}

{p 9 9 2}
	The {helpb function:byteorder()} function returns 1 or 2 depending on
	whether the computer being used records data in hilo or lohi format.


{marker A2}{...}
{title:Appendix A2:  Actions of binary output formats with out-of-range values}

{pstd}
Say that you write the number 2,137 with a {cmd:%1b} format.  What value will
you later get back when you read the field with a {cmd:%1b} format?  In this
case, it turns out the answer is {bf:.}, which is to say, Stata's missing
value, because the {cmd:%1b} format is in fact a variation of {cmd:%1bs} that
supports Stata's missing value.  If you wrote 2,137 with {cmd:%1bs}, it would
read back as 127; and if you wrote it with {cmd:%1bu}, it would read back as
255.

{pstd}
In general, in the Stata variation, missing values are supported and numbers
outside of the range are written as missing.  In the remaining formats, the
minimum or maximum is written as

                                            value written when value ...
  format        min value       max value        too small       to large
  {hline 72}
   {cmd:%1b}               -127             126                {bf:.}               {bf:.}
   {cmd:%1bs}              -127             127             -127             127
   {cmd:%1bu}                 0             255                0             255

   {cmd:%2b}            -32,767          32,766                {bf:.}               {bf:.}
   {cmd:%2bu}           -32,767          32,767          -32,767          32,767
   {cmd:%2bs}                 0          65,474                0          65,474

   {cmd:%4b}     -2,147,483,647   2,147,483,646                {bf:.}               {bf:.}
   {cmd:%4bs}    -2,147,483,647   2,147,483,647   -2,147,483,647   2,147,483,647
   {cmd:%4bu}                 0   4,294,967,296                0   4,294,967,296

   {cmd:%4z}             -10^36           10^36                {bf:.}               {bf:.}
   {cmd:%8z}            -10^308          10^308                {bf:.}               {bf:.}
  {hline 72}

{pstd}
In the above table, if you write {bf:.} (missing value), take that as writing
a value larger than the maximum allowed for the type.

{pstd}
If you write a noninteger value with an integer format, the result will be
truncated to an integer.  For example, writing 124.75 with a {cmd:%2b} format
is the same as writing 124.


{marker sr}{...}
{title:Saved results}

{phang}
{cmd:file} {cmd:read} returns scalar {cmd:r(eof)} containing 1 on end-of-file
and 0 otherwise.  If the file is {cmd:text}, {cmd:file} {cmd:read} also
returns macro {cmd:r(status)} containing

	{cmd:r(status)} = "win"    line read, line ended in cr-lf
		    "mac"    line read, line ended in cr
		    "unix"   line read, line ended in lf
		    "split"  line read, line was too long and so split
		    "none"   line read, line was not terminated
		    "eof"    line not read because of end-of-file

{p 8 8 2}
{cmd:r(status)}=="split" indicates that 67,783 (3,339 Small Stata)
characters of the line were returned and that the next {cmd:file}
{cmd:read} will pick up where the last read left off.

{p 8 8 2}
{cmd:r(status)}=="none" indicates that the entire line was returned, that
no line-end character was found, and the next {cmd:file} {cmd:read} will
return {cmd:r(status)}=="eof".

{p 8 8 2}
Note that if {cmd:r(status)}=="eof" ({cmd:r(eof)}==1), the local macro into
which the line was read contains "".  The local macro containing "", however,
does not imply end-of-file, because the line might simply have been empty.

{phang}
{cmd:file} {cmd:seek} returns scalar {cmd:r(loc)} containing the current
position of the file.

{phang}
{cmd:file} {cmd:query} returns scalar {cmd:r(N)} recording the number of open
files.

{phang}
The other {cmd:file} commands return nothing.


{title:Also see}

{psee}
Manual:  {bf:[P] file}

{psee}
Online:  
{helpb serset};
{helpb filefilter},
{helpb hexdump},
{helpb display};
{helpb insheet},
{helpb infile},
{helpb infix}
{p_end}