*! version 0.9 01 March 2012
help for esaveversion 0.9 (01 March 2012)

Title

esave -- extended save

Table of contents

Syntax
Description
Options
Main options
Options for ASCII export
Options for spreadsheet export
Other options
Remarks
Author
Also see

Syntax

esave [using] filename [, options]

Main
format(string) data format for file export

Options for ASCII export
delimiter("char") use char as delimiter (ascii_custom format only)

nonames do not write variable names on the first line (ascii_custom, ascii_tab, ascii_comma and ascii_semicolon formats only)

noquote do not enclose strings in double quotes (ascii_custom, ascii_tab, ascii_comma and ascii_semicolon formats only)

Options for spreadsheet export
sheet("sheetname") saves to the worksheet named sheetname (ooxml and excel formats only)

cell(start) specifies the start (upper-left) cell in the Excel worksheet to begin saving to (ooxml and excel formats only)

sheetmodify exports data to the worksheet without changing the cells outside the exported range (ooxml and excel formats only)

sheetreplace clears the worksheet before the data are exported to it (ooxml and excel formats only)

firstrow(variables|varlabels) specifies that the variable names or the variable labels
be saved in the first row in the Excel worksheet (ooxml and excel formats only)

datestring("datetime_format") exports all datetime variables as strings formatted by datetime_format
(ooxml and excel formats only)

missing("repval") exports missing values as repval (ooxml and excel formats only)

locale("locale") specifies the locale used by the workbook (ooxml and excel formats only)

legible format XML to be more legible (xml_excel and xml_stata formats only)

Other options
nolabel export values instead of value labels, if any
(ooxml, excel, ascii_custom, ascii_tab, ascii_comma, ascii_semicolon, stata and stata_old formats only)

orphans save all value labels (stata format only)

emptyok save dataset even if zero observations and zero variables (stata format only)

all save e(sample) with the dataset; programmer's option (stata and stata_old formats only)

rename rename variables and value labels to meet SAS XPORT restrictions (sas format only)

vallabfile(xpf) save value labels in formats.xpf (sas format only)

vallabfile(sascode) save value labels in SAS command file (sas format only)

vallabfile(both) save value labels in formats.xpf and in a SAS command file (sas format only)

vallabfile(none) do not save value labels (sas format only)

replace overwrite existing file without warning

verbose give verbose output

Description

esave is a wrapper for Stata's most common file export commands. Currently, it can replace the commands save, saveold, outsheet, export excel,
export sasxport (formerly: fdasave) and xmlsave.

For ease of use, esave provides one single command to write various dataset formats. It determines which of Stata's export commands to use by the format option,
or, if not specified, by parsing the filename's file extension. Thereby, it can pass through various commonly used options to the appropriate file export routine.

Options

Main

format(format) file format to write the using file to.

If not specified, the appropriate format is guessed by the given file extension, if any. If this is not possible, stata format is used.

Supported formats are:

stata: Stata file format (typical extension: dta). This is equivalent to running the command save.

This is the default if no format is specified and the file extension is dta.

stata_old: Stata file format (typical extension: dta), old version. This is equivalent to running the command saveold.

Note that the file format version is dependent on your Stata's version: Stata 12 will save in datasets suitable for Stata 9/10, whilst Stata 11 will save in Stata 8/9 format, and so on.

ascii_tab: ASCII format, tab-separated (typical extension: txt or dat). This is equivalent to running the command outsheet.

This is the default if no format is specified and the file extension is dat.

ascii_comma: ASCII format, comma-separated (typical extension: txt or csv). This is equivalent to running the command outsheet with option comma.

This is the default if no format is specified and the file extension is txt or csv.

ascii_semicolon: ASCII format, semicolon-separated (typical extension: txt or csv). This is equivalent to running the command outsheet with option delimiter(";").

This is needed to seamlessly export a CSV file to Microsoft Excel. Note that it may be easier to use one of the formats ooxml, excel or xml_excel (whilst ooxml is recommended in this case).

ascii_custom: ASCII format, separated by custom character. This is equivalent to running the command outsheet.

You need to specify the delimiter option for this format, or it will be changed to ascii_tab.

ooxml: Microsoft Excel spreadsheet format, version of Microsoft Office 2007 or newer (typical extension: xlsx) - also known as Office Open XML (OOXML).
This is equivalent to running the command export excel. This is the recommended option for exporting spreadsheets.

This is the default if no format is specified and the file extension is xlsx, and will be overridden if the file extension is xls.

excel: Microsoft Excel spreadsheet format, version prior to Microsoft Office 2007 (typical extension: xls).
This is equivalent to running the command export excel.
This is not recommended unless you necessarily have to export to old Excel versions, in any other case please consider using the ooxml format.

It is the default if no format is specified and the file extension is xls, and will be overridden if the file extension is xlsx.

sas: SAS XPORT format (typical extension: xpt). This is equivalent to running the command export sasxport (in Stata 12 or newer) or fdause (older Stata versions).

This is the default if no format is specified and the file extension is xpt.

xml_stata: XML file format, Stata DTD (typical extension: xml). This is equivalent to running the command xmlsave with option doctype(dta).

