Export Data

DESCRIPTION:

Export a data frame or bdFrame to a variety of file formats.

USAGE:

exportData(data, file="", type="",
    keep=character(), drop=character(), filter=character(),
    format="", delimiter="", colNames=T, rowNames=F, quote=T,
    odbcConnection="", odbcTable="",
    server="", user="", password="", database="", table="",
    sUseObjectNameForSDD=<<see below>>, time.out.format="",
    decimal.point=".", thousands.separator=",", use.locale=F,
    appendToTable = T, na.string = "")

REQUIRED ARGUMENTS:

data
a data frame or matrix or bdFrame to be exported.

OPTIONAL ARGUMENTS:

file
a character string specifying the name of the export file to be created. If the file has a known suffix (see the type argument below), S-PLUS assumes the file is of that type. This can be overridden by providing type explicitly. The file argument is not required when exporting to a relational database.
type
a character string specifying the type of file to create. The case of the character string is ignored Possible values are listed in the help file for . S-PLUS exports to all the same file types it imports from with the following exception: S-PLUS for Windows does not export to SigmaPlot (file suffix jnb). See Details for more information.

In addition to the file types listed in the importData help file, S-PLUS also exports to HTML tables. To create HTML data files, specify a name for the file argument that has an htm suffix or set type="HTML".

keep
a character vector of column names or a numeric vector of column numbers. The columns specified are exported to the data file. Only one of keep and drop can be given.
drop
a character vector of column names or a numeric vector of column numbers. The columns specified are NOT exported to the data file. Only one of keep and drop can be given.
filter
a logical expression that specifies the rows to be exported to the data file. See the help file for for a description of valid filter expressions.
format
a character string specifying the format to use when exporting to formatted ASCII files ( type="FASCII"). A valid format string includes a percent % sign followed by the width and precision for each column in the data file, separated by a period. The elements in the string are separated by commas. For example, the format string %3,%7.2,%4,%5.2 exports the first and third columns as whole numbers with 3 and 4 digits, respectively. The second and fourth columns each have two decimal digits of precision.

The precision value is ignored if it is given for a character column. If the precision is not specified, it is assumed to be zero. If you export row names for your data set, the first entry in the format string is reserved for the row names.

Specifying a format string can potentially speed up the export of data sets that have many character columns. If a format string is not specified, S-PLUS must check the width of every entry in a character or factor column and determine a width large enough for all values in the column. Because many of the supported file types use fixed widths, considerable space can be saved by specifying a narrow width for character columns that have many short values and only a few long values; with this approach, the few long values are truncated.

S-PLUS truncates column names at 35 characters when you export data to a *.txt or Microsoft Windows Excel file. When this occurs S-PLUS displays a warning, indicating the new column name.

delimiter
a character string specifying the character to use as a delimiter in an ASCII export file. The expressions \n and \t are the only multi-character delimiters allowed, and denote a newline and a tab, respectively. For any other multi-character string, only the first character is used as the delimiter. Double quotes are reserved characters and therefore cannot be used as standard delimiters.
colNames
a logical flag. If colNames=TRUE, the column names are exported to the data file.
rowNames
a logical flag. If rowNames=TRUE, the row names are exported to the data file. This argument is not supported when exporting a bdFrame object.
quote
a logical flag. If quote=TRUE, quotes are placed around character strings when exporting to ASCII text files ( type="ASCII").
odbcConnection
a character string containing an ODBC connection string. This argument is required if type="ODBC" and is functional only in S-PLUS for Windows. See the help file for for information on the form this string should take.
odbcTable
a character string denoting the name of the table to be created if type="ODBC".
server
a character string specifying the database server when importing from a relational database. If type="DIRECT-SQL", and you are accessing a non-default instance of SQL Server, specify server="SERVERNAME\\INSTANCE". To access the default instance, use server= "SERVERNAME".

This should be left as the empty string "" if type="DB2".

user
a character string specifying the user name when exporting data to a relational database.
password
a character string specifying the user's password for accessing the database when exporting to a relational database. If type="ORACLE" and you are using Remote OS Authentication, specify password="self" and no user argument.
database
a character string specifying the database to use when exporting to a relational database. This should be left as the empty string "" if type="ORACLE".
table
a character string specifying the name of the table to create when exporting to a relational database.
sUseObjectNameForSDD
a character string specifying the name of the exported data set when exporting to a S-PLUS transport file ( type="SPLUS"). If this is not specified, S-PLUS extrapolates the name of the data set from the data argument by calling deparse(substitute(data)). In some circumstances, doing this to obtain the name of the object will fail; this arises when calling exportData from another function with a data parameter passed from outside the calling function, for example. In these situations, sUseObjectNameForSDD can be specified.
time.out.format
a character string specifying the format to use when exporting date/time data to ASCII or FASCII text files. By default, this is determined by options("time.out.format").
decimal.point
a single character specifying the decimal point character for ASCII data files. By default, this is the period (.).
thousands.separator
a single character specifying the thousands separator character for ASCII data files. By default, this is the comma (,).
use.locale
a logical value. If use.locale=TRUE, the default values of decimal.point and thousands.separator come from the current locale set by Sys.setlocale. Otherwise, the default values are as described above.
appendToTable
a logical value. This argument determines what happens if the database table already exists. If TRUE, the exported database values are appended to the database table. If FALSE, the database table is deleted, and the exported database values are written to a new table. The default value is FALSE. This argument only applies when exporting directly to a database i.e. you must not be using the file argument and you must have specified the odbcConnection and odbcTable arguments or the server and table arguments.
na.string
a character string that will be written to an ASCII text file to represent a missing value.

VALUE:

an integer specifying the number of rows that were exported.

SIDE EFFECTS:

If specified, the file named file is created and data is written to it.

DETAILS:

If you try to export data and encounter problems, S-PLUS displays a warning describing the problems encountered.

When variable names are exported, they may be changed to conform to the output format. For example, if an output format only supports upper case variable names, variable names will converted to upper case on export. Some variable names may be changed to avoid reserved words. For example, the Oracle database does not permit a table column to be named "TYPE" , so this column name is changed to "TYPE_" on export.

When you export a STATA dataset, you are limited to 2,047 characters. For larger STATA datasets--with up to 32,767 variables--specify type="STATASE" .

When you export a MATLAB dataset, to export a pre-MATLAB 7 version, specify type="MATLAB". To export a MATLAB 7 version, specify type="MATLAB7".

When writing to a table in a database, exportData creates a new table if one by the specified name does not exist; otherwise, it either appends rows of data to the existing table (if appendToTable=TRUE) or deletes the table and recreates it. When appending a data frame or bdFrame to an existing table, if some or all of the column names in the exported S-PLUS data frame do not correspond to fields in the table, these extra columns are ignored.

Another way of adding rows to an existing table in a database is to write to a temporary table and then use an INSERT statement with executeSQL to merge the temporary table to an existing one. This may reduce issues with a database being locked due to another process writing to it. See the help file for examples using exportData to export data to an Oracle database.

NOTE:

The functions and can be used to export data in sequential blocks of a specified size.

SEE ALSO:

, , , , , .

EXAMPLES:

exportData(fuel.frame, "fuel.txt", type="ASCII",
     filter="Weight > 2500")