Contents

inforead()

Usage:

inforead(fileName,Name [,quiet:F, echo:T or F, silent:T, notfoundok:T,\
  nofileok:T,badkeyok:T]), fileName and Name CHARACTER scalars; FileName
  can also be CONSOLE or be string:charVal where charVal is a CHARACTER
  scalar or vector.

Keywords: input, files, character variables

inforead(FileName,Name) returns the comments (lines starting with ')')
following the header line of data set or macro Name on file FileName.
They are returned, with the leading ')' stripped off, as a CHARACTER
scalar which can be printed.

The contents of the data set or macro are ignored and there is no
checking as to whether the header line is in correct format.  The header
lines are not echoed unless 'quiet:F' is an argument; see below.

It is an error if the file cannot be read or if the named data set or
macro is not found, but see keywords 'notfoundok' and 'nofileok' below.

Name must be a quoted string or CHARACTER scalar and FileName normally
has a similar form, but see keyword 'string' below.

In versions with windows (Macintosh, Windows, Motif), if FileName is the
null string "", you will be able to select the file using a dialog box.

inforead(FileName) does the same for the first data set or macro on the
file, assuming that the first non-empty line is the header line of a
data set or macro.

inforead(file:FileName [,Name]) is equivalent to inforead(FileName
[,Name]).

See below for the usage inforead(string:charVec [,Name]).

Example:
  Cmd> haldinfo <- inforead("macanova.dat","halddata"); print(haldinfo)

reads the comments describing data set halddata on file macanova.dat
into variable haldinfo and then prints haldinfo.

Commands save() and asciisave() would save haldinfo in a file along with
the rest of your workspace.  When you later use restore() to recover the
workspace, print(haldinfo) displays information about the data without
having to refer to the original data file.

Keywords 'quiet', 'silent', 'notfoundok', 'nofileok' and 'badkeyok'
modify the behavior of inforead().  'echo' is recognized but ignored.

  Keyword phrase        Meaning
   quiet:T          Header and descriptive comments will not be printed
                    (the default for inforead())
   quiet:F          Header and descriptive comments will be printed
                    in addition being returned as value.
   silent:T         Only error messages will be printed; incompatible
                    with quiet:F or echo:T
   notfoundok:T     Failure to find the macro or data set is not
                    considered an error so NULL is returned and
                    no error message is printed
   nofileok:T       Failure to open the file is not considered an error
                    so NULL is returned and no error message is printed
   badkeyok:T       Unrecognized or duplicate keywords are silently
                    ignored.

Keywords notfoundok and nofileok are designed to be helpful in a macro.
You can check the returned value using isnull() and take special action
if the isnull() returns True.  See isnull().

inforead(string:CharVar) where CharVec is a CHARACTER scalar or vector,
does not read from a file.  Instead, it "reads" CharVar as if each
element were a line (or several lines if there are embedded end-of-line
characters) read from a file.

The first element or line of CharVar must be a header line for a data
set or a macro.  In particular, info <- inforead(string:CLIPBOARD) would
read the header information of the first variable on a replica of a data
file in the special variable CLIPBOARD.  In the Macintosh, Windows and
Motif versions this would be taken from the Clipboard.  See topic
'CLIPBOARD'.

If either keyword 'file' or 'string' is used, they can appear in any
position in the argument list, as can setName which must be the only
non-keyword argument.  For example, inforead(quiet:T,"mymacro",
file:"myfile.dat") is equivalent to inforead("myfile.dat","mymacro",
quiet:T).

See topics 'matread_file' and 'macro_files' for information on the
format of files readable by inforead().

See also matread(), macroread(), save(), asciisave().