JKEYAUTO JKEYAUTOThis program allows a single program to control the actions of many other programs. It can be used in many ways, for example benchmarking and regression testing. The fundamentals of operation are that you build up a script that defines one or more program to be executed, and then use the jkeyauto program to interpret the script, thus controlling one or more programs. Currently jkeyauto is available on Unix platforms only.
The programs that are controlled by jkeyauto need not be jBASE programs ; they can equally be jBASE programs, Unix scripts, Unix programs, telnet sessions and so on.
The program jkeyauto is called as:
jkeyauto {-h?stx} script_name
jkeyauto -S LOCK|UNLOCK|WAIT|TEST locknumber {-ffor_timeout}
Where:
| -h or -? | display this help screen |
| -ffor_timeout | set the timeout value for WAITing on a sync. lock |
| -s | ignore any SLEEP statements |
| -t | turn tracing ON |
| -x | upon eXit, display all internal variables |
| -S | Manipulate the sync. Lock |
The file script_name contains a list of commands for jkeyauto to execute. All the options, including the alternative invocation with the -S option, are fully described later. For most uses you will simply invoke it as "jkeyauto scriptname".
The syntax of a jkeyauto script looks like a subset of normal jBC code and so should be easily understood by a jBC programmer. The layout of the script file has the following elements:
(a) Labels. These are similar to jBC labels and should be the first element of a
line. For example:
doagain: print "do this
again"
(b) Variables. Your script can create named variables that are then referenced
by other statements. They are created intrinsically once they are first referenced. You
can explicitly create and set them using the = command, for example:
username = "this is a
name"
The variables can also be created using the SET statement (see later description).
(c) Expression. You can use the + - / * : ( ) characters as in jBC code to
manipulate variables. The % operator provides the modulo. For example:
message = "This is loop
":loopcounter:" , and we use port " : ((portno*2)+2)
This example calculates a random number between 300 and
399:
message = "I would guess he weighs at least ":(($RND % 100) +
300):" pounds."
Expressions can be an integral part of other statements, such as:
IF time EQ (begintime -
currenttime) THEN GOTO error_label
(d) String constants. A string constant is simply of the form
"helloworld" or "hello world". You can embed non-printable characters
in the string constant using the format ~nnn where nnn is the decimal number. For example,
to embed a 0x07 (decimal 7) in a string constant you could do this:
PRINT "Here is a
bell~007"
Similarly to simulate an escape sequence generated by a function key you could:
INPUT "~027OP"
(e) Background. It is up to you if you want to run your test application in the
background or not. If you do, use the -Jb option in the program statement, for example:
filename =
"SLIPPERS"
itemid =
"JIM"
progname = "MYPROG
-Jb " : filename : " " : itemid
program progname
This will cause program "MYPROG" to be loaded with the operands "-Jb"
, "SLIPPERS" and "JIM". The -Jb operand causes the program to run in
the background.
(f) Internal variables. The use of environment variables in the format $VARNAME have some special cases. Commonly used variables are $UBOOT to get an accurate timing value or $PIPE to get the pipe number of the last allocated pipe with the PROGRAM statement. See the full table of names later on.
(g) Pipe numbers. You can load more than one program at a time with jkeyauto. When a program is loaded from the PROGRAM statement, then the pipe number for that program can be obtained from the $PIPE expression. Commands such as the INPUT statement allow you to specify a pipe number to them so you can send different keyboard input to different program.
(h) Naming convention. The statement keywords are case insensitive so "print" or "Print" or "PRINT" are equal. Variable0 names cannot be the same as keywords, so you cannot have a variable name called "Print" or "PRINT" . Variable names are case sensitive so "slipper" and "Slipper" refer to different names.
(i) Comments. Any statement that begin with * or # are treated as comments and are ignored. Any blank lines are also ignored.
(j) Compound statements. You can have more than one statement per line and use the semicolon character; to delimit each statement.
(k) Port Numbers. You may want to allocated different port numbers when executing jBASE programs using jkeyauto. To do this you need to ensure the environment variable JBCCONNECT is set to an illegal value, such as "". Also if you want to allocate your own port number instead of allowing jBASE to allocate one on your behalf, then you need to set the JBCPORTNO environment variable.
Summary of the statements that can be executed in a jkeyauto script. When a timing value is used (for example the FOR argument, the SLEEP and TYPEDELAY statements) this can be expressed as a fractional number or expression. For example "A=0.3; SLEEP A*2" will cause a sleep of 0.6 seconds. The actual slept time will depend upon the accuracy of the clock on your computer and the current load.
CRT {expression} {:}
Display expression to screen, converting unprintable characters to a 3 digit decimal
number ~nnn
EXECUTE expression {CAPTURING variable} {SETTING variable}
Execute an external Unix program and wait until the program completes.
EXIT {expression}
Terminate the jkeyauto script and return "expression" as an exit value to the
parent process of jkeyauto.
GOSUB label
Temporary transfer execution of the script to the label, which then uses a RETURN
statement to continue execution.
GOTO label
Permanently transfer execution of the script to the label.
IF resultant THEN statements Conditional operator.
INPUT expression {TO expression} {NOCR}
Pass data as keyboard input to the program(s) loaded with the PROGRAM statement.
PERFORM expression {CAPTURING variable} {SETTING variable}
Execute an external Unix program and wait until the program completes
PRINT {expression} {:}
Display expression to the screen.
PRINTERR {expresssion} {:}
Display expression to the stderr device
PIPEREAD {PIPE expression} {TO expression} {FOR expression} {SETTING variable}
{UNTIL expression}
Read back data from the program executed with the PROGRAM statement.
PRECISION expression
Adjusts the precision of floating point calculations from 0 through 10 decimal places.
PROGRAM expression {STDOUT expression} {STDERR expression} {SETTING variable}
Begin execution of an external program. This program can be controlled using the INPUT
statement to simulate keyboard data sent to it and the PIPEREAD statement which allows the
script to read data sent to the terminal by the program.
PUTENV expression
Create a Unix environment variable which will be exported to all subsequent child
processes initiated by the PERFORM , PROGRAM or EXECUTE statement
READDELAY expression
Allows tuning of the PIPEREAD statement.
RETURN RETURN from a GOSUB call SLEEP {expression} | ON | OFF
Sleep for a number of seconds (default is 1.0 seconds) . The ON and OFF options allows the
script to enable or disable the execution of the SLEEP statement.
STOP {expression}
Optionally display a message to the terminal and then exit the jkeyauto program returning
0 back to the calling parent.
SYNC LOCK|UNLOCK|TEST|WAIT expression {FOR expression} {SETTING variable}
Allows synchronization between scripts and the jkeyauto program.
TRACE ON|OFF
Enables or disables scripts command tracing.
TYPEDELAY expression
Sets the delay between characters being sent via the INPUT statement. The default is 0.1
seconds between characters.
WAIT {PIPE expression} {FOR expression} {SETTING variable}
Wait for a program to complete
JKEYAUTO