Produce Text Representations of S-PLUS Objects

DESCRIPTION:

Creates a file containing an ASCII representation of the objects that are named.

USAGE:

data.dump(names, file="dumpdata.sdd", connection="dumpdata.sdd",
          where=1, meta=0, oldStyle=F, test=NULL,
          direct=F, iterative=T, .001.where=where) 

REQUIRED ARGUMENTS:

names
vector of character strings giving the names of data objects. (Unless direct=T; see below.)

OPTIONAL ARGUMENTS:

file
character string naming the file on which the objects will be written. If file is specified, connection is ignored.
connection
character string specifying a connection object on which to write the dump. If you want to append to an existing file or send the output to another process, specify a connection object rather than a file.
where
the database from which to get the objects. By default, uses the working data.
meta
a numeric code specifying the type of database from which to get the objects.
0

ordinary S-PLUS object database

1
meta-database
2
documentation database

The same dump cannot mix the three types, and dumped files must be restored as the appropriate type (meta-data as meta-data, doc as doc, ordinary as ordinary).
oldStyle
if TRUE, an old-style data dump is produced, without object classes and without a distinguishing header. Should be FALSE unless the dump is to be read by a version of S-PLUS that does not have universal classes (that is, S-PLUS 4.x or earlier).
direct
as noted above, the names argument is a character vector. if direct=FALSE (the default), the names argument is taken to be the names of objects to be written to the file or connection. Thus you are writing the objects indirectly, via their names.

if direct=TRUE, the names argument is itself written directly to the file or connection, without a header or other identification. Files written with direct=TRUE cannot be read via data.restore. Use this setting to write data to a dump file or for communication with code that reads S-PLUS data dumps directly, rather than via data.restore.

See the examples below for more information.
iterative
this argument is used for internal development only.
.001.where
this argument is used for internal development only.

VALUE:

the character string file or connection.

SIDE EFFECTS:

the file or connection is created or changed, and contains text representations of the objects given in names. The files are ASCII text, and they can be shipped to another machine; the shipped file can then be used to restore the objects with data.restore. As long as oldStyle is not TRUE, the dump contains all the class information about the objects and their components. Objects can be dumped either from ordinary data or from meta-data. On restoring via data.restore, the target database can differ from the one used to produce the dump.

DETAILS:

This function dumps the objects listed, using S-PLUS's universal text-based object format, so the objects can be restored on any machine. You should always use data.dump in preference to dump for dumping general objects, such as S-PLUS language objects; dump output is only for human editing (for example, of functions). The data.dump function is for transmitting objects between machines; it is much faster than dump, and the restore process is equally speeded up, particularly for large objects containing numeric data.

File names ending with ".sdd" are recommended, as this file type is associated with S-PLUS.

SEE ALSO:

, , , .

EXAMPLES:

data.dump(ls(), "allFiles.sdd") 
data.dump(c("x", "y", "reg.xy")) 
## Write character representations of the numeric vectors x and y to ## the file "indirect.sdd":

x <- 1:3
y <- 2
data.dump(names=c("x","y"), file="indirect.sdd", direct=F)

## Write the two characters "x" and "y" to the file "direct.sdd"

data.dump(names=c("x","y"), file="direct.sdd", direct=T)

## The latter will create a file that looks like this (excluding #'s):

# character
# character
# 2
# x
# y