TweetFollow Us on Twitter

Writing ACGIs with MacApp

Volume Number: 14 (1998)
Issue Number: 3
Column Tag: Webtech

Writing ACGIs with MacApp

by Klaus Halfmann

It's easy and done fast using the simple class introduced in this article

Introduction

I recently was (and still am) working on a project involving a database to be used on the web. I had a short look at [Develop #29, March 1997] High Performance ACGIs in C by Ken Urquhart, but decided against it, for several reasons.

  • I don't like to leave the familiar environment of MacApp.
  • I want to use C++ not C.
  • It would have been more difficult to dig into new ground than just using MacApp.
  • Performance was not such an issue (and we will see that we still can have reasonable speed).

I thought it would take me about a week to implement the ACGI interface but found that after two days I was ready with a skeleton ACGI. Because MacApp needs more support I decided to publish this article. So, maybe some older MacApp Applications can be found on the web soon.

I use MacApp R12, since R13 was not in a state to be used at the time I started my project. I do not expect major changes in the idea of the implementation, but many details (e.g. streaming) will change. I do not know whether I will migrate our companies project to R13.

You should be familiar with the concept of cgis and ACGIs on the Macintosh in general and with AppleEvent handling in MacApp. If not, you can still use my code, but will have trouble using / modifying some parts of it.

As an example I will show how to build a simple Form where you have three fields of a formula a x b = c. The x can be chosen with a popup out of +, -, * and /.

Building the HTML-Form

Forms can be used with two Methods: Post and Get. The obvious difference is that the parameters are invisible.

Using Get you get the familiar url ".../myacgi.acgi ?operand1=17&operand2=28&operation=+&result=". Using Post the user can not see any arguments, but your ACGI gets them nonetheless. The post method allows larger argument sizes. Also, the arguments are contained in the keyPostArgs otherwise in the keyPathArgs.

My approach allows you to use both ways. Before you start a larger project you should decide which of both to use.

Using PathArgs your ACGI can be used by an url from everywhere, but the visible arguments may confuse the user and tend to become large. An other bad habit is to use passwords in pathArgs. The password is useless (imho) if the user can create a Bookmark containing it.

Using PostArgs your ACGI can only be used by forms. The user sometimes becomes confused because the url stays the same all the time, but the contents changes. The history also may look strange. Anyway, my approach does support both methods. Lets now look at the form: (The form found in the supplied archive is more complex of course.)

<FORM ACTION="myacgi.acgi" METHOD=Get>
  <INPUT NAME="operand1" SIZE=16> 
      <SELECT Name ="operation">
        <OPTION VALUE="+" SELECTED>+
        <OPTION VALUE="-">-
        <OPTION VALUE="*">*
        <OPTION VALUE="/">/
      </SELECT>
    <INPUT NAME="operand2" SIZE=16> </TD>
    <INPUT NAME="result" SIZE=16> </TD>
    <INPUT Name = "Calc" VALUE="Calc" TYPE=submit>
</FORM>

Figure 1. A simple HTML Form.

Build an ACGI with MacApp

MacApp has a class TAppleCommand that descends (surprise) from TCommand and has the two subclasses TServerCommand and TClient command. If you are not familiar with command handling in MacApp it's now time to read the Programmers Guide to MacApp.

In our case TServerCommand is our candidate, since the ACGI is a server for the webserver (which in this case is the client). See, it's easy, the server is the client and ... yes, you got it, fine.

I have written a class TACGICommand that descends from TServerCommand and has a skeleton of routines needed for an ACGI, for parameter parsing and the like. So we go and create a Subclass of TACGICommand: TMyACGICommand. The most important method (as in every other TCommand) is the DoIt() method. You must override it to get your work done.

As a framework I took the Skeleton example out of the examples supplied with MacApp. The archive does contain the complete skeleton code since I had to modify some parts of the code.

MacApp uses a resource based mechanism to dispatch apple events. The resource is the 'aedt' (AppleEventDispatchTable). In order to enhance this table we need another command number first:

  #define cACGICommand  404

We can now define our own aedt resource and can use any number for it since MacApp locates all tables automagically and builds a complete table. (Well numbers below 404 are used by MacApp)

resource 'aedt' (404) 
{  
  { 'WWWQ',         'sdoc',         cACGICommand; }
};

Now we need an object which cares about the command. This is most naturally the application. In order to create our TMyACGICommand we will have to override

TApplication::DoScriptCommand();

(With MacApp R12 this is actually TDispatcherDoScriptCommand() but that is an other story.)

Here is the interesting part of DoScriptCommand:

...
  switch (aCommandNumber)
  { 
    case cACGICommand:
      PostCommand(new TMyACGICommand(this, message, reply);
      break;
    default:
  Inherited::DoScriptCommand(aCommandNumber, message, reply);
...

Some elder MacApp Programmer may wonder what happened to IMyACGICommand. Well, it simply does not exist, since MacApp R13 will eliminate IMethods anyway. I stopped using and implementing them in all my current projects.

The last thing to be done is to introduce the new files to the makefile. If you are using the Metrowerks IDE, add them to the project. I use MPW, and am satisfied doing so.

Doing the Real Work

First lets have a look at our Constructor:

TMyACGICommand::TMyACGICommand(
  TCommandHandler* itsContext,
  TAppleEvent* message, 
  TAppleEvent* reply) :
    TACGICommand(itsContext, message, reply)
{
}

There is nothing special here. As a first approach we will create an empty ::DoIt() method. Now our program should compile and run.

Setting Up The Environment

Meanwhile we should look at our related programs. We need a webserver that supports ACGIs. I use Quid Pro Quo 1.0 (I know there is a newer version out there), but any other Macintosh Web Server should do.

During the development process a special setup is needed. In my archive I have included an alias to my webserver. This should remind you to replace it with an alias to your webserver. On the other side (in your webservers root folder) create an alias to your project folder and in your project folder create an alias to your program named "myacgi.acgi". The webserver will not recognize an ACGI until its extension is ".ACGI".

Figure 2. Setting up the aliases.

Your final setup may be different. As we will later see you will need additional helper or template files which have to be stored (as of this implementation) besides the ACGI. But you may wish to avoid to make them public. So you might use aliases in a final setup, as well.

A browser is needed, too. Keep in mind that people with other browsers and even other operating systems (you know those windows people) look at your site. So make sure that your forms look neat on different browsers.

The ACGI should be ready now, so lets set a breakpoint at the ::DoIt() Method. Look at your url http://yourmac.yourcompany.yourdomain/myacgi/multiply.html and click at the "Calc" button. As we expect we hit our breakpoint, smile happily, and continue our program.

You may find that you did not hit your breakpoint, if so check the following areas:

  • Look with ResEdit if the aedt resource is really there.
  • Set a breakpoint at TDispatcher::DoScriptCommand, maybe your override did not work.

After hitting the breakpoint and telling the application to continue, the browser shouts at us "Document contains no data". Indeed we did nothing to give him any data.

Filling the Empty Method

The building of the ACGI should have taken us about half an hour (if you are familiar with MacApp). Now lets fill our DoIt() method with something reasonable. First we should parse our arguments. The TACGICommands already has an universal weapon for parsing these nasty lines so we call:

  ParseArgs(fArgs, keySearchArgs);  
  // may use keyPostArgs in some other case

fArgs is a Member Variable we have inherited from TACGICommand. It is of type TAssociation. TAssociation is one of the not so well known, all-round classes used internally by MacApp. For example it's used in MacApp MPW-Tools or for the MAParamText/MAReplaceText mechanism. In our case TAssociation is our Swiss army knife to cut our problem.

After the call to ParseArgs fArgs is filled with name / value pairs which can easily be retrieved. If you examine the routine ParseArgs you will find that it in turn calls InsertArg. This method can be overridden, so that your ACGI can intercept some variables.

void TACGICommand::InsertArg(
  TAssociation& argList, 
  TStream* htmlStream, 
  const CPascalStr& argName)

The default implementation parses the stream (the AppleEvent arguments have mutated into a stream) up to the next & (ampersand) and inserts the name / value pair into the argList. You may, for larger data, call ExtractHandle() to extract larger parameters which do not fit into an 255 byte Pascal string.

     Handle  ExtractHandle(TStream* htmlStream);
    // Helper for InsertArg, extract Handle from Stream up to the next & 

Well now that we have the parsing done, lets extract our 3 parameters and the button:

  // Get our operands and such
  CStr255 oper1, oper2, oper, result, message;
  
  if (fArgs.EntryWithKey("\pCalc")   &&  // Did the user press "Calc" ?
    fArgs.ValueAt("\poperand1",oper1) && // Look if we have all
    fArgs.ValueAt("\poperation",oper) && // our fields
    ...

I use EntryWithKey() just to check if the user really pressed Calc, this makes sense as soon as there is more than one button. ValueAt() extracts the parameter out of fArgs and returns if the name was really there. The code after the if statement does the real work and I will skip it here. We create a result and put it back into our AppleEvent reply

CStr255 msg(oper1 + ' ' + oper + ' ' 
            + oper2 + " = " + result);
fReply->PutKeyString(keyDirectObject,msg);

Now lets compile and test it. Maybe there are some pitfalls we have not seen yet.

I made the following mistake: I used KeyAt instead of ValueAt, which works just the other way round but was not what I expected. If you find that you have no arguments at all maybe you should verify that you have got the right mix of Post / Get and keyPostArgs / keySearchArgs.

Figure 3. Result of our first approach.

Output via Template Files

Our ACGI works fine now, but you will not be able to sell this as a final solution since the result page is almost empty, there are among others no back-links. So what about showing the result at the bottom of the original page so that the user can start over with the next calculation? TACGICommand has already a build in mechanism helping you with this work. If you look into the file multiply.html you will find a line

  <!!!!result>

since "<!" starts a HTML comment it will not show up in a browser. But the TACGICommand can parse this sort of comment and replace the entire comment with a match from its second TAssociation: fMarker. Instead of putting the result directly into the reply use

    fMarker.InsertEntry("\presult",msg);
    InsertMarker("\pMultiply.html");

This way we can put any whistles and bells into our HTML-page without affecting our core ACGI. This approach has a flaw I should mention. The parser is not quite intelligent and needs some recovery after an opening "<" character. So <HR><!!!!mydata> will not work since the parser analyses "<HR><!" finds it is no "!!!!" comment and skips both tags. In practice this is not a serious limitation, but a cause of unexpected errors you should be aware of.

Lets look at the result now:

Figure 4. Final appearance of Example.

The error shows us a general problem. What happens if an exception is thrown inside our ACGI? MacApp is polite and shows us a nice alert-box, but our actual user is the user at the other side of the internet. Another problem arises when our ACGI tries to open the dialog. During this time it is blocked and will not react to further requests. So you should always wrap your DoIt() code with a failure-handler and let the real user know what has happened:

  CATCH_ALL  // oops someone has thrown an exception
  {
    CStr15 num;
    CStr255 msg = "\p<B> CGI fatal error ";
    NumToString(fi.error, num);
    msg += num;
    msg += " </B>\n";
    fReply->PutKeyString(keyDirectObject,msg);
    // do not rethrow, we have handled it
  }
  ENDTRY

I think what we did can be done in less than one hour. I spent most of the time doing the actual work (and correcting my misspellings and the like) and had almost no work with ACGI related tasks.

Speed Considerations

MacApp can queue several Commands if needed, so if your DoIt() method is short there should be no problem. If you need some more time you will have to do your work in chunks and use some more sophisticated command handling. This way you can still be responsive if you must. If your webserver does the IP communication mostly asynchronous the webserver and your ACGI can get optimal performance out of the process. As far as I can see "Quid Pro Quo" 1.0 does not use asynchronous IP transfers, but I may be wrong on that.

One not so obvious Speedhole opens in the TACGICommands Constructor:

TACGICommand::TACGICommand(
  TCommandHandler* itsContext,
  TAppleEvent* message, 
  TAppleEvent* reply)
{
  fSuspendTheEvent = true;
  IServerCommand(cACGICommand, itsContext, kCantUndo, 
    kDoesNotCauseChange, NULL, *message, *reply);
  
  fArgs.  IAssociation();
  fMarker.IAssociation();
}

If you look close you will see that the call to IServerCommand makes a copy of the message. This is necessary since we are asynchronous and answer the request at some later time. The original message will vanish and trying to access it will result in the rarely seen error errAEReplyNotArrived (if I'm not wrong on this one). The error message is somewhat misleading since it appears when you try to read the message, not the reply.

If you fear about this problem you can start parsing the command in the constructor and create a different constructor for TACGICommand, this is left as an exercise for the reader.

I use MacApps THandleStream to do all the parsing. This should be no problem for the input side of the ACGI since the arguments are usually small. The output side is more difficult. Here we cannot stream our results directly into the webserver but must pass it back in the apple event. On the other Hand we must be flexible enough to handle output of varying sizes. You can optimize this somewhat by adjusting the resize parameter I use to initialize the THandleStreams, this way you can avoid excessive calls to ResizeHandle.

Do It Yourself

If you really want to use my classes you should try out the following exercises before actually using it, you will get aware of some more pitfalls my approach has:

  1. Go and modify the example in order to reinsert the result into the form instead of displaying it in a separate part of the window. See the problem(s)?
  2. Change the <FORM> and the ACGI to use the Post method.
  3. Create a big text-input field (more than 255 characters) and parse its contents.

Conclusion

I hope I could show you that MacApp is a good foundation for writing ACGIs in a short time. My solution is not perfect but I use it in an actual project and our customer is quite happy (at least with this part of the implementation).


Klaus Halfmann is the leader of software development at the InTeCo GmbH, Hochspeyer (Germany). He has studied computer science at the university of Kaiserslautern and after his diploma has been Programming mostly on Macintosh and MacApp. He worked more than a year at the StarDivison (Hamburg) porting the StarOffice 3.1 to the Macintosh. Now at InTeCo he is working on an autonomous project: DepotChart, a Stock Database program with a lot of numerical stuff and a sophisticated Charting Engine, currently targeted at the German market. If not programming on this project he manages the In-house Network, teaches his colleagues the many aspects of computing, cares about the other projects and chats with customers on the phone. Sometimes, after the working hours he can be found playing AVARA, a real-time TIME 3D Game by Ambrosia, on the Internet.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Ember 1.8.3 - Versatile digital scrapboo...
Ember (formerly LittleSnapper) is your digital scrapbook of things that inspire you: websites, photos, apps or other things. Just drag in images that you want to keep, organize them into relevant... Read more
Apple iTunes 12.1 - Manage your music, m...
Apple iTunes lets you organize and play digital music and video on your computer. It can automatically download new music, app, and book purchases across all your devices and computers. And it's a... Read more
LibreOffice 4.4.3 - Free, open-source of...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
FoldersSynchronizer 4.2.1 - Synchronize...
FoldersSynchronizer is a popular and useful utility that synchronizes and backs-up files, folders, disks and boot disks. On each session you can apply special options like Timers, Multiple Folders,... Read more
Simon 4.0.2 - Monitor changes and crashe...
Simon monitors websites and alerts you of crashes and changes. Select pages to monitor, choose your alert options, and customize your settings. Simon does the rest. Keep a watchful eye on your... Read more
Cocktail 8.1.2 - General maintenance and...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Cyberduck 4.6.4 - FTP and SFTP browser....
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Herald 5.0.2 - Notification plugin for M...
Note: Versions 2.1.3 (for OS X 10.7), 3.0.6 (for OS X 10.8), and 4.0.8 (for OS X 10.9) are no longer supported by the developer. Herald is a notification plugin for Mail.app, Apple's Mac OS X email... Read more
DEVONthink Pro 2.8.3 - Knowledge base, i...
Save 10% with our exclusive coupon code: MACUPDATE10 DEVONthink Pro is your essential assistant for today's world, where almost everything is digital. From shopping receipts to important research... Read more
Boom 2 1.0.1 - System-wide pro audio app...
Boom 2 is a system-wide volume booster and equalizer app that is designed especially for OS X 10.10 Yosemite. It comes with a smart interface, self-calibrates itself according to your Mac, offers... Read more

Playworld Superheroes Review
Playworld Superheroes Review By Tre Lawrence on January 30th, 2015 Our Rating: :: HERO CRAFTINGUniversal App - Designed for iPhone and iPad It’s all about the imagination, fighting bad creatures — and looking good while doing so.   | Read more »
Join the SpongeBob Bubble Party in this...
Join the SpongeBob Bubble Party in this New Match 3 Bubble Poppin’ Frenzy Posted by Jessica Fisher on January 30th, 2015 [ permalink ] | Read more »
Handpick Review
Handpick Review By Jennifer Allen on January 30th, 2015 Our Rating: :: TANTALIZING SUGGESTIONSiPhone App - Designed for the iPhone, compatible with the iPad Handpick will make you hungry, as well as inspire you to cook something... | Read more »
Storm the Halls of Echo Base in First St...
Storm the Halls of Echo Base in First Star Wars: Galactic Defense Event Posted by Jessica Fisher on January 30th, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Contradiction Review
Contradiction Review By Tre Lawrence on January 30th, 2015 Our Rating: :: SPOT THE LIEiPad Only App - Designed for the iPad Contradiction is a live action point and click adventure that’s pretty engaging.   Developer: Tim Follin... | Read more »
Unlock Sunshine Girl in Ironkill with th...
Unlock Sunshine Girl in Ironkill with this special 148Apps code Posted by Rob Rich on January 29th, 2015 [ permalink ] Robo-fighter Ironkill has been out on iOS a | Read more »
Crossroad Zombies Review
Crossroad Zombies Review By Jordan Minor on January 29th, 2015 Our Rating: :: CROSSWALKING DEADiPad Only App - Designed for the iPad Crossroad Zombies is a rough draft of a cool genre mash-up.   | Read more »
Blood Brothers 2 – Tips, Cheats, and Str...
War is hell: Is it the kind of hell you want to check out? Read our Blood Brothers 2 review to find out! Blood Brothers 2, DeNA’s follow-up to the original Blood Brothers, is an intriguing card collecting / role-playing / strategy hybrid. There’s... | Read more »
Blood Brothers 2 Review
Blood Brothers 2 Review By Nadia Oxford on January 29th, 2015 Our Rating: :: AN AGGRAVATING RELATIVEUniversal App - Designed for iPhone and iPad Blood Brothers 2 is built on a simple, solid foundation, but its free-to-play system... | Read more »
I AM BREAD, the Toast of the Town, is Ro...
Have you ever dreamt of being deliciously gluten-y? Do you feel passionate about Rye and Wheat? The guys at Bossa Studios do and that is why they are bringing I AM BREAD to iOS soon. The loafy app will feature all the new content that is being... | Read more »

Price Scanner via MacPrices.net

Intel Aims to Transform Workplace With 5th-Ge...
Intel Corporation today announced the availability of its 5th generation Intel Core vPro processor family that provides cutting-edge features to enable a new and rapidly shifting workplace. To meet... Read more
iOS App Sharalike Introduces New Instant Smar...
Sharalike slideshow and photo management software for iOS, is making it easier than ever to create shareable meaningful moments with its new instant SmartShow technology. Staying organized is a goal... Read more
Apple Becomes World’s Largest Smartphone Vend...
According to the latest research data from Strategy Analytics, as global smartphone shipments grew 31 percent annually to reach a record 380 million units in the fourth quarter of 2014. Apple became... Read more
Cut the Cord: OtterBox Resurgence Power Case...
Dead batteries and broken phones are two of the biggest issues for smartphone users today. Otterbox addresses both with the new Resurgence Power Case for Apple iPhone 6, promising to make those panic... Read more
13-inch Retina MacBook Pros on sale for up to...
B&H Photo has 13″ Retina MacBook Pros on sale for $200 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.6GHz/128GB Retina MacBook Pro: $1199.99 save $100 - 13″ 2.6GHz/... Read more
15-inch 2.5GHz Retina MacBook Pro on sale for...
 B&H Photo has the 15″ 2.5GHz Retina MacBook Pro on sale for $2319.99 including free shipping plus NY sales tax only. Their price is $180 off MSRP, and it’s the lowest price available for this... Read more
Back in stock: Refurbished iPod nanos for $99...
The Apple Store has Apple Certified Refurbished 16GB iPod nanos available for $99 including free shipping and Apple’s standard one-year warranty. That’s $50 off the cost of new nanos. Most colors are... Read more
Apple lowers price on refurbished 256GB MacBo...
The Apple Store has lowered prices on Apple Certified Refurbished 2014 MacBook Airs with 256GB SSDs, now available for up to $200 off the cost of new models. An Apple one-year warranty is included... Read more
New Good Management Suite Simplifies Enterpri...
Good Technology has announced the availability of the Good Management Suite, a comprehensive cross-platform solution for organizations getting started with mobile business initiatives. Built on the... Read more
15-inch 2.0GHz Retina MacBook Pro (refurbishe...
The Apple Store has Apple Certified Refurbished previous-generation 15″ 2.0GHz Retina MacBook Pros available for $1489 including free shipping plus Apple’s standard one-year warranty. Their price is... Read more

Jobs Board

*Apple* Solutions Consultant- Retail Sales (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Event Director, *Apple* Retail Marketing -...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global engagement strategy and team. Delivering an overarching brand Read more
At-Home Chat Specialist- *Apple* Online Stor...
**Job Summary** At Apple , we believe in hard work, a fun environment, and the kind of creativity and innovation that only comes about when talented people from diverse Read more
SW QA Engineer - *Apple* TV - Apple (United...
**Job Summary** The Apple TV team is looking for experienced Quality Assurance Engineers with a passion for delivering first in class home entertainment solutions. **Key Read more
*Apple* Retail - Multiple Positions(US) - Ap...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you re also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.