Macros are used to execute repetitive tasks or create sequences of commands used to perform more complex tasks. Before reading further on you should be aware that EDA offers other facilities, not described below, but useful to perform complex or repetitive tasks. Many commands have special options for advanced uses.
Letter variables are normally defined as ordinary scalar values. It is however possible to define them as auto-increment, i.e. each reference to that variable will cause the variable to be incremented (see the section on expressions for additional details).
If you want to display results you will mainly use the OUT command and the various procedures it offers (see the chapter on expressions for details).
There are a number of input functions, explained in the section on expressions, you may use to request numerical information from the user; the SET string$ ASK command may be used to query strings from the user. Furthermore (see below) there are commands you may use to read and parse information from files.
The following control options are available with the EXECUTE and LOOP commands (and the LET/CALC/OUT family of commands).
<control-options>::= | FOR <index> [START=indstart] END=indend
| [INCREMENT=indincrement
| <vlist> INDEX <index>
| INDEX <index> VARIABLE=indexvar#
The first form uses an index <ind> and increments the value at
each step as specified. By default the first index of value is 1 (or
as specified with the START=start_value option). The final index
is mandatory. The index is incremented by 1 at teach step, unless a
different increment has been specified using the INCREMENT= option.
The second form is indexed on the current variable list, i.e. at each iteration the index takes the value from the current variable list.
The third form uses a variable in the WA, instead of the variable list. (**) See also auto-increment letter variables for an alternative.
Scalar variables are defined with a LET CALC or IF command. LET and CALC may be omitted, as long as the = sign is specified in column 2 of a command line.
>A=20.5 >LET A=20.5 >CALC A=20.5are identical commands. This command defines 'A' as a letter variable having value 20.5. Initially letter values are undefined, and reference to a undefind variable produces an error.
Scalar variables (called letter-variables) are usually modified explicitly by the user via a new value assignment.
(*) Alternatively letter values may be defined as auto incrementing variables, i.e. after each reference to the variable it is automatically incremented by a specified value.
The complete syntax is as follows:
<letter>=<sarg>
Autoincrementing
<letter>=<sarg> \ AUTOINCREMENT [I=incr] [E=end]
<letter>=<sarg> \ VARIABLE [S=start-ind] [E=end-ind]
<letter> is a single letter A..Z, <sarg> is a scalar value,
letter variable or an expression evaluated to a scalar
result.
The second format defines <letter> as an auto incrementing variable. If I (increment) and/or E (End) are not present the increment after each reference is 1 and no limit is specified. The I=increment options specifies the desired increment. If E=end-val is present, the <letter> index is incremented until it reaches this value, then <letter> remains defined at the maximum, i.e. the auto-incrementing scalar variable is no longer defined as auto-incrementing. <sarg> gives the starting value.
The third format VARIABLE indexes <letter> on the variable number given by <sarg>, i.e. the scalar variable is defined as an auto incrementing variable: <letter> takes the values from a variable in the WA, starting at case 1 and stopping at the last case (unless this default is modified using the START/END options).
The STATUS VARIABLES command is used to display the current definition status of the letter variables.
The MMG command, explained in the macro section, offers options to save and restore the current values of scalar variables during macro execution.
Note that scalar variables are also used to control loops, i.e when using a command like LET #A=log(#A) \ FOR A END=20 the A scalar variable is used to control the loop and will, after loop termination, be undefined. When using complex macros make sure not to use scalar variables containing data used further in the macro as loop control indices. Note that EDA does not perform any checks and results are impredictable.
<control-options> | FOR <index> [START=first] END=last
| [INCREMENT=inc]
| <vlist> INDEX <index>
| INDEX <index> VAR=indexvar#
| FOREVER
(Note that, with the exception of the FOREVER option,
these constructs are also used by the LET/CALC/OUT
family of commands to control repetitive execution of an
expression; the \ character, used to separate the expression part
from the control part of a command line does not apply for
the EXECUTE and LOOP commands).
The first three forms are controlled by an <index> variable. <index> is a (scalar) letter variable A..Z. These letter variables are automatically modified by the <control-option> and become undefined after the loop has terminated (normally or abnormally). Make sure to understand that <index> is a normal letter variable, i.e. for instance when you use the letter variable A as a loop control <index>, it will be set to the initial value, run through the iterations and finally be undefined, i.e. any value you might have stored into that variable will be lost. Caution: You should not set any letter variable used as an <index> within the loop (unless you really know what you do).
FOR is useful when an <index> is to be incremented in a regular way from a starting value to an ending value. Note that the START=, END= and INCR= options are standard EDA options, i.e. the value specified after the equal sign may be a simple expression, including not only scalar values but also system constants, like the number of variables in the WA ($NVR) and the like, therefore
>EXECUTE FOR A END=$NVRwill vary index A from 1 (default, as no START= option is present) to the number of variables in the current WA (This example requires that the variables be contigous) and execute the currently defined macro that many times.
This format is helpful whenever a macro is to be repeated on a number of variables in the WA, as the index is controlled by the current variable list. Consider the following single line macro:
>EXECUTE 1 5 8 10-20 INDEX A "LINE 40 #A"Index A will take successively values 1, then 5, 8, 10, 11 until it reaches 20. Index A is used in the variable list of the line macro, i.e. the macro defines a number of exploratory lines where variable '40' is always the dependent variable, and A the independent variable (different at each iteration).
This command form is mostly useful when the <index> variable is to be controlled by some computed variable, e.g. a random sequence of numbers or information/results obtained from EDA commands. Consider the following example: You want to produce an exploratory line for all groups defined by the current GVAR (grouping variable).
Please note that this examples illustrates a number of EDA features useful in macros.
>GVAR GINFO >LET G=$0 >EXECUTE INDEX B VARIABLE=G "ANALYSE GROUP=B;LINE 1,2"GVAR GINFO is used to produce a variable containing the group numbers, i.e. it produces a variable in the WA containing the group ids. Suppose that the current GVAR defines five groups (1 3 5 7 and 9) then the create variable will simply contain 1 3 5 7 9, i.e. a variable of length 5.
LET G=$0: GINFO defines result variables and result variable $0 contains the number of the variable to which the ids have been copied. Note that in this example LET G=$0 is not really needed as we could have replaced by VARIABLE=G by VARIABLE=$0 in the next command. It is however good practice to save result variables to scalar variables as many commands change the result variables automatically. (For instance in this example the LINE command will define new result variables; this does no harm to the execution loop as the variable number is only needed to start the loop. Consider for an instant that your next version of the above sequence attempts to delete the variable produced by GVAR GINF, by adding a fourth command line containing a DELETE command!).
The EXECUTE command controls a sequence of two commands (multiple commands separated by a ;). EXECUTE defines an index B, taking a value from the variable referred to in VARIABLE=G, i.e. the location to which GVAR GINFO has saved the group ids. B will therefore take a value of 1 at the first iteration: the ANALYSE command defines a selection, where only group 1 is included; LINE then operates only on group number 1. At the next iteration B will take a value of 3, performing the same command sequence on group 3 and so on until the same sequence has been performed on the last group, i.e. 7.
Make sure that the macro terminates somehow, otherwise your computer will loop forever, unless some error condition occurs.
Here is an example using the LOOP FOREVER command.
> This macro displays all lines in a file SET A$ ASK "*Enter the file name:" SET RAWIN "$A$" LOOP FOREVER ! start loop RAWIN ! get a record (line) IF $0=0 DO ! if $0 is 0, we've got a record STAT Z$ ! Show it! &ELSE LEAVE ! otherwise leave LOOP &END &LOOPEND
(Commands preceded by a + are explained elsewhere in this manual)Line macros (abbreviations):
DEFMAC define a line macro DELMAC delete a line macro + STAT MACROS show line macros EXECUTE "command" one-shot macrosMulti-line-macros
MACRO define and edit macros + TED MACRO define and edit macros RUN run macros stored in libraries or files. EXECUTE execute current macroMacro specific commands
IF .. DO conditional execution using &ELSE and &END tags LOOP start a loop within a macro LOOP "command" execute a single command in a loop CYCLE next iteration LEAVE exit loop or macro ERRORIF check error/working conditions VIF verify error/working conditions FMG file and special operations SKIP skip lines in macro execution (obsolete) MMG Misc. macro related tasksInput/Output
> Messages for the user INPUT Read from RAWIN PARSE Parse input RAWIN Read from RAWIN $<$ Read from rawinMiscellaneous commands:
MMG Macro related utilities CMPT produce intermediate results for statistical macros LOAD get program specific variables STACK stack ResVars
There are additional forms of this command: >> and >>>, useful only
within macros.
>>
> This is a plot demo > > PLOT has many options for instance: > >>>PLOT 1 2 CASID ! scatterplot using casids >>>PLOT 1 2 NUMBER ! scat with sequence numbers > > demo end.The lines starting with a single > are displayed as is. The >>> lines appear as is with a ==> in front of the text and the execution pauses. Entering <return> will execute the command and then go to the next line. If the user enters a / at the first PLOT, execution of PLOT CASID will be skipped. Note that if the users enters // macro execution will be canceled. Therefore when designing this kind of demo scripts make sure that you explain this carefully.
CMPT v1 v2 | DICHO [NORESVAR] [DIVISION=div]
| SUMS
CMPT v1 DISTRIBUTION [DETAILED | FENCES]
This command produces result variables ($0...$9)
or letter variables which are often
useful in computations, but are somewhat tedious to perform
with the LET command. No screen output is produced.
All values smaller or equal 0 (or div, if DIVISION=div is specified) are considered 0 (false), 1 (true) otherwise.
If NORESULTVAR is set results are stored in letter variables using the standard names:
default NORESULTVAR --------------------------- a $0 a b $1 b c $2 c d $3 d n $4 n
$5 sum X (X=first variable) $6 sum Y (Y=2nd variable) $7 sum X*X $8 sum Y*Y $9 sum X*Y
Without an additional option the following ResVars are set:
$0 Number of outliers (far + out)
$1 Number of farout values
$2 Number of out values
$3 Number of adjacent values
$4 Number of in values
$5 Lower inner fence
$6 Upper inner fence
$7 Lower outer fence
$8 Upper outer fence
The DETAILED option produces the following ResVars:
$0 Number of outliers (far + out)
$1 Number of farout values
$2 Number of out values
$3 Number of low far values
$4 Number of high far values
$5 Number of low out values
$6 Number of high out values
$7 Number of low adjacent values
$8 Number of high adjacent values
$9 Number of in values
The FENCES option produces the following ResVars:
$5 Lower inner fence
$6 Upper inner fence
$7 Lower outer fence
$8 Upper outer fence
CYCLE [SAME] [OUTER]The CYCLE command is only valid in macros.
CYCLE terminates the current iteration of a multi-line macro or a LOOP and skips to the next iteration, i.e. the control index is incremented.
Note that a CYCLE command specified in a macro without control options has the same effect as a LEAVE command.
The OUTER option is useful within a LOOP within a macro you are repeating; then OUTER cycles to the next iteration of the outer loop, i.e. the control expression specified on the EXECUTE command. Without OUTER CYCLE would then cycle to the next iteration in the inner loop (controlled by the expression on the LOOP command).
SAME option: Normally a CYCLE command starts a new iteration which means
that the control indexed is incremented as specified on the EXECUTE
or LOOP command. With SAME the control index is not changed, the macro is just
restarted. Be warned: This might produce endless loops, if you do not
provide a way of terminating the macro.
DEFMAC
DEFMAC <name> "command-line" DEFMAC &READ ["filename"] DEFMAC &WRITE ["filename"] DEFMAC &EDITDEFMAC defines an abbreviation or single line macro with name <name>. If <name> is used later as a command, the line is expanded to <command-line> which may be any valid EDA command line. The number of line macros is limited (See STAT LIMITS and check the NMACS value).DELMAC <name>
STAT MACROS
A macro with the same <name> as a previously defined macro, replaces that macro. Whenever a <name> is identical to an EDA command, the macro takes precedence, i.e. the normal EDA command is disactivated as long as the macro definition exists.
Normally whenever you define a new macro EDA looks for a free macro location and stores it there, i.e. normally you do not have control on where macros are stored. This is not very convenient when it comes to defining key bindings. For this reason Line macro names of the form FNn or FNnn, where <n> and <nn> are integers are treated in a special way: The number following FN is interpreted as the macro number.
This is not a problem, as long as you do not mix ordinary names with FN definitions. If you do so a problem arises. Let us suppose that no macros are currently defined, then you type DEFMAC PC "PLOT CASID" followed by a DEFMAC F1 "PRINT". As no macros are currently defined the first definition becomes the first macro; the second definition defines a new first macro, i.e. erases the first definition. Therefore you would be well advised, if you mix both forms, to define all FN macros first, followed by the non FN macros.
Note that an FN macro is not different from an ordinary macro line, i.e. you may type FN1 to execute the macro or hit the corresponding function key. The same is true for a first macro called PC: you may invoke it by typing PC or hitting the function key 1.
Note that DEFMAC &READ starts by undefining all currently define macros, i.e. after a DEFMAC &READ only the macros from the file will be active.
Note also that up to NMACS macros are read; if there are more in the file a message will be issued and the remaining macros not read. NMACS is an implementation dependent constant. ?DEFMAC or STAT LIMITS can be used to check how many line macros can be used in your EDA version.
The default file name is DEFMAC. Each macro definition has to be specified on a single line. The first word on a line is used as the macro name, the remaining section of the line contains the macro definition.
Duplicate names are rejected (only the first is used; macro names have to be different in the first four characters). Long names are truncated to the first four letters. Blank lines are ignored, as well as lines starting with the EDA comment character (default !).
A macro file might look like this:
CPLOT PLOT CASID
PBOX BOXPLOT PARALLEL
! macros used to simplify the use of the LIST command
DLIS LIST CODED DISTRIB
FLIS LIST CODED FRACTIONAL
Notes: Four macros are defined CPLO PBOX DLIS and FLIS, the ! line is
a comment line.
Note that CPLOT will be truncated to CPLOT (four letters)
The blanks between PBOX and BOXPLOT PARALLEL are ignored, as well as the
blanks before and after FLIS (4th line). There is not distinction
between lower and upper case macro names.
Read also the section above on FNnn macros.
<name> <vlist> <options>Single line macros or abbreviations are defined using the DEFMAC command. Use STAT MACROS to see the currently defined macros and their meaning.
Note that these macros may be used to redefine commands as they are searched first. If you define a macro called PLOT, the macro will be executed and not the "normal" PLOT command.
Unless you use this facility only to define simple abbreviations, you will need some understanding how the options specified with the macro definition and those specified when actually calling the macro interact. Let us consider the following macro:
>DEFMAC CPLOT "PLOT CASID X=60"
and the following examples, where the macro CPLOT is called:
>CPLOT 1,2 ! (1)
>CPLOT 1,2 Y=10 ! (2)
>CPLOT 1,2 Y=10 X=40 ! (3)
EDA works as follows: It analyses first the command line and its options
and sets them accordingly. Then it substitutes the macro definition
and re-analyses the options. This means that options set in the
macro definition override options specified on the actual command line;
options not specified in the macro definition are taken from the
actual command line. This means that example 1 will plot variables 1 and
2 a specified in the macro definition; example 2 will make a plot with
a shorter Y axis. The third example is however problematical, as
the X option specified will be ignored, i.e. the analysis of the
expanded macro will set X=60.
Information for old friends: Line macros may be used in any context:
normal EDA mode, macros, command files and loops. There are no restrictions.
ERROR
ERROR ["msg"]
ERRORIF <condition> ["message"]
<condition> NONRECTANGULAR
NODATA
var# EXIST
var# NOEXIST
SELECTION
NPFILE
NOGVAR
NOMATRIX
NOC1
NOC2
VERSION_NOT_AT_LEAST=version
var# NREQUIRED=min.n.of.cases
ERROR checks specific conditions and, if the checked condition is
not met, causes an error, i.e. aborts the current macro and
displays a message.
This command makes only sense from within macros.
Outside macros it only displays the message and no further action
is taken.
Compare with the VIF command explained below (VIF verifies the same conditions but instead of just producing a message and aborting the macro it lets you take a specific action whenever one of the conditions specified occurs.
ERROR "msg" is used in macros to terminate processing in a abnormal fashion, i.e. macro processing is immediately terminated and EDA returns to normal keyboard mode, after displaying the "msg" string. If no "msg" is present only <ERROR> is display.
The other forms of the command check conditions which should be met before running a macro or a section of it. These options are provided to offer a better error handling facility than letting the macro run into trouble itself.
Normally the standard EDA message with the corresponding error number is displayed. If a "msg" is specified, "msg" is used instead, i.e. the error messages can be customized.
NONRECTANGULAR checks whether the WA is rectangular, i.e. an error occurs if the WA is not rectangular, i.e. error message number 38 is displayed.
NODATA checks whether there is data in the WA.
v EXIST/NOEXIST checks the existence or non existence of a variable (EXIST causes and error if v exists).
SELECTION an error occurs if a selection is active.
NPFILE checks whether there is an active print file; if currently the file is not active (open, but inactive) or not open an error occurs and a message is displayed.
NOMATRIX checks whether a MATRIX is stored.
NOC1 NOC2 check if a C1 or C2 configuration matrix has been stored.
NOGVAR checks whether there is a GVAR or not.
VERSION=eda.version is provided (for the future) to make sure that a macro only runs in an appropriate version, i.e. a macro using a new feature previously not available. This option makes sure that the macro is not executed and the user gets an intelligible message. Eda.version has the form major.minor (e.g. 2.0) only.
NREQUIRED=min.n.of.cases is used to make sure that a variable has at least as many cases as specifiec, i.e. this option is useful to make sure that the macro does not run into trouble, because there are not enough cases to operate.
Hints: Besides the ERROR command there are a number of other ways of controlling macro execution. IF ... DO lets you check conditions and act accordingly (LEAVE may be used to stop the execution of a macro). System constants ($<name>) provide information you might need to check working conditions for your macros.
When working with i/o operations you may need a more
specific treatment. FMG allows for the interpretation of i/o
error codes.
EXECUTE
EXECUTE EXECUTE [<control-options>]The first format executes a multiline-macro defined by the MACRO command once or as specified by the control parameters. See the section on repetitive execution for more details on the control parameters.EXECUTE <control-options> "command-line"
<control-options>::= | FOR <ind> [S=s] E=e [I=i] | <vlist> INDEX <ind> | INDEX <ind> VAR=indexvar#
The second format treats "command-line" as command line to be executed using the control-parameters, thus allowing for repeated execution of any command. For instance:
>EXECUTE FOR A START=2 END=10 "STEMLEAF #1,#A"
>EXECUTE FOR A END=$NVR "BOXPLOT #A;DLINE #A"
The first example produces a back-to-back stemleaf for each combination
using of variable 1 and
variables 2 through 10. The second line produces a BOXPLOT followed
by a density line for each variable in the work area ($NVR is a
system constant).
(*) Macro users: EXECUTE "<command>" and LOOP "<command>" are in
fact identical commands.
FMG
FMG | "file" EXIST |
| "file" DELETE | [ABORT]
| "file" FULL |
| UNIQUE |
| ERROR=n |
The following options may not be available
on all platforms.
FMG | DO "command"
| RENAME "fnam1,fnam2"
| LOCK "fnam"
| UNLOCK "fnam"
| MD or MKDIR "dirnam"
| GETENV "name"
| BROWSE "name"
FMG (for file manager functions) performs some file functions which are
useful mostly in macros. No terminal output is produced, only result
variables are set.
The common option ABORT controls the action, whenever the function is not correctly done, i.e. $0=0. If no ABORT is present, execution of the macro continues, otherwise it is aborted. In the first case the macro writer has to make sure that conditions are correctly tested before proceeding. In normal terminal mode the ABORT option has no effect.
If the action could not be done, $0=0, otherwise $0=1.
DO "command" submits <command> to the system interface for execution. Note that no all systems can execute all commands from within another program, i.e. EDA. Some systems support only subsets of the normal command set. Furthermore you might not be allowed (restrictions) to do so or the system may not have the resources (namely memory) to do so. The DO option is an alternative to the system interface (on most systems called typing a $ in column 1 of an EDA command line) call. Both functions are identical, except that the normal system interface call asks you to type return before going back to EDA; FMG DO does not pause, i.e. is is especially useful if you use the system interface to perform some short command (where you are not interested in the screen output produced).
RENAME lets you rename a file. The syntax is somewhat particular, i.e. FMG RENAME "fnam1,fnam2", where <fnam1> is the original name you want to change into <fnam2>. The comma between the two names is essential.
LOCK/UNLOCK is used to set file attributes. LOCK set read only attributes, i.e. the file is protected against modifications or deletions. UNLOCK does the opposite, it sets write and delete attributes. Before relying on this make sure that you understand this on your system. These options cannot work if you do not have privileges to set file attributes.
MD or MKDIR makes a directory. You need the required permission in order to perform the function. Note that there are differences between operating system, some consider that creating a directory when it exists already is an error some other consider this a normal situation. [On some systems the FMG "filnam" EXIST command may be used to verify the existence of a directory].
GETENV "name" looks up the external environment to find a definition for <name> and returns it in Z$ when found. If name is not defined, Z$ will be an empty string. [There is never an error, except when the facility is not implemented]. "name" refers on many computers to "environment variables" or "logical names". On a PC-DOS system, as well as on a Unix system this refers to variables defined with the SET (DOS) or SETENV (Unix) command.
BROWSE shows "name" using the currently defined Web browser (if no browser is defined this command does not work).
Result variables set:
0 set by all options $0=0 not successful $0=1 successful 1 for DELETE/FULL contains the error status, i.e. the system specific i/o error number returned by system z$ UNIQUE contains the string result
IF <scalar-logical-expression> DOThis special form of the IF command is used in macros to provide a way of executing portions of a macro conditionally. IF .. DO is used together with the &END and &ELSE tags, which are special commands used only after an IF .. DO command.
The logical expression may only be a scalar expression. Important: IF .. DO should clearly be distinguished from IF .. DO <command> which is used to execute a single EDA command.
An &END command (tag) is mandatory to indicate the scope of the IF .. DO. An &ELSE tag can optionally be used to provide alternatives.
Limitation: Note that IF .. DO ... &END cannot be nested.
>IF A=1 DO >> This section is executed only when >> the scalar variable A is equal to 1 >&ELSE >> In all other cases you will see this >> message on your screen. >&END >> This will be shown in all cases.Note that this is only an illustration the > command is used here to display informational messages. [Note the second > is the command, the first is only the EDA prompt you do not type].
LEAVE LEAVE DO <command> LEAVE MACRO [DO <command> ] LEAVE ALL [DO <command> ]
The LEAVE command is used to exit a macro, loop or command file.
When used without control options or in command files, LEAVE simply terminates the current activity. In command files and macros LEAVE is then used to terminate the execution somewhere else than at the end of the command sequence, i.e. usually in conjunction with an IF command.
When used within a macro, controlled by a control expression, LEAVE terminates its execution.
Within a LOOP, LEAVE is used to terminate the LOOP, but not the macro itself, unless either the ALL or MACRO option are added.
This options is particularly handy, as you may have only a single current macro. But you could use the DO option to chain to a different macro (either stored in an archive, so you can run it; or in a file where you could retrieve e.g. by using LEAVE DO MACRO "newmacro";EXECUTE, i.e. the contents of the file "newmacro" are made the current macro which then is executed.
ALL is useful when your are within a LOOP in a macro called from a command file and you want to make sure that you really return to normal EDA mode, i.e. ALL returns control always to the user.
The LEAVE command is used to terminate a macro, command file or loop
in a normal condition. You should not use LEAVE to terminate a macro
because an error occurred, use the ERROR command instead; this makes
sure that the macro terminates in error and the necessary cleanup
operations are performed. This makes also sure that EDA terminates when
you are running it as a batch job or from a command file; LEAVE could
then produce strange messages.
LOAD
LOAD | v CSEL --> SELMANAGER command
| vlist VLIST --> DS/VARS/DESCRIBE commands
| GREFERENCE --> GVAR command
LOOP <control-options> LOOP <control-options> "command-line"The LOOP command is only allowed within a multi-line macro. It is used to repeat one or several EDA commands under the control of an index. See the section on repetitive execution for more details on the control options.<control-options>::= | FOR <ind> [S=s] E=e [I=i] | FOREVER | <vlist> INDEX <ind> | INDEX <ind> VAR=indexvar#
LOOP comes in two forms: LOOP followed by a sequence of command lines and terminated by the special tag-command &LOOPEND and in a single-line form, where the commands to be repeated are specified as a "string".
The following rules and restrictions apply:
MACRO
MACRO {["fname"]
MACRO WRITE {"fnam"}
MACRO LIST
With no option MACRO
defines a macro containing a series of EDA commands
(multiline-macro) which is invoked by the EXECUTE
command. EDA will prompt you for commands to be stored as
the current macro (an m: prompt will appear). You may enter
any number of commands (disk space permitting).
Terminate with the // (end signal). Then normal EDA mode
resumes.
Macros may also be created and edited with the EDA text editor TED, using TED MACRO (see there for details).
The current macro may also be defined automatically when GETTing a new work area (see the PUT command for details). Optionally the macro can be executed automatically when loading the WA, i.e. after reading in the WA, the program behaves as if an EXECUTE command had been issued. See the PUT command on how to save a macro on an EDA file.
Macro execution is terminated by the program if an error is detected during execution, the system then displays
... macro execution terminated.
the preceding error message explains the reason. If no error condition is detected, no message is displayed. See also the SET command, if you want to continue macro execution (SET ERROR), despite of errors. There is also an SET (MESSAGE) command to suppress informational messages issued during macro execution (namely the starting and ending messages).
Special note for string variables: When reading from the terminal string variables are always substituted, i.e. when typing in macro commands containing e.g. an $A$ reference, it will be substituted when you type in the macro, and not when you execute it. If this is not what you want, i.e. if string variables are to be substituted during macro execution you will have to enter them as &A$, &B$ etc.
Macros may contain a number of commands not allowed in normal EDA mode, namely the LOOP, CYCLE, LEAVE and IF .. DO commands (see there).
You may also enter an explanatory text at the end of the macro. This text will be displayed when you type ?EXECUTE. This text may have any length and starts with a special tag: &/ (columns 1 and 2). All lines following this tag are not executed, but only displayed with ?EXECUTE.
The WRITE option causes the current macro be written to a file named EDAMAC or as specified by "fnam". The
LIST option simply lists the stored macro to the screen.
In many circumstances command files are an alternative
to macros. Compare also to the RUN command.
MMG
Macro execution status MMG [PRINT]MMG handles a number of macro related tasks.Zero variables MMG SET_LETTER_VARS ZERO [AtoM | NtoZ] Set variables MMG SET_LETTER_VARS <l>=<val> (...) Set ResVars MMG RETURN_RESVAR <l>=val (...) ["string"] Save/restore variables MMG SAVE [<what>] MMG RESTORE [<what>]
<what> : [ALL] | [RESVARS] [LETTER | AtoM | NtoZ] [STRING]
ZERO sets all variables to 0, with the exception of letter variables in use as index variables, i.e. you may use MMG SET ZERO savely from within a LOOP or repeated macro.
Note that MMG SET ZERO sets all variables to zero, including the variables you have not used yet. (Initially all letter variables are undefined, i.e. whenever you refer to such a variable you will receive an error message. After a MMG SET ZERO this will not be the case, as it defines all variables by setting them to 0.
MMG SET <letter>=<value> [<letter>=<value> ...]MMG SET is used to set letter variables to specific values. You may specify as many letter variables as needed on the same command.
MMG SET A=1 C=21 M=16 H=19.2 V=-1This option simplifies macro writing as you write a single line instead of a sequence of LET commands assigning a value to letter variables. Note that you may only use simple expressions with MMG SET, i.e. whenever <value> is a complex expression you cannot use MMG SET. MMG SET is therefore helpful only for simple initializations, common at the start of a macro.
MMG RETURN <letter>=<value> [<letter>=<value> ...] ["string"]This options lets you define result variables, i.e. its intented use is to let you define macros behaving the same way as normal EDA commands, i.e. producing ResVars at command termination.
As the EDA syntax does not allow for assignment of values to result variables you will need to use letters instead. The following table shows the equivalence between letters and ResVars:
letter ResVar Letter ResVar
---------------- ---------------
A $0 F $5
B $1 G $6
C $2 H $7
D $3 I $8
E $4 J $9
Remember that ResVars $0 through $4 are integer values; $5 through
$9 real values.
The optional "string" specifications defines Z$.
By default letter variables (A..Z) and the string variables (A$, B$ etc) are saved and restored. Result variables are not saved/restored. You may change the default variables by specifying an additional option. ALL saves all variables, including ResVars ($0 through $9). STRING, LETTER and RESVAR save only string, letter and result variables respectively. The AtoM and NtoZ save only either letter variables A to M or N to Z.
Note that MMG SAVE is temporary, i.e. when QUItting EDA the saved settings are lost. Furthermore if you issue e.g. an MMG SAVE LETTER command you will save the current state of the letter variables. All other variables (ResVars and String variables) are saved as all 0 and all blank, i.e. if you issue e.g. an MMG RESTORE ALL, letter values will be restored to the values saved, but the ResVars will be set to 0 and the string variables to blank.
Defines the following ResVars $0 Max number of lines possible in a LOOP $1 Current iteration of outer loop (-1 if no outer loop) $2 Current iteration of inner loop (-1 if no inner loop)
Parse full string(Compatibility notice: PARSE has been expanded considerably and the syntax has been clarified, especially the long FORMAT=() for numerical values. Although the old format is no longer documented, it is still supported, i.e. there is no need to change old macros). The purpose of this command is to extract numerical values or strings from Z$ and placing the result into variables or casids, labels and descriptors.PARSE LINE VARIABLE[=var# {APPEND}] [NOLABEL] [NODESCRIPTOR] [IGNORESTRINGS] [Form=position][<opt>] PARSE vlist LINE CASE[=cas#] [NOCASID] [IGNORESTRINGS] [<opt>] [IGNORESTRINGS] [Form=position] [NOCOMPUTE] [<opt>]
Parse a single value:
PARSE [PULL] [<target>] [Format=(Position{wid,ndec})] [<opt>]
<target> | $n (default $5) | letter_variable | VARIABLE=var# [CASE=case#] [NOCOMPUTE]
Parse casids, labels or descriptors
| CASID=cas# | PARSE [PULL] | LABEL=var# | [Format=(pos[,wid])] [<opt>] | DESC=var# |
<opt> [ERR=val] [ABORT | NOMESSAGE] ["separlist"]
Make sure to understand that PARSE offers facilities to create macros for particular or more complex data input needs not covered by ordinary EDA facilities. Therefore before reading on, check the *READ command and its various options, as well as the EDA Toolbox (especially the DG/Data Grabber utility).
PARSE processes the current Z$ (ResVar) which usually contains a string read by the RAWIN command (see there) or stored by some other means (SET command or implicitely by a command). Remember that Z$ is a special string variable, set automatically by many commands, i.e. is important to PARSE it before another command stores a different string. (This is usually not a problem as most macros will read data input and process it immediately.)
PARSE offers basically two ways of extracting information: PARSE LINE which attempts to process the full Z$ in a single step and the other options used to extract individual items (values, casids, labels or descriptors).
PARSE LINE as well as the other forms of the command (not reading from fixed positions) consider the Z$ string as a sequence of items. Items are either numerical or string and are separated from each other by a common separator (space, comma,tab or semicolon). (There is also a "separlist" option; it lets you specify alternative item separators.) A string starts with an alphabetical character a numerical item with a numerical (digit, sign or decimal point). A string may also be quoted (using single or double quotes).
Let us consider some examples:
abcd,1,20,31,23,21 30;34
abcd,efg,xyc 1 20 31
"abcd,efg,xyc" 2 39 31
The first record contains 8 items: 7 are numerical and the first is
a string. The second record has three strings and three numerical
items. The third record contains one string (as it is quoted) and
three numbers.
Note that PARSE offers a number of ways of processing unexpected items (string instead of a number). Please make sure to understand what PARSE will do whenever an error occurs. Check your macro; do not only use well behaved data!
During processing an error may occur: usually a non-numerical item is parsed as a numerical item, i.e. PARSE will not be able to extract a number. By default a missing value is assigned (defined by default: SET REPVAL or by the ERROR=value option on the PARSE command line) and a message is issued. Two additional options are available: NOMESSAGE does not produce an error message, but assigns missing values and ABORT which issues a message and aborts, i.e. the macro is aborted amd no further element is parsed. Usage of these options will depend upon the kind of problem your are solving and the amount of macro commands you are prepared to write in order to detect error conditions.
Empty Z$: An empty string cannot be parsed. If you try to do it, an error occurs and is treated as all other errors: Default (message, no parsing, but macros are not aborted), NOMESSAGE (no parsing, no message, macros not aborted), ABORT (message, no parsing and abort macros). Note that $0 is set to 999. Empty Z$ can be detected: RAWIN has an option to ignore empty records; SET/STAT strings produce ResVars with information on strings; PARSE PULL returns the remaining trim length as $1.
PARSE LINE VARIABLE considers the Z$ as a sequence of items belonging to a variable. By default the first string item (if present) is stored as variable label, the second string item (if present) is stored as variable descriptor, all other strings are considered as data, i.e. will produce an error or a missing value depending upon the options you have selected. Numerical items are of course considered as valid numerical data, i.e. the first number is the first case, the second the second and so on. The variable will be stored into a free location in the WA (a message tells you where the variable has been stored. If no strings are present or the descriptor is missing labels and descriptors will contain question marks, but no error will occur nor a message will be issued. Blank strings (i.e. quoted strings but empty) will cause an error, handled according to the overall rules (NOMESSAGE, ABORT options).
Alternatively you may specifiy a target variable using the VARIABLE=var# option. With this option you may also request to APPEND the newly parsed data to the variable specified, enabling you to process several strings and still building a single variable.
There are three options dealing with string items. NODESCRIPTOR does not create a descriptor, i.e. the second string item found is treated as numerical item (i.e. an error or a missing value). NOLABEL inhibits the creation of the label and of the descriptor. Futhermore IGNORESTRINGS may be used to handle string items in locations where numerical items are expected: String items are simply ignored, i.e. they do not cause an error message to be produced or a missing value to be generated, they are simply skipped.
PARSE LINE CASE considers the contents of the Z$ as a single case (observation). This form of the command requires a variable list (<vlist>) telling EDA for which variables a case has to be created. In most macros a sequence of PARSE commands will be used to create the required number of cases for the same variables; this requires of course that each case contains the same number of numerical items.
PARSE LINE CASE may be used to append a case to existing variables or to create new variables. PARSE 1-10 LINE CASE will create a new case for variables 1 to 10. If the variables exist they should have the same length, if they do not exist they will be created. (Note that if some variables exist and some don't an error message will be issued).
Appending a new case means adding a new case after the last case, i.e. increasing the number of cases by one. You may also specify CASE=cas#, which then means that you want to replace an existing case by the data read with PARSE.
By default the first string item will be stored as the CASID for the case to be created. Further string items will be treated as errors and produce either an error message or a missing value. The NOCASID option may be used to inhibit the creation of a new casid. Furthermore the IGNORESTRINGS option may be used to ignore strings, i.e skipping them.
Want to optimize?(with PARSE LINE CASE): All EDA variables have attributes containing minimum, maximum and a center value, the default center value is the median, i.e. after the creation of each case (imagine an example where you create 200 cases with 200 PARSE LINE CASE commands in a loop) PARSE will compute these attributes for each variable. If you want to avoid this add the NOCOMPUTE option, but then these attributes will be wrong, unless you perform the last PARSE option without this option. Another possibility is to compute these attributes after all cases have been created using the COMPUTE vlist command found in the EDIT module. You will probably want to execute it in "immediate mode", i.e. by sending the /COMPUTE vlist command from normal EDA mode (instead of entering EDIT, executing COMPUTE and leaving EDIT, i.e. a three command step).
Hint: PARSE LINE CASE works well as long as all input strings fit into the same scheme (casid always present and same number of items etc), but, even with the automatic generation of missing codes, you may not always get what you want. Consider that PARSE LINE VARIABLE creates a new variable each time, i.e. two PARSE LINE VAR in a sequence do not have this kind of constraints. On the other hand EDA offers a number of facilities for transposing single variables (see expressions) or transposing the whole WA, i.e. you may often be able to work around the constraints of the PARSE LINE CASE command by reading each "case" as a "variable", arranging the variables the way you want then and finally tranposing in order to get the "case" you wanted from the start.
There are basically two ways of performing this task: extract from fixed positions and extract items. Whenever you specify a Width on the FORMAT option PARSE operates on fixed locations, otherwise EDA extracts the next item found in Z$. By default PARSE starts in column one (FORMAT=position defaults to 1). If you want to start parsing at a different location you may specify a different position.
Whenever you specify a FORMAT=(Position,width) option the information is extracted from the information starting at Position and width columns wide. A third item may be specified with FORMAT telling EDA how many decimal positions should be read.
PULL: when parsing items (without width) it is often useful to remove the information you have parsed from the Z$ string, i.e. the next PARSE command starts again at the beginning of the string. Let us consider an example:
Consider Z$ = Socialists Communists Liberals(This example uses the LABEL option, but all other options shown in this section can make use of PULL). LABEL=1 asks PARSE to extract the first item in the string as the label of variable #1, i.e. the label of that variable will be "Socialis" (truncated to 8 characters); PULL means that, after the command has terminated, Z$ contains only "Communists Liberals". Therefore the second command line will set the label of variable #2 to "Communis" and leave Z$ as "Liberals" and finally the last command will extract that item and store it as a label for variable #3, leaving Z$ empty. Note that the FORMAT= option is usually not useful with PULL.>PARSE PULL LABEL=1 >PARSE PULL LABEL=2 >PARSE PULL LABEL=3
(1) Result variables $2 through $9. Remember that $2 through $4 are considered integer values, $5 through $9 real. Result variables $0 and $1 cannot be used as the return error codes and other information from the PARSE process. When using this option make sure to understand that ResVars are result variables modified by many commands, i.e. you will most likely put a value into a ResVar and the next command in the macro will take it up to do something with it.
(2) Letter values: the letters A through Z, which then may be used anywhere you like.
(3) Finally you may store the result into a variable in the WA, using the VAR=var# option. If the variable does not exist it will be created. If the CASE=cas# option is present the value will replace the current value, i.e. cas# refers to an existing case in the variable. If CASE is not specified the parsed value will be appended to the variable. The NOCOMPUTE option has the same meaning as with PARSE LINE CASE (see there) and may be used to speed up macros reading large amounts of data.
(4) If no <target> is specified the result will be stored into $5.
You may also specify an option dealing with error handling. If a string is not present, i.e. blank, an error occurs. It is handles as follows: By default a message is issued and the result set to '?'; if NOMESSAGE has been specified the result is '?' and no message is issued (however $0 is set); finally ABORT stops the parsing process and, if present in a macro, aborts the macro.
PARSE LINE
$0 Number of missing values produced, i.e. errors when
converting numbers or blank strings replaced by '?'
$0=0 No errors have occurred.
$0=999 Attempt to parse an emtpy Z$
$1 Number of numerical items extracted.
Other options:$0 Number of missing values produced, i.e. 0 or 1. $0=1 if conversion error occurred or if a number has been found instead of a string (CASID, LABEL, DESCRIPTOR). $0=999 Attempt to parse an emtpy Z$ $1 Only with PULL: Trim length of Z$ after PULLing, i.e. if $1=0 Z$ is empty.
TED can also be used to perform preliminary editing, e.g. Remove specified columns, align on specific columns etc.
Whenever the data is read from the keyboard
(e.g. SET Z$ ASK "Your prompt")
you might find alternatives with the input fonctions offered with
expressions: QRY (query a value) QRL (query a value and check
limits) QRA (Yes/no query) and RDV (read a data vector).
RAWIN
RAWIN [NOABORT] NOMESSAGES] [NOCLOSE]
[SKIP=n.of.records]
[BLANKSKIP]
[SEARCH "string" {ANY | POS=column} [REWINDBEFORE}]
Purpose: reads a single record from the RAWIN file into Z$.
RAWIN must be open; use SET RAWIN do so, as well as for other
operations in connection with this file (closing, rewinding etc.).
A RAWIN command reads the next record in the file, i.e. after
opening a first RAWIN command reads the first line in the file, a
next RAWIN command will read the second record and so on.
A number of options are available to skip a number of records or to search for a particular record.
SEARCH ANY: The ANY option checks for the string anywhere (not in fixed locations) on the current record. With ANY wildcards cannot be used.
REWINDBEFORE: This option is useful if you want to start the search from the beginning of the file and not from the current position.
If the RAWIN command contains a SEARCH option an additional message is issued telling you that no match has been found.
If you do not want to display these messages use the NOMESSAGES option. These messages are not displayed if you have the MESSAGE switch is OFF (see SET MESSAGE).
Note that the end of file condition is not considered an error, i.e. a macro will not be aborted. Note however that if you attempt to perform another RAWIN operation an error will occurr (RAWIN not open), unless you specified the NOCLOSE option.
See the section on ResVars below on how to check the end of file condition.
If no option is present the command and the macro are aborted and the system issues an I/O error message, explaining the reason why the I/O operation has failed.
NOMESSAGES aborts the macro and the command, but no RAWIN specific i/o error message is issued (i.e. a well designed macro will handle that problem somehow.)
NOABORT: When this option is present the macro is not aborted. I.e. a well designed macro is expected to check error conditions (see below) and act accordingly.
ResVars: Z$ contains the record read
$0 I/O termination status
$1 trim length of z$
An alternative to the RAWIN command is the string variable
substitution invoked by $<$, meaning that the string variable
is to be taken from the RAWIN file (this is similar to $A$
invoking the substitution of $A, the string is however read
from the
RAWIN file). The only difference between the RAWIN command is that
RAWIN is a separate command (with some options) and $<$ may be
part of any keyboard input. It offers however less control on what to
do in case of error.
Note also the $<$ in fact reads the record on RAWIN into Z$, i.e. the temporary string variable. This is important as you should not rely on the contents of Z$ from previous commands, as well as after a $<$ reference (e.g. most file command return the name of the file in Z$, this of course is set after the $<$ substitution which has been done on syntax scan). Therefore as a general rule whenever you wish to use variables either from $<$ or Z$ make sure to use nonvolatile string variables instead.
Hint: If you need to know how many records are in a file for
RAWIN control purposes you may use e.g. the SNIFF tool which
will return in $0 the number of records (use immediate mode and
the nodisplay switch).
RUN
RUN name
RUN &DIR
RUN "file name"
Runs a macro found in the EDA macro library. This feature does
only work if a macro library is installed at your site.
The macro named is searched and then treated like a sequence
of MACRO "name" followed by an EXEC. In fact this command uses
the same mechanism, therefore destroys a previously defined macro.
On the other hand an EXEC will re-execute the macro RUNned previously.
RUN &DIR is used to display the names of the macros in the
library.
The second form, RUN with a name enclosed in strings, does not
search the EDA macro library, but takes a file name; it is
identical to MACRO "filename" followed by a EXECUTE command.
SKIP
SKIP [C=ncomm]This provides a primitive form for conditional execution of commands in macros. Default is to SKIP the next command line, i.e. SKIP one command line. C=n may be used to SKIP a specified number of command lines in a macro. n may be negative. Note that SKIP may be used to terminate a macro or to cycle to the next iteration if a control structure is present by skipping a very large number of commands (make sure that n is larger than the total number of command lines).
STACK
STACK $n ["label descriptor"]
STACK OFF
This command is used in advanced applications, where it is desired
to keep the temporary results of a command stored into the result
variables ($0..$9).
It is possible to store them into letter variables or into
vector variables in the WA using the various facilities supplied, e.g.
using the CC() function to concatenate a $var with an already existing
variable. Sometimes, especially when playing around with some numerical
experiment this might be rather tiresome and/or time consuming. Here
the STACK command can help.
The STACK command is used to activate and control stacking, i.e. storing a specified result variable into a variable in the WA. Actual stacking is performed by specifying the global switch /S on the command line (command whose resvar is to be stacked.
/S has only an effect if STACKING has been activated using the STACK command. If this has not been done nothing happens (no message given). Stacking is activating by saying STACK $n, where <n> is 0..9, i.e. one of the $vars. The effect is that a free location in the WA is set aside in order to receive the values one at the time. If no free locations are available, an error occurs. If you enter STACK $1, each time a command is entered with the /S switch the value of $1 is stored into that variable after the command has terminated normally (in case of an error nothing is stored). In order to use the variable containing the result you need to terminate stacking, i.e. entering STACK OFF.
This way of keeping the result variables, i.e. storing them into a variable in t means that up to MCAS values may be stored that way. If you attempt to store more the stack is considered full (/S never issues any messages) and further /S will have no effect. All STACK commands will tell you that the stack is full.
The "label descriptor" option is used to give a name to the resulting variable; if no "s" is present, default a default label and descriptor will be generated.
STACK OFF is used to terminated stacking and making the variable available to the user. During stacking the variable exists, but is not accessible to normal commands. The DESCRIBE command will show you the variable, as being of length 1 and of type 'O'. The variable will not be created if no /S has been specified, i.e. no value has been stacked. If STACK OFF issues a message "stack full" this means that more than MCAS values have been stacked, and only the first MCAS values have been stored and will be available in that variable. This is a warning only, i.e. STACK OFF is performed.
Finally STACK without any option shows the current state of the STACK command, i.e. whether stacking is active or not, and what resvar you are stacking into what variable.
resvars: STACK OFF $0 target variable
$1 length of target (# of items)
Let us consider an example: Suppose you want to perform a numerical
experiment involving the slopes of exploratory lines and the variables
to do so are stored in the WA in locations 1-100, variable 1 being the
dependent variable. You need to keep all slopes in a variable. With
stacking this can be done as follows:
STACK $5 ! $5 contains the slope from a LINE command
EXECUTE "LINE #A,1 /S" 2-100 INDEX A
STACK OFF
STACK $5 activates stacking. The next line asks for repetitive
execution of the LINE command on the variables 2-100 indexed on A.
At each invocation a different $5 is produced and stored into a
free location in the WA. (The /S switch does this).
Finally the STACK OFF turns stacking off and tells you where the
results are.
It is important to understand that each command containing a /S stores
only one value. Therefore a command like DISP 1-10 /S will stack only
the last result variable.
In this case you will also need a EXEC command if you
intend to keep the resvar for each variable in the list.
VIF
VIF <condition> "<command>"
VIF (Verify_IF) checks <condition> and if it is true executes the
<command> specified in quotes.
<condition> are the working conditions/settings listed with the ERRORIF command above. Unlike VIF, ERRORIF produces an error message and aborts the macro.
"<command>" contains the command (or multiple commands separated by semicolons) to be executed whenever the <condition> occurs. Note that "<command>" is limited to the maximum length of option strings (60).
The following command (within a macro):
>VIF NPFILE "PRINT ALL"checks whether a print file is open (NPFILE = No print file), if a print file is open no action is taken, otherwise the PRINT ALL command is executed.
<letter>=<value> <param>
where <value> may NOT be a full expression, however a simple
expression may be specified.
Also you should not use string variable A$ in macros to avoid possible conflicts with commands you might add, as this variable is often used to communicate some string to a command.