ViGYAN's DESL

( TI) DESL Macros

One of the more powerful features of DESL is that which allows the user to build custom command sequences - macros - from the system-supplied standard DESL commands. These new macros can then be executed as if they were normal DESL commands with the added capability of being able to pass them one or more arguments.

In this context, therefore, the term macro is defined as a special block of input containing a series of one or more DESL command input sequences. This block of input must have a header line containing two fields :

the string macro
a macro name

Example : macro plot.mac

The block must be ended by a line containing the special DESL non-operative command endm as its first field.

Macros are installed in a DESL session via the macrolib DESL command.
Up to 100 macros can be installed at any one time in a DESL session.
All macro lines, like all lines in any other form of input, are in free-field format and limited to the first 130 columns read.
Formal option argument lists contained within macros can reference dummy arguments whose names are of the form %str, where str is the name of an argument which can be passed to the macro at the time of execution. The percent sign (%) is the leading character of an argument in the macro which is to be substituted for at run time.
Dummy macro arguments used in formal argument lists do not have to stand alone; they can be used as a part of another string.
For example, all three of the following string sections are legitimate :
1. %val
2. run%run
3. Config%body
In the second and third cases, you will note that the dummy arguments "%run" and %body, respectively, do NOT stand alone but are used as a part of the longer string "run%run" and "Config%body.
Up to 99 arguments can be passed into a macro by including them on the command line and on one or more macro invocation continuation lines. Continuation lines can follow lines which ended in the & field (blank + ampersand).
The thru option can be used during the specification of macro arguments but the user has to be aware that it is passed to the macro literally; i.e., it is not used at macro invocation time to expand the passed in arguments. Expansion may be done in the context of the argument list(s) in the macro after all argument substitution has occurred.
Each macro argument must be 16 or less characters long. If an argument has one or more embedded blanks the question mark (?) string delimiters must be used. If an argument longer than 16 characters needs to be used, it must be broken up into parts of 16 or less characters in length.
Dummy arguments within a macro which argument names which were not actually specified, are illegal unless they are enclosed in square brackets ([ ... ]) implying that the entire bracketed section of input will be eliminated at run time unless every argument contained therein is actually passed to the macro.
At the time a macro is invoked all dummy arguments in that macro, as well as in any macros which are called by that macro, have their settings established. Therefore, within a macro, command input can include the use of "readn" and/or "usen". The input pointed to by either of these global options, however, should NOT contain any macro argument strings (strings of the form %str ). The expansion of both "readn" and "usen" is not done until the pertinent command input is encountered as the associated DESL command is being processed.
Macros can execute other macros. Macro nesting can occur up to 100 deep. Macros, however, cannot be recursive; i.e., they cannot execute themselves.
Any installed macro which has a name equal to a standard DESL command or command abbreviation name will cause that macro, at the time of execution, to be used instead of the similarly-named DESL command.
No blank lines should be included in a macro.
DESL System and User registers can be used as arguments at the time of invocation of a macro.

Lines in a macro should not contain sequences of characters longer than 16 characters (sequences this long without intervening blank(s)) unless it is intended that such a sequence be considered as a single entity. Where possible, use blanks to keep sequences of characters no longer than 16 characters. The standard question mark delimiters can be used to force the consideration of a sequence of characters longer than 16 characters as a single entity. During the interpretation of lines in DESL sequences of characters longer than 16 characters without the question mark delimiters will be truncated to 16 characters.

Some examples of practical macro examples exist for your perusal. More will be added as time goes on.

The following is an example of a sequence of lines containing two macros, "m1". Its serves to illustrate all of the macro features mentioned above. A discussion of the content of this macro and its execution is also given.


macro m1
* The purpose of this macro is, via "filter", to break a
* multi-run SIF up into up to 10 temporary new files, each of
* which corresponds to one value of "run".  Then, for each
* of the new files just created by "filter", the variables
* "cl", "cd", and "cm" are then fit to fixed values of the
* independent variable.  The constant value of "run" is also
* retained.  Then, as a final step, the new fit files are
* stacked into a single new file and the macro ends.
*
* The following arguments must be specified
* on the invocation line :
*
* Arg name
*
* fn    .... the original multirun SIF file to operate on
* newfn .... the final resultant fit, stacked file containing
*            the desired, specified "run" data
* ivname ... the independent variable name
* vals ..... the desired values of "run" for this execution
*
  echo off
  os on
  filter
    files %fn run eq vlist
    newfilex >flist1
    values  %vals
    seq  go
  fit
    files  %fn <flist1 values 0 to 20 by 1
    names %ivnam cl cd cms
    nofit run newfilex >flist2 go
  stack
    files <flist2 newfiles %nf go
  cl
    xfiles <flist1 <flist2 go
  os off
  echo on
  endm

As an example, this macro can be executed with a command form as follows :

m1 -fn multirun -nf stakfit -ivnam alpha -vals 1 4 5 7 9 12 45

As a result of the above macro execution line DESL will take the following actions :

(1) Turn off system echoing

(2) Turn on the ability to overstore existing files

(3) Execute the "filter" function :
    (a)  Access the setting of argument "fn" as the file to
         filter : "multirun"
    (b)  Attempt to create new files to satisfy the multi-valued
         "run" filter condition whose values have
         been passed in as arguments and are 1, 4, 5, 7, 9,
         12, and 45.
    (c)  Via "newfilex", capture the system-generated new file
         names in list "flist1".

(4) Execute the "fit" function :
    (a) Files to fit will be established by satisfying the
        dummy argument references from the "m2" execution
        line.  All of the file in the list "flist1" will be
        used.
    (b) The independent variable to be used in the fitting
        operations is a dummy argument.  Referenced as
        argument %ivnam on the macro execution line, the
        variable "alpha" is substituted.
    (c) Fit fill attempt to create new files, whose names will be
        stored in list "flist2".

