help mata st_fopen() undocumented
-------------------------------------------------------------------------------
Title
[M-5] st_fopen() -- Open file the Stata way
Syntax
real scalar st_fopen(filename, suffix, mode, replace, public)
real scalar st_fopen(filename, suffix, mode, replace)
real scalar st_fopen(filename, suffix, mode)
where
filename: string scalar containing filename or path and filename
such as "myfile" or "myfile.dta"; filename is updated
by st_fopen() to contain the full name of the file,
which would be "myfile.dta" in both examples
suffix: string scalar containing default suffix with leading
period, such as ".dta"
mode: string scalar containing "r", "w", or "rw"
replace: relevant only if mode is "w" or "rw";
if mode is "w", replace is an optional real scalar
containing
2 file may be overwritten (but is left in place for
read/write access) and display note if file does
not exist,
1 file may be replaced (and is erased before
opening if it already exists) and display note if
file does not exist,
0 file may not be replaced,
-1 file may be replaced (and is erased before
opening if it already exists) but do not show
note if file does not exist, or
-2 file may be overwritten (but is left in place for
read/write access) but do not show note if file
does not exist.
replace<0 treated as -1; replace>0 treated as 1;
replace==. treated as 0; replace not specified treated
as 0
if mode is "rw", replace is an optional real scalar
containing
1 file may be replaced and display note if it is,
0 file may not be replaced, or
-1 file may be replaced but do not show note if it
is.
replace<-1 treated as -2; replace>1 treated as 2;
replace==. treated as 0; replace not specified treated
as 0
public: relevant only if mode is "w" or "rw";
optional real scalar containing
0 file to be private or
1 file to be public
All nonzero (including missing) treated as 1; 1
assumed if public not specified
Description
st_fopen(filename, suffix, mode, ...) is an alternative to [M-5] fopen()
for opening files. Files can be opened only in pure read or write modes
("r" or "w"), but in return st_fopen() provides Statalike notes and error
messages and, on error, st_fopen() aborts without producing a Mata
traceback log.
If the file opens successfully, argument filename is updated with the
full filename and st_fopen() returns a file handle that can be used with
any of the other [M-5] fopen() functions just as if the file were opened
by the standard fopen().
Remarks
st_fopen() is for use in Mata functions that will be run from Stata
ado-files. st_fopen() duplicates Statalike behavior such as
. save myfile, replace
(note: file myfile.dta not found)
file myfile.dta saved
If you were writing save, it would be your responsibility to produce the
message "file myfile.dta saved", but the note about myfile.dta not being
found even though replace had been specified would be handled by
st_fopen() for you. st_fopen() also updates the shortened filename to
make it easier to produce the closing message. The code to produce the
above output would be
fh = st_fopen(filename, ".dta", "w", repflag)
...
... (code to write data)
...
printf("file %s saved\n", filename)
The above code works even when filename initially contains myfile and not
myfile.dta.
Similarly, consider the Statalike output
. save myfile
file myfile.dta already exists
r(602);
Note the lack of a Mata traceback log. The above would be created by the
same code just shown except that, here, repflag would contain 0 rather
than 1.
Conformability
st_fopen(filename, suffix, mode, replace, public):
input:
filename: 1 x 1
suffix: 1 x 1
mode: 1 x 1
replace: 1 x 1 (optional)
public: 1 x 1 (optional)
output:
filename: 1 x 1
result: 1 x 1
Diagnostics
st_fopen(filename, suffix, mode, replace, public) aborts with error --
but nicely, without a traceback log -- if filename cannot be opened.
st_fopen() aborts with error -- with a traceback log -- if it is used
improperly, such as calling it with mode different from "r" or "w".
Source code
st_fopen.mata
Also see
Manual: undocumented
Help: [M-5] fopen; [M-4] io
