IAC Toolkit 2
Volume Number: 7
Issue Number: 8
Column Tag: Tools of the Trade
UserLand's IAC Toolkit 
By Neil Ticktin, Los Angeles, CA
About the author
[Neil is the President of The Truin Group -- a consulting and software
development firm in Los Angeles. He is one of the authors of Extender DialogHandler by
Masters Publishing and has been developing Macintosh software and writing technical
documentation since 1986.]
What is IAC Toolkit?
UserLand’s IAC Toolkit is an Application Program Interface (API) and system
software for adding interapplication communication (IAC) to your application. It is
both System 6 and System 7 compatible. On the surface, IAC Toolkit can be placed in the
same tool category as Apple’s AppleEvents or Microsoft’s Dynamic Data Exchange
(DDE). But, once you look deeper at all three, you will see that IAC Toolkit stands in a
class by itself.
What can IAC Toolkit do for you?
As a developer, you already well know that no program can do everything.
Sometimes, developers strive for this ultimate completeness, but many times they end
up with a bad case of featuritis. The Macintosh helped to prevent this problem with the
advent of the clipboard. It wasn’t necessary to be able to draw a picture in Microsoft
Word because you could create a picture in MacDraw and paste it in to your Word
document.
But, there are many situations that the clipboard does not handle at all or as
well. For example, let’s take the scenario of putting together a mass mailing. The best
tools for writing are obviously word processors. The best tools for keeping data
organized are databases. With IAC, you could have your word processor make a request
to your database and receive back information for the mailing list. With the clipboard,
you would have to make a request in the database, copy the information, paste it into the
word processor and possibly reformat it. Each time you wanted another mailing list
you’d have to go through this process. But, with IAC, you could set up the query once
and watch the applications do all the work.
With this all in mind, you can now think about creating a set of applications that
are each very focused. This way, your applications will avoid the featuritis problem.
By building a suite of applications, you can think about a different type of development
and release schedule. For example, instead of one massive program with a 18 month
development cycle, you can release three different products with a six month
development cycle each. This is a lot easier on your company’s cash flow.
How does it work?
The IAC Toolkit comes with a manual, examples and the necessary files. The files
included are headers, THINK C and MPW libraries, and the UserLand INIT that you will
need for System 6 use. To install the product on a System 6 machine, you simply copy
the UserLand INIT into the System Folder. The header and library files simply need to
be copied to their appropriate place within your compiler environment.
To actually implement IAC code in your message receiving application you would
do the following:
• Add initialization and closing code
• Load up the symbol table with the verbs your application supports
• Add a call to the UserLand event filter
• Implement your “ handleverb” routine
• Implement the verb handlers
• Implement your required-event handlers (open, open document, quit, and print
document)
• Set the MultiFinder attributes of your project
• Add a few UserLand STR# resources to your resources
To implement the message sending code, you would do the following:
• Set up a new verb message
• Push the necessary verb parameters
• Send the verb message by “ending” it.
Let’s take a look at a very simple example that implements the “quit” message.
To test the example, I used the “Noogie” program to send a “quit” message to my tester
application. The tester application was taken from the “Bullseye” example in the
THINK C package.
The first thing I did was to modify Noogie so that it sends the message to Bullseye
instead of UserDex (another UserLand example). To do so, I simply changed the
“idotherprogram” constant in noogie.h from “UDEX” to “BlEy” (the signature I used
for the bullseye example).
Next, I went into the bullseye project and added the “#include “ line and
added some macros and global variables at the top of bullseye.c.
/* 1 */
#include "land.h
#define notoken 0L
#define quitprogramtoken 'quit'
boolean quitNow; /* global flag variable */
Then I added the UserLand IAC Toolkit library to my bullseye project. The toolkit
has initialization and close routines which I placed in the main program. You can also
see the initialization and checking of the “quitNow” variable to enable quiting from a
routine. In addition, there is the initialization of the landglobals structure and the call
to landaddverb. The landglobals structure contains a pointer to the handleverb routine
so that when a verb comes in, that routine is called. The landaddverb call loads up the
symbol table with the information needed for each verb handled.
/* 2 */
main() {
InitMacintosh(); /* bullseye init routine */
if (!landinit()) {
return;
}
landglobals. handleverbroutine = & handleverb;
landaddverb (quitprogramtoken);
SetUpMenus(); /* bullseye init routine */
SetUpWindow(); /* bullseye init routine */
quitNow = false;
for (;quitNow == false;)
HandleEvent(); /* bullseye routine */
landclose();
}
Finally, I created a “ handleverb” routine that actually does the work of each
verb. In this case, we have only one verb -- “quit”. It sets the boolean flag so that the
main program will clean up and exit.
/* 3 */
boolean handleverb (hverb)
hdlverbrecord hverb; {
switch ((**hverb).verbtoken) {
case quitprogramtoken:
SysBeep(4);
SysBeep(4);
SysBeep(4);
quitNow = true;
break;
}
}
That is all there is to being able to receive verbs and handle them via IAC Toolkit.
Now, sending is a bit more difficult, e specially since the manual doesn’t really go into
it, but at least you get a head start with receiving messages which is more important
for initial System 7 compatibility anyway.
The Code
Their code is well written and fairly compact. In fact, the UserLand INIT for
System 6 machines is only 5K. The INIT takes up about 6K in your user’s System heap
plus space for each message as it is transferred. Their main “land.h” header file is a
12K document.
While first working with the code, I did run into a number of slightly annoying
problems. These were caused mostly by changes in THINK C’s interfaces. (Symantec is
making a move to make THINK C code source compatible with MPW C). I found
UserLand’s technical support to be very responsive here, although they almost always
do technical support via call backs.
I did find two other very minor annoyances. First, true, false, and boolean were
declared without the use of a #ifndef and therefore conflicted with other tools I was
using. And, I prefer that routine names be mixed case instead of all lower case to be
more readable, but this is a personal style difference.
All of their demonstration code was thoroughly debugged and commented in the
necessary places. The examples ran without a hitch. UserLand is extremely confident
about their engine for handing IAC. They say that it has had millions of messages sent
through it without a hitch. That confidence comes through in the right places.
Compatibility is the product’s strongest feature. If you write an application
using IAC Toolkit,
• You will be fully compatible with any other IAC Toolkit or AppleEvent program.
• Your users can use IAC on either System 6 or System 7.
• You will be using a fully tested and debugged toolkit.
The Documentation
Fortunately, the only major thing that I do not like about this product is its
documentation. The good news is that the IAC toolkit manual is only about 70 pages long.
In fact, I was able to read it cover to cover in about an hour.
The bad news is that it does not get close enough to the first time IACer. There
are step by step instructions on how to write an application that can receive and handle
IAC verbs, but at times, these steps are unclear. Worse yet, there are no examples in
the manual describing how to send IAC verbs. They are covered in the reference
portion of the manual, but not in a way that is easy to follow. The manual basically says
to see the “Noogie” example to see how this works. And, in fact, Noogie comes with full
C source, but I would like to see something in the documentation to supplement the
example. The documentation reflects UserLand’s belief that it’s much more important
to support IAC servers, not clients.
The manual is small, so finding things is not too bad. Their is an index which is
best used to find where routine declarations are located in the reference. Finally, in all
fairness, while I would like to see a lot more in the manual, it is better than Apple’s
Event Manager documentation.
Pricing
At this time, UserLand IAC Toolkit sells for $395 for the development package.
When you are ready to ship an application, you’ll need to get a 5 year distribution
license from UserLand. “The cost is $4000 for a fully-paid; royalty-free license to
include the Toolkit with as many of your company’s applications as you like.” When
you license the code from UserLand, you will receive the full source for the Toolkit as
soon as you return the non-disclosure agreement.
Now, while some of you may think that $4000 is a lot of money to license a
programming tool, you should think about the amount of time this product will save
your programmers and what their time is worth. For those of you that are working on
low dollar products or shareware, discuss your problem with UserLand, maybe you and
they can come up with a creative solution. UserLand certainly seems open to this idea.
Where is this leading
If you haven’t heard by now, UserLand is not only in the business of producing
IAC Toolkits, but much more importantly, a user scripting system called Frontier.
UserLand Frontier is the first general-purpose user scripting utility for external
control of the Macintosh OS and its applications.
Frontier works with applications even if they don’t use the IAC Toolkit. Frontier
is Apple event-aware and uses the Apple Object Model. When Frontier is used with an
IAC-aware application, it will be as if the application had user scripting built in to it
from the beginning. But better yet, you could easily combine the efforts of multiple
applications in one script.
Frontier is different from utilities such as QuicKeys™ or Tempo™ which record
macros. Frontier is a full programming language with structures and logic. Its
scripting system’s interface is based on an “outline processing metaphor”. This should
be no surprise when you realize that the president of UserLand is Dave Winer, the
creator of ThinkTank and MORE.
UserLand realizes that many of Frontier’s scripting users may not have
programming background. As a result, Frontier has a professional programming
language, based on the syntax of C combined with BASIC’s interactivity. Behind the
scripting system is full blown object database which is a cross between a language
symbol table and a computer filing system. UserLand considers this object database to
be extremely robust and powerful while remaining much more friendly than traditional
programming languages.
In UserLand’s words, “Frontier provides five fundamental benefits:
• It offers a better scripting environment than those provided by individual
programs.
• The user can script applications that never had integrated scripting.
• The user can write scripts that control the file system and operating system.
• The user needs to learn just one language to write scripts for many applications.
• Because Frontier is built around IAC, scripts can be written that integrate the
functions of multiple applications.”
There are those people who say that people should wait for AppleScript, but
remember, we are still waiting to find out what AppleScript is, let alone when it might
ship. Many people believe that shipping dates are probably still years off.
In addition to the Macintosh OS, UserLand is currently exploring the possibility
of extending Frontier (and hopefully IAC Toolkit) to control Microsoft DDE-based
applications. UserLand is also investigating the possibilities of Windows, OS/2, Unix
and PenPoint versions, but has not yet announced any of these.
Frontier will be available in two versions: the complete development system
with scripting and a run-time version that will only be able to execute scripts.
Frontier runtime will be priced at under $200. As of this writing, Frontier is
expected to ship in October, 1991.
The Bottom Line
First and foremost, I strongly recommend this product. Last year, I took the
[very long] time to read about AppleEvents in the pre-release version of Inside
Macintosh, Volume VI. I can honestly tell you that I have no idea what I read. Even with
its limitations, UserLand IAC Toolkit’s manual allowed me to understand the basic
fundamentals of IAC and got me to the point that I could implement them within hours.
Obviously, UserLand has developed IAC Toolkit so that when the time comes for
Frontier to ship, there will be a number of IAC aware products on the market. This goal
has forced them to make IAC as simple as possible. Their toolkit has accomplished this
task.
I’ve seen pre-release versions of Frontier running. It is an exciting product.
From a developer’s point of view, you will want this utility to be able to take full
advantage of your application. The easiest way to accomplish this is to use IAC Toolkit
to implement interapplication communication in every one of your programs.
For those of you out there that are worried about a third party writing an
operating system level utility, you need to hear a few things. First, Apple is interested
in IAC Toolkit working well for developers, perhaps because they did such a poor job of
helping with AppleEvents. In fact, it seems that Apple has given UserLand its
semi-official blessing through an agreement reached in October, 1990 to make
UserLand’s communication protocol fully compatible with Apple’s. Second, there are a
number of companies that have written OS level utilities -- have you ever heard of
Adobe Type Manager™? Next, realize that UserLand has important people involved.
Dave Winer is responsible for the Macintosh’s greatest outliners. In addition, UserLand
has Jean-Louis Gassée on its board of directors. And, although Jean-Louis is no longer
at Apple, he certainly has an idea of where they are going (at least as much as anyone
can).
From a technical point of view, IAC Toolkit is a top notch product, although its
documentation could use some polishing. UserLand’s technical support was both
responsive and accurate.
What more can I tell you? You should be thinking IAC. If you want to have any
time left to develop the rest of your product, you should be thinking UserLand IAC
Toolkit.
For more information, contact:
UserLand Software, Inc.
490 California Avenue
Palo Alto, CA 94306
Voice: 415-325-5700; Fax: 415-325-9829
Retail Price: $395 for the toolkit, $4000 5 yr licensing fee (with full
sources).
Referenced by (2):