TweetFollow Us on Twitter

CGIs in 4D
Volume Number:12
Issue Number:5
Column Tag:Internet Development

Writing CGI Applications With 4D

Beam your web pages into the 4th DIMENSION

By Mike Cohen, Casper, WY

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

In previous articles [in, for example, MacTech Magazine 11.7, 11.8, 11.9, 11.12, and 12.1 - man], you were shown how WebSTAR or MacHTTP can interface with CGI applications. In this article, I’ll demonstrate how to use this same CGI interface to have your Web server communicate with 4th DIMENSION, using System 7 Pack from ISIS International.

About System 7 Pack

System 7 Pack, from ISIS International, is a 4th DIMENSION external package that lets you send and receive Apple events in your databases. With System 7 Pack, 4D applications can control other applications, such as Microsoft Excel or QuarkXPress, and can be accessed by other local or remote applications. Once it possesses an Apple event handler, your 4D database can act as a CGI application for WebSTAR or MacHTTP.

CGI Applications

If you’ve read previous articles in this series, you probably know the basics of CGI applications, but I’ll review them here. When a Web client requests a file, WebSTAR (or MacHTTP) uses the filename’s suffix to determine how the file should be handled. In most cases, the file will simply be returned to the client. However, for a file type of .cgi or .acgi, the application will be launched, if it isn’t already running, and an Apple event will be sent to it with information passed from the client. After processing that event, the CGI application returns HTML text to WebSTAR.

Using 4D to Write CGI Applications

The first thing you need to do is to put a copy or alias of either 4D itself or a compiled 4D database merged with Runtime into your WebSTAR folder and give it a name ending in .cgi or .acgi. If you use the suffix .acgi, your application will be called asynchronously: WebSTAR won’t wait for an Apple event to complete before sending additional requests. Such an application must be prepared to have multiple outstanding requests, and may need to use semaphores to prevent simultaneous access to global variables or data files.

Install an Apple Event Handler

The first thing your CGI application must do when 4D starts up is to install a handler for the Apple event WebSTAR sends you. The following line of code in our startup procedure will take care of that:

 $Err := HandleAEVT ("WWW ";"sdoc";"CGI Handler")

This System 7 Pack function tells 4D to call the procedure named CGI Handler whenever it receives an Apple event of class 'WWW ' and ID 'sdoc', which is the event that WebSTAR sends to CGI applications. The full startup procedure (see Listing 1) also initializes several global variables that the rest of the application will use.

Since many of our global variables will be used by the Apple event handlers, which run in a separate process, we use interprocess variables identified by a name beginning with the diamond character ( ). The most important variables, ae_headRslt, ae_TextHdr, and ae_PictHdr, contain standard HTTP headers that must be returned along with any data we send back to WebSTAR.

When 4D receives an Apple event, it automatically starts a process called Apple Event Manager, in which all event handler procedures run. With some versions of 4D (most notably 4D Server 1.0.5 and any non-server version earlier than 3.0.5), the first Apple event received is discarded or takes a long time to handle. To avoid these problems, we have our startup procedure send a dummy Apple event to itself.

Listing 1: STARTUP
    ` let’s define a few global variables here
 q:=Char(34)  ` double quote
 nl:="<br>" ` html line break

    ` standard HTML header
 "HTTP/1.0 200 OK"+ crlf+"Server: WebSTAR"+ crlf
  ae_headRslt+"MIME-Version: 1.0"+ crlf
  ae_headRslt+"Content-type: text/html"+ crlf+ crlf
  ae_headRslt+"Content-type:image/gif"+ crlf+ crlf

    ` install our Apple event handlers
$Err:=HandleAEVT ("WWW ";"sdoc";"CGI Handler")

    ` some versions of 4D lose the first Apple event or take unusually long
    ` to process it, so we’ll send ourselves a bogus event to start the
    ` AppleEvent Manager process which will handle all incoming events

Hand Off the Apple Event

Next, you need to write a procedure that will be executed in response to the Apple event. It’s important for this procedure to run as quickly as possible, since each incoming Apple event is queued and dispatched to this single process. A good approach is to simply call AESuspend (a function introduced in System 7 Pack 3.8.3) and pass the event returned from it to another process. For the sake of simplicity, I merely start a new process here, but for better performance, you should start the process when the application starts up, suspend it, and wake it up each time an event comes in.

