Running OneGate is quite simple. The most common way CGI programs are invoked is via an HTML FORM, where information is put into fields, and a SUBMIT button is pressed to invoke the CGI application.

Within this methodology, your form's ACTION tag should look like the following:

ACTION="http://www.myhost.com/cgi-bin/onegate"

In addition, your form must contain one field, which should be of the HIDDEN type. The field should look like the following:

<INPUT NAME="onegate_set" TYPE="HIDDEN" VALUE="my_program_set_name" METHOD="POST">

Please note that if you are going to use HTTP File Upload, you must add the following to your FORM tag:

ENCTYPE="multipart/form-data"

Alternately, you may create regular links to OneGate in the following fashion:

<A HREF="http://www.myhost.com/cgi-bin/onegate?onegate_set=my_program_set_name">Click Here!</a>

Please note that HTTP File Uploads will not work from regular HREF links, and they do require the ENCTYPE attribute, as shown above, as well as the POST method type.

The HREF methodology performs a GET style request rather than POST, and is not recommended for more than a few kilobytes of data. My rule of thumb is to use POST if you have more than 100 characters of data or so. This methodology was meant for brief queries, such as those sent to search engines. Sending large amounts of data with the GET method may result in the argument space of the server's process being exceeded on some platforms, which will corrupt your transactions. This is a technical limitation of the GET method as relates to argument space availability within operating systems. Always use POST for more than the smallest amounts of data, as it also keeps URLs short and manageable, which is considered good form.

An interesting feature to note is that the first time you run an application, it creates its [maindir]/spool/[progset] directory. Inside this directory, a tmp directory is also created. This directory is persistant. When OneGate runs the application, it changes the PWD environment variable to the [maindir]/spool/[progset]/tmp directory, and also internally changes directory to this location for the execution of the program set. When your programs run, if they need any persistant configuration files of their own, you can safely store them here and open them from the current directory. Should you need this directory prior to running the application for the first time, simply create the heirarchy leading up to it ([progset] and tmp itself, starting inside the spool) and make sure your *nix ownership and permissions (or Windows security settings) are set correctly for the directories.