Stata 15 help for mf_st_fopen

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


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index