Listing 2: CGI Handler
$Err := AESuspend ( theEvent; theReply)
New process("CGI Script";32000;"CGI Script Handler")

The function AESuspend makes a copy of the incoming event and reply, and informs the AppleEvent Manager that it shouldn’t (as it normally does) automatically send the reply when the procedure finishes. Note that you must use interprocess variables (indicated by a variable name that begins with ), since the event will later be handled in a separate process.

The New Process command then starts up a separate process called CGI Script Handler that will run the procedure CGI Script to do the actual event handling. Once this procedure finishes, 4D will then be free to receive additional Apple events while the CGI Script Handler process finishes handling the event.

Process the Apple Event

Finally, the function CGI Script (see Listing 3), which will be run in a separate process, finishes handling the request and sends the reply to WebSTAR. The first thing we do is to save the Apple event and reply in process variables, since a new Apple event coming in at this time would modify the interprocess variables. Next, we initialize several variables we use to extract data from the incoming Apple event. We then extract the path argument, sent as the direct object using the System 7 Pack function GetTextParam. The additional arguments sent by WebSTAR, including the method, search, and post arguments, are also extracted by calling GetTextParam. Next, we inspect the various arguments to decide how to handle the request. In this procedure, we handle all POST requests by adding a record to the database.When we receive a GET request, if no PATH argument is given, we simply return a list of all records containing the search string. If the PATH argument begins with rec, we assume the search argument is a record number and return the full record. If the PATH argument begins with pict, we use the search argument as a record number and return a picture field from that record as a GIF image.

Listing 3: CGI Script
evt:= theEvent
rep:= theReply

` assume the reply format will be TEXT
$hdr:= ae_TextHdr

C_TEXT(http_meth) `the method - either “GET” or “POST”
C_TEXT(http_srcha)`the search arguments
C_TEXT(http_post) `the post argument
C_TEXT(http_path) `the path argument
C_TEXT(use_address) `the user issuing this request

$err:=GetTextParam (evt;"----";http_path)
    `extracts the “direct object” parameter of the
    `Apple event which caused this procedure to be launched
    `the “direct” object of an Apple event passed from WebSTAR is the
    `“path” argument

    `get other pieces from this apple event
$err:=GetTextParam (evt;"meth";http_meth)
$err:=GetTextParam (evt;"kfor";http_srcha)
$err:=GetTextParam (evt;"post";http_post)
$err:=GetTextParam (evt;"addr";use_email)

Case of 
 : (http_meth="post")` handle a post request
 $ostr:=DoPost (http_post)
 : ((http_srcha="") & (http_path=""))` all blank
 $ostr:="No search terms were given."+
 "What do I search for?"+ crlf
 : http_path="rec@") ` handle a record # detail request
 $ostr:=GetRecord (http_srcha)
 : (http_path="pict@")  ` handle an image request
 $ostr:=GetImage (http_srcha)
 $hdr:= ae_PictHdr
 : (http_path="")`it’s a simple search
 $ostr:=DoSearch (http_srcha)
 $ostr:="ERROR- The path '"+http_path+
 "' is not supported."+ crlf
End case 

    ` now, send the reply back to WebSTAR for this Apple event
$err:=PutTextParam (rep;"----";$hdr+$ostr)

    ` finish processing this event and send the reply
$err:=AEResume (evt;rep)

Let’s take a closer look at this procedure.

The first two lines copy the event and reply from interprocess variables into process variables, both for convenience and to avoid trouble if they get changed by another process. If you expect to have many incoming events, you should probably use an array into which the Apple event handler pushes values, and use this function to pop them out.

We then use GetTextParam to extract the parameters that WebSTAR passed to the CGI script. The direct object is the path value (the text that follows the $ in your HTML request). The other important values are the method (http_meth, or the 'meth' descriptor in the Apple event), which is either GET or POST, the post argument (http_post, or the 'post' descriptor in the Apple event), which contains the data entered in the form which uses a POST method, and the search argument (http_srcha, or the 'kfor' descriptor in the Apple event), which contains the text that follows the ? in your HTML request.

