3.1 Displaying usage

Executing wozix on the command line without any parameters will display a wozix usage message.

wozix

Will display a usage message to stdout.

3.2 Optional arguments

The location of wozix and wozterm.ovm may be specified vial the command line switch -w. For example, if wozix and wozterm.ovm are stored in the directory /tmp/, you can specify the location by using the -w switch as follows:

wozix -w /tmp/

The location of library files may be specified with the command line switch -l. These locations will be searched when using the @uselibraryfile command. For example, if the libraries you wish to use are located in the directories /tmp/ and /usr/local/ then you can specify those directories as follows:

wozix -l /tmp/ -l /usr/local/

3.3 Pre-Compiling Scripts

To pre compile a user script use the -c, or -c0 command line option. Example.

wozix -c myfile.txt myfile.ovm

Wozix will attempt to read the script file myfile.txt and produce the compiled file myfile.ovm. If any syntax errors are found during compilation myfile.ovm will not be created. If only warnings are present they may indicate logic errors in the user script file but myfile.ovm will still be created.

Use the -c0 option if you want to strip debugging information from the user script. Using -c0 removes all @debug statements from the compiled file, and also prevents the compiled file from keeping track of which line number the user script is currently executing. Use -c0 when you are sure your script is bug free and you want to improve the script's speed. Note that using -c0 will result in extra warnings being generated to inform you that @debug statements have been removed. Using -c0 does not change the contents of your original user script file. Only the contents of the compiled file.

Note. Compilation progress, errors, and warning messages are sent to stderr.

3.4 Running Scripts

You may run either pre-compiled or raw user scripts using wozix. If the user script is a raw text file wozix will attempt to compile it on the fly using the same options as a -c compile.

To run a script you must use the -v switch with the appropriate verbosity number. For example.

wozix -v3 myfile.ovm

will attempt to execute the previously compiled user script file myfile.ovm. Script @comment and @display lines will be displayed as will any data received from network elements.

wozix -v0 myfile.txt

will attempt to compile the file myfile.txt into memory using the -c option, and then execute the compiled script (if there were no syntax errors). Note that with -v0 no messages or data will be displayed by wozix so this is also known as silent mode. Note however, any syntax errors are still displayed to stdout during the compilation phase.

Verbosity numbers are set as power of 2 bit flags. Add the require numbers shown below to determine how verbose wozix will be at runtime.

1 - Show user script comments to stdout. Eg @comment, @display.
2 - Show communications data to stdout.
4 - Show wozterm.ovm debug information to stdout.
8 - Show compiler progress, and warning messages to stdout. Note errors always display.
16 - Show user script runtime error messages to stderr.

3.5 Wozix Shell Scripts

If you wish to run your script as a shell script, you must use the -s switch in the shebang line of your script. An example script is shown bellow:

#!/usr/bin/wozix -sv5
@comment("Hello")

Where '/usr/bin/wozix' is the path to the wozix command and '-sv5' specifies that you are running the script as a shell script with a verbosity of 5. Note that you will have to make the file executable in order to run it as a shell script.

3.6 WOZIXHOME Environment Variable

If you wish to place wozix in a common area for all users or you wish to be able to run wozix from any working directory you must set the WOZIXHOME environment variable to the directory that holds the wozterm.ovm file (typically the same directory that holds wozix). For example.

If wozix, and wozterm.ovm are stored in the directory /usr/local/bin then the WOZIXHOME environment variable should be set to /usr/local/bin/

Note that the directory /usr/local/bin must also be in your path.

3.7 Using kill -1

Sending a kill -1 to the main wozix process will result in a message being displayed to stderr that shows the line numbers the user script and the wozterm.ovm script are executing. If you have used -c0 to compile your user script then the user script line number will always show 0. Similarly, if you are using a non-debug version of wozterm.ovm (one compiled with the -C0 option) then its line number will always show 0 also.

Note. Use kill -1 sparingly as occassionally it may cause wozix to crash. It is provided as a debugging tool for when you believe your user script has hung.