General information
SCRIPT launcher
I-SCRIPT launcher
SCRIPT/I-SCRIPT substitution parameters
Terminal controls for SCRIPT/I-SCRIPT execution
Editing SCRIPT/I-SCRIPT launcher
Editing SCRIPT/I-SCRIPT file
SCRIPT/I-SCRIPT file linking
COMMAND Launcher is the simplest way of automation in the terminal but it does not allow to execute predefined sequences of multiple commands from one single launcher.
If user has a sequence of commands that represents the steps of some procedure and execution of the next step depends on the result of execution of the previous step then the sequence of commands can be better represented as a collection of the COMMAND launchers. In this case user can decide himself which COMMAND launcher to execute next depending on the result of the previous command. In other words, if the sequence of command execution can change depending on the result of execution of some particular command user himself can control the command executing order. To do so, user keeps his commands on the Launcher Tree as the sequence of COMMAND launchers.
Representing sequence of commands as sequence of COMMAND launchers on the LauncherTree doesn't require any programming knowledge because in this case user himself is responsible for the correct order of command execution along the steps of the procedure. If user is capable of programming then he/she can write a plug-in that will send first command, analyze result of its execution and select which is the next command to be sent depending on the result of execution of the previous command. Therefore, plug-in would allow to automatically choose the sequence of command but the user will have to program the rules for the selection of the next command. Plug-in is the program written in any language but that is written specifically to be executed by PLUGIN launcher and not by the shell.
If sequence of commands that has to be executed does not change depending on the result of every particular command then user can use SCRIPT or I-SCRIPT launcher for the execution of such "fixed" command sequence. Commands are sent automatically line by line from the SCRIPT/I-SCRIPT text file.
When user executes COMMAND launcher he/she has to wait until the equipment will finish processing of the current command, show the prompt to the user (prompt would tell that equipment is ready to receive the next command). Only after receiving the prompt user can proceed to execute next COMMAND launcher. Therefore, when executing sequence of the COMMAND launchers manually, user will have to monitor the terminal screen and wait for the next prompt before the execution of the next COMMAND launcher. When sequence of commands is executed from the file that is configured in the SCRIPT or I-SCRIPT launcher the program will have to automatically detect the situation when the equipment is ready to receive the next command. SCRIPT and I-SCRIPT launchers use different algorithms in order to decide when is the right time to send the next command to the remote equipment.
In order to use SCRIPT launcher user has to create text file that would contain the sequence of commands, one command per line and every line has to be terminated by new line character. Path to this file is configured in the SCRIPT launcher. When SCRIPT launcher is executed the program will open text file with the commands and it will send each command into terminal the same way the COMMAND launcher does.
SCRIPT launcher is using following algorithm in order to decide when is the right time to send the next command to the remote equipment:
After sending next command the program will start monitoring results/printout of the command execution. This printout is arriving as the stream of the text bytes from the remote equipment to the terminal. As long as this stream of the text is continuing the program is waiting and it is not sending the next command assuming that the previous command is still executing and it is still printing results of its own execution. As soon as the byte stream coming from the remote equipment will stop for some significant time the program will assume that this stop has occurred because the remote equipment finished command execution and printed the prompt that is showing that equipment is ready to receive the next command. At this moment program will send next command from the SCRIPT file. Depending on how fast equipment is and how much work is to be done during the execution of the particular command, command print out may contain the pauses of different duration that are not related to the situation when the equipment has already finished execution of the previous command and waiting for the next command to be received. User has to manually execute all the sequence of commands and experimentally figure out the maximum duration of the pause that is not related to waiting for the next command to be sent. In most cases the pauses during command execution do not exceed split seconds. When creating SCRIPT launcher user will have to supply the value for the duration of the pause that should be longer than the maximum pause that may be encountered in the process of the execution of any of the commands that are contained in the SCRIPT file. If user-supplied duration of the pause is detected in the stream of bytes coming as a result of execution of the previous command the program will automatically assume that such a long pause can be only encountered in the situation when equipment is waiting for the next command, so the program will send the next command from the SCRIPT file. When creating SCRIPT launcher the default value of control pause is set to one second and it is assumed that the pauses during the command execution will never exceed one second. If in particular case the pauses during the command execution can be compared to or even longer than one second user will have to increase the value of control pause so that the program will not send the next command in the situation when the equipment is still busy with the execution of the previous command but not yet ready to receive the next command and didn't give a prompt yet indicating that it is ready to receive the next command.
Therefore, the longer the control pause that is configured in SCRIPT launcher for particular SCRIPT file, the less is the probability to send the next command too early when the equipment is still busy with the execution of the previous command but not yet ready to receive the next command for the execution.
On the other hand increasing the control pause too much will result in the situation when the SCRIPT execution algorithm will have to count down this control pause after the end of each command while the equipment is staying idle waiting for the next command. For example, if the pause in the process of execution of the individual command does not exceed one second but user has specified control pause equal to 10 seconds then SCRIPT execution algorithm will have to count down 10 seconds (continuous time in the state when equipment has stopped printing to the terminal) before sending every next command from the SCRIPT file.
The value of control pause is specified for the whole sequence of commands, therefore, it has to be defined to be longer than any pause that can be encountered in the process of execution of the worst command. The worst command is the command that would produce longest pause in the printout before actually completing. SCRIPT launcher will allow to specify the values for the control pause in the range 1-3600 seconds. This control pause has to be specified when creating SCRIPT launcher and by default it is set equal to one second.
The risk of using SCRIPT launcher is when the control pause is specified to be too short and the SCRIPT can send the next command at the moment when the equipment is still busy with the execution of the previous command and it is not yet ready to receive the next command. Therefore, before using SCRIPT launcher please make sure (somewhere in the lab) that your equipment can handle such unexpected situation without major problems. High-quality equipment when it is receiving the next command before it is ready will discard such command or it will buffer it and execute it after finishing executing previous command. Low quality equipment in some rare cases may react in an unpredictable fashion when receiving commands before it is ready. For example, equipment may reboot, restart, get frozen or hung.
The advantage of using SCRIPT is that when it is created user doesn't have to know any programming. The only thing user have to do is to define the control pause correctly for the whole SCRIPT so that SCRIPT will reliably detect the moment when equipment is ready to receive the next command.
SCRIPT launcher doesn't check whether the actual prompt came back from the equipment and what kind of prompt it is. Instead it detects the prompt by the duration of the pause that it will encounter in the command printout results. In many cases it may not be enough if the user has to be hundred percent sure that the prompt has arrived and the prompt is exactly the same prompt that user would expect before sending the next command. In this case user can use I-SCRIPT launcher.
SCRIPT algorithm does not have any error detection, it will continue to paste commands line by line even if the remote equipment is not responding to commands or returning the errors. Therefore, unattended execution of SCRIPT launcher is not recommended. User has to be monitoring the execution and be ready to terminate execution of SCRIPT at any time, if something goes wrong.
If unattended execution is required user can use I-SCRIPT launcher.
In order to use I-SCRIPT launcher user will have to create text file in which every line contains three components separated from each other with the help of separator <PROXY> and every line will be terminated by the new-line character.
First component of the line is the same as for SCRIPT launcher: it represents the command that needs to be sent to remote equipment. Second component is a search pattern written in the language of regular expressions (PCRE - PERL-Compatible Regular Expressions) that allows program to detect necessary prompt in the text of the command printout. The third component specifies the maximum pause that is allowed to be encountered while receiving command printout text before command execution is complete (before prompt is found). The path to I-SCRIPT file is configured in I-SCRIPT launcher.
When executing I-SCRIPT launcher the I-SCRIPT file is being read from disk line by line and every line that consists out of the three components is executed according to the following algorithm.
First, proxy32 will send command part of the line to the remote equipment, then it will scan the printout of the command results that is arriving to terminal. The scanning continues until one of two events will happen: either the matching prompt is detected in the arriving command printout results (prompt is matching Regex search pattern, given in the second part of the line). Or while receiving text of the command printout program detected the pause that exceeds given maximum pause (maximum pause is given in the third part of the line). If prompt is detected then proxy32 will send the next command from the I-SCRIPT file. If pause is detected that exceeds the maximum specified pause then proxy32 would assume that either equipment is frozen and not returning the command prompt or the search pattern to look for the equipment command prompt was specified incorrectly. In this case the next command will not be sent and I-SCRIPT execution is terminated.
I-SCRIPT launcher has following advantages:
Disadvantage of using I-SCRIPT launcher is that for execution of every single command user will have to give not only the text of the command but also two additional parameters: - REGEX search pattern to search for the equipment command prompt that is expected to be returned by this particular command. Finding this matching prompt is the condition of the continuation of the I-SCRIPT. -the maximum pause in the stream of command printout results that can occur during the normal command execution before command is completed. Exceeding this maximum pause is the condition of the termination of the I-SCRIPT.
The need to specify two additional parameters individually for every command would require more effort from the user and in some context can be considered to be a programming. Those two parameters specify condition for continuation of the I-SCRIPT and condition for termination of the I-SCRIPT individually for every command in the I-SCRIPT file.
I-SCRIPT Notes:
Every SCRIPT/I-SCRIPT launcher contains in its configuration text fields to hold 9 substitution parameters. Those parameters are similar to command line parameters given to shell scripts. They are substituted in to lines of the script on script execution. Inside of any line of the SCRIPT file or inside of command part of any line of the I-SCRIPT file, values <PROXYPARM1> to <PROXYPARM9> are replaced by the substitution values of the positional parameters 1 to 9 respectively. Replacement is taking place right before the line is executed. This allows to pass parameters into the script files and, therefore, reuse the same script for different purposes by modifying positional (start up) parameters that are passed into the script from particular launcher. As positional parameters are stored in the launcher, one should create multiple launchers referring to the same script file in order to be able to run the same script with different positional parameters. This will increase the number of the different SCRIPT/I-SCRIPT launchers, but they all will use single SCRIPT/I-SCRIPT file that is located on the disk and not changing.
Every SCRIPT/I-SCRIPT launcher contains two fields for each of 9 positional parameters. First field is just a comment/name that user puts for himself/herself to remember the purpose of this positional parameter in this particular SCRIPT/I-SCRIPT file. The second field is the actual substitution value, that will be used to replace appropriate placeholder (<PROXYPARM1> to <PROXYPARM9>) in the text of the SCRIPT/I-SCRIPT file during execution.
To make things more flexible (and more complicated) substitution value of the positional parameter in the SCRIPT/I-SCRIPT launcher can in turn contain named parameters and passwords. So if some day user decided that he/she does not want to keep values of positional parameters literally in the text of the SCRIPT/I-SCRIPT launcher, then user can put named parameters and passwords into substitution value of the positional parameter in the SCRIPT/I-SCRIPT launcher.
Inside of any line of the SCRIPT file or inside of command part of any line of the I-SCRIPT file, named parameters and passwords (<PROXYPARM=...> and <PROXYPASSWORD=...>) are also substituted, but positional parameters have their own important use by allowing to change the purpose of the SCRIPT/I-SCRIPT by simply calling it via different launcher. This would not require changing values on every execution as it would be the case if named parameters and passwords would be used for the same purpose.
When user double-clicks on SCRIPT or I-SCRIPT launcher on the LauncherTree, SCRIPT or I-SCRIPT will start executing to active terminal (active terminal is highlighted by red frame). SCRIPT or I-SCRIPT are supported only in the built-in terminal, so if the other window is active in the workspace (window of external process or window of script editor) then SCRIPT or I-SCRIPT will not start when user double-clicks on SCRIPT or I-SCRIPT launcher on the LauncherTree. Built-in terminal can execute only one SCRIPT or I-SCRIPT (or PLUGIN) at the time, so if active terminal window is already busy executing SCRIPT or I-SCRIPT or PLUGIN, then new SCRIPT or I-SCRIPT will not start when user double-clicks on SCRIPT or I-SCRIPT launcher on the LauncherTree. If active terminal window is not connected, then new SCRIPT or I-SCRIPT will not start when user double-clicks on SCRIPT or I-SCRIPT launcher on the LauncherTree.
When SCRIPT or I-SCRIPT will start executing, following will happen:
"Kill" button plays important role in SCRIPT/I-SCRIPT execution. It allows user to terminate SCRIPT/I-SCRIPT execution at any point. For example, SCRIPT algorithm does not have any error detection, it will continue to paste commands line by line even if the equipment is not responding or returning the errors. Therefore, unattended execution of SCRIPT launcher is not recommended. User has to be monitoring the execution and be ready to terminate execution of SCRIPT at any time (using "Kill" button at the bottom of the terminal window), if something goes wrong.
SCRIPT/I-SCRIPT does not have any logic to create cycles/loops to send the same command multiple times. This is the price to pay for the simplicity of using SCRIPT/I-SCRIPT functionality. However, if user creates long SCRIPT/I-SCRIPT file that contains the same line many times, this can serve the purpose of sending the same command multiple times. If execution of such long SCRIPT/I-SCRIPT file has to be terminated before such long SCRIPT/I-SCRIPT file executed to the last line, "Kill" button can be used to stop execution of the script at any point.
Execution progress indicator shows proportion of the SCRIPT/I-SCRIPT file that was already pasted relatively to total number of line in the SCRIPT/I-SCRIPT file. For example, if the SCRIPT/I-SCRIPT file contains 100 lines and 50 lines were already pasted during the execution of the the SCRIPT/I-SCRIPT file, then progress indicator will be filled to the half.
Execution progress indicator will help to detect situation when execution of the SCRIPT/I-SCRIPT is stuck if user accidentally specified control pause or maximum pause to be too long.
When SCRIPT/I-SCRIPT execution is finished normally (all lines in the file were pasted) or via user intervention (user pressed "Kill" button), or terminal is by user or by remote server during the SCRIPT/I-SCRIPT execution, combination of "Kill" button and SCRIPT/I-SCRIPT execution progress indicator will be replaced by the clipboard viewer panel, and user's input into terminal will be re-enabled.