Syntax & configuration

baserunner configuration file
Application configuration file
Command line and form variables
Actions
Security
Cookies

Creating a baserunner application requires several elements: database(s), configuration files, and HTML templates. In constructing an application, baserunner places very little restriction on you pass information to baserunner. baserunner requires that specific variables be available to properly parse the templates processes and sends to the user. These variables are passed to baserunner through configuration files, through the command line, through HTML forms, or through cookies: baserunner is very flexible in terms of how the necessary variables are passed.

All variables passed to baserunner, unless they refer directly to a database field, are prefixed with an underscore "_".

The first call to baserunner will specify the name of the application configuration file through the _cfg variable. When baserunner processes a call that contains a _cfg variable, it starts a new user session.

All subsequent calls to baserunner must include the name of the user's session (generated by the first call the the program) through the _ses variable. The _ses variable always is given a value of {session}, which is replaced by baserunner with the unique name assigned to the current user's session..

Beyond those two rules, baserunner permits you a great deal of latitude in constructing calls to the program within your templates.

A baserunner application requires two configuration files. These files will contain many of the variables baserunner needs to run. Once baserunner is started, the variables from the configuration files are treated no differently than variables passed on the command line or through a form.  The configuration files are standard ASCII text files. Each variable name must begin with an underscore ("_"), formatted _variable=value. Any configuration file variable not beginning with an underscore will be ignored. Text files are formatted differently under DOS and Unix; however, baserunner will handle DOS formatted configuration files under Linux.

Under Linux configuration files must end with a blank line.

Under Windows lines in a configuration file are limited to 254 characters.

Variables that may be included in the application configuration file may also be passed to baserunner via the command line or a form variable. Generally, variables that will not change while the application is running should be placed in the configuration file. Even if a variable is included in the application configuration file, it may be overridden by a variable of the same name passed from the command line or a form. Variables contained in the baserunner configuration file cannot be overridden.

baserunner sees treats all variables the same way, whether submitted through a form, sent on the command line or included in a configuration file. The priority baserunner gives to variables is:

1. baserun.cfg.
2. the command line (GET).
3. form variables (POST).
4. http cookie information.
5. the application configuration file.

Variables with higher priority will override variables with lower priority: e.g. a _dbf variable passed on the command line will take precedence over a _dbf variable included in the application configuration file. There are several variable types:

baserunner configuration file

The first configuration file is available to all baserunner applications; it is named baserun.cfg. (Note: The name of this file is actually the same as the name of the baserunner executable file. So, if you rename baserun.exe, say, database.exe, the name of this configuration file is database.cfg). This file must be located in the in the default directory for the executable, normally cgi-bin, but depending on the server configuration it could be the web root directory. Using this file is optional, but strongly recommended--see the note under Security, below. baserun.cfg may contain any variables that will be available to all your baserunner applications. Variables contained in this file cannot be overridden by variables sent through a form or on the command line.

Examples:

_sessionpath=/home/mydir/www/cgi-bin/sessions/ _configpath=/home/mydir/www/cgi-bin/configs/ _datapath=/home/mydir/www/cgi-bin/database/ _templatepath=/home/mydir/www/cgi-bin/html/ _expired=Your baserunner session has expired!

Note: All the paths in baserun.cfg must end with a trailing "\" or "/" depending on the file system. These paths are the physical paths to the files, not the virtual paths you would use in a URL. Long directory names and file names are acceptable. If you do not include the path variables, You must specify the full path to the files in the application configuration file or from the command line. You may include other variables in baserun.cfg as well. Because of its having the highest priority, variables in baserun.cfg cannot be overridden. All baserunner applications should make use of the path variables in this configuration file.

Application configuration file

Application configuration files determine most of the basic behavior of a baserunner application. Unlike baserun.cfg, you may give this file any name (and extension) you wish. There is no limit on the number of configurations you can use with baserunner. The format of the application configuration file is the same as that of baserun.cfg.

An application configuration file is required for each baserunner application. Any variable that you want your application to treat as a default should be placed in the application configuration file. Some variables are only passed to baserunner from a form or from the command line. The variables that are normally or always contained in the application configuration file are shown in the table below. Variable names in boldface may have any name (as long as it does not conflict with another variable name).

CFG = May be included in the application configuration file.
CL=May be included on the command line or as a form variable.

Command line and form variables

baserunner can be called through a standard link that passes a command line to the program or through a form. The variables that are passed to baserunner tell it the name of the user’s session, the target template file to open, and the action the program should take before opening that template along with any other information you require. While CGI is a well established standard, the way different servers handle data sent from a user does vary. Some methods of calling baserunner may not always work on some server configurations. Generally, if you are getting unexpected results from one method of calling baserunner, try another--if, for instance, you have trouble sending variables through the command line, try rewriting the call as a small HTML form. Trial and error is the best way to find out what works. Most servers will handle any of the calling methods with no problem at all.

The first call to the program needs to pass the name of the configuration file. Normally that is the only parameter that is necessary. The program will open the default target, _defhtml, if no _tar variable is specified.

<a href="/cgi-bin/baserun.exe?_cfg=[configuration file]"></a>

or to start baserunner with a form:

