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

MACRO SUBSTITUTION CHARACTER

Name:
    MACRO SUBSTITUTION CHARACTER
Type:
    Support Command
Purpose:
    Specify the character to use in macros to signify an argument to the macro.
Description:
    You can now pass arguments to macros. Recall that Dataplot macros are simply ASCII files containing Dataplot commands (i.e., there is no compilation of macros).

    To pass arguments to a macro, do something like

      CALL SAMPLE.DP arg1 arg2 arg3

    Up tp 10 arguments may be passed (although limits on command line lengths still apply). Arguments containing spaces or hyphens should be enclosed in quotes. The character limit for a single argument is 40 characters.

    In the SAMPLE.DP macro, if a $1 is encountered, it will be replaced with "arg1", if a $2 is encountered, it will be replaced with "arg2" and so on. A $0 will substitute the number of arguments given on the CALL command.

    This substitution will only occur if a command line is contained within a macro (i.e., if no macro is active, the "$" will not signal any substitution and it will remain in the command line as given).

    Dataplot currently only supports one level of argument substitition for macros. That is, the values of the macro arguments (i.e., the $1, $2, etc.) will contain the values given by the most recent CALL command that specified at least one argument. If you need to nest CALL commands with macro arguments, the recommended work around is to have the higher level macro extract any macro arguments passed to it into temporary variables or strings before calling any other macros. For example, supposse SAMPLE.DP needs to call SAMPLE2.DP with arguments. You could do something like the following in SAMPLE.DP:

      . Start of SAMPLE.DP macro
      let string zzzzs1 = $1
      let string zzzzs2 = $2
      let string zzzzs3 = $3
      ...
      call sample2.dp newarg1 newarg2

    The default character for argument substitution is the "$". To use a different character, enter the command

    The MACRO SUBSTITUTION CHARACTER command allows you to specify a character other than "$" to signify argument substitution.

Syntax:
    MACRO SUBSTITUTION CHARACTER <char>
    where <char> is the character to use as the macro substitution character.
Examples:
    MACRO SUBSTITUTION CHARACTER @
    MACRO SUBSTITUTION CHARACTER $
Note:
    Substitutions for the value of a parameter or a string (signified by a "^") are performed before the substitutions for a macro argument. Both of these substitutions are performed before the command line is interpreted.
Note:
    By default, quotes are stripped off the command line arguments. For example, you can have the file SUB.DP that contains

      print "Arg 1: $1"
      print "Arg 2: $2"

    If you initiate this macro with the command

      call sub.dp "arg 1" "arg 2"

    then the sub.dp macro will print

      Arg 1: arg 1
      Arg 2: arg 2

    If you enter

      set macro quote strip off
      call sub.dp "arg 1" "arg 2"

    then the sub.dp macro will print

      Arg 1: "arg 1"
      Arg 2: "arg 2"

    That is, the quotes enclosing the arguments will not be stripped off. This may be useful if you want the called macro to distinguish between arguments that denote literal text from those that denote the name of a previously defined string or parameter. That is, arguments to be interpreted as literal text will be enclosed in quotes and those that denote previously defined parameters or strings will not be enclosed in quotes. Note that in this case it is the responsibility of the called macro to decide how to interpret the arguments and to strip off the enclosing quotes if needed.

    To restore the default of stripping off the enclosing quotes, enter

      set macro quote strip on
Note:
    The command line arguments remain defined until another macro is called with command line arguments. There may be times you want to clear the currently defined command line arguments. You can do this in either of the following two ways.

    The first way is to call a macro with NULL as the first argument. This clears the command line argument list and sets the number of arguments to 0 (i.e., $0 will be 0).

    The second way is to enter the comamnd

      RESET COMMAND LINE ARGUMENTS
Note:
    The 2016/10 version of Dataplot added support for named command line arguments. For example,

      call macro.dp y=y1 x=x2 "title = Scatter Plot for Sample Data"

    Then in "macro.dp", substitutions would occur for $y, $x, and $title.

    Analogous to how $0 returns the number of command line arguments, the sequence $00 returns the number of named command line arguments.

    If a particular argument has spaces or hypens, it should be enclosed in quotes. The "=" should be enclosed in quotes. That is, use

      call macro.dp "title=Scatter Plot for Sample Data"

    rather than

      call macro.dp title="Scatter Plot for Sample Data"

    You may include one or more spaces on either side of the "=" sign. The use of spaces around the "=" sign is optional.

    The use of named arguments can be useful when you have multiple arguments and you would like one or more of the arguments to be optional (i.e., a default value will be used if the argument is not provided).

    The use of ordered arguments ($1, $2, etc.) and named arguments (e.g., $y, $title, etc.) can be mixed. For example, $4 in the called subroutine will substitute the fourth argument in the list regardless of whether it is a named argument in the calling macro.

    It is up to the called macro to support either orded arguments only, named arguments only, or both orded and named arguments.

    Although ordered arguments and named arguments can be mixed, the called macro will typically be simpler if they are not mixed.

    Arguments names should be 8 characters or fewer. They should not start with a numeric value (e.g., 1Y should not be used) to avoid ambiguity with ordered arguments. That is, $1Y will actually substitute for "$1" rather than "$1Y.

Note:
    The 2016/10 version added the command

      LIST COMMAND LINE ARGUMENTS

    This will list the currently defined ordered command line arguments and then list the currently defined named arguments.

Note:
    The 2016/10 version added the command

      PROBE COMMAND LINE ARGUMENT <name>

    where <name> is the command line argument name you are checking for. If <name> is found in the current list of command line arguments, a value of 1 is returned. If <name> is not found, a value of 0 is returned. This provides a way for the called macro to check if a specific named argument was given. For example,

     
        PROBE COMMAND LINE ARGUMENT Y
        IF PROBEVAL = 1
           LET Y = $Y
        ELSE
           PRINT "The Y argument was not specified"
        ENDIF
        

    Alternatively, you can use

      IF COMMAND LINE ARGUMENT <name> EXISTS

    So the above example would be

        IF COMMAND LINE ARGUMENT Y EXISTS
           LET Y = $Y
        ELSE
           PRINT "The Y argument was not specified"
        ENDIF
        
Default:
    The default macro substitution character is $ .
Synonyms:
    None
Related Commands:
    CALL = Execute the commands stored in a file.
    SUBSTITUTE CHARACTER = Define the character that specifies the substitution of the value of a parameter or a string in a command line.
    TERMINATOR CHARACTER = Define the character that terminates a command.
    CONTINUE CHARACTER = Define the character that specifies that a command is continued onto the next line.
Applications:
    Macros
Implementation Date:
    2005/11
    2016/05: Added SET MACRO QUOTE STRIP command
    2016/09: Added NULL option and RESET COMMAND LINE ARGUMENTS
    2016/10: Support for named arguments
Program:
     
    MACRO SUBSTITUTION CHARACTER @
    LET Y = NORMAL RAND NUMBERS FOR I = 1 1 100
    CALL HIST.DP  "Title for Sample Plot" Y
        
    where HIST.DP contains the lines
     
    TITLE @1
    HISTOGRAM @2
        

Privacy Policy/Security Notice
Disclaimer | FOIA

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

Date created: 12/05/2005
Last updated: 10/19/2016

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