(5) Execute the "stack" function :
    (a) access files named in the list "flist2" created by
        the fit function.
    (b) create a stacked file "stakfit", which is named
        via the dummy argument %nf substitution from the macro
        "m1" execution line.

(6) Execute the "cleanup" command
    (a) the new files named in the two lists, "flist1"
        and "flist2" will be deleted from the users
        current directory

(7) Turn off the ability to overstore existing files

(8) Turn on system echoing

Another practical example of a DESL macro is the following which could be used to calculate the classical beta derivatives.

macro bd * * macro bd : * * Compute standard beta derivatives from two files * containing alpha sweep data at two different values * of beta. The second file's dependent variable data * will be fit via a third-order fit to correspond * the values of the independent variable from the first * file. * * Calling syntax : bd file1 file2 newfile * * Assumed : Name of file containing the equations * to be defined in-line to calculate the * derivatives = eq.nbd * * Names of variables which will be used to * compute derivatives : alpha,beta,crm, * cym,cy,run * os on echo off merge files %fn nameset 1 alpha1 = alpha beta1 = beta crm1 = crm cym1 = cym cy1 = cy run1 = run nameset 2 alpha2 = alpha beta2 = beta crm2 = crm cym2 = cym cy2 = cy run2 = run names alpha order 3 newfiles tempfil go create eqn.bd local deltab deltab = beta2-beta1 newrun = aint (run2+.5) * 1000 + aint (run1+.5) dcrmdb = (crm2-crm1) / deltab dcymdb = (cym2-cym1) / deltab dcydb = (cy2-cy1) / deltab endcreate eqn files tempfil eqfile eqn.bd newfiles %nf go cl xfiles tempfil go os off echo on endm

This macro can be executed by the line :

bd -nf run3 run4 -nf beta3-4

where "run3" contains data for an alpha sweep at beta1 = sideslip and "run4" contains data for an alpha sweep (nominally the same alphas as "run3") at beta2 = sideslip.

The individual functions performed in this macro are the following :


(1) Turn on the ability to overstore SIF files to make sure that
"tempfil" will be produced.

(2) Turn off the DESL echo state so the screen will not reflect the
individual macro components' reports

(3) Combine, via "merge" with curve-fitting, two SIF files with
the same nominal range of values of alpha.  The dependent variables
"beta", "crm", "cym", "cy", and "run" will be thus combined,
record-by-record, to form a new file, "tempfil", which contains
information from both files in each record.

(4) Using the "create" and "endcreate" commands create the file "eqn.bd".
    This file will contain the equations which the "eqn" function will
    subsequently need for the computation of the beta derivatives.

(5) Using the new file produced by "merge", operate on each record
by using the "eqn" function and the equations in the equation file "eqn.bd".
These equations will compute, for each record, the new "beta derivatives"
"dcrmdb", "dcymdb", "dcydb" by doing a delta-coefficient/delta-beta
operation.

(6) Eliminate the temporary new file "tempfil" via "cl".

(7) Go back to the state of "overstore off", "echo on".

An example macro exhibiting preset arguments and bracketed conditional blocks of input is presented below. The brackets enclose sections of the macro input specifications which will be eliminated if at least one of the macro arguments contained within is not specified.


macro void.mac
* ******************************************************
* ******************************************************
*
*    void.mac :  To void points
*
*   ********************************************************
*   ********************************************************
*
*  The following are argument presets : There are the values
*  the respective arguments will take on if the user
*  does not specify overriding values.
*
# echo off
# sv -888.
*
*   =========================================================
*
*   The intent of this macro is to process one or more
*   incoming SIF files by applying the record voiding
*   conditions found in the void file and producing
*   one or more new SIF files.
*
*   =========================================================
*
*   void.mac calling arguments :
*     -------------------------
*
*    -f       name of SIF file to read
*
*    -nf      optional, name of SIF file(s) to create
*
*    -v       optional, name of void file to use
*
*    -sv      optional, value of "setvoid" to use
*
*    -read   optional, classic DESL "read" file name; forces the
*            insertion the named file (with file edit if interactive)
*            into "copy" input
*
*    -readn  optional, classic DESL "readn" file name; forces the
*            insertion of the named file (without file edit) into
*            "copy" input
*
*    -reads  optional, classic DESL "reads" file name and section
*            name; forces the insertion of the named section of the
*            named file (with file edit if interactive) into "copy"
*            input
*
*   -readsn optional, classic DESL "reads" file name and section
*           name; forces the insertion of the named section of the
*           named file (without file edit) into "copy" input
*
*     -cset optional, std. DESL file-specific conditions (no default)
*
*
  echo %echo
  os on
*
  copy
     files %f
     [ cset %cset ]
     [ newfiles %nf ]
     [ vfilen %v ]
     [ setvoid %sv ]
     [ read %read ]
     [ readn %readn ]
     [ reads %reads ]
     [ readsn %readsn ]
     go
*
  echo on
endm

The two potential arguments %sv and %echo are preset to -888 and off, respectively.

The only "files" argument %f is required here. All of the other potential arguments are in the square bracketed sections; if their respective arguments are not specified, the associated bracketed input section, including the brackets are removed from the input sequence before the macro executes.

Contact the DESL manager

ViGYAN, Inc.
30 Research Drive
Hampton, VA 23666
Voice: (757) 865-1400
Toll Free: (800) 288-3998
FAX: (757) 865-8177

( TI) DESL Macros

© 1999 ViGYAN, Inc.