*! version 1.3 15 March 2017
help for saveasciiversion 1.3 (15 March 2017)

Title

saveascii -- A convenient wrapper for saveold , incorporating
translation of unicode characters to extended ASCII encodings

Table of contents

Syntax
Description
Options
Remarks
Examples
Author
Also see

Syntax

Save data in memory to file in Stata 13, 12, or 11 format, converting all
characters from unicode to extended ASCII

saveascii
filename
[,
version(#) nolabel replace all nodata encoding(enc) nopreserve verbose]

Default options of saveold version(#) specify version 11<=#<=13;
default is version(13), meaning Stata 13 format

nolabel omit value labels from the saved dataset

replace overwrite existing dataset

all save e(sample) with the dataset; programmer's option

Advanced options of saveascii
nodata only convert meta data, leave data set content as it is

encoding(enc) use enc
as target encoding for file translation

nopreserve do not preserve the active (unconverted) dataset in memory

verbose give verbose output

Description

saveascii acts as a wrapper for Stata's saveold command.
In contrast to this Stata command,
it converts all string contents of the data set
(i.e. variable names, data and variable labels, value label names and contents,
characteristics' names and contents) from unicode to extended ASCII,
when the target format is older than Stata 14.
Thereby, it is designed to be a seamless replacement to Stata's regular
saveold. This means that saveascii is to be used in the same way as
saveold itself, and behaves exactly like saveold
in Stata versions older than 14.

In most cases, the results of using saveascii
would be identical to those of saveold.
This is especially true if you use saveascii
on Stata versions prior to 14, where it simply passes all arguments on to
saveold.
In Stata 14 or newer, however, saveascii
performs some conversion steps before calling saveold.
All string contents of the data set that contain unicode characters are
converted to extended ASCII, and the resulting data is saved using
saveold.

The idea for this progam came from a
thread on Statalist,
where Svend Juul and Alan Riley discussed the topic.
Most of Alan Rileys proposed solutions from this thread have been incorporated
into saveascii,
and all credits regarding these parts belong to him (and / or StataCorp).

Options

Default

version(#) is an option of Stata's regular saveold.
It specifies which previous .dta file format is to be
used. # may be 13, 12, or 11. The default is
version(13), meaning Stata 13 format. To save datasets in the modern,
Stata 14 format, use the save command, not saveold.

nolabel is an option of Stata's regular saveold.
It omits value labels from the saved dataset.
The associations between variables and value-label names, however,
are saved along with the dataset label and the variable labels.

replace is an option of Stata's regular saveold.
It permits saveold to overwrite an existing dataset.

all is an option of Stata's regular saveold.
It is for use by programmers. If specified, e(sample) will
be saved with the dataset. You could run a regression; save mydata, all;
drop _all; use mydata; and predict yhat if e(sample).

Advanced

nodata if specified,
contents of the data set will not be altered before it is saved;
only meta data will be converted.
This means that variable name and string variable content conversion is skipped.
It may at least lead to export problems with long string variables,
if the target version is below Stata 13, and saveold can not continue.
You have been warned.

encoding(enc) if specified,
enc will be used as the target encoding for the file saved
when 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
${SAVEASCII_encoding} containing enc
as the desired target encoding to use, overriding this option.

nopreserve overrides preserving the active dataset in memory;
after finishing conversion, the converted dataset will stay in memory
(and possibly be barely readable for the human eye);
this can speed up conversion for larger datasets.

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

Remarks

saveascii, by performing unicode conversion,
oversimplifies the problem of unicode translation:

It assumes a default target encoding, depending on the current operating system,
for the file saved (unless a different encoding is specified by you, the user,
using the option encoding(enc) or the global macro
${SAVEASCII_encoding}).
Only assuming a proper target encoding can produce strange results if the
assumed encoding is different from the encoding used by an older version
of Stata that later on opens the file;
please refer to Stata 14's help on unicode,
encodings and unicode encoding
for details on this topic.

When the final data set is eventually saved using saveold,
Stata may issue messages like this for each converted string:

. note: variable label "�"
contains unicode and thus may not display well in Stata #.

This message originates from saveold itself,
which can not be aware of the fact that all contents already have been
converted to the target encoding, and can be safely ignored.

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 saveold examples in Stata's
help for saveold apply,
with "saveold" replaced by "saveascii".

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

Author

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

Also see

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