# jkeyauto Overview

Updated: 11/30/2021, 7:00:45 PM
Created: 11/30/2021, 7:00:45 PM
Last Updated By: Jake Tuttle
Read Time: 7 minute(s)

Tags: program profiling

# Description

This 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

  1. A script is built that defines one or more programs to be executed, and then
  2. 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
1

or

jkeyauto -S LOCK|UNLOCK|WAIT|TEST locknumber {-ffor_timeout}
1

Where:

  • -h or -? display the help screen,
  • -ffor_timeout sets 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, simply invoke it as "jkeyauto scriptname".

# jkeyauto Script Layout

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"
1

(b) Variables. The script can create named variables that are then referenced by other statements. They are created intrinsically once they are first referenced. An explicit create can be done, then set them using the **=**command, for example:

username = "this is a name"
1

The variables can also be created using the SET statement.

(c) Expression.  The use of + - / * : ( ) 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)
1

This example calculates a random number between 300 and 399:

message = "I would guess he weighs at least ":(($RND % 100) + 300):" pounds."
1

Expressions can be an integral part of other statements, such as:

IF time EQ (begintime - currenttime) THEN GOTO error_label
1

(d) String constants. A string constant is simply of the form "helloworld" or "hello world". Non-printable characters can be embed 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:

PRINT "Here is a bell~007"
1

Similarly to simulate an escape sequence generated by a function:

INPUT "~027OP"
1

(e) Background. There is the option to run a test application in the background or not. The -Jb option in the program statement makes this possible, for example:

filename = "SLIPPERS"
itemid = "JIM"
progname = "MYPROG -Jb " : filename : " " : itemid
program progname
1
2
3
4

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.

(g) Pipe numbers. More than one program at a time may be loaded 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 allows for specifying a pipe number to them so different keyboard input may be sent to the  different programds.

(h) Naming convention. The statement keywords are case insensitive so "print" or "Print" or "PRINT" are equal. Variable names cannot be the same as keywords, so a variable name called "Print" or "PRINT" are not permitted. 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. More than one statement per line is possible with the use of the semicolon character; to delimit each statement.

(k) Port Numbers. It is recommended that different port numbers are allocated when executing jBASE programs using jkeyauto. To do this, ensure the environment variable JBCCONNECT is set to an illegal value, such as "". Also to allocate a custom port number instead of allowing jBASE to allocate one, set the JBCPORTNO environment variable.

# jkeyauto Statement Summary

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 the 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

Back to jKeyAuto