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:

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:

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:

Examples:

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:

If you initiate this macro with the command

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

then the sub.dp macro will print

If you enter

then the sub.dp macro will print

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 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:

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 argument list can be enclosed in parentheis. Note that the use of parenthesis is optional. You can optionally include one or more spaces between the arguments and the parenthesis.
For named arguments with quoted values, you can include only the value of named argument in quotes. That is,
Previously, this had to be entered as
"file=c:\my data\test.txt"
If the argument name is not inside the quotes, then you cannot have spaces around the equal sign. If the argument name is inside the quotes, then spaces around the equal sign are optional.
Commas can optionally be used as an argument delimiter. You can mix the use of spaces and commas as the delimiter. For example
Although this is allowed, it is recommended that if you use commas that you do so consistently. That is,
Previously, calling a macro without arguments would clear the current command arguments. This was changed so that a CALL command without arguments will not modify the current command list arguments.

Specifically, the following are all acceptable ways to enter the same argument list.

Previously supported:

New formats:

The choice of which syntax to use is primarily a matter of personal preference.

Note:

LIST COMMAND LINE ARGUMENTS

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

Note:

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:

Program:

 
MACRO SUBSTITUTION CHARACTER @
LET Y = NORMAL RAND NUMBERS FOR I = 1 1 100
CALL HIST.DP  "Title for Sample Plot" Y

 
TITLE @1
HISTOGRAM @2