home *** CD-ROM | disk | FTP | other *** search
/ back2roots/padua / padua.7z / padua / misc / arpdoc13.lzh / EXECUTE < prev    next >
Encoding:
Text File  |  1989-06-30  |  8.5 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      Execute(V1.3)           ARP User's Manual           Execute(V1.3)
  5.  
  6.  
  7.  
  8.      NAME
  9.           Execute - Cause the shell to execute commands from a file.
  10.  
  11.      SYNOPSIS
  12.           Execute [Filename] [ARGS...]
  13.  
  14.      DESCRIPTION
  15.           Execute causes the shell or CLI to read the commands from
  16.           the filename specified as Execute's input argument.  When the
  17.           end of the file is reached, control returns to the keyboard.
  18.           You can force the Shell to abort any script file processing
  19.           by typing a C-d (Control D) sequence while the script is
  20.           being executed.
  21.  
  22.           Note that the ARP Shell contains Execute as a builtin
  23.           command.  For the most part, the disk based version of
  24.           Execute and the builtin command operate similarly.  The main
  25.           difference is that the builtin command can be piped into,
  26.           while the diskbased version can only accept diskfiles or
  27.           devices as input.
  28.  
  29.      DIRECTIVES
  30.           Execute recognizes several special commands known as
  31.           Directives.  Each of these Directives begins with a DOT '.',
  32.           but this character can be redefined if needed.  Execute is
  33.           reasonably flexible in allowing you to redefine its special
  34.           characters, which is quite fortunate, as you will soon see.
  35.  
  36.           In order for Execute to recognize these directives, the DOT
  37.           character must be placed at the beginning of the line, and
  38.           the directive name must follow immediately, with no
  39.           intervening whitespace.  You can also use the DOT (again, at
  40.           the beginning of a line only) to introduce a comment. This
  41.           usage is ".<whitespace>Anything" where whitespace is any of
  42.           space, tab or newline.
  43.  
  44.           Many of these directives deal with passing arguments to
  45.           scripts and establishing defaults for arguments.  These are
  46.           described below:
  47.  
  48.      .KEY and PARAMETERS
  49.           The .KEY directive (which may be abbreviated as .K) is used
  50.           to declare the names of parameters which will be used in the
  51.           course of the script file. Note that these are not
  52.           environment variables.  If you intend to pass arguments to a
  53.           script file, it is wise to use this directive as the first
  54.           line of a file. If the first non-empty line (i.e., a line
  55.           which contains anything other than a newline) does not
  56.           contain a dot command (directive), then the arguments will
  57.           not be processed.
  58.  
  59.           The .KEY directive accepts any legal ARP template.  These
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 4/28/89)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      Execute(V1.3)           ARP User's Manual           Execute(V1.3)
  71.  
  72.  
  73.  
  74.           are the same kinds of templates you see all the time in the
  75.           ARP or AmigaDOS commands. Note that currently, there is no
  76.           support for multiargs (the /... template type) in scripts,
  77.           and so you should not use this in your templates.  All the
  78.           usual processing associated with templates is active in
  79.           scripts, including the '?' display of the template, and
  80.           position independent arguments.
  81.  
  82.           When you use the .KEY directive, Execute matches up the
  83.           users arguments with your template keywords, and if no error
  84.           occurred, scans the file for any items surrounded with the
  85.           BRA KET characters.  These are initially '<' and '>', which
  86.           is quite unfortunate, since these tend to conflict with the
  87.           IO redirection operators.  It is wise to change these to
  88.           another character using the .BRA and .KET operators (see
  89.           below).
  90.  
  91.           When a BRAKET sequence is encountered, Execute replaces the
  92.           keyword inside the BRAKET with the users argument.  If the
  93.           user did not enter an argument for that keyword, and there
  94.           is no default setting for this keyword, then Execute removes
  95.           the argument all together, resulting in a NULL string.
  96.           Arguments that do not take an argument, for example,
  97.           switches (template type /S), are handled somewhat
  98.           differently.  If the user supplied the switch on the command
  99.           line, then the braket sequence is replaced by the actual
  100.           name of the switch, otherwise, it is null.
  101.  
  102.      DEFAULT VALUES FOR PARAMETERS
  103.           You can set default values for your variables in two ways.
  104.           The first way is to use the .DEFAULT directive.  .DEFAULT
  105.           (which may be abbreviated as .DEF) takes a template keyword
  106.           and a default value.  If that keyword does not have a value
  107.           at the time the .DEFAULT statement is scanned, then Execute
  108.           binds the value to that keyword.  Here is an example of its
  109.           use:
  110.  
  111.             .DEFAULT Foobar "Testing123"
  112.  
  113.  
  114.           Another way to set default values is by using the DOLLAR
  115.           (initially each time the parameter is used, it does not set
  116.           it permanently:
  117.  
  118.             Echo "<Foobar$Testing123>"
  119.  
  120.           Note that a .DEFAULT statement will override all following
  121.           DOLLAR defaults. The decision as to which to use is usually
  122.           based on how many times you use that parameter.  If you only
  123.           use it once, then either will do. If you use it many times,
  124.           then .DEFAULT is probably the simplest.  Also note that
  125.           there is not a conflict between this use of the DOLLAR and
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 4/28/89)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      Execute(V1.3)           ARP User's Manual           Execute(V1.3)
  137.  
  138.  
  139.  
  140.           the use of the dollar during Shell environment expansion:
  141.           The DOLLAR is special to Execute only inside of BRAKETS, and
  142.           the shell expands the environment variables only after
  143.           Execute has parsed the file.  Unless you use environment
  144.           variables inside of BRAKETs, there should be no need to
  145.           change your .DOLLAR character.
  146.  
  147.           You can also use a double DOLLAR inside of brackets. This
  148.           will be replaced by the current CLI number.
  149.  
  150.      CHANGING THE META CHARACTERS
  151.           The following directives are used to change the default meta
  152.           characters used by Execute.  Each take a single character as
  153.           their argument.
  154.  
  155.           .BRA and .KET
  156.                These change the bracket characters (initially '<' and
  157.                '>', respectively) to something else.  It is highly
  158.                recommended you make a habit of doing this, whether you
  159.                think you need to or not.  Good characters to use
  160.                instead are the curly braces ('{' '}') since these are
  161.                not needed for anything else, currently.
  162.  
  163.           .DOT This changes the DOT character (initially '.').
  164.  
  165.           .DOL or .DOLLAR
  166.                This changes the DOLLAR character (initially '$').
  167.  
  168.      MISCELLANEOUS
  169.           Execute may be nested, i.e., you may include Execute
  170.           commands in scripts, which can also contain Execute
  171.           commands.
  172.  
  173.           Execute will sometimes need to write a temporary file.  If
  174.           you have assigned a directory or device to T:, then this
  175.           location will be used.  If not, and there is a :T directory
  176.           for the current directory, then Execute will create the
  177.           assignment, and use this directory.  Otherwise, it will
  178.           attempt to create both the directory and the assignment in
  179.           the current directory.
  180.  
  181.      EXAMPLES
  182.           Here is an example of a KEY directive which contains a
  183.           switch.  This illustrates a good way to handle and use /s
  184.           style arguments in script files.
  185.  
  186.              .KEY MySwitch/s
  187.  
  188.              IF "<MySwitch>" EQ "MySwitch"
  189.                 Echo "The switch is on!"
  190.              ELSE
  191.                 Echo "The switch is off!"
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 4/28/89)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      Execute(V1.3)           ARP User's Manual           Execute(V1.3)
  203.  
  204.  
  205.  
  206.              ENDIF
  207.  
  208.           If the user doesn't supply MySwitch as an argument on the
  209.           command line, then the comparison will fail (the first
  210.           argument will be ""), otherwise, the comparison will succeed
  211.           (the switch is "on").
  212.  
  213.           Other good examples of script files, parameter expansion,
  214.           and other uses may be found in the Ash Manual (ASH is the
  215.           ARP Shell).
  216.  
  217.      SEE ALSO
  218.           AshManual If Skip Failat Lab Echo Quit
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                                          (printed 4/28/89)
  262.  
  263.  
  264.  
  265.