There are several ways to start a ScriptBasic program. The different ways also depend on the installation. Windows NT may associate the extension T<.sb> with the ScriptBasic interpreter. In this case you can start a ScriptBasic program double clicking on its name in the explorer. You can type the name of the text file containing your basic program and UNIX will start it for you automatically if the first line of the program contains the starting information like
#! /usr/bin/scriba
and the file itself is executable. The simplest way among all is to type the name of the executable. First try to start it without any command line argument:
options: -o file_name
specify output file, save binary format to file but don't execute
-b file_name
load binary format from file and execute
-n
do not use cache (no save, no load)
-e
execute after binary format was saved
-v
print version info and stop
-c
inform scriba that this is a CGI script.
-C
save C program output.
-E
save executable output. (may not work under some OS)
-p preprocessor
specify external preprocessor.
-i preprocessor
specify internal preprocessor.
-f configurationfile
specify configuration file
-d
debug module error (UNIX only)
-k text_config_file
compile the configuration file to binary
-D
dump the configuration file in text format
$ scriba
Usage: basic [options] program.bas
The program does not insist on its name, the person installing can name it basic, scriba or any other name. However scriba is the preferred name for the executable. When you start the program without arguments it tells you the different options. If the program does not start check that the executable is in the path or specify the full path to the executable. Under UNIX you may need to start ScriptBasic after you have compiled as ./scriba
The compilation and execution of the code can be altered and driven by command line options. There are not too many and usually you do not need any. If you want to start a basic program you can type:
$ scriba hello.bas
Hello world!
$ _
The program will execute the basic code and after executing the final statement it exists the process.
OPTION -o
ScriptBasic STANDARD variation is able to dump the compiled code to a file and later use this image to execute the basic program. To do this you can type
$ scriba -o hello.bbf hello.bas
This command will compile the program hello.bas into the file hello.bbf. The code itself will not be executed. The extension bbf stands for basic binary format, but you can use any extension. ScriptBasic does not assume any default extensions.
OPTION -b
The saved binary format can be executed by the interpreter issuing the command
$ scriba -b hello.bbf
The switch `-b' tells the interpreter that the file is already a compiled format and it needs only execution. However ScriptBasic STANDARD variation is intelligent enough to recognize the binary format and it will not try to interpret it as basic text even if you miss the switch `-b'. The command line
$ scriba hello.bbf
should also work. The switch `-b' is available because recognizing the binary format applies some heuristics and using the `-b' switch to execute a compiled basic program is the safe way.
Note that the compiled format is not compiled in the sense of usual compilers. The compiled format is NOT machine executable. This is the internal format that the interpreter interprets and executes. This format is created and stored in memory each time a basic program is executed. When the `-o' switch is used this internal format is saved and can be reloaded later to execute again the basic program.
This binary format is proprietary and is NOT portable. This binary format was designed to load the programs fast and allow the interpreter speedy startup for codes executed many times. You have to "compile" your basic code on the architecture you want to run it. It needs not be physically the same machine, but it should be the same type of operating system, the same compiler used to compile ScriptBasic executable and the same ScriptBasic version and build number. The different variations may accept each others binary format. For example the Eszter SB Application Engine variation accepts the binary format created by the STANDARD variation. We recognized that the STANDARD variation running on Linux compiled with gcc can execute the binary format generated by the Windows NT version of ScriptBasic, but this is only the fact of life and it is not a guaranteed feature.
OPTION -e
In certain situations you may want to save the binary format and execute the code the same time. In this situation you can issue the command line:
$ scriba -o hello.bbf -e hello.bas
The switch `-e' tells ScriptBasic to execute the code. This is not the normal behavior when binary format is saved to file. Note that you need the switch `-e' only when the switch `-o' is also on the command line. To execute a program without saving the binary format to a file you need no switches at all.
OPTION -n
The binary format of the code is usually saved into a directory without user intervention. The cache directory is defined in the configuration file using the configuration key cache. In certain situation you want to avoid caching of the code. If you use the command line option `-n' neither cache checking for newer version nor cache writing will be performed.
OPTION -c
You should use the `-c' option in programs that are executed as CGI scripts. This helps the error reporting system to cooperate with the web server and send properly formatted HTML formatted errors whenever and error occurs.
OPTION -C
The option `-C' asks the interpreter to generate C language compiled code. For more about this option read in Compiling BASIC programs to C.
OPTION -E
The option `-E' asks the interpreter to create a stand alone executable from the BASIC program. This is an option that works only on some platform, but not on all. It does work on Windows and under Linux and some users reported success using it under FreeBSD and Solaris. When using this option the interpreter creates a file that can be started and contains the compiled BASIC program in itself. This is not a compilation just as well as compiling into binary format is not a real compilation. All it does that it copies the interpreter and the binary format of the BASIC program into one file and sets it so that executes the BASIC program embedded into the executable file.
OPTION -p
The option `-p' should be used to specify an external preprocessor. This preprocessor has to be configured in the configuration file of ScriptBasic. Ask the system manager responsible for your installation about the available preprocessors. If this person is you read the section Using external preprocessor. You can specify more than one preprocessors on the line. These are executed one after the other in the order they are specified on the command line. If no preprocessor is defined on the command line the interpreter will execute the preprocessor or preprocessors that are assigned to the extensions of the source file name. The assignments should be configured in the ScriptBasic configuration file.
OPTION -i
The option `-i' specifies an internal preprocessor. Internal pre-processors are implemented as DLL or SO file. These programs are loaded by the ScriptBasic interpreter when the command line option `-i' is used, or when the program contains the command USE. The internal pre-processor can alter the source code after the interpreter read the code into memory, but also can do a lot of other things while ScriptBasic compiles the code, and some of them even during run time. For more information on internal pre-processors read the guide of the actual pre-processor, or read the developers guide that details how internal pre-processors should be developed.
The argument to this option has to be the name of the internal preprocessor as configured in the configuration file. For example, to start the program in command line debugger mode the user has to type:
scriba -i dbg hello.bas
The program will load the preprocessors in the order they are specified.
OPTION -f
When ScriptBasic starts it reads its configuration file. Some programs can run without any configuration information, however more complex programs will need external modules and this most probably will require configuration. The configuration file is located usually at `/etc/scriba/basic.conf' under UNIX or in the same directory where the executable is under Windows NT. However in some situation you may want to run ScriptBasic using some special configuration file. In this case you can specify the configuration file using the option `-f'. The argument to this option is the name of the file that is the compiled configuration information. The only exception is when you are using this option along with the option `-k' to compile the configuration information. In this case the argument to the option `-f' has to be the name of the configuration file that is to be created.
OPTION -d
The option `-d' is a special one and you need it only if you are using UNIX and you compiled some of the external modules yourself. If you use Windows or somebody else installed ScriptBasic for you on the UNIX box you do not need this option. What is more: on Windows this option is totally ignored.
On UNIX the option `-d' prints out the system error message when an external module fails to load. Without this option the interpreter says: 'module can not be loaded', but you, the installer of the module do not know why. Here is the reason why it is needed in some cases on UNIX and why not under Windows.
On Windows when you compile source code to DLL all symbolic references have to be resolved. If a module uses the zlib.lib for example, you have to link it against the DLL during link time. UNIX is more allowing. If you miss the `-lz' (to stay with the example of needing zlib) when you link the shared object the linker does not complain, because UNIX dynamic loading system allows symbolic reference resolution during run time. However when you run ScriptBasic and want to load the module this missing function appears immediately.
A real word example is the MySQL module. The first version of ScriptBasic MySQL module supported MySQL v3.22. The version v3.23 already required the zlib library. The v2.23 was tested only on Windows NT and when it was first compiled by a FreeBSD user, the module was not loadable. He needed the `-d' to see the error, which said 'unresolved reference: uncompress' making immediately clear that the option `-lz' had to be added to the Makefile.
OPTION -k
The option `-k' can and should be used to compile a text configuration file to binary format. In this case the input file name should specify a text format configuration file and not a BASIC program. The output file can be specified by the option `-f', but it is not a must. If the option `-f' is not used along with the option `-k' the output file will be the default configuration file.
Note that ScriptBasic command line parsing is the same when you use the option `-k' as it is when executing a program. Therefore all options, typically the option `-f' should precede the input file name. If the option `-f' is placed after the input file name, the command line parsing program believes that it will be some command line argument for the BASIC program and ignores it.
OPTION -D
The option `-D' can be used to display the content of the current compiled configuration file. ScriptBasic will read the configuration file and dump the content formatted according to the text configuration syntax to the standard output. You can use the option `-f' to specify an alternate compiled configuration file if not the default is to be debugged. If an output file is specified using the option `-o' along with the option `-D' the text content of the configuration file is printed into the output file. The output can be sent to the standard output explicitly specifying -o STDOUT as output or to the standard error specifying -o STDERR.
OPTION -v
The last switch is `-v', which can be used to print version information.
ScriptBasic v2.0
Variation >>STANDARD<< build 0
Magic value 859010867
Node size is 16
Extension interface version is 11
Compilation: Jul 23 2002 22:24:56
Executable: T:\ScriptBasic\bin\scriba.exe
$ scriba -v
When you use this switch ScriptBasic does not execute any program. Instead it prints out information on itself and stops. The information lines printed are:
Note that the actual version and build may and most probably is different from the example presented here. This is a printout of the version by the time this part of the documentation was written.
This is usually 16bytes on 32 bit machines. If you get a higher value on a 32bit-machine when you compile ScriptBasic from source check your compiler for alignment options.
Tru64 UNIX compiler creates 24bytes nodes.
If you do not understand all this node size stuff, just forget about it.
The actual magic value and the compilation date will be different when you try the option `-v' on the released version of ScriptBasic, because this documentation was created using a pre-release version of ScriptBasic v2.0b0.
Note that any command line option should be specified before the name of the BASIC program. Any command line option or argument specified following the name of the file containing the basic program in text or binary format will be passed to the basic program itself. The basic program can use the function COMMAND() to access this part of the command line.