TweetFollow Us on Twitter

CGI Programming with REALbasic and Apache

Volume Number: 20 (2004)
Issue Number: 6
Column Tag: Programming

CGI Programming with REALbasic and Apache

by Mark Choate

With the recent release of REALbasic 5.5, RB has become an excellent tool to use for web development. The most recent version sports improved networking features and support for XML (including XSLT and Xquery), plus the ability to compile command-line applications, called console applications in REALbasic. Perhaps most interesting is the ability to compile applications for use on Windows and Linux, in addition to Macintosh platforms.

Traditionally, Mac web servers communicated with CGI applications through Apple events. This doesn't work with Apache, however, so a CGI application needs to be able to be able to receive information from the server in the normal CGI way - through environment variables. This article illustrates the steps necessary to implement this in REALbasic. One important thing to note: since many of the features that enable CGI programming in REALbasic are new, the current release (5.5.1) has some bugs, which I have had to work around. Some may be fixed by the time this article is released, but hopefully this will save you some time for those that have not been fixed.

The first step will be to review CGI programming for those who aren't familiar with it. CGI stands for the common gateway interface. It's called an interface because it provides the means for Apache (or any web server that supports CGI) to execute scripts and applications on the host machine of a web server. When a user types a URL into his or her web browser, that URL often represents the location of an HTML file that the server just picks up and sends back to the browser. In a CGI program, the URL represents a script or a program that gets executed. The output of the program then gets sent back to the user. In order to provide security, Apache allows the administrator to configure which directories allow CGI programs to be executed. On OS X the cgi-bin directory is here:

/Library/WebServer/CGI-Executables

This article assumes that you haven't made any changes to the default Apache configuration that comes with OS X. The configuration file that Apache uses is available at /etc/ httpd/http.conf. If you have never modified this file, now is not a good time to start - but you shouldn't need to. It's worth taking a look at it just to make sure that CGI is set up properly. My httpd.conf file has this, about 2/3 of the way through the document:

    # ScriptAlias: This controls which directories contain server scripts.
    # ScriptAliases are essentially the same as Aliases, except that
    # documents in the realname directory are treated as applications and
    # run by the server when requested rather than as documents sent to the client.
    # The same rules about trailing "/" apply to ScriptAlias directives as to
    # Alias.
    #
    ScriptAlias /cgi-bin/ "/Library/WebServer/CGI-Executables/"

The last line indicates two things. "/cgi-bin/" is going to be part of the URL for the CGI application - something like: http://localhost/cgi-bin/ plus the name of your script. The second path is the absolute path for this directory on the server. For this example, we'll be placing our REALbasic CGI program in this directory. Sometimes you'll see CGI scripts that end with a ".cgi" extension, but we won't need to use that - in fact, you should avoid using any extensions because it will mess things up. Other scripting languages, like perl and Python, usually reside on the web server as text files that are executed by an interpreter. Apache uses extensions to map an interpreter to a particular file. Since REALbasic is a compiled program, it doesn't need an interpreter and it's better just to leave the extension off. It also provides for a much nicer URL, which is important, too.

Now we can start work on the program. The easiest way to work is to save the project in the CGI-Executables directory. This is because you'll need to compile the application in order to test it with Apache, and it's easier to just compile it and leave it there to test than it would be to compile it and copy it to the CGI directory.

In RB, a console application is one that does not have a graphical interface - it runs on the command line. In order to create a console application, simply create a new project in REALbasic 5.5+, and select the "Console Application" template. Once that is done, RB will provide you with the shell of an application with one class called "App".


Figure 1. Starting a new console application in REALbasic.

There are two default events in a console application - "UnhandledException" and "Run". The "Run" event is triggered when the program is launched - in the case of a CGI application, it is triggered when a user requests it by typing the application's URL in her web browser.


Figure 2. Blank console application project.