xml_excel: XML file format, Microsoft SpreadsheetML DTD (typical extension: xml). This is equivalent to running the command xmlsave with option doctype(excel).

This is the default if no format is specified and the file extension is xml.

Options for ASCII export

demiliter(char) use char as delimiter.
This option is only valid with the ascii_custom format, and mandatory for this format;
it will be passed to outsheet. See the corresponding help file for details:
outsheet

nonames do not write variable names on the first line.
This option is only valid with one of the formats ascii_custom, ascii_tab, ascii_comma or ascii_semicolon,
and will be passed to outsheet. Refer to the corresponding help file for details:
outsheet

noquote do not enclose strings in double quotes.
This option is only valid with one of the formats ascii_custom, ascii_tab, ascii_comma or ascii_semicolon,
and will be passed to outsheet. Refer to the corresponding help file for details:
outsheet

Options for spreadsheet export

sheet("sheetname") saves to the worksheet named sheetname.
This option is only valid with one of the formats ooxml or excel,
and will be passed to export excel. Refer to the corresponding help file for details:
export excel

cell(start) specifies the start (upper-left) cell in the Excel worksheet to begin saving to.
This option is only valid with one of the formats ooxml or excel,
and will be passed to export excel. Refer to the corresponding help file for details:
export excel

sheetmodify exports data to the worksheet without changing the cells outside the exported range.
This option is only valid with one of the formats ooxml or excel,
and will be passed to export excel. Refer to the corresponding help file for details:
export excel

sheetreplace clears the worksheet before the data are exported to it.
This option is only valid with one of the formats ooxml or excel,
and will be passed to export excel. Refer to the corresponding help file for details:
export excel

firstrow(variables|varlabels) specifies that the variable names or the variable labels be saved in the first row in the Excel worksheet.
This option is only valid with one of the formats ooxml or excel,
and will be passed to export excel. Refer to the corresponding help file for details:
export excel

datestring("datetime_format") exports all datetime variables as strings formatted by datetime_format.
This option is only valid with one of the formats ooxml or excel,
and will be passed to export excel. Refer to the corresponding help file for details:
export excel

missing("repval") exports missing values as repval.
This option is only valid with one of the formats ooxml or excel,
and will be passed to export excel. Refer to the corresponding help file for details:
export excel

locale("locale") specifies the locale used by the workbook.
This option is only valid with one of the formats ooxml or excel,
and will be passed to export excel. Refer to the corresponding help file for details:
export excel

legible format XML to be more legible.
This option is only valid with the xml_excel format,
and will be passed to the xmlsave. Refer to the corresponding help file for details:
xmlsave

Other options

nolabel export values instead of value labels, if any.
This option is only valid with one of the formats ooxml, excel, ascii_custom, ascii_tab, ascii_comma,
ascii_semicolon, stata or stata_old,
and will be passed to the appropriate export command. Refer to the corresponding help files for details:
save, saveold, export excel, outsheet

orphans save all value labels.
This option is only valid with the stata format,
and will be passed to save. Refer to the corresponding help file for details:
save

emptyok save dataset even if zero observations and zero variables.
This option is only valid with the stata format,
and will be passed to save. Refer to the corresponding help file for details:
save

all save e(sample) with the dataset; programmer's option.
This option is only valid with one of the formats stata or stata_old,
and will be passed to the appropriate export command. Refer to the corresponding help files for details:
save, saveold

rename rename variables and value labels to meet SAS XPORT restrictions.
This option is only valid with the sas format,
and will be passed to the appropriate export command. Refer to the corresponding help file for details:
export sasxport (Stata 12 or newer) or fdasave (older verions of Stata)

vallabfile(xpf) save value labels in formats.xpf
This option is only valid with the sas format,
and will be passed to the appropriate export command. Refer to the corresponding help file for details:
export sasxport (Stata 12 or newer) or fdasave (older verions of Stata)

vallabfile(sascode) save value labels in SAS command file
This option is only valid with the sas format,
and will be passed to the appropriate export command. Refer to the corresponding help file for details:
export sasxport (Stata 12 or newer) or fdasave (older verions of Stata)

vallabfile(both) save value labels in formats.xpf and in a SAS command file
This option is only valid with the sas format,
and will be passed to the appropriate export command. Refer to the corresponding help file for details:
export sasxport (Stata 12 or newer) or fdasave (older verions of Stata)

vallabfile(none) do not save value labels
This option is only valid with the sas format,
and will be passed to the appropriate export command. Refer to the corresponding help file for details:
export sasxport (Stata 12 or newer) or fdasave (older verions of Stata)

replace replace filename without warning if it already exists. If not specified, an error message is triggered in such cases.

verbose drops verbose output during the process. Eventually needed for debugging.

Remarks

In order to use the import formats ooxml or excel, Stata 12 (or newer) is required. If this is not the case, Stata 10 is required.

It is recommended that even if you use Windows, you use forward slashes (/) rather than backward slashes (\) for specifying directory names.
Stata will understand and there will then be no clash with other meanings for the backward slash.

This command is part of the NEPmgmt bundle, written to help creating the NEPS dataset files.

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.

Author

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

Also see

Help: NEPSmgmt, euse, export, export excel, export sasxport, outsheet, save, saveold, xmlsave