System Files and Portable Files
*******************************

The commands in this chapter read, write, and examine system files and portable files.

APPLY DICTIONARY
================

     APPLY DICTIONARY FROM='filename'.

APPLY DICTIONARY applies the variable labels, value labels, and missing values from variables in a system file to corresponding variables in the active file.  In some cases it also updates the weighting variable.

Specify a system file with a file name string or as a file handle (see FILE HANDLE).  The dictionary in the system file will be read, but it will not replace the active file dictionary.  The system file's data will not be read.

Only variables with names that exist in both the active file and the system file are considered.  Variables with the same name but different types (numeric, string) will cause an error message.  Otherwise, the system file variables' attributes will replace those in their matching active file variables, as described below.

If a system file variable has a variable label, then it will replace the active file variable's variable label.  If the system file variable does not have a variable label, then the active file variable's variable label, if any, will be retained.

If the active file variable is numeric or short string, then value labels and missing values, if any, will be copied to the active file variable.  If the system file variable does not have value labels or missing values, then those in the active file variable, if any, will not be disturbed.

Finally, weighting of the active file is updated (see WEIGHT).  If the active file has a weighting variable, and the system file does not, or if the weighting variable in the system file does not exist in the active file, then the active file weighting variable, if any, is retained.  Otherwise, the weighting variable in the system file becomes the active file weighting variable.

APPLY DICTIONARY takes effect immediately.  It does not read the active file.  The system file is not modified.

EXPORT
======

     EXPORT
             /OUTFILE='filename'
             /DROP=var_list
             /KEEP=var_list
             /RENAME=(src_names=target_names)...

The EXPORT procedure writes the active file dictionary and data to a specified portable file.

The OUTFILE subcommand, which is the only required subcommand, specifies the portable file to be written as a file name string or a file handle (see FILE HANDLE).

DROP, KEEP, and RENAME follow the same format as the SAVE procedure (see SAVE).

EXPORT is a procedure.  It causes the active file to be read.

GET
===

     GET
             /FILE='filename'
             /DROP=var_list
             /KEEP=var_list
             /RENAME=(src_names=target_names)...

GET clears the current dictionary and active file and replaces them with the dictionary and data from a specified system file.

The FILE subcommand is the only required subcommand.  Specify the system file to be read as a string file name or a file handle (see FILE HANDLE).

By default, all the variables in a system file are read.  The DROP subcommand can be used to specify a list of variables that are not to be read.  By contrast, the KEEP subcommand can be used to specify variable that are to be read, with all other variables not read.

Normally variables in a system file retain the names that they were saved under.  Use the RENAME subcommand to change these names.  Specify, within parentheses, a list of variable names followed by an equals sign (=) and the names that they should be renamed to.  Multiple parenthesized groups of variable names can be included on a single RENAME subcommand.  Variables' names may be swapped using a RENAME subcommand of the form /RENAME=(A B=B A).

Alternate syntax for the RENAME subcommand allows the parentheses to be eliminated.  When this is done, only a single variable may be renamed at once.  For instance, /RENAME=A=B.  This alternate syntax is deprecated.

DROP, KEEP, and RENAME are performed in left-to-right order.  They each may be present any number of times.  GET never modifies a system file on disk.  Only the active file read from the system file is affected by these subcommands.

GET does not cause the data to be read, only the dictionary.  The data is read later, when a procedure is executed.

IMPORT
======

     IMPORT
             /FILE='filename'
             /TYPE={COMM,TAPE}
             /DROP=var_list
             /KEEP=var_list
             /RENAME=(src_names=target_names)...

The IMPORT transformation clears the active file dictionary and data and replaces them with a dictionary and data from a portable file on disk.

The FILE subcommand, which is the only required subcommand, specifies the portable file to be read as a file name string or a file handle (see FILE HANDLE).

The TYPE subcommand is currently not used.

DROP, KEEP, and RENAME follow the syntax used by GET (see GET).

IMPORT does not cause the data to be read, only the dictionary.  The data is read later, when a procedure is executed.

MATCH FILES
===========

     MATCH FILES
             /BY var_list
             /{FILE,TABLE}={*,'filename'}
             /DROP=var_list
             /KEEP=var_list
             /RENAME=(src_names=target_names)...
             /IN=var_name
             /FIRST=var_name
             /LAST=var_name
             /MAP

