| |
| contents | queries | |
| configuration | templates | |
| expressions | sessions | |
| databases | data entry | |
| passwords | ||
| license | support |
Contacting baserunner
Installing baserunner
Error messages
The support page at the baserunner web site: baserunner.com, is updated frequently with new information about commonly asked questions. You may e-mail support questions to support@baserunner.com. With any support request, we will be able to provide much better service if you attach (zipped) copies of you configuration, database, and template files to your message. If there files are large, please upload them via anonymous ftp to ftp.baserunner.com. The more detail you provide, the faster we can solve the problem--the message "it doesn't work," will generally not get a very useful response.
Registered users should always provide their registration code when contacting baserunner Software. Registered users always receive the highest priority for support.
baserunner provides a mailing list as a forum for baserunner users to exchange ideas and information as well as for technical support and announcements.
To subscribe to the list, send a message to: baserunner-request@baserunner.com
The subject of the message should be subscribe. To get off the list, send a message to the same address with the subject unsubscribe. Once you are subscribed, you may send messages to the list at baserunner@baserunner.com.
baserunner is a CGI executable program. It must be run under a web server. If you run baserunner simply from a DOS or Linux command line, nothing much will happen.
Evaluating baserunner and developing baserunner applications will be a much simpler process if you run a web server locally. There are many web servers available for Windows 96/98/NT. Quite a few of these are probably overkill for simple development purposes: they're big or they cost quite a bit. If you do not have a server installed locally, I highly recommend the Xitami web server; MS PWS will also work well. Under Linux, you almost certainly have the Apache server already installed. baserunner applications are portable between Windows and Linux; so, if you use a hosting service that runs Linux, you can develop your application under Windows on you desktop (or vice-versa). Obviously, you will need to modify the paths you use for your files.
Your local web server is usually available at http://127.0.0.1. Some systems may use
"localhost" or the name of your system for local access.
To run baserunner, copy whichever baserunner executable you wish to use to your web server's CGI directory (normally, cgi-bin, sometimes scripts). The example application assumes that the executable is named baserun.exe; so, you should rename the chosen executable baserun.exe. There is no particular requirement that the executable should be named baserun.exe (even the .exe.extension does not matter under Linux), that is simply what the example application uses. Note: Some Linux servers do require a .cgi extension for cgi executables. If this is the case with your server, name the executable baserun.cgi, and edit the templates to replace baserun.exe with baserun.cgi. Under Linux, you also need to set baserun.exe's permissions to "x" (executable).
The example application consists of several files (laser.cfg, laser_*.htm, laser.dbf, and laser.ftp/dbt).
The first step in running the example application, or any baserunner application is to create a baserun.cfg file. That file will contain the paths to the various files needed by the application. Create a directory for the application files (or several directories for each type of file), set the permissions for those directories so that baserunner will be able to read and (in the case of the session directory and the database directory) write the files in those directories.
The baserun.cfg file is normally placed in the cgi-bin directory alongside baserun.exe. Some systems are set up so that a cgi will actually run from the web root directory--if this is the case with your system, baserun.cfg needs to be placed in the web root. baserunner must be able to open and read this file with no path information.
For instance, say, you create the following directories under your server: ~/baserun/data, ~/baserun/session, ~/baserun/template, ~/baserun/config. You would then copy the example files to the appropriate directories (*.dbf/fpt to data, *.htm to template, *.cfg to config). Your baserun.cfg file would look something like this:
_templatepath=/usr/local/httpd/baserun/template/
_datapath=/usr/local/httpd/baserun/data/
_sessionpath=/usr/local/httpd/baserun/session/
_configpath=/usr/local/httpd/baserun/config/
or
_templatepath=c:\xitami\baserun\template\
_datapath=c:\xitami\baserun\data\
_sessionpath=c:\xitami\baserun\session\
_configpath=c:\xitami\baserun\config\
Of course, your paths may vary. Once you have copied the files to the appropriate locations, you should be able to start the example with a call to:
http://127.0.0.1/cgi-bin/baserun.exe?_cfg=laser.cfg
If your CGI directory is named "scripts" rather than "cgi-bin" (as is the case with MS PWS), change the value of the _cgidir variable to "scripts" (without the quotes) in the laser.cfg file, and use:
http://127.0.0.1/scripts/baserun.exe?_cfg=laser.cfg
You cannot simply open one of the template files in your browser and run the application--baserunner must be started with the name of an application configuration file and it needs to set up a user session. If you simply open one of the templates, baserunner will not know what configuration to use or have a session record available--you'll just get a session expired message.
You may choose not to use a baserun.cfg file. Please see the section on security on the configuration page, before you make that decision. If, you go that route, you will need to supply the full local paths to the application files in the application configuration file. For instance, rather than:
_record=laser_r.htm
you would need:
_record=c:\xitami\baseun\template\laser_r.htm.
The link to start the application would need the full path to the configuration file:
http://127.0.0.1/cgi-bin/baserun.exe?_cfg=c:\xitami\baserun\config\laser.cfg
And the _dbf variable would need the full path to the database files. The session database would be created in the cgi-bin directory.
The third option, is to simply put all the files in the cgi-bin directory. While this is the easiest option, using a baserun.cfg file is the best.
The concept with any of these options is simple: baserunner needs to be able to locate and read the files used in the application. With most server configurations, if you simply give a file name with no path, baserunner will look for the file in the CGI directory. Some servers will be configured to run CGI programs as if they were in the server's root directory. If this is the case, baserunner would look for the file in the root rather than the CGI directory. If you use relative (i.e. with dot notation) rather than full paths to the files, this is important. If you use a baserun.cfg file, that file will usually need to be placed in the CGI directory alongside the executable. If your server is configured so that CGI's run from the root, that file will need to be placed in the root.
The paths to files are local paths, not virtual paths. baserunner runs as a local program on the server. It (and any CGI program) is unaware of the Net and the virtual paths used in URL's. This is all very simple when you are setting things up on your local server. It can get more complicated once you are ready to move your application to a virtually hosted site. You will need to find out what the local paths to your directories are. The best way to get that information is to ask your system administrator. Getting the results of the server variable PATH_TRANSLATED will give you a good starting place.
Once you have put you application together and have tested it on your local server, moving it to the net should mostly be a matter of changing your local paths to those of the server. Since baserunner applications are portable between Windows and Linux servers, paths are the usually the only changes that need to be made. Using a baserun.cfg file is certainly the best way to move applications between servers--just have one baserun.cfg file for your local server and another for your remote server.
baserunner does need permission to use the application files. baserunner will need "read" permission for any directories that contain application files. For the directory that contains the session and application databases, baserunner will need write permission as well. Some virtual servers make permissions simple; some make them complex. If you have trouble with getting permissions set properly, contact your server administrator first.
Under Linux systems permissions are a bit more complicated than they are under Windows. CGI programs are usually run as a special user (named wwwrun, or something similar) and a member of a special group (named nogroup, or something similar). Either this special user or this special group needs to have access to the directories and files baserunner uses, and you need to set permissions accordingly. As a general rule, you want to set up the minimum access necessary, use a baserun.cfg file, and, probably, password protect the directories that contain the various application files.
These error messages are part of baserunner's start-up routine. They indicate problems that keep baserunner from executing properly:
This error indicates that baserunner was unable to create the session database. Almost always, this error occurs when baserunner does not have permission to write to the directory where the session database is to be created. If you get this error, you will need to contact the administrator of your web server.
This error indicates that no "_cfg" variable was used when baserunner was started. An application configuration file is required for each baserunner application, and the _cfg variable must be passed to baserunner with the first call to start the application.
This error indicates that baserunner was unable to open the specified configuration file. Either the file specified does not exist, the path to the file is incorrect, or baserunner does not have permission to read the file.
This error indicates that baserunner was unable to create a new record in the session database. This error may indicate a problem with permissions or a corrupt session database. Normally, the solution should simply be to delete the session database files and let baserunner recreate them. If you switch from one database format to another (e.g. FoxPro to dBase), you must delete the session database files before running the new version. Also, when you upgrade from one version to another (e.g. 2.0 to 2.5), always delete the session database files before running the new version.
This error indicates that baserunner was unable to open the specified database. This error most often occurs because the path or name of the database is incorrect. It may also indicate that baserunner does not have permission to read the file. It could also be called if the database itself is corrupted.
If your users browse your baserunner application with the Opera browser (and a few others, such as the internal browser in KDE's file manager), they may see some unexpected behavior. These browsers will not refresh the display if the new page is called with the same command line as the current page. For instance, if you have a navigation action like:
<a href=/cgi-bin/baserun.exe?_ses={session}&_act=next>
a user browsing with Opera will need to click her refresh button to see the new information. Otherwise it will appear that nothing has happened even though baserunner has, indeed, moved to the next record. The way around this problem is to add some additional data to the link that will make it appear unique:
<a
href=/cgi-bin/baserun.exe/{rand}?_ses={session}&_act=next> or
<a href=/cgi-bin/baserun.exe?_ses={session}&_act=next&_fake={rand}>
In this case, the {rand} tag inserts a random number into the link that causes Opera to display the new data. The random number is passed to the server in the PATH_INFO variable, or as a "fake" variable, and this is simply ignored by baserunner. Using forms for your calls will largely mitigate the trouble as well.
|