Next, we use a case to determine what type of request we got and take the appropriate action for it. If we got a POST request, we call the function DoPost, which parses the post arguments and updates the database with the new data. The other requests we handle are: a simple GET request with no path value, in which case we simply do a search and return a list of matching records; a GET request with a path value of REC, for which we return the full details of a record specified by number; and a GET request with a path value of PICT, for which we return a picture field from a record specifed by number. Note that string comparisons are case insensitive and can include 4D’s wildcard character (@).

Finally, we call PutTextParam to place the text to be returned into the reply event, and call the function AEResume, which informs the AppleEvent Manager that we’re finished handling the event that we previously suspended and sends the reply event back to WebSTAR.

Process POST Data

The procedure DoPost handles a POST request. In this case, we simply add a record to the database. Your system should probably check to see if the record already exists before it adds a new record.

The POST arguments, which provide the data to be saved in the record, are sent as a string of field names and values, such as lname=Mike&fname=Cohen&city=Casper&state=WY. Spaces are replaced with plus signs [only for Netscape and Mosaic; other browsers replace spaces with '%20' - jaw], and other special characters are encoded as hexadecimal values. You could write a procedure to parse the string in 4D, but it would be very slow. The easiest way to handle the POST string is to use the Parse Post Args function of Wayne K. Walrath’s excellent Acme Script Widgets OSAX.

AppleScript OSAXen are additions to the AppleScript language that work by installing a system-level event handler. You can call any scripting addition by sending the appropriate Apple event either to your own application or to the system, without having to call AppleScript. In this case, I send an event to the system, since some versions of 4D seem to have problems with re-entrancy when sending an Apple event to themselves.

Listing 4: DoPost
    `create a new record

    `call the parse post args function of Acme Script Widgets
$err:=MakeAddress ("MACS";$system)
$err:=CreateAEVT ("zCGI";"ppar";$system;$aevt)
$err:=PutTextParam ($aevt;"----";$1)
$err:=SendAppleEvent ($aevt;$reply;kAEWaitReply ;-1)
$err:=GetList ($reply;"----";MyArray)

    ` examine the array of fields and values to determine
    ` where to place each piece of data
For ($i;1;Size of array(myArray))
 $err:=GetNthItem (MyArray{$i};1;$aKey;$aType;$theField)
 $err:=GetNthItem (MyArray{$i};2;$aKey;$aType;$theValue)
 Case of 
 : ($theField="fname")
 [Names]First Name:=$theValue
 : ($theField="lname")
 [Names]Last Name:=$theValue
 : ($theField="address")
 [Names]Address 1:=$theValue
 : ($theField="city")
 : ($theField="state")
 : ($theField="zip")
 : ($theField="country")
 : ($theField="email")
 End case 
