


             Execute(V1.3, 2.x, and 3.x in C:)



     NAME
            Execute - Cause the shell to execute commands from a 
        file.

     SYNOPSIS
            Execute [Filename] [ARGS...]

     DESCRIPTION
            Execute causes the shell or CLI to read the commands 
        from the filename specified as Execute's input argument.  
        When the end of the file is reached, control returns to 
        the keyboard.  You can force the Shell to abort any 
        script file processing by typing a C-d (Control D) 
        sequence while the script is being executed.

            You can even include nest an Execute inside your 
        script to cause one script to call another one during its 
        execution.

            In AmigaDOS 1.3 and above, you can execute a script 
        without typing EXECUTE and just typing name of the script 
        if the 'S' bit is set.

         
	 KEYWORDS
		  FILENAME
            The name of the script to execute.

		  ARGS
            Any arguments to be passed to the file. These may be 
        any valid AmigaDOS string (including filenames and all 
        sorts of devices.	

     DIRECTIVES
            Execute recognizes several special commands known as 
        Directives.  Each of these Directives begins with a DOT 
        '.', but this character can be redefined if needed.  
        Execute is reasonably flexible in allowing you to 
        redefine its special characters, which is quite 
        fortunate, as you will soon see.

            In order for Execute to recognize these directives, 
        the DOT character must be placed at the beginning of the 
        line, and the directive name must follow immediately, 
        with no intervening whitespace.  You can also use the DOT 
        (again, at the beginning of a line only) to introduce a 
        comment. This usage is ".<whitespace>Anything" where 
        whitespace is any of space, tab or newline.

            Many of these directives deal with passing arguments 
        to scripts and establishing defaults for arguments.  
        These are described below:

     .KEY and PARAMETERS
            The .KEY directive (which may be abbreviated as .K) 
        is used to declare the names of parameters which will be 
        used in the course of the script file. Note that these 
        are not environment variables.  If you intend to pass 
        arguments to a script file, it is wise to use this 
        directive as the first line of a file. If the first 
        non-empty line (i.e., a line which contains anything 
        other than a newline) does not contain a dot command 
        (directive), then the arguments will not be processed.

            The .KEY directive accepts any legal template.  These 
        are the same kinds of templates you see all the time in 
        the AmigaDOS commands. Note that currently, there is no 
        support for multiargs (the /... template type) in 
        scripts, and so you should not use this in your 
        templates.  All the usual processing associated with 
        templates is active in scripts, including the '?' display 
        of the template, and position independent arguments.

            When you use the .KEY directive, Execute matches up 
        the users arguments with your template keywords, and if 
        no error occurred, scans the file for any items 
        surrounded with the BRA KET characters.  These are 
        initially '<' and '>', which is quite unfortunate, since 
        these tend to conflict with the IO redirection operators.  
        It is wise to change these to another character using the 
        .BRA and .KET operators (see below).

            When a BRAKET sequence is encountered, Execute 
        replaces the keyword inside the BRAKET with the users 
        argument.  If the user did not enter an argument for that 
        keyword, and there is no default setting for this 
        keyword, then Execute removes the argument all together, 
        resulting in a NULL string.  Arguments that do not take 
        an argument, for example, switches (template type /S), 
        are handled somewhat differently.  If the user supplied 
        the switch on the command line, then the braket sequence 
        is replaced by the actual name of the switch, otherwise, 
        it is null.

     DEFAULT VALUES FOR PARAMETERS
            This assigns the value string to all occurrences of 
        the substitution argument described below.

            You can set default values for your variables in two 
        ways.  The first way is to use the .DEFAULT directive.  
        .DEFAULT (which may be abbreviated as .DEF) takes a 
        template keyword and a default value.  If that keyword 
        does not have a value at the time the .DEFAULT statement 
        is scanned, then Execute binds the value to that keyword.  
        Here is an example of its use:

            .DEFAULT Foobar "Testing123"


            Another way to set default values is by using the 
        DOLLAR (initially each time the parameter is used, it 
        does not set it permanently:

            Echo "<Foobar$Testing123>"

            Note that a .DEFAULT statement will override all 
        following DOLLAR defaults. The decision as to which to 
        use is usually based on how many times you use that 
        parameter.  If you only use it once, then either will do. 
        If you use it many times, then .DEFAULT is probably the 
        simplest.  Also note that there is not a conflict between 
        this use of the DOLLAR and the use of the dollar during 
        Shell environment expansion: The DOLLAR is special to 
        Execute only inside of BRAKETS, and the shell expands the 
        environment variables only after Execute has parsed the 
        file.  Unless you use environment variables inside of 
        BRAKETs, there should be no need to change your .DOLLAR 
        character.

            You can also use a double DOLLAR inside of brackets. 
        This will be replaced by the current CLI number.

     CHANGING THE META CHARACTERS
            The following directives are used to change the 
        default meta characters used by Execute.  Each take a 
        single character as their argument.

          .BRA and .KET
            These change the bracket characters (initially '<' 
        and '>', respectively) to something else.  It is highly 
        recommended you make a habit of doing this, whether you 
        think you need to or not.  Good characters to use instead 
        are the curly braces ('{' '}') since these are not needed 
        for anything else, currently.

          .DOT 
            This changes the DOT character (initially '.').

          .DOL or .DOLLAR
            This changes the DOLLAR character (initially '$').

     MISCELLANEOUS
            Execute may be nested, i.e., you may include Execute 
        commands in scripts, which can also contain Execute 
        commands.

            Execute will sometimes need to write a temporary 
        file.  If you have assigned a directory or device to T:, 
        then this location will be used.  If not, and there is a 
        :T directory for the current directory, then Execute will 
        create the assignment, and use this directory.  
        Otherwise, it will attempt to create both the directory 
        and the assignment in the current directory. EXECUTE uses 
        <$$> with the task number of the CLI from which it is run 
        to create this.

     EXAMPLES

            1. To execute a script named RunThis located on Df0:

			EXECUTE df0:RunThis

            2. Here is an example of a KEY directive which 
        contains a switch.  This illustrates a good way to handle 
        and use /s style arguments in script files.

             .KEY MySwitch/s

             IF "<MySwitch>" EQ "MySwitch"
                Echo "The switch is on!"
             ELSE
                Echo "The switch is off!"
             ENDIF

          If the user doesn't supply MySwitch as an argument on the
          command line, then the comparison will fail (the first
          argument will be ""), otherwise, the comparison will succeed
          (the switch is "on").

     SEE ALSO
          If Skip Failat Lab Echo Quit