<form action="/cgi-bin/baserun.exe" method="GET"> <input type="hidden" name="_cfg" value="[configuration file]"> <input type="submit" value="Start"> </form>

With the initial call that includes the application configuration file name, baserunner creates a session record for the user and assigns her a unique session name. The three variables that are used with most subsequent calls to baserunner are: _ses (session), _act (action), and _tar (target template).

On every call to baserunner after the first, the session name is passed using the session variable: _ses={session}. The _tar variable specifies the target template that baserunner should process. The _tar variable may be omitted if the current template will be used again. The _act variable is the action baserunner should take when parsing the target template (or reading the submitted form). If you simply wish to open another template without repositioning the record pointer, you may specify a _tar variable and omit the _act variable. _ses, _act, and _tar are the most common variables. Other variables may also be passed either on the command line or through a form. If a variable is sent from the command line or from a form, it will override a variable of the same name in the configuration file. Variable names in boldface take the name(s) of a field in the current database. These are the only variables that do not begin with an underscore.

CFG = May be included in the application configuration file.
CL=May be included on the command line or as a form variable.

You may include any additional variable you wish with a form or on the command line. You simply must give it a name that begins with an underscore, "_". These additional variables may be assigned any value, and those values may be retrieved by using the variable name as a tag.

When passing variables that take expressions (or other values that contain characters that might interfere with HTML) on the command line, you will need to URL encode that value. To accomplish this, you may use the tags <%. . .%> to specify the text that baserunner should URL encode. For instance, if you pass a _fil variable on the command line, you could instruct baserunner to encode the value: _fil=<%expression%>. Any value that contains characters that are not alphanumeric should be URL encoded when passed on the command line. If such values are passed through a form the browser will take care of the encoding. Values contained in a configuration file do not need to be encoded.

The actions that are recognized by baserunner are detailed below. On the command line (the information following the question mark, "?") the variables are separated by an ampersand "&". The command line may include URL encoded information

<a href="/cgi-bin/baserun.exe?_ses={session}&_act=[action]&_tar=[template]"></a>

When passed through a form, the variables should normally be included as hidden variables within the form. A form may use either GET or POST as its method. Generally for queries, entry, and editing, you should prefer POST; otherwise GET is appropriate:

<form action="/cgi-bin/baserun.exe" method="GET"> <input type="hidden" name="_ses" value="{session}"> <input type="hidden" name="_act" value="[action]"> <input type="hidden" name="_tar" value="[template]"> <input type="submit" value="Submit"> </form>

If you use post as the method, you also have the option of passing both form variables and a command line:

<form action="/cgi-bin/baserun.exe?_ses={session}&_act=[action]&_tar=[template]" method="POST"> <HTML Form Variables> <input type="submit" value="Submit"> </form>

Actions

The _act variable may use any of the following values:

Security

For an excellent discussion of the security issues raised by all CGI programs, please see this page at w3.org. Any use of CGI presents some risks. baserunner seeks to minimize these risks. Setting appropriate variables and using the tools your server provides will make baserunner more secure.

baserunner does require the ability to write files on the server. The only files baserunner creates are the session database and its associated memo file. baserunner also can write data to the application's database(s). baserunner cannot be used to write any other files to the server.

Permitting your users to enter HTML code into database fields should be closely monitored--particularly if your server permits SSI. You may set baserunner to strip HTML tags from user entry. baserunner does expect your application to be responsible for most form validation. With data entry forms, baserunner will ignore inappropriate user entries. baserunner uses dynamically sized storage for variables.

Under Linux, the internal calls to the sendmail program are generated with the -t option that helps eliminate malicious use of that feature.

When running baserunner under Linux, set directory and file permissions to the least necessary to run your application. Windows permissions are less sophisticated than those used by Linux so you don't have as much flexibility there.

Any database or configuration file that contains confidential information should be placed in a password protected directory. baserunner is just sitting there on the hard disk--it has no control over a user downloading a database or a configuration file from your server. A knowledgeable user will probably be able to determine where the various files are on your server, and, if they are in unprotected directories, will be able to get them without much difficulty. If you have questions about how to secure directories or files, consult your server administrator.

Using a "baserun.cfg" file to hold the paths to your application files is probably the single most important security measure you can take. Since the path included in the configuration file is used for opening all files, it eliminates the possibility of a user using baserunner to call a specific file from the command line (e.g. _tar=c:\autoexec.bat). On a well configured server, this is not a huge concern, but could potentially open up the system to attack. Running baserunner without a baserun.cfg file specifying paths to the directories containing your application files should be considered insecure.

Cookies

Using cookies to supply some variables, particularly the session name, may provide some additional security because the application won't rely on variables or hidden variables that can be easily edited by the user before submission (or bookmarked). Cookies can also simplify calls to baserunner by supplying variables globally (much like the configuration files, except that these variables may be generated at runtime). The downside is that the user must have cookies enabled for any of this to work. Setting and managing cookies are best dealt with through JavaScript. A very simple script to add cookie variables would look something like this, although there are many options available:

Obviously, to use this script, the _tagstart and _tagend variables are set to "[" and "]" respectively. This script would need to be included in the template contained in _defhtml (at least to make the _ses variable available to the rest to the application).