*! version 1.2 11 July 2016
help for useoldversion 1.2 (11 July 2016)

Title

useold --
A convenient wrapper for unicode translate
when used under Stata 14 or younger

Table of contents

Syntax
Description
Options
Remarks
Examples
Author
Saved results
Also see

Syntax

Load Stata-format dataset

useold
filename
[,
clear
nolabel
encoding(enc)
verbose]

Load subset of Stata-format dataset

useold
[varlist]
[if] [in]
using
filename
[,
clear
nolabel
encoding(enc)
verbose]

Default options of use
clear specifies that it is okay to replace the data in memory,
even though the current data have not been saved to disk

nolabel prevents value labels in the saved data from being loaded

Advanced options of useold
encoding(enc) use enc as source encoding for file
translation, if conversion is necessary

verbose give verbose output

Description

useold acts as a wrapper for Stata 14's unicode translation commands
unicode translate and unicode analyze,
when used in Stata 14, converting the file to use into unicode.
Thereby,
it is designed to be a seamless replacement to Stata's regular use.
This means that useold is to be used in the same way as use itself,
and behaves exactly like use in Stata versions older than 14.

In most cases,
the results of using useold would be identical to those of use.
This is especially true if you use useold on Stata versions prior to 14,
where it simply passes all arguments on to use.
In Stata 14 or newer, however,
useold performs a data check on the file to be used prior to opening it.
After copying the file to a temporary file,
it is first checked with unicode analyze
in order to determine if a unicode conversion process is needed for the file.
If not, again, all arguments are passed on to Stata's use.
Else, the file is converted to unicode using Stata 14's unicode translate,
and the resulting file is opened.
In any case, the original data set file remains untouched.

Options

Default

clear is an option of Stata's regular use.
When the final data set is openend, this argument is passed on to use.

nolabel is an option of Stata's regular use.
When the final data set is openend, this argument is passed on to use.

Advanced

encoding(enc) if specified,
enc will be used as the source encoding for the input file,
if unicode translation is performed.
See encodings on a detailed description;
all encodings listed there or by unicode encoding list
are valid arguments to be used as enc.
If the option encoding(enc) is not used,
the default code page of the current operating system is assumed:
windows-1252 on Windows machines,
macroman on Mac OS machines,
and ISO-8859-1 on Unix and Linux machines.

Note that you can also define a global macro
${USEOLD_encoding} containing enc
as the desired input encoding to use, overriding this option.

verbose gives verbose output during the process.
Possibly needed for debugging conversion problems.

Remarks

useold, by performing file conversion,
oversimplifies the problem of unicode translation:

It assumes a default input encoding, depending on the current operating system,
of the source file (unless a different encoding is specified by you, the user,
using the option encoding(enc) or the global macro
${USEOLD_encoding}).
This is due to the fact that the true encoding of a given input file can not be
validly detected by Stata (or probably any other program).
Only assuming a proper input encoding can produce strange results if the
assumed encoding is different from the real encoding of the file;
please refer to Stata 14's help on unicode,
encodings and unicode encoding
for details on this topic.

Warning: Note that in case that the target file had to be
translated to unicode prior to using it,
it is the temporary copy of the file that is actually opened.
This results in an unavoidable issue:
Stata's internal macro c(filename)
now points to the name of the temporary file,
not the originally file name.
Eventually, it is not valid to use Stata's internal c(filename)
or a simple save , replace (without explicitly specifying a file name)
after this.

If this is the case, useold will issue a warning message to let you know.
In any case, it leaves a macro r(filename)
that can be used as a replacement to c(filename).

The source code of the program is licensed under the
GNU General Public License version 3 or later.
The corresponding license text can be found on the internet at
http://www.gnu.org/licenses/ or in gnugpl.

Examples

All examples in Stata's help for use apply,
with "use" replaced by "useold".

If, by now, you do not understand the meaning of the two additional options
encoding(enc) and verbose, you either will never need them or
useold is not meant for you.

Saved results

useold saves the following in r():

Macros

r(filename) the file name of the target file that has been opened

Author

Daniel Bela (daniel.bela@lifbi.de),
Leibniz Institute for Educational Trajectories (LIfBi), Germany.

Also see

NEPSmgmt (if installed), use, encodings, unicode,
unicode translate,
unicode analyze,
unicode encoding