Section Links

• Getting Your Data Uploaded
• Starting A Sesame Server On The Web
• Building A Webpage To Serve Sesame Data
• Putting It All Together
• Using PuTTY

With the free release of the Sesame API, it has never been easier to deploy a Sesame application on the web. Using Sesame's ability to save a form as HTML (the language of web pages) and to then integrate that web page with an online Sesame application using the API, it is no more than an afternoon's work to get your application "on the web." Providing support for the common scripting languages of the web (PHP, Perl, Python, Java, and C#), the API lets any web page send data to a Sesame server, or get data from the server in much the same way as the usual Sesame client software.

As many of you have seen, the convenience of having an application on the web is paramount in today's business climate. Customers, salespeople, regional offices, and your people "on the road" all need access to information, and they need it immediately wherever they are. Deploying information on the web provides that information to your customers or employees anywhere they can get on the internet, with no more software than a web browser. This means that they no longer have to wait until they get back to the office to update the application or get the latest information from the database. It is, quite literally, at their fingertips all of the time.

Getting Your Data Uploaded

Almost all web servers, the machines that provide web pages, run either Linux or Windows. Currently Linux is the much more popular choice for web servers. If you have Sesame for Windows, you can obtain and run Sesame for Linux at no additional cost. To run Sesame on a web server that you own and manage is as simple as copying the executable to that server along with your application and license files. If you are using a third party web server, as most of us are, it is not much more difficult to deploy Sesame, but there are a few simple requirements. You must have some way of copying files to the web server. Typically, this is done using a program known as FTP ("file transfer protocol/program"). There are special FTP programs for Windows that have an easy to use graphical user interface. Alternatively, a command line FTP program comes with every version of Windows since Windows 95. A typical FTP session to send Sesame to a web server would look something like this:

(Instructions are in italics and bold. The portions you need to type are in bold and appear after a "ftp>" or "C:>" prompt. Replies from FTP usually start with a number (i.e.: 220, 230, etc...) and may vary from one server to another.)

On the command line type ftp, followed by the name of your web site
C:\> ftp www.YourWebSite.com
220-Welcome to www.YourWebSite.com

FTP will now prompt you for your login name and password. These should be provided by the company providing your web server.
Name: YourLoginName
331 User YourLoginName OK. Password required
Password: ************
230-User YourLoginName has group access
230 Ok. Current directory is /
Remote system type is UNIX.
Using binary mode to transfer files.

Go into the directory where web pages are kept - usually "www" or "public_html".
ftp> cd www
250 OK. Current directory is /www

Make a directory ("folder") to put sesame in.
ftp> mkdir Sesame2
257 "Sesame2" : The directory was successfully created

Go into that directory.
ftp> cd Sesame2
250 OK. Current directory is /www/Sesame2

Send sesame to the web server putting it in the directory you just created: "Sesame2".
ftp> send sesame
local: sesame remote: sesame
229 Extended Passive mode OK (|||36665|)
150 Accepted data connection
100% |*******************************************************************************************************************| 6746 KB 77.14 KB/s 00:00 ETA
226-File successfully transferred
226 87.699 seconds (measured here), 76.93 Kbytes per second
6908361 bytes sent in 01:27 (76.92 KB/s)

Log out of FTP and disconnect from the server.
ftp> bye
221-Goodbye. You uploaded 6748 and downloaded 0 kbytes.
221 Logout.

Yes, it is a bit cryptic and difficult, mostly due to its age. FTP is probably one of the oldest programs still in general use, invented in the late 1960s. Don't let it intimidate you. At the end of the day, it is simply a program from copying files from one machine to another. For this example, send sesame (the linux executable), sunlock (the linux version), s_license2.lic (your license file), and the sample application Customers files - both the .db and the .dat files to your web server, using the approach seen above. You can send more than one file by re-issuing the "send" command for each file. You can send files using a wildcard by using the "mput" command. For example, "mput *.html" will send each HTML file in your local directory to the server.

Starting a Sesame Server on the Web

After you have Sesame uploaded to the server, the next step is learning how to execute Sesame as a server. Fortunately, most web servers provide their users with a simple means for launching programs. Unfortunately, because web servers do not, and usually cannot, have a graphical user interface, we'll be spending a bit more time on a command line. If you are acquainted with the Windows (DOS) command line, this will not be very different. If you have only used icons and menus, this is may help you better understand one of the basic ideas behind any operating system. Whether you are using a graphical user interface (GUI) on Windows or one Linux, you have actually always been using a command line, the graphics simply hide this from you. Right click on any icon on your desktop and select "Properties" from the menu that appears. This will launch the "Properties" dialog box for that icon. Dig around a little and you will find fields that tell the operating system what program to launch and in what directory ("folder") to launch it. These are exactly the same things you would type on a command line, except the operating system's desktop does the typing for you.

Web servers need to provide capabilities to many users at once and need to send information to hundreds, if not thousands, of users simultaneously. It would be impractically slow to provide so many users with their own GUI and desktop through the internet. Instead, most web servers provide a command line interface to your account, files, and directories on the server. Because we are "on the internet," this connection between your computer and the web server for this command line is usually encrypted. This keeps prying eyes from getting your passwords and other critical information you may not want to share with the internet at large. Almost all Linux web servers provide a facility called "ssh" for connecting to a command line on your web account. Linux provides ssh as part of the operating system. For Windows users there are many free ssh utilities. The most prominent of these is PuTTY. If your web server does not provide any means to get to a command line, you should seriously consider changing web server companies.

Setting up ssh or PuTTY to work with your web server isn't difficult and there are dozens of examples for each program provided on the internet. Adapting these examples to your situation is usually just a matter of typing in the name of your web server and the login and password provided when you purchased the web site. Some web providers require that you provide additional identification when you apply to get ssh access to your web site. They do this to make sure that no one else is getting access to your stuff.

Once you have ssh setup, you are ready to log in. You will be asked to provide a user and and password. PuTTY lets you set these up once for each server you plan to access, so you don't have to type them in each time you connect. After successfully logging in, you will be provided with a command prompt. Because your web server is probably a Linux box, this command prompt will probably look a bit different from the command line in the command window in Windows. For example it may use "$" or "#" as the prompt character, instead of the ">" that Windows uses. Some of the commands you can issue on the command line will be the same as those used by "DOS" and some are different. For example, Linux uses "cd" to change directories, just as DOS does. But, instead of "DIR", Linux uses "ls" to list files and directories. Also, Linux is case sensitive. So, "ls" is a known Linux command, but "LS" and "Ls" are not. Another difference is that Linux uses the forward slash ("/") to separate directory names, where DOS uses the backslash character ("\"). To see the path where you are logged in, type the command "pwd". You should see something like: "/home/YourWebName".

To launch Sesame on the server, you will need to "navigate" to the directory you created using FTP. So issue the command "cd www/Sesame2". Now type "pwd" and you should see that your current directory is "/home/YourWebName/www/Sesame2". If you type "ls", you should see sesame, sunlock, s_license2.lic, Customers.db and Customers.dat listed. Launching Sesame on a web server is very similar to launching it on an ordinary Sesame server.

sesame -daemon -server localhost:20000:20001 &

The three differences you should immediately notice are that you have used the "-daemon" flag, that the server is called "localhost", and the command line ended with a "&". The "-daemon" flag tells Sesame to run without any kind of graphical user interface. If you forget to specify this flag, Sesame will complain that it can't open a "display" and exit. We specify "localhost" instead of the server name because we don't want Sesame to be directly accessible to the internet. Huh? What, you ask, wasn't that the point? Well, sort of. Most web servers only allow a handful of well known "ports" to be directly accessible to people connecting to that server from the outside world. Port 80 is open because that is the port that the web server software uses to talk to web browsers. Port 25 is usually open to provide email services. But ports 20000 and 20001 are usually closed on the server's firewall and cannot be opened to the public. So, instead we open those ports on "localhost". The "localhost" is a a nickname for the virtual network that is only available to programs running on the very same computer. Since we want Sesame to be available to the web server software, usually "Apache", and that software is running on the same computer as the Sesame server software, using "localhost" is the way to go. Apache will be responsible for providing access to Sesame to the outside world. The last bit that is different is the ampersand "&" that appears at the end of the command line. This tells Linux that we want our command line back before the Sesame server has completed executing. By running Sesaame "detached", you get to continue issuing commands to Linux while Sesame is running, and Sesame will continue running after you log off.

If you get an error message "Permission denied" when you try to launch Sesame, that means that FTP did not set the execute permissions on the file when it transfered it from your computer. Type "chmod +x sesame" to tell Linux that sesame is a executable file. Linux does not use file extensions like ".exe" to determine if a file is an executable. Instead, it uses permissions that are much the same as the read/write permissions Windows files have. The command chmod ("change mode") is used to change those permissions.

Building a Web Page to Serve Sesame Data

The next steps take place back on your computer, so we need to stop sesame and log off the Linux server. To stop sesame, type "killall sesame". This tells Linux to stop any processes you own (you launched it, so you own it) named "sesame". Once sesame is terminated, log off of the Linux server by pressing ctrl-d or typing exit. You should now be disconnected from the web server and back on your own computer.

Sesame has the ability to make a web page from a form. As an example, open the Customers.db sample application, open the only form, enter "Add Mode" so the form is blank, and select "Save Current Record to HTML" from the menu. Set the filename to "customers.html". HTML is the language of web pages. Basically, you have told Sesame to translate the current form into HTML and to save result in a text file with a ".html" extension. Some small modifications to this file will be needed in order to use it as a web page for the Sesame API. Using a text editor (not a word processor), edit the customers.html file. The code you are seeing is the "source code" of a web page. In our case it is a HTML form. Most of the lines in the file represent different elements that appeared in the Sesame customer's form. You can bring this web page up in your web browser by browsing to the directory where you created the file and selecting "customers.html". The web page should resemble the original Sesame form. In your text editor, move to the line that says "<FORM>" and change it to read:

<FORM action="main.cgi" method="post">

Open a blank line above the line that says, "</FORM>" and type in the following lines:

<div style="position:absolute; left:200; top:500px; background:#e5e5e5; color:#000000;">
<input type="submit" name="mysubmit" value="Search">
&lt/div>

This will create a "Search" button at the bottom of the form. Save the file. The first change to the <FORM> tag tells the web server that the program called "main.cgi" is to be used when someone submits this form. The second change adds a button that will cause the submit to take place.

Using the Sesame API

The next step is to write the "main.cgi" file that runs when a user presses the "Search" button. Again, use a text editor to create a file named "main.cgi". It should contain the following code:

#!/usr/bin/python2.6

import sesame_python_api
import cgi
import os
import sys

happy = sesame_python_api.SesameConnect("www.YourWebSite.com")
if(happy < 1):
        os.system("./sunlock Customers.db")
        os.system("./sesame -daemon -server www.YourWebSite.com > t.t 2> t2.t &")
else:
        sesame_python_api.SesameDisconnect()

happy = sesame_python_api.SesameConnect("www.YourWebSite.com")
if(happy > 0):
        search_str = ''
        form = cgi.FieldStorage()
        for field in form.keys():
                if(field != 'mysubmit'):
                        search_str = search_str + '!' + field + '=' + form[field].value + '%'
        search_str = search_str[:-1]
        nn = sesame_python_api.SesameSearch("Customers.db", "Customers", 0, 2, search_str, "", "")
        print 'Content-Type: text/html\n'
        print ''
        print ''
        print ''
        print 'Search Results'
        print ''
        print ''
        if(nn > -1):
                num = sesame_python_api.SesameTotal(nn)
                if(num > 0):
                        sesame_python_api.SesameSort(nn, "Last:-1")
                        print '

Search Results

' print '

Your search returned ' + str(num) + ' records:

' print '

Start a New Search

' print '

' + str(loop) + '	' + last + '	' + first + '	' + company + '

' else: print '

Your search returned no matching records.

' print '

Start a New Search

' sesame_python_api.SesameClose(nn) else: print '

Error: Search failed.

' print '

Start a New Search

' print '' print '' sesame_python_api.SesameDisconnect() else: print 'Content-Type: text/html\n' print '' print '' print '' print 'Search Results' print '' print '' print '

Error: Sesame server cannot be started.

' print '' print ''

Of course, replace "YourWebSite" with the actual name of your website. The code is written in the very popular scripting language known as "Python". It is easily adapted to any of the other scripting languages the Sesame API supports, such as PHP, Perl, Java, or C#. If you know SBasic, then you should recognize a number of the commands in the code. For example "sesame_python_api.SesameSearch" is the same command as "XResultSetSearch" in SBasic. Basically, this program knows how to start a Sesame server, if it is not running, get search values off of the submitting web page ("customers.html"), connect to the Sesame server, perform a query based on the values from the web page, and return the results in a table on a new web page.

Putting It All Together

Using FTP, upload the customer.html file, the main.cgi file, and the following files from the free Sesame API package to the same directory (/home/YourWebSite/www/Sesame2) where you uploaded sesame, sunlock, and the Customers.db and Customers.dat files:

sesame_python_api.py
sesame_python_api.pyc
_sesame_python_api.so

Log into your server using ssh or PuTTY. Navigate to your directory ("cd www/Sesame2"). If you issue the command "ls" you should see a list of files. You should have the following files listed:

Customers.dat
Customers.db
customers.html
main.cgi
sesame
sesame_python_api.py
sesame_python_api.pyc
_sesame_python_api.so
s_license2.lic
sunlock

To make sure that each of the files are executable, issue the following commands:

chmod +x main.cgi
chmod +x sesame
chmod +x sunlock
chmod +x sesame_python_api.py
chmod +x sesame_python_api.pyc
chmod +x -sesame_python_api.so

You can now check out your work. Using a web browser navigate to "http://www.YourWebSite.com/Sesame2/customers.html". You should see the same form you looked at earlier. Type a Q&A style search spec into the form, for example set "First" to "a.." and press the "Search" button at the buttom. The main.cgi script will be invoked. It will check if sesame is running. If not it will start it. This may take a short while. It will then return a web page with a table of the results for those people that have a first name that starts with "a":

Your search returned 17 records:

0	Black	Arnold
1	Charles	Angie
2	Delavina	Alice
3	Dent	Anthony	Dent & Dent
4	Depaulo	Anthony
5	Di Paola	Ann	Di Paola Executive Placement Service
6	Farquharson	Aurora & Banny
7	Gemmill	Amy	Gemmill & Partners
8	Harper	Arinn
9	Hughes	Ali	Nationwide Self Storage
10	Liddell	Alice
11	Serra	Armando
12	Targan	Adrian
13	Thompson	Anna	Hop Skip & Jump Enterprises
14	Varnell	Ann Marie
15	Webb	Alice
16	Wise	Anne & Francis

If Sesame is already running, searches will take less time because the web server doesn't have to start up the Sesame server. So it is probably a good idea to run the first search yourself before you let the general public have a go. Of course, if the web server needs to rebooted at any time, the first person to use your page will see the slight slow down as Sesame is invoked.

A Live Example

To see this very example up and running on a website. Send your browser to http://www.lantica.com/APIExample. I have kept this example especially plain and simple so that the code would be as uncluttered as possible. But it is not difficult to pretty it up a bit or even completely change it to post information to a Sesame application, or use multiple applications - some reading others writing. The possibilities are endless. And, because this is a Sesame application running on web page, it can be accessed from all over the world with nothing more complicated than a web browser.

Accessing Sesame Securely Using the Sesame Client

One question that keeps coming up since Sesame was a new product and has special relevence to running Sesame on the web, is "Can I run Sesame through a secure connection?" The answer is, and always has been, "yes". Earlier, you set up ssh or PuTTY to access your web server. As I mentioned, this connection is encrypted. The type of encryption is identical to that used by web sites that need a secure connection for commerce or banking. We can take advantage of the ssh software to use a Sesame client/server connection to talk to the Sesame server running up on your website. Just as Apache (the web server) can be used to talk to the outside world for the Sesame server, the ssh process that is running on your web server can also be used to connect a Sesame client running on your machine to the Sesame server running on your web server.

When you set up the Sesame server for your website, you set it to use the default ports 20000 and 20001 on "localhost". These ports are not allowed to be opened to the outside world, but other programs running on your web server are allowed to talk to Sesame through these ports on "localhost". If you were allowed to run the Sesame client right on your web server, and it could open a graphical user interface window and send it through the internet to your computer, we wouldn't need a "proxy program" to run Sesame securely through the net. Unfortunately, almost no web servers provide that kind of interface. Instead, we can set up ssh or PuTTY to act as a proxy between Sesame running on localhost ports and the internet, and run Sesame client right on your computer. The ssh program (and PuTTY) both know how to use a technique called "port forwarding". This is where a program reads all of the data that comes in to localhost on one or more specified private ports and then sends that across the net on its own public port. It also listens to its public port and send any data it receives to any number of private localhost ports. If your web server is accessible using ssh or PuTTY, it is unlikely that you will need to make any changes to it to connect a Sesame client on your computer to a Sesame server on your website.

Using SSH

If you are using ssh, a simple command line is all you need to connect a Sesame client to a Sesame server on a website:

ssh -L 20000:www.YourWebSite.com:20000 -L 20001:YourWebSite.com:20001 YourLogin@YourWebSite.com

The "-L" flag tells ssh that you want to forward ports locally and on the server. After it is invoked, it will prompt you for your login password. Once that is typed in, you will be connected to the server and see the Linux command line. You don't have to type anything on that command line. Simply stay logged in. Now, on your computer start a Sesame client:

sesame -client localhost:20000:20001

Because ssh has set up port forwarding, the "conversation" the Sesame client has on ports 20000 and 20001 will get intercepted on your computer by ssh. Ssh will encrypt that conversation and send it across the internet on its own port (usually 22) to the ssh server running on your web server. Because ssh has been told to forward these ports, the ssh server on your web server will then send the conversation to the Sesame server listening to ports 20000 and 20001 on the localhost interface. Once the connection between Sesame client and the Sesame server has been established, you can log off of the remote command line. Ssh will continue to run and maintain the connection, unless you explicitly stop the process.

Using PuTTY

PuTTY has a graphical user interface, so set up is a bit different than the command line ssh. After filling your profile for the connection as you would for any other PuTTY session, select and expand "SSH" on the command tree. Your dialog should appear very similar to the screen shot below. Only two fields here need to be changed. Type 20000 into the "Source port" field, type "localhost:20000" into the "Destination" field and press the "Add" button. A line for that port will appear in the "Forwarded ports:" field. Repeat for the second port, 20001. Of course, if you are using port pairs other than 20000 and 20001, use those instead. Go back to the "Session" screen by selecting "Session". If you have not done so, set your server name, login, and password appropriately for your web server, and save the changes for your session.

With your session complete, you can now invoke that session in PuTTY. PuTTY will connect to your server and setup a SSH command line for you. It is also forwarding ports 20000 and 20001 from your localhost virtual network interface to its own port (usually 22) and sending any data that shows up on those ports to the SSH process on you web server. That SSH process will automatically send any data it receives to the Sesame server running on localhost ports 20000 and 20001 on the web server. Start a Sesame server running on the web server:

sesame -daemon -server localhost:20000:20001

then start a Sesame client on your computer:

sesame -client localhost:20000:20001

and you are now connected to the Sesame server on your web server computer using an encrypted secure connection.

This technique kills two birds with one stone. It allows anyone with ssh or PuTTY and a Sesame client to access Sesame applications hosted on a web server from anywhere in the world. It also encrypts their conversation, so prying ears can't listen in. SSH provides password protection, encryption, and port forwarding. This means that you can run a Sesame server on a central computer and then any of your employees or customers with a Sesame client can access it with an internet connection. But, because it is secured using ssh or PuTTY, unwanted visitors are kept away. And because they are using the same Sesame client ordinarily used to access the Sesame server, all of your forms, reports, programming, and customizations are in place and active. For the price of web site hosting, typically less than $10 a month, you can get a Sesame wide area network.