End for 

    ` clean up everything we allocated
$err:=DisposeDesc ($reply)
$err:=DisposeDesc ($aevt)
$err:=DisposeDesc ($system)

$0:="Record Added."

The first thing we do with this code is to create a new record. Next, we parse the POST arguments passed to our script by calling the ACME Script Widgets OSAX. The function MakeAddress is used to create a target address referring to the system process. We use that target address to create an Apple event of class 'zCGI' and ID 'ppar', which invokes the Parse Post Args function. After we send the event, we extract the array of field name and value pairs it returns.

Next, we examine each name/value pair and use the data to update the record. The array we got back from Parse Post Args consists of a series of sub-arrays containing a field name and value. We inspect each field name and use it to determine which data field the value should be placed into.

After we finish processing the data, we dispose of all the Apple event records and other descriptors we created, to avoid any memory leaks.

Finally, we save and unload the new record. Our procedure returns the text “Record Added”. This will be sent back to WebSTAR and displayed in the browser as an acknowledgement that the form was accepted.

Process SEARCH Data

The procedure DoSearch handles a simple search request by returning a 
formatted list of all records which match the search string.  Each item 
is returned as a URL that will display the entire record if it is clicked. 
 This procedure will be passed the search argument and will use it to 
do a substring search.  If any records match the search string (in this 
case, we use the last name field), they will be returned as a formatted 
list of first and last name.  Clicking one of them in your browser will 
display the full details for that record.
Listing 5: DoSearch
` our search form has a single unnamed field, so we strip off the
` equal sign for the label that precedes the search value
If ($1¾1 ="=")
End if 
SEARCH([Names];[Names]Last Name=$1)
If (Records in selection([Names])=0)
 $reply:="<strong>No matching items.</strong>"
 $reply:="<Title>Search Results</Title>"+
 "<b>Matching items:</b>"+ crlf+"<ul>"+ crlf
 For ($i;1;Records in selection([Names]))
 $fn:=[Names]First Name
 $ln:=[Names]Last Name
 "<li> <A HREF="+ q+"4d.acgi$recno?"+
 String(Record number([Names]))
 $reply:=$reply+ q+">"+$fn+" "+$ln+"</A>"+ crlf
 End for 
 $reply:=$reply+"</ul>  "
End if 

The search result is returned as HTML text. If any matching records are found, we format them as a list. Each item is a clickable link that will send a new request back to our application, which will display the full details of our record. The URLs will look something like this:

 <li><A HREF="4d.acgi$recno?1">Mike Cohen</A>

Retrieving Detailed Records

The next procedure, GetRecord, is called from the main Apple event handler in response to a record number detail request. It takes a record number passed as the search argument, goes directly to that record, and returns a formatted name and address label for that record.

Listing 6: GetRecord
$reply:="<Title>Search Results</Title>"+
 "<STRONG>Client Info:</STRONG><p>"+ crlf
If ([Names]showImage)
 "<img src="+ q+"4d.acgi$pict?"+$1+ q+">"+ crlf
End if 
$reply:=$reply+[Names]First Name+" "+[Names]Last Name+ nl
$reply:=$reply+[Names]Title+ nl+[Names]Company+ nl
$reply:=$reply+[Names]Address 1+ nl+[Names]Address 2+ nl
$reply:=$reply+[Names]City+", "+[Names]State+
 "  "+[Names]Zip+ nl
$reply:=$reply+[Names]Phone 1+ nl+[Names]Phone 2+ nl
If ([Names]Email#"")
 $reply:=$reply+"<A HREF=mailto:"+
 [Names]Email+">"+[Names]Email+"</A>"+ crlf
End if 

This procedure will go directly to the specified record and return the data formatted as HTML text. If an image is present, it will be passed as another ACGI request that will be sent back to our application to display that image. If an email address is available, it will be returned as a clickable mailto URL.

Handling Requests for Images

Images in a 4D database are stored as PICT fields. Since PICT isn’t supported by most Web browsers, we must convert it to GIF format before we return it to WebSTAR. The procedure GetImage will return a PICT field from the specified record as a GIF image to be displayed, using Yves Piguet’s freeware Clip2Gif utility. As in the previous procedure, we use the search string as a record number and go directly to that record.

Listing 7: GetImage
 ` if Clip2Gif isn’t running, launch it now
If (IsRunning ("c2gf")=0)
 $err:=Launch ("c2gf";"")
