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 Dataplot Pages

Dataplot Program Control
Types of Program Control Structures Dataplot provides the following types of program control structures:
  1. Looping
  2. Conditional Execution
  3. Subprograms
Looping
Looping Can Often Be Avoided Most Dataplot programs do not need loops. In FORTRAN, for example, the use of loops is commonly used for intermediate calculations en route to the final output. In Dataplot, however, the existence of numerous high-level graphics and analysis commands frequently obviates the need for such intermediate looping.
Loops Implemented with the LOOP Command If a loop is required, it is initiated with the LOOP command. The general syntax is
    LOOP FOR <par> = <start> <incr> <stop>
where <par> is the loop index, <start> is the starting value for the loop index, <incr> is the increment for the loop index, and <stop> is the stop value for the loop index.

The loop index will be a parameter in the usual Dataplot sense. As the loop is being executed, the loop index will be successively changed (depending on start, increment, and stop values). The

    END OF LOOP
or
    END LOOP
commands will terminate the loop.
Loop Index Parameter can be Used in Computations The loop index parameter is global and can be used by any calculation or specification within the loop. Thus
    LOOP FOR I = I 1 10
      WRITE I
    END OF LOOP
    will result in the sequence 1, 2, 3, ..., 9, 10 being printed.

    You should not modify the value of the loop index parameter. If you do, you will obtain unpredictable (and undesirable) results.

Some Examples The following loop
    LOOP FOR L = 1 1 5
      PLOT Y X SUBSET LAB L
    END OF LOOP
will result in five distinct plots being generated:
  1. a plot of Y versus X but restricted to those values for which the LAB variable = 1;
  2. a plot of Y versus X but restricted to those values for vhich the LAB variable = 2;
  3. a plot of Y versus X but restricted to those values for which the LAB variabIe = 3;
  4. a plot of Y versus X but restricted to those values for which the LAB variable = 4;
  5. a p1ot of Y versus X but restricted to those values for vhich the LAB variable = 5;
The following loop
    LOOP FOR D = 1 1 10
      FIT Y = A*B*X SUBSET DAY D
      LET A2(D) = A
      LET B2(D) = B
      LET S(D) = RESSD
    END OF LOOP
will carry out 10 linear fits of Y on X. Each fit will be restricted to values of the DAY variable = to 1, then 2, then 3, etc. Further, for each fit, the value of the fit parameter A will be copied into the D-th element of variable A2, the value of the fit parameter B will be copied into the D-th element of the variable B2, and the value of the fit residual standard deviation parameter RESSD (automatically provided by Dataplot) will be copied into the D-th element of the variable S.

The following loop

    FEEDBACK OFF
    ERASE
    LOOP FOR I = 10 10 80
      LET IY1=IX1
      LET IX2=IX1+10
      LET IY2=IX2
      BOX IX1 IYl IX2 IY2
    END OF LOOP
will generate a sequence of boxes along the lower left to upper right diagonal of the screen.
Values in the LOOP Command Can Be Either Numbers or Parameters As is usual, the start value, increment, and stop value can be either numbers or parameters. Thus
    LOOP FOR I = 1 1 5
      PLOT Y X SUBSET LAB L
    END Of LOOP
and
    LET A = 1
    LET B = 1
    LET C= 5
    LOOP FOR L = A B C
      PLOT Y X SVBSET LAB I
    END OF LOOP
are equivalent.
BREAK LOOP Loops can prematurely terminated with the BREAK LOOP command.
Checking the Value of the Loop Index Parameter The checking of the loop index parameter is done at the beginning of the loop. It is possible for a loop not to be executed at all (if the increment is positive and the stop value is smaller than the start value; or if the increment is negative and the stop value is larger than the start value); thus
    LET STOP = -1
    LOOP FOR A = 1 1 STOP
      PRINT A
    END OF LOOP