Now is a good time to select the FILE a Build Settings... menu and configure the application. Select "Build for OS X" (this program has only been tested on OS X, although it should work on other platforms as well. Click on the top popup menu on the page, and select "Mac OS Settings". The only thing to change here is the name - be sure to give it a name without an extension and without spaces or punctuation. In this example, I've chosen the name "CGI", which is short and easy to type into a browser window.

Once that is done, it's time to write some code.

Since console applications do not have a graphical interface, they have to be able to input data and output data in some other fashion. For programs that are executed on the command line, this is typically referred to as "Standard Input" and "Standard Output" respectively. With a REALbasic console application, the command "INPUT" represents (you guessed it) standard input. "PRINT" sends data to standard output. In addition to standard input and output, CGI applications also make use of environment variables that are set by the web server. In order to access environment variables, you need the system object, which includes the method: System.EnvironmentVariable(), which returns the value for the environment variable that is passed to it. In the current version (5.5.1) there is a bug that causes REALbasic to crash if you try to access a variable that does not exist. This places some real limitations on what you can do, but it is supposed to be fixed in 5.5.2.

The console application "App" class is where the action is. It has two events: "Run", and "UnhandledException". The "Run" event is triggered when the application is invoked by the web server, so it is in the "Run" event that we put the main part of our code. I also created a "request" object, which is created when the "Run" method is executed. It is a sub class of Dictionary and it is used to hold the data that is passed to the CGI application from Apache. It also executes a "Write" method, that sends data back to the client browser.

The "Run" method should look like this:

App.Run
#pragma disableBackgroundTasks 
  
request = new request
  
request.value("SERVER_SOFTWARE") = system.environmentVariable("SERVER_SOFTWARE")
request.value("SERVER_NAME") = system.environmentVariable("SERVER_NAME")
    
request.value("REQUEST_METHOD") = system.environmentVariable("REQUEST_METHOD")
    
request.value("QUERY_STRING") = system.environmentVariable("QUERY_STRING")
request.value("REMOTE_ADDR") = system.environmentVariable("REMOTE_ADDR")
    
request.getQueryString
request.handleRequest

Background tasks are disabled because Apache doesn't work well with them. If you don't disable them, every time you do a loop, or execute anything that triggers a new thread or background task, the application crashes mercilessly.

In this example, I have only gathered the minimal environment variables necessary to execute the program, because of the bug mentioned earlier. One notable environment variable missing is "HTTP_COOKIE", which is very useful if you use cookies, which provide a way to track a visitor to the site. A complete list of variables is included in the sample script, but commented out.

The two variables that matter most to use are "REQUEST_METHOD" and "QUERY_STRING". There are several kinds of requests a web server can accept. The two that concern us are "Post" requests and "Get" requests. The distinction between the two in actual practice is virtually non-existent, except that it changes the way that form data is passed to the CGI program.

Any time you fill out a form on a web page, either to log in or make a purchase, the information that you enter needs to be transferred to the server so that it can take some appropriate action. When you create a form in HTML, you have the option of selecting the request method you want to use - either "Get" or "Post". If you choose "Get", then the data from the form is encoded and sent across as part of the URL. If you use "Post", then the data is sent to the CGI program as standard input. Here is an example of a "Get" request URL:

http://localhost/cgi-bin/test?cat=dog

The first step in processing a CGI request is to find out what kind of request it is, and process it accordingly. In the request class, I have implemented the following method:

App.request.getQueryString
#pragma disableBackgroundTasks // Throws an error during the loop
  
  Dim query_string, field, key, value As String
  Dim x As Integer
  
  query = New Dictionary
//If the REQUEST_METHOD is a "post", then get the string from standard input, 
   otherwise get it from QUERY_STRING
  If me.hasKey("REQUEST_METHOD") then
    if me.value("REQUEST_METHOD") = "POST" Then
      query_string = Input
    Else
      query_string = System.EnvironmentVariable("QUERY_STRING")
    End If
  end if
  
  if query_string <> "" then
    //parse the query string
    For x = 1 to CountFields(query_string, "&")
      field = NthField(query_string, "&", x)
      key = NthField(field, "=", 1)
      value = NthField(field, "=", 2)
      value = ReplaceAll(value, "+", " ")
      value = DecodeURLComponent(value)
      query.value(key) = value
    Next
  end if
  

The method creates a new dictionary to hold the values of the query (the data from the form). If the request method is a "Post", then the method grabs the string from standard input. If it is a "Get", then it grabs it from the environment variable "QUERY_STRING". Beyond that, everything else is the same and the string is parsed and the dictionary values are set.

We now have a request object that contains all the needed values from the request, plus the query parsed into a dictionary. Normally, this would be sent to some method that would provide a response based upon the content of the query. For our example, we'll just send back to the client all the information stored in the request object.

To send data back to the client, we need to send some header information followed by an HTML string.

App.request.write
#pragma disableBackgroundTasks
  // simple write method that returns the data in the request.
  dim output as string
  dim html as string
  dim requestString, queryString as string  
  dim x,y as integer 
  
  // set the value for "Content-type", followed by a blank line
  output = "Content-type: text/html" + chr(13) + chr(10) + chr(13) + chr(10)
  
  // create the html string 
  html = "<html><head><title>TestOutput</title></head><body>"
  
  y = me.count
  for x = 0 to y-1
    requestString = requestString + me.key(x) + ": " + me.value(me.key(x)) + "<br />"
  next
  
  y = me.query.count
  for x = 0 to y-1
    queryString = queryString + me.query.key(x) + ": " + me.query.value(me.query.key(x)) + "<br />"
  next
  
  html = html + requestString + queryString + "</body></html>"
  
  output = output + html
  
  print output

If you placed the application in the /Library/WebServer/CGI-Executables directory, and set the application name as "CGI", then you should be able to access the script from the following URL:

Localhost/cgi-bin/CGI/CGI

You should be able to paste it in the browser, hit return, and then get back a list of the variables. If you want to test the query string, then enter a URL like the following:

Localhost/cgi-bin/CGI/CGI?key=value


Figure 3. Results of CGI application.

You now have a good starting point for writing CGI programs in REALbasic for Apache. One thing you'll notice, especially if you have a lot of traffic on your site, is that CGI can be slow at times. The reason for this is that the program has to be started up with each request, which produces a lot of overhead. The downside to RB is that it produces large executable files - about 1.3 MB for this simple CGI program, so the particular solution is best limited to low-traffic sites. Because of this, there have been a variety of CGI workarounds that speed up the process. They way they work is that instead of invoking the program each time it is requested, the program stays resident in memory and handles the requests as they come in. This is usually accomplished with an Apache plug-in. This is an interesting approach that can be used with REALbasic as well - and you don't need to rely on console programming.

I developed an RB application that worked with an Apache plug-in called "mod_scgi". Mod_scgi works by taking the data that Apache would normally send as environment variables to a CGI program, and instead sends it as a block of data over a TCP connection. Using REALbasic's networking abilities, you can create a SocketServer that creates a pool of TCPSockets that listen on the appropriate port, gets the data when it is available, parses it and acts on it just like a CGI program. As soon as the individual socket is done, instead of exiting, it returns to listening on the port for the next request. This creates a huge performance boost, and is a tactic that should be considered if you expect a lot of traffic to your site.

The original (and best) guide to CGI from the inventor's of Mosaic, NCSA:

http://hoohoo.ncsa.uiuc.edu/cgi/


Mark Choate

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Together 3.6.1 - Store and organize all...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Features Smart storage. With simple drag-and-drop... Read more
Cloud 4.1.1 - File sharing from your men...
Cloud is simple file sharing for the Mac. Drag a file from your Mac to the CloudApp icon in the menubar and we take care of the rest. A link to the file will automatically be copied to your clipboard... Read more
OmniFocus 2.7.1 - GTD task manager with...
OmniFocus helps you manage your tasks the way that you want, freeing you to focus your attention on the things that matter to you most. Capturing tasks and ideas is always a keyboard shortcut away in... Read more
CleanApp 5.1.1 - Application deinstaller...
CleanApp is an application deinstaller and archiver.... Your hard drive gets fuller day by day, but do you know why? CleanApp 5 provides you with insights how to reclaim disk space. There are... Read more
ForkLift 3.0 Beta 2 - Powerful file mana...
ForkLift is a powerful file manager and ferociously fast FTP client clothed in a clean and versatile UI that offers the combination of absolute simplicity and raw power expected from a well-executed... Read more
Sublime Text 3126 - Sophisticated text e...
Sublime Text is a sophisticated text editor for code, markup, and prose. You'll love the slick user interface, extraordinary features, and amazing performance. Features Goto Anything. Use Goto... Read more
1Password 6.3.3 - Powerful password mana...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
WhatsApp 0.2.1880 - Desktop client for W...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more
NeoFinder 6.9.3 - Catalog your external...
NeoFinder (formerly CDFinder) rapidly organizes your data, either on external or internal disks, or any other volumes. It catalogs all your data, so you stay in control of your data archive or disk... Read more
Amadeus Pro 2.3.1 - Multitrack sound rec...
Amadeus Pro lets you use your Mac computer for any audio-related task, such as live audio recording, digitizing tapes and records, converting between a variety of sound formats, etc. Thanks to its... Read more

Our 5 Favorite iMessage Sticker Packs
At long last, iMessage joins the ranks of messaging apps the likes of LINE and Whatsapp, adding an impressive collection of stickers. They’re a great way to add a little something extra to your daily conversations. [Read more] | Read more »
How to get past Vulture Island's tr...
Vulture Island is a colorful and quirky mish-mash of platforming and puzzles. It’s creative and fresh, but sometimes the game can throw a curveball at you, leaving you stuck as to how you should progress. These tips will help you explore smoothly... | Read more »
The new Clash of Kings is just for Weste...
If you’ve played the original Clash of Kings, you’ll probably recognise the city building, alliance forging and strategic battles in Clash of Kings: The West. What sets this version apart is that it’s tailor made for a Western audience and the... | Read more »
Frost - Survival card game (Games)
Frost - Survival card game 1.12.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.12.1 (iTunes) Description: *Warning: the game will work on iPhone 5C and above and iPad Pro / 4. Other devices are not supported* | Read more »
How to build and care for your team in D...
Before you hit the trail and become a dog sledding legend, there’s actually a fair bit of prep work to be done. In Dog Sled Saga, you’re not only racing, you’re also building and caring for a team of furry friends. There’s a lot to consider—... | Read more »
How to win every race in Dog Sled Saga
If I had to guess, I’d say Dog Sled Saga is the most adorable racing game on the App Store right now. It’s a dog sled racing sim full of adorable, loyal puppies. Just look at those fluffy little tails wagging. Behind that cute, pixelated facade is... | Read more »
Let the war games commence in Gunship Ba...
Buzz Lightyear famously said, “This isn’t flying, this is falling – with style!” In the case of Gunship Battle: Second War, though, this really is flying - with style! The flight simulator app from Joycity puts you in control of 20 faithfully... | Read more »
How to get a high score in Fired Up
Fired Up is Noodlecake Games’ high score chasing, firefighting adventure. You take control of a wayward firefighter who propels himself up the side of a highrise with blasts of water. Sound silly? It is. It’s also pretty difficult. You can’t... | Read more »
NBA 2K17 (Games)
NBA 2K17 1.0 Device: iOS iPhone Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: Following the record-breaking launch of NBA 2K16, the NBA 2K franchise continues to stake its claim as the most authentic sports video... | Read more »
Dog Sled Saga (Games)
Dog Sled Saga 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: A game by Dan + Lisa As a rookie musher, foster a dogsledding team whose skills will grow if they're treated right. Week by... | Read more »

Price Scanner via MacPrices.net

15-inch 2.2GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 15″ 2.2GHz Retina MacBook Pro (MJLQ2LL/A) on sale for $1799, including free shipping plus NY sales tax only. Amazon also has the 2015 15″ 2.2GHz Retina MacBook Pro (... Read more
Toughbook Celebrates 20 Years of Ruggedized M...
Panasonic System Communications Company of North America, Division of Panasonic Corporation of North America (Panasonic) today celebrates the 20th anniversary of its industry-leading Toughbook mobile... Read more
12-inch 1.1GHz Gray Retina MacBook on sale fo...
B&H Photo has the 2016 12″ 1.1GHz Gray Retina MacBook on sale for $1199.99 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
13-inch 2.5GHz MacBook Pro (Apple refurbished...
Apple has Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros... Read more
Save 30% on Camera Guard’s Secure Protection...
To celebrate the release of macOS Sierra, Miami-based security solutions company, ProtectStar has announced a special 30% discount on Camera Guard Professional for Mac 2016. This innovative security... Read more
DVDFab Special Deal – Get a 1-Year Free Licen...
Beijing, China based specialist in the field of DVD, Blu-ray and video backup solutions, Fengtao Software has launched its Autumn Special Deals 2016, giving a 1-year free license of a randomly picked... Read more
21-inch iMacs on sale for up to $120 off MSRP
B&H Photo has 21″ iMacs on sale for up to $120 off MSRP including free shipping plus NY sales tax only: - 21″ 3.1GHz iMac 4K: $1379 $120 off MSRP - 21″ 2.8GHz iMac: $1199.99 $100 off MSRP - 21″ 1... Read more
13-inch 2.7GHz/256GB Retina MacBook Pro on sa...
Amazon.com has the 13″ 2.7GHz/256GB Retina Apple MacBook Pro on sale for $151 off MSRP including free shipping: - 13″ 2.7GHz/256GB Retina MacBook Pro (sku MF840LL/A): $1348 $151 off MSRP Read more
Apple TVs on sale for up to $50 off MSRP
Best Buy has 32GB and 64GB Apple TVs on sale for $40-$50 off MSRP on their online store. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store... Read more
Apple refurbished 13-inch Retina MacBook Pros...
Apple has Certified Refurbished 13″ Retina MacBook Pros available for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.7GHz... Read more

Jobs Board

Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Sr. *Apple* Mac Engineer - Net2Source Inc....
…staffing, training and technology. We have following position open with our client. Sr. Apple Mac Engineer6+ Months CTH Start date : 19th Sept Travelling Job If Read more
*Apple* Retail - Multiple Positions-Norfolk,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Lead *Apple* Solutions Consultant - Apple (...
# Lead Apple Solutions Consultant Job Number: 51829230 Detroit, Michigan, United States Posted: Sep. 19, 2016 Weekly Hours: 40.00 **Job Summary** The Lead ASC is an Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.