End if 
 ` send a “save” event to clip2gif to convert PICT to GIF
$err:=MakeAddress ("c2gf";$Clip2Gif)
If ($err=0)
 $err:=CreateAEVT ("core";"save";$Clip2Gif;$aevt)
 If ($err=0)
 $err:=PutPicParam ($aevt;"----";1;[Names]Logo)
 $err:=PutLongParam ($aevt;"fltp";"type";Long ("GIFf"))
 $err:=PutLongParam ($aevt;"kfil";"type";Long ("itxt"))
 $err:=SendAppleEvent ($aevt;$reply;kAEWaitReply ;-2)
 If ($err=0)
 $err:=GetTextParam ($reply;"----";$gifText)
 End if 
 $err:=DisposeDesc ($reply)
 $err:=DisposeDesc ($aevt)
 End if 
 $err:=DisposeDesc ($Clip2Gif)
End if 

Again, let’s review. First, we make sure Clip2Gif is running, and if it isn’t, we launch it. Next, we send a 'save' event with the PICT data and ask to have it returned in GIF format. Clip2GIF has several options for creating GIF images, including transparency and interlacing. (Information about these options and how to access them via Apple events is included with the software.) We then extract the GIF data from the reply and return it as the result of this procedure, to be sent back to WebSTAR.

Sample HTML Forms

Now that we have the code for our CGI application, here are some sample HTML forms that can be used to drive it. The DBSearch.html form (Listing 8) will start a search of the database and return a list of links to matching records.

Listing 8: DBSearch.html
<HEAD><TITLE>Search Database</TITLE></HEAD>
Item to search for:<INPUT name="" TYPE="text" SIZE=32>
(use '@' as a wildcard)
<INPUT TYPE="submit" VALUE="Search">
<INPUT TYPE="reset" VALUE="Cancel">

The DBUpdate.html form (Listing 9) will send a POST request to create a new record in the database.

Listing 9: DBUpdate.html
<HEAD><TITLE>Update Database Entry</TITLE></HEAD>
Name:<INPUT TYPE="text" NAME="fname" SIZE=20>
<INPUT TYPE="text" NAME="lname" SIZE=20><P>
Address:<INPUT TYPE="text" NAME="address" SIZE=40><P>
City:<INPUT TYPE="text" NAME="city" SIZE=15>
State:<INPUT TYPE="text" NAME="state" SIZE=2>
Zip:<INPUT TYPE="text" NAME="zip" SIZE=10><p>
Country:<INPUT TYPE="text" NAME="country" SIZE=15><p>
Email:<INPUT TYPE="text" NAME="email" SIZE=20><p>
<SELECT NAME="System Type">
<OPTION>Macintosh II series
<OPTION>Macintosh Quadra
<OPTION>Powerbook or Duo
<INPUT TYPE="submit" VALUE="Update">
<INPUT TYPE="reset" VALUE="Cancel">


For most Web sites, the most important function of the server is to deliver information to users. If you already have data in a 4D database, you can now easily make this information available directly from your Web pages. You can also develop Web-based front ends to your 4D applications for uses such as kiosks, where the 4D user interface is inappropriate or too complex. Once you get started I am sure that you will find dozens of ways that you can use a 4D CGI application to improve your Web site.


Community Search:
MacTech Search:

Software Updates via MacUpdate

World of Tanks Generals guide - Tips and...
World of Tanks Generals is a brand new card game by the developer behind the World of Tanks shooter franchise. It plays like a cross between chess and your typical card game. You have to keep in consideration where you place your tanks on the board... | Read more »
TruckSimulation 16 guide: How to succeed...
Remember those strangely enjoyable truck missions in Grand Theft Auto V whereit was a disturbing amount of fun to deliver cargo? TruckSimulation 16 is reminiscent of that, and has you play the role of a truck driver who has to deliver various... | Read more »
The best GIF making apps
Animated GIFs have exploded in popularity recently which is likely thanks to a combination of Tumblr, our shorter attention spans, and the simple fact they’re a lot of fun. [Read more] | Read more »
The best remote desktop apps for iOS
We've been sifting through the App Store to find the best ways to do computer tasks on a tablet. That gave us a thought - what if we could just do computer tasks from our tablets? Here's a list of the best remote desktop apps to help you use your... | Read more »
Warhammer 40,000: Freeblade guide - How...
Warhammer 40,000: Freebladejust launched in the App Store and it lets you live your childhood dream of blowing up and slashing a bunch of enemies as a massive, hulking Space Marine. It's not easy being a Space Marine though - and particularly if... | Read more »
Gopogo guide - How to bounce like the be...
Nitrome just launched a new game and, as to be expected, it's a lot of addictive fun. It's called Gopogo, and it challenges you to hoparound a bunch of platforms, avoiding enemies and picking up shiny stuff. It's not easy though - just like the... | Read more »
Sago Mini Superhero (Education)
Sago Mini Superhero 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: KAPOW! Jack the rabbit bursts into the sky as the Sago Mini Superhero! Fly with Jack as he lifts impossible weights,... | Read more »
Star Wars: Galaxy of Heroes guide - How...
Star Wars: Galaxy of Heroes is all about collecting heroes, powering them up, and using them together to defeat your foes. It's pretty straightforward stuff for the most part, but increasing your characters' stats can be a bit confusing because it... | Read more »
The best cooking apps (just in time for...
It’s that time of year again, where you’ll be gathering around the dinner table with your family and a huge feast in front of you. [Read more] | Read more »
Square Rave guide - How to grab those te...
Square Rave is an awesome little music-oriented puzzle game that smacks of games like Lumines, but with its own unique sense of gameplay. To help wrap your head around the game, keep the following tips and tricks in mind. [Read more] | Read more »

Price Scanner via

Sunday roundup of Holiday weekend Mac sales:...
Take up to $500 off MSRP on the price of a new Mac at B&H Photo today as part of their Black Friday/Holiday weekend sale. Shipping is free, and B&H charges NY tax only. These prices are... Read more
Holiday weekend: Apple Watch on sale for $50-...
B&H Photo has the Apple Watch on sale today for $50-$100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - Apple Watch Sport: $50 off - Apple Watch: $50-$100 off Read more
Holiday weekend: iPad Air 2s on sale for up t...
B&H Photo has iPad Air 2s on sale for up to $80 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $459 $40 off - 64GB iPad Air 2 WiFi: $569 $30 off - 128GB iPad Air... Read more
Holiday weekend Mac sales roundup: B&H Ph...
B&H Photo continues to have all new Macs on sale for up to $500 off MSRP as part of their Black Friday/Holiday weekend sale. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina... Read more
iMobie Releases its Ace iOS Cleaner PhoneClea...
iMobie Inc. has announced the new update of PhoneClean 4, its iOS cleaner designed to reclaim wasted space on iPhone/iPad for use and keep the device fast. Alongside, iMobie hosts a 3-day giveaway of... Read more
U.S. Cellular Offering iPad Pro
U.S. Cellular today announced that it is offering the new iPad Pro with Wi-Fi + Cellular, featuring a 12.9-inch Retina display with 5.6 million pixels — the most ever in an iOS device. U.S. Cellular... Read more
Newegg Canada Unveils Black Friday Deals for...
Newegg Canada is offering more than 1,000 deep discounts to Canadian customers this Black Friday, available now through Cyber Monday, with new deals posted throughout the week. “Black Friday is... Read more
Black Friday: Macs on sale for up to $500 off...
BLACK FRIDAY B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their early Black Friday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $... Read more
Black Friday: Up to $125 off iPad Air 2s at B...
BLACK FRIDAY Walmart has the 16GB iPad Air 2 WiFi on sale for $100 off MSRP on their online store. Choose free shipping or free local store pickup (if available): - 16GB iPad Air 2 WiFi: $399, save $... Read more
Black Friday: iPad mini 4s on sale for $100 o...
BLACK FRIDAY Best Buy has iPad mini 4s on sale for $100 off MSRP on their online store for Black Friday. Choose free shipping or free local store pickup (if available): - 16GB iPad mini 4 WiFi: $299.... Read more

Jobs Board

Technical Program Manager, Strategic Merchant...
# Technical Program Manager, Strategic Merchants - Apple Pay Job Number: 44001177 Santa Clara Valley, Califo ia, United States Posted: Oct. 30, 2015 Weekly Hours: 40.00 Read more
Frameworks Engineer, *Apple* Watch - Apple...
# Frameworks Engineer, Apple Watch Job Number: 41403122 Santa Clara Valley, Califo ia, United States Posted: Jul. 1, 2015 Weekly Hours: 40.00 **Job Summary** Join the Read more
Software Engineer - *Apple* Pay - Apple (Un...
# Software Engineer - Apple Pay Job Number: 44003246 Santa Clara Valley, Califo ia, United States Posted: Nov. 16, 2015 Weekly Hours: 40.00 **Job Summary** Apple Pay Read more
Merchant Operations Manager: *Apple* Pay -...
# Merchant Operations Manager: Apple Pay Job Number: 43593822 Santa Clara Valley, Califo ia, United States Posted: Nov. 10, 2015 Weekly Hours: 40.00 **Job Summary** The Read more
Product Design Engineer - *Apple* Watch - A...
# Product Design Engineer - Apple Watch Job Number: 41727161 Santa Clara Valley, Califo ia, United States Posted: Jul. 22, 2015 Weekly Hours: 40.00 **Job Summary** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.