.BG
.VE $Header: /usr3/s/current/s/.help/RCS/extract,v 1.2 83/12/30 19:28:12 rab Exp $
.FN extract
.TL
extract: Extract Columns or Fields as S Datasets
.CS
!S extract [flag] file [desfile extfile]     # UNIX command
.PP
.AG file
the name (unquoted) of a file containing input data, either
in specific columns or else as fields separated by a field
separator character.
.PP
.AG flag
selects warning levels: `\-f' (fatal) causes `extract' to terminate
on the first error encountered. `\-w' (warning, the default)
prints a warning message whenever a field is not present in a record
or does not contain valid information.  Numeric fields with errors
are set to NA; character fields are set to null strings.
`\-s' (silent) suppresses warning messages.
.AG desfile
the name of a description file specifying how to extract
data from `file'.  Defaults to `file.des'.
.AG extfile
the name of the file onto which the external form of the
extracted S data structures will be written.  Defaults to
`file.ext'.
.PP
The macro form, `?extract',
extracts the datasets, writes them to the extract file
and uses the `restore' function to bring these datasets into the
user's working data directory.  The utility version,
`S extract', just forms the extract
file, which could then be shipped to another computer system, etc.
.PP
The `description file' lists the name of each of the datasets to be
extracted and their position in the records of the file.  In `column'
form of description, each line of the description file is of the form:
.IP
name mode start length
.PP
with `name' the name of the extracted dataset, `mode' the desired mode
of the extracted data (R, I, C for REAL, INTEGER and CHARACTER),
`start' the beginning column for the data items on each record, and
`length' the number of columns in the item.  In the `field' form of
input, the first line of the description file should be of the form
.IP
\-f%
.PP
where "%" is the desired field separator character (white-space, tabs
or spaces, by default).
Remaining lines of the description file are then of the form:
.IP
name mode field
.PP
with `name' and `mode' as before, and `field' defining which field of
the record becomes the data item.
.SH SEE ALSO
`?extract'.
.KW data management
.KW utilities
.KW file
.WR