MATCH FILES merges one or more system files, optionally including the active file.  Records with the same values for BY variables are combined into a single record.  Records with different values are output in order.  Thus, multiple sorted system files are combined into a single sorted system file based on the value of the BY variables.  The results of the merge become the new active file.

The BY subcommand specifies a list of variables that are used to match records from each of the system files.  Variables specified must exist in all the files specified on FILE and TABLE.  BY should usually be specified.  If TABLE is used then BY is required.

Specify FILE with a system file as a file name string or file handle (see FILE HANDLE), or with an asterisk (*) to indicate the current active file.  The files specified on FILE are merged together based on the BY variables, or combined case-by-case if BY is not specified.  Normally at least two FILE subcommands should be specified.

Specify TABLE with a system file to use it as a table lookup file.  Records in table lookup files are not used up after they've been used once.  This means that data in table lookup files can correspond to any number of records in FILE files.  Table lookup files correspond to lookup tables in traditional relational database systems. It is incorrect to have records with duplicate BY values in table lookup files.

Any number of FILE and TABLE subcommands may be specified.  Each instance of FILE or TABLE can be followed by DROP, KEEP, and/or RENAME subcommands.  These take the same form as the corresponding subcommands of GET (see GET), and perform the same functions.

Variables belonging to files that are not present for the current case are set to the system-missing value for numeric variables or spaces for string variables.

IN, FIRST, LAST, and MAP are currently not used.

MATCH FILES may not be specified following TEMPORARY (see TEMPORARY) if the active file is used as an input source.

SAVE
====

     SAVE
             /OUTFILE='filename'
             /{COMPRESSED,UNCOMPRESSED}
             /DROP=var_list
             /KEEP=var_list
             /VERSION=version
             /RENAME=(src_names=target_names)...

The SAVE procedure causes the dictionary and data in the active file to be written to a system file.

OUTFILE is the only required subcommand.  Specify the system file to be written as a string file name or a file handle (see FILE HANDLE).

The COMPRESS and UNCOMPRESS subcommand determine whether the saved system file is compressed.  By default, system files are compressed. This default can be changed with the SET command (see SET).

By default, all the variables in the active file dictionary are written to the system file.  The DROP subcommand can be used to specify a list of variables not to be written.  In contrast, KEEP specifies variables to be written, with all variables not specified not written.

Normally variables are saved to a system file under the same names they have in the active file.  Use the RENAME subcommand to change these names. Specify, within parentheses, a list of variable names followed by an equals sign (=) and the names that they should be renamed to. Multiple parenthesized groups of variable names can be included on a single RENAME subcommand.  Variables' names may be swapped using a RENAME subcommand of the form /RENAME=(A B=B A).

Alternate syntax for the RENAME subcommand allows the parentheses to be eliminated.  When this is done, only a single variable may be renamed at once.  For instance, /RENAME=A=B.  This alternate syntax is deprecated.

DROP, KEEP, and RENAME are performed in left-to-right order.  They each may be present any number of times.  SAVE never modifies the active file.  DROP, KEEP, and RENAME only affect the system file written to disk.

The VERSION subcommand specifies the version of the file format. Valid versions are '3' and '3x'.  Version 3x system files are identical to version 3 files, except that variable names greater than 8 bytes will be truncated.  The default version is 3.  The VERSION subcommand is optional.  There is no need ever to use it.

SAVE causes the data to be read.  It is a procedure.

SYSFILE INFO
============

     SYSFILE INFO FILE='filename'.

SYSFILE INFO reads the dictionary in a system file and displays the information in its dictionary.

Specify a file name or file handle.  SYSFILE INFO reads that file as a system file and displays information on its dictionary.

SYSFILE INFO does not affect the current active file.

XSAVE
=====

     XSAVE
             /OUTFILE='filename'
             /{COMPRESSED,UNCOMPRESSED}
             /DROP=var_list
             /KEEP=var_list
             /RENAME=(src_names=target_names)...

The XSAVE transformation writes the active file dictionary and data to a system file stored on disk.

XSAVE is a transformation, not a procedure.  It is executed when the data is read by a procedure or procedure-like command.  In all other respects, XSAVE is identical to SAVE.  See SAVE, for more information on syntax and usage.