would result in the loop not being executed.
Loops Can Be Nested Seven Deep Loops can be nested seven deep. Thus to generate plots of Y versus X for each combination of variables OP (with three levels), LAB (with five levels), and DAY (with five levels), one could enter
    LOOP FOR 0 = 1 1 3
    LOOP FOR L = 1 1 5
    LOOP FOR D = 1 1 5
      PLOT Y X SVBSET OP 0 SUBSET LM l SVBSET DAY D
    END OF LOOP
    END OP LOOP
    END OF LOOP
Using the Substitution Character (^) in Loops To have the 60 plots sequenced and to have them properly labeled with the current operator, lab, and day value, one could use the ^ keyword in conjunction with the ..LABEL command, as follows:
    SEQUENCE
    LOOP FOR 0 = 1 1 3
    LOOP FOR L = 1 1 5
    LOOP FOR D = 1 1 5
      XLABEL OPERATOR = ^0
      X2LABEL LAB = ^L
      X3LABEL DAY = ^D
      PLOT Y X SUBSET OP O 5UBSET LAB L SUBSET DAY D
    END OF LOOP
    END OF LOOP
    END OF LOOP
CALL Command in Loops Any valid Dataplot command can be executed within the context of a loop. A particular1y important command is the CALL command that alllows a subprogram to be referenced. Thus for more complicated applications, it may be of interest to set up a loop in the main program and then specify a desired set of operations in a subprogram, as in
    LOOP FOR 0 = 1 1 3
    LOOP FOR L = 1 1 4
    LOOP FOR D = 1 1 5
      CALL A.
    END OF LOOP
    END OF LOOP
    END OF LOOP
where subprogram A might consist of
    XLABEL OPERATOR = ^O
    X2LABEL LAB = ^L
    X3LABEL DAY = ^D
    PLOT Y X SUBSET OP 0 SUBSET LAB L SUBSET DAY

Main Menu

Conditional Execution
Two Methods for Conditional Execution Conditional execution of statements is handled in two different ways in Dataplot:
  1. the augmentation of SUBSET/ EXCEPT/ FOR qualifications at the end of any graphics or analysis command (this is used when the conditionality is the based on values within variables);

  2. the use of the IF command in conjunction with the END OF IF (or END IF) command (this is used when the conditionality is based on values of parameters).
SUBSET/
EXCEPT/
FOR Clauses 		Method 1 is the most popular and is the most straightforward way of conditionally executing commands. It is a Dataplot feature that any graphics or analysis command can be conditionally executed (that is, have its execution restricted to a certain subset of data, or have its execution contingent on the value of certain variables) by simply appending the qualification to the end of the command line. As far as the analyst is concerned, the primary general objective is to generate a plot, carry out a fit, carry out an analysis of variance, etc., whereas the restriction of such an activity to a specific subset is, in a sense, an afterthought. This being the case, the Dataplot structure is to have the Dataplot command (PLOT, FIT, ANOVA, etc.) appear first and foremost on the line, and then to simply append the qualification to the end of the line. Thus it is easy and natural to extend
    PLOT Y X
    FIT Y = A+B*LOG(X)
    ANOVA Y X1 X2 X3
to
    PLOT Y X SUBSET LAB 4
    FIT Y = A+B*LOG(X) SUBSET X > 50 EXCEPT X = 140
    ANOVA Y X1 X2 FOR I = 1 1 40
The specified subset is extracted before the command is executed. If the subset is empty, then the command will not be executed.
IF Command Method 2 is a much less popular way of conditionally executing statements, but does have occasional application. To conditionally execute a "chunk" of Dataplot code, one can use the IF command in combination with the END OF IF (or END IF) command. The general form for the IF command is
    IF <parameter or number> <relative operator> <parameter or number>
where the relational operators are
= equality
<> inequality
< less than
<= or <= less than or equa1 to
> greater than
>= or => greater than or equal to
Some Examples of the IF Command The conditionality specification is done in terms of parameter values (as opposed to variable values in the SUBSET/EXCEPT qualification). For example, suppose a variable X has 100 values in it and it is desired to determine the maximum value in X. The easiest way to do this in Dataplot is to simply enter
    LET MAX = MAXIMUM X
Hovever, for purposes of illustration of the use of the IF command, one could achieve the same result via the following statements--
    LET MAX = -INFINITY
    LOOP FOR I = 1 1 100
      LET XI=X(I)
      IF XI > MAX
        LET MAX = X(I)
      END OF IF
    END OP LOOP
It is clear that the second method is an extremely inefficient method for computing the parameter MAX.

As a second example, suppose it is desired to determine that cambination of A and B (over a specified lattice of values) for which the L1 fit of A+LOG(B+X) is achieved. The easiest way to carry this out in Dataplot is

    FIT POWER
    PRE-FIT A+LOG(B+X) FOR A = 1 1 10 FOR B = l00 20 200
At the end of the PRE-FIT, the optimal values will reside in the parameters A and B. An alternate (and much longer way of doing the same is
    LET MIN = INFINITY
    LOOP FOR A = 1 1 10
      LOOP FOR B = 100 10 200
        .
        LET PRED = A+LOG(B+X)
        LET RES = Y-PRED
        LET RES2 = ABS(RES2)
        LET SUMAD = SUM RES2
        .
        IF SUMAD < MIN
          LET A2 = A
          LET B2 = B
        END OF IF
        .
      END OF LOOP
    END OF LOOP
At the end of execution of this code, the optimal values of A and B will reside in the parameters A2 and B2.
IF Statements Can Be Nested 10 Deep IF statements can be nested up to 10 deep, as in
    IF A > 10
    IF B > 7
    IF C <= 100
      WRITE A B C
    END OF IF
    END OF IF
    END OF IF
The parameters A, B, and C will be scanned; only if the 3 specified conditions are satisfied will the WRITE occur.
Any valid Dataplot statment can occur within the context of the IF set of statements. A particularly powerful entry is thc CALL statement which allows subprograms to be executed. Thus, for example, to conditionally execute (only if the residuals standard deviation RESSD from some fit is less than .1) a subprogram XYZ, one could enter
    IF RESSD < .1
      CALL XYZ.
    END OF IF
The END OF IF can optionally be written as END IF.
IF Command Lightly Used in Dataplot The IF capability in DATAPL0T is a low-level capability (no one does IF as an end objective in itself). Conditionally executing a chunk of code is an elementary capability of any computer language. In Dataplot, due to the existence of high-level capabilities, and due to the SUBSET/EXCEPT/FOR qualification capability, the IF capability is only lightly used.

Main Menu

Subprograms
Subprograms are Independent Programs Stored in External ASCII Files The typical Dataplot program consists of a main prooram. The existence of higher-level capabilities (e.g., PLOT, FIT, LET, etc.) often precludes complicated nesting of subprograms. However, subprograms can be included in Dataplot as needed.

Subprograms are completely independent programs in their own right and must be placed in separate mass storage files. Such subprograms are accessed via the CALL command and are identified by the name of the mass storage file in which the subprogram resides. These files are simply ASCII files that contain Dataplot commands. There is no special structure or compilation required.

Example For example,
    CALL XYZ.
(which would execute the subprogram residing in file XYZ), or
    CALL XYZ.DP
(which would execute the subprogram residing in the file XYZ.DP). As with all Dataplot commands that involve file names, the file name must contain a period or have a trailing period included (i.e., for a file name that does not include a period, you place a trailing period at the end of the file name in the Dataplot command, Dataplot will still find the file). The period in the name tells Dataplot that the name is a file name. We recomend using a specified file extension on those systems that allow it to identify the file as a Dataplot subprogram. We tend to use ".DP". However, this is more for the analyst's convenience as Dataplot does not enforce any specific extension for Dataplot subprograms.
Rules for Subprograms The following are the basic rules governing the use of Dataplot subprograms.
  • When the last line of the subprogram in the file is executed, it returns to the main program to the statement immediately following the CALL statement.

  • The name of the subprogram is taken to be the name of the file where the subprogram resides.

  • Modularity is strictly adhered to in that only one subprogram may exist in any given file.

  • There is no necessity for internal identification of the subprogram. For example, there is (as would be the case in FORTRAN, BASIC, and ALGOL) no need for a SUBPROGRAM, SUBROUTINE, or PROCEDURE statement as the first line of the subprogram. Nor is there any need to terminate the various subprograms with a terminator statement (e.g., RETURN). In fact, the existence of EXIT (or END, STOP, HALT, or BYE) will cause the Dataplot run to be terminated. Thus EXIT (and its synonyms) is usually reserved for the last line of the main program.

  • All parameter, variable, and function names are global and names defined in the main program may be used and modified in subprograms (and vice versa).

  • Subprograms may in turn call other subprograms. The maximum number of nested subprograms is seven (including the main progran).

  • Subprograms may not be recursive, that is, a subprogram may not call itself.
Common Usages of Subprograms The four most important ways in which subprogram usage arises are as follows:
  1. Unconditional calls
  2. Conditional calls
  3. Unconditional loops
  4. Conditional loops
For example:
  1. Unconditional calls
    In this case, a subprogrram is called once and only once. For example,

      CALL SIGMA.

    would cause subprogram SIGMA to be unconditiona1ly called once and only once.

  2. Conditional calls
    This calls a subprogram exactly once and only under certain conditions. For example,

      IF A > 4
        CALL SIGMA.
      END OF IF

    would cause subprogram SIGMA to be called only if the current value of the parameter A exceeds 4, but not to call SIGMA otherwise.

  3. Unconditianal loops
    In this case, a subprogram is called multiple times. For example,

      LOOP FOR B = 1 1 10
        CALL SIGMA.
      END OF LOOP

    would cause subprogram SIGMA to be unconditionally called 10 times (for B = 1, 2, ..., 9, 10).

  4. Conditianal loops
    5. In this case, a subprogram is called for a number of times that depends on calculations that occur within the subprogram being called. For example,

      LOOP FOR B = 1 1 C
        CALL SIGMA.
      END OP LOOP

    (where the parameter C is pre-defined but may also be redefined within the subprogram being called) would cause subprogram SIGMA to be called a variable number of times depending on how C is redefined within the loop.

Main Program Can Be Initiated With CALL As one would expect, execution of a pre-stored main program may be initiated in an identica1 fashion as one would execute a subprogram, namely via the CALL command. Thus, for example, if the analyst has signed onto Dataplot, and if a pre-stored main program resides in a file called A, then execution of the main program could start with the entry of the statement
    CALL A.
Creating Subprograms
Use Your Local Editor The most common and most efficient method for creating Dataplot subprograms is via the local editor. That is, before the analyst enters Dataplot, he/she enters into a file with the local editor and creates a Dataplot program and any needed Dataplot subprograms. There is no substitute for an excellent local editor and the analyst is encouraged to use such an editor for creating Dataplot programs and subprograms.
Create Dataplot Subprogram on the Fly Using CREATE One the other hand, it is at times convenient to be able to create a Dataplot subprogram "on the fly" while one is executing a Dataplot program. A prime example of this is in the construction of diagrammatic graphics in which one makes an interactive pass at forming the diagram, stores the commands that were used en route, and then executes these commands as a block in a semi-interactive mode.

If one is running Dataplot interactively, one can automatically store the entered interactive command lines into a file by use of the CREATE command. For example, to instruct Dataplot that all subsequently keyed-in commands should be in a file XYZ.DP as they are being entered, the analyst would enter

    CREATE XYZ.DP
To terminate the creation of the file XYZ.DP, the analyst enters
    END OF CREATE
or
    END CREATE
To execute the contents of XYZ.DP, one would enter
    CALL XYZ.DP
Listing Subprograms - LIST
LIST Command The LIST command can be used to list the contents of any file. Usually such a capability is taken advantage of when the file contains a subprogram, but it can also be used when the file contains data. The usual convention about periods following the file name is followed. Thus to list the contents of the file XYZ, one enters
    LIST XYZ.
If the file contains an extension, for example XYZ.ABC, one enters
    LIST XYZ.ABC
The LIST command only lists the file. It does not execute the contents of the file.

Main Menu

Date created: 06/05/2001
Last updated: 04/29/2022
Please email comments on this WWW page to alan.heckert@nist.gov.