SED navigation bar go to SED home page go to Dataplot home page go to NIST home page SED Home Page SED Staff SED Projects SED Products and Publications Search SED Pages
Dataplot Vol 1 Vol 2

READ

Name:
    READ
Type:
    Support Command
Purpose:
    Reads data into variables
    1. from an ASCII mass storage file;
    2. from within a CALLed DATAPLOT sub-program;
    3. from the terminal.
Description: Syntax 1:
    READ <x1> <x2> ... <xk>
    where <x1>, <x2>, ... <xk> are the desired names for the variables into which the data are read.

    This syntax is used to read from the terminal or from within a macro file. All lines are read until an END OF DATA is encountered.

Syntax 2:
    READ <file> <x1> <x2> <x3> etc.
    where <file> is the name of the mass storage file where the data resides;
    and <x1>, <x2>, ... <xk> are the desired names for the variables into which the data in <file> are read.

    This syntax is used to read from a file. All lines are read until an END OF DATA or the physical end of file is encountered.

Examples:
    READ CALIB. PRES TEMP TIME
    READ ASTM.DAT Y1 Y2 Y3 X DAY LAB
    READ Y1 Y2 Y3 X DAY LAB
Note:
    By default, Dataplot peforms free format reads. However, it has the capability for supporting Fortran style formats. Formatted reads can be about 10 times faster on many systems which can be helpful for large data files. Enter HELP READ FORMAT for more details.

    Note that Fortran formats are based on the decimal point lining up consistenly between rows. Spreadsheet programs such as Excel tend to generate either right justified or left justified columns when generating fixed width ASCII files. These are typically not consistent with Fortran formatted reads.

Note:
    Blank lines in data files are ignored.
Note:
    In order to determine whether the first argument is a file name or a variable name, it looks for a period in the name. If it finds one, it assumes a file name. If it does not, it assumes a variable name. If your file name does not contain a period, attach a trailing period (no spaces) to the file name on the READ command.
Note:
    Dataplot does not assume specific extensions for file names. Although using conventions (e.g., ".DAT" or ".TXT" for data files, ".DP" for Dataplot macros) can be helpful for distinguishing between types of files, this is more for the analysts convenience. Dataplot itself does not enforce any conventions.

    File names have the following restrictions:

    1. The file name should be a valid file name for the local operating system.

    2. The file name should contain a period "." in the file name itself or as a trailing character. Dataplot strips off trailing periods on those systems where it is appropriate to do so. On systems where trailing periods can be a valid file name (e.g., Unix), Dataplot tries to open the file with the trailing period. If this fails, it then tries to open the file with the trailing period stripped off.

    3. If the file name contains spaces or hyphens, then it needs to be enclosed in quotes.

    4. File names are currently limited to 80 characters. This can in particular be a problem if the file name is contained within a long path name. The following can be helpful in these cases.

      • You can use the CD command to make the path where the file is stored the current directory. This is most useful for data files. For example,

        pwd
        cd <path where data file resided>
        read file.dat ...
        cd ^CURDIR

        The pwd command is used to save the current directory. The cd command is then used to set the current directory to the path where the data resides, the read is performed, and then the cd command is used to restore the original working directory (the cd command saves the current path in the string CURDIR).

      • You can use the SEARCH DIRECTORY command to specify an additional directory to search for file names.
Note:
    File names are case sensitive on Unix/Linux/Mac OS X systems. For these systems, Dataplot attempts to open the file as given. If this fails, it attempts to open the file as all upper case characters. If this fails, it attempts to open the file as all lower case characters.

    As a further caution for Unix/Linux hosts, certain expansion characters (specifically ~ to refer to your home directory) are interpreted by the shell and are not recognized by the Fortran compiler. These expansion characters are interpreted as literal characters and do not yield the intended file name.

Note:
    In general, Dataplot does not read binary data. However, it can read and write binary data using Fortran unformatted I/O. Note that although the Fortran standard includes unformatted I/O, the implementation details are left to the individual compiler. This means that Fortran unformatted files are not portable across systems and compilers.

    The primary use for this option is if you have a large data file that you will be accessing frequently. In this case, it can speed up the I/O to save a binary version of the file (you should keep the original ASCII version).

    For details, enter HELP SET READ FORMAT.

Note:
    Many data sets are now collected as images. On some implementations, Dataplot can use the GD library to read image data into numeric arrays.

    Although the GD library supports a limited number of image formats, open source software packages such as Image Magick and Netpbm can be used to convert a large number of image formats to ones supported by the GD library.

    For details, enter HELP READ IMAGE.

Note:
    There are variants of this command for reading matrices, parameters, and strings/functions. See the Related Commands section below.
Note:
    After a READ command, Dataplot creates the following parameters:

    ISKIP   the number of header lines skipped
    NUMLRD   the number of data lines read
    NUMVRD   the number of variables read

    In addition, the variable names read are saved in the strings ZZZV1, ZZZV2, ZZZV3, and so on. These parameters and strings are updated each time a READ is performed.

    This capability was added 2014/12.

Default:
    1. If no file name is specified and a CALL is being executed, then the data values should be listed directly in the DATAPLOT sub-program immediately after the READ command (do not forget the END OF DATA statement).

    2. If no file name is specified and the commands are being manually entered/executed one at a time from the terminal, then the data should be entered directly from the terminal immediately after the READ command (also terminated by an END OF DATA statement).
Synonyms:
    None
Related Commands: Applications:
    Data Input
Implementation Date:
    Pre-1987
    1988/02 Ignore column limits when reading from the terminal
    1990/05 Check for comment character in data files
    1995/04 Support for unformatted read
    1996/04 Ignore SET READ FORMAT for READ STRING
    1997/10 Support for SKIP AUTOMATIC
    1998/11 Support for more than 100 variable names
    1999/12 Support for READ ROWID
    2002/07 Support for quotes on file name
    2003/02 Maximum number of characters per record user settable
    2004/01 Support for reading variable names from file
    2004/01 Support for reading character data
    2004/11 PACK/DISPERSE options for READ with SUBSET
    2014/11 Support for reading from system clipboard
    2014/12 Create several automatic parameters/strings for READ
    2019/03 Support for SET READ ASTERISK IGNORE
    2019/12 Support for SET READ PERCENT SIGN IGNORE
    Numerous bug fixes over the years
Program:
     
    SKIP 25
    READ BERGER1.DAT Y X BATCH
        

Privacy Policy/Security Notice
Disclaimer | FOIA

NIST is an agency of the U.S. Commerce Department.

Date created: 10/29/2014
Last updated: 02/03/2020

Please email comments on this WWW page to alan.heckert@nist.gov.