TweetFollow Us on Twitter

Toolbox from Ada
Volume Number:5
Issue Number:3
Column Tag:Ada Additions

Calling the Mac ToolBox from Ada

By Jerry N. Sweet, Laguna Hills, CA

[Jerry Sweet is a member of the technical staff at Meridian Software Systems, Inc. Meridian is located at 23141 Verdugo Drive, Suite 105, Laguna Hills, CA 92653. Their phone number is (714) 380-9800.]


This report gives an overview of the techniques and tricks needed to write AdaVantage programs that call Macintosh native system facilities, Specifically, how to build "double-clickable" applications with AdaVantage is discussed


Meridian plans to introduce an Ada binding for the Macintosh Toolbox facilities later. This report has been written to help those who who have special system programming needs or who need to create Macintosh Toolbox interfaces immediately. Readers should possess an understanding of how to use the AdaVantage compiler, a reading knowledge of 68000 assembly language, MPW C, and Macintosh Pascal, a familiarity with Inside Macintosh, and an understanding of the whys and wherefores of object code linkage.

Making Calling Conventions Match

The Macintosh AdaVantage compiler uses C calling conventions. The Macintosh operating system uses Pascal calling conventions or specialized (assembly language) calling conventions that are different from the C calling conventions. This means that to write Ada code that interfaces to the Macintosh system facilities, a combination of C code interfaces and machine code insertions must be used.

One might assume that a liberal application of pragma interface is all that is required to gain access to the Toolbox. Unfortunately, that is not the entire story, because many of the Toolbox routines do not exist in object form such that they can be linked with an Ada subprogram. This means that the linker will report unresolved symbols for many or most interface routines, leaving the programmer wondering what object library was omitted in the linkage or wondering what else might have gone wrong.

The solution to this problem is to write one’s own “glue” routines that force the Toolbox routines to become available in a linkable form. Glue routines are so called because they create a bridge (i.e. “glue”) between two typically very different collections of software. This is relatively easy to do with very small C subprograms that may be named in interface pragmas. Alternatively, but not so easily in many cases, machine code insertions may be used.

The most compelling reason for using glue routines written in C is that MPW C provides a ready set of object code libraries and a corresponding set of “include” files ( .h files) that permit C programs to use most of the Macintosh system facilities directly (i.e. a C language Toolbox binding is already defined). However, most of the C function definitions contained in these include files use a Macintosh-specific extension to the C language that generates in-line machine code for the Toolbox A-line traps and at the same time translates the calling conventions automatically from C to Pascal (“Pascal external” definitions). Because these function definitions are bound directly at compile time, rather than at link time, they cannot be referenced by Ada programs. To make these function definitions available to Ada programs via pragma interface , small “wrapper” routines can be written in C that simply call the in-line routines.

Another reason for using glue routines written in C wherever possible as opposed to Ada machine code insertion routines is that one does not then have to figure out the stack offsets of the various subprogram parameters and function results and then write 68000 machine code to push and to pop the parameters.

Consider this example of an in-line C function definition, as defined in the MPW C include file quickdraw.h :

/* 1 */

pascal void InitGraf(globalPtr)

 Ptr globalPtr;
 extern 0xA86E;
/* This definition causes an in-line machine instruction */
/* to be generated at the point of the call to this      */
/* function.  This is conceptually similar to applying   */
/* Ada’s pragma inline to a machine code insertion       */
/* routine.                                              */

and here is an example of the corresponding wrapper routine that one would write in C to make InitGraf accessible to an Ada program:

/* 2 */

#include <quickdraw.h>
void MSS_InitGraf ( globalPtr )
 Ptr globalPtr;
 InitGraf ( globalPtr );
/* This definition causes a subprogram entry to be emitted */
/* to the object file so that MSS InitGraf is accessible   */
/* to an Ada program via pragma interface.                 */

and here an example of the corresponding Ada procedure specification and interface pragma that would appear in a package specification:


package QuickDraw is
  -- lengthy sequence of type definitions
 type GrafPtr is ... 
 procedure InitGraf ( thePort : out GrafPtr );
 pragma interface (c, InitGraf, “MSS_InitGraf”);
end QuickDraw;

If one were to omit the pragma interface and substitute a machine code insertion routine in the package body, it would look something like this:


with machine code;

package body QuickDraw is

 procedure InitGraf ( thePort : out GrafPtr ) is
  -- MOVE.L  8(A6), -(A7) ; push thePort
 machine code.instruction’(val => 16#2F2E#);
 machine code.instruction’(val => 16#0008#);
  -- FCB     0A86EH       ; InitGraf A-line trap
 machine code.instruction’(val => 16#A86E# - 16#1_0000#);
  --           note: the trickiness about subtracting
  --           16#1_0000# is needed because the compiler
  --           requires a signed 16-bit value, and A86E
  --           is greater than ‘last of that range.
  --           The subtraction works because the 
  --           computation is universal.
  -- ADDQ.L   4, A7       ; pop thePort
 machine code.instruction’(val => 16#588F#);
 end InitGraf;

end QuickDraw;

Note that C, machine code, and even Pascal may play somewhat fast and loose with data types. This can present some interesting challenges for Ada application writers who wish to take advantage of Ada’s strong typing capabilities. It is not really very difficult to translate the Toolbox’s Pascal data definitions to Ada, but some care must be exercised to ensure that data containers of the correct sizes are used. For example, Macintosh Pascal’s integer and MPW C’s int types are 16 bits wide, whereas AdaVantage’s integer is 32 bits wide. AdaVantage’s 16-bit integer type is called short_integer. To avoid confusion, it is really best to use explicit range definitions instead:


        type Int8  is -2**7  .. (2**7)  - 1;
        type Int16 is -2**15 .. (2**15) - 1;
        type Int32 is -2**31 .. (2**31) - 1;

Getting the parameter modes right is very important. Because there is no cross-checking in the data type or subprogram definitions between the interface subprogram and its Ada counterpart, it is easy to pass a parameter by value mistakenly when it must be passed by reference, or worse, to pass the wrong parameter type. Pascal var parameters are expressed in Ada as out or in out parameters. It is a little bit harder to tell from the C definition of a subprogram what the proper Ada mode should be. For example, a C struct * parameter is really an Ada record type parameter of mode in, since AdaVantage always passes records by reference.

It should be noted that Ada functions cannot have mode out parameters. Those Macintosh system functions that take Pascal var parameters must be expressed in Ada as procedures with two out parameters. This requires a slightly different method of expressing the glue code. For example, consider the definition of GetNextEvent from Inside Macintosh

FUNCTION GetNextEvent (eventMask: INTEGER;
VAR theEvent: EventRecord ) : BOOLEAN;

This would have to be expressed in Ada as:


package Events is
 procedure GetNextEvent (
 eventMask : in EventID;
 theEvent  : out EventRecord;
 result    : out Boolean
  -- Pascal functions with VAR parameters must be 
 -- expressed as procedures in Ada.
 pragma interface (c, GetNextEvent, “MSS_GetNextEvent”);
end Windows;

The C glue code corresponding to this is:

/* 7 */

#include <events.h>

void MSS_GetNextEvent ( eventMask, theEvent, result )
 short eventMask;
 EventRecord *theEvent;
 Boolean *result;

 *result = GetNextEvent ( eventMask, theEvent );

Compilation and Linkage Issues

To create an application, the steps required for compilation and linkage are:

1. Prior to any compilations, a newlib command is absolutely required in a new folder. This only needs to be done once per each folder in which AdaVantage compilations are to take place. The newlib command creates an AdaVantage program library named ada.lib and an auxiliary directory, :ada.aux: .

2. If other Ada component libraries are required, the appropriate lnlib commands must be applied to link them into the local library. For example, if package Bit from the AdaVantage Utility Library is used, then something like this command must be given:


lnlib  {MeridianAdaRoot}adautil:ada.lib

This command only needs to be given once per library.

3. Ada compilations may be performed either by pulling down the AdaVantage menu and selecting Ada or by typing the ada command. If machine code insertions are used, then the ada -g option should be given if references are made to the frame pointer, A6. In the Ada dialog box, this corresponds to the Use MacsBug button in the More Options dialog. This option ensures that LINK and UNLINK instructions are generated at subprogram entries and exits so that parameters can be referenced via the frame pointer.

Normal rules for Ada compilation ordering hold, as always. However, as a point of possible interest, pragma interface is a substitute for the body of a subprogram. Because pragma interface definitively decouples an Ada subprogram specification from its body, one is in effect permitted to compile the “body” (in C or assembly) before the specification, which would not be permitted in “pure” Ada.

It should be noted that the MPW tools dealing with automatic recompilations, such as CreateMake, do not really provide adequate support for Ada. Makefiles may be created by hand if the order of compilation is known. The targets and dependencies should be either the .atr or .c.o files that result from AdaVantage compilations, as in this example:


AUX = :ada.aux:  
ADA = ada -g  
obj = .c.o  

prog ƒƒ  {AUX}prog{obj}
 bamp -app prog  

prog ƒƒ  prog.r  
 rez prog.r -o prog -append  
 setfile -a B prog  

{AUX}prog{obj} ƒ  {AUX}pkg{obj} prog.ada  
 {ADA}  prog.ada  

{AUX}pkg{obj} ƒ pkg.adb  
 {ADA} pkg.adb

Note: the ƒ symbol is created by holding down the Option key and pressing the f key. Also note: AdaVantage truncates all output file names to eight characters, excluding the extension; for example, the object file corresponding to compilation of and quickdraw.adb is :ada.aux:quickdra.c.o (note the truncated w in quickdraw). Furthermore, it is not always possible to predict what an output file name will be, because if compilation unit names collide in the first eight characters, a file with a name such as aaaaaaaa.c.o may be produced. After hand-compiling a unit, its object file name may be determined with the lslib -l option. The BuildProgram operation (invoked with the command-B key) should not be used with AdaVantage, because it turns on “echo” mode for MPW shell scripts, which causes each line of the ada command, which is implemented as a shell script, to be printed as the line is executed. This slows down compilations considerably. Instead of using BuildProgram, create a two-line shell script called domake that contains these lines:


make -f Makefile > tmp

Running the domake command has the effect of running BuildProgram without echoing each MPW command script line as it executes.

Helpful hint: when continuing a long MPW command line with “” characters (Option-d), select all lines in the continuation before pressing Enter.

4. The C or assembly language subprograms corresponding to Ada interface subprograms may be compiled either before or after their corresponding Ada compilation units, since no information from the C or assembly language compilations is used in Ada compilations; it is only at link time (when bamp is invoked) that the C or assembly language code modules are required.

5. For each Ada package that contains instances of pragma interface, the auglib command must be applied to augment the library entry for the package with the name of the C or assembly language object module containing the implementations of the interface subprograms. This must be done only once, following the first compilation of the package. For example:

ada -g quickdraw.adb
auglib quickdraw quickdrawGlue.c.o
c quickdrawGlue.c

The information attached to the library package is supplied to the object linker when bamp is invoked. To see the augment information associated with a particular library unit, use the lslib -l option.

It is possible to use auglib so that an augmenting code module is linked in whenever any library unit from a particular program library is linked with some Ada program. This is done by specifying the library unit name all with auglib, as in this example:

auglib all MasterGlue.c.o

Again, this only needs to be done once, and then the information is kept permanently, or at least until it is explicitly removed with auglib -r. Refer to the AdaVantage Compiler User’s Guide for additional information about auglib.

Special note: because of a “feature” of bamp, full path names for augmenting object module names should be specified. This is because if a component program library that has been augmented is linked to a program library in another directory, bamp may not be able to find the augumenting code module unless the entire path was specified when the auglib command was given. For example, this is a more appropriate auglib command form to apply:

auglib all ‘directory‘MasterGlue.c.o

The backquoted directory command inserts the path of the current working directory into the command line.

6. To link an application, use the bamp -app option. Without the -app option, the program is linked as an MPW tool, which may not be what is desired.

There are additional bamp options that may be useful to apply to a program to be linked as an application; refer to the AdaVantage Compiler User’s Guide for a list of the available options.

7. All Macintosh files possess two “forks”: a resource fork and a data fork. In the case of the executable file for a Macintosh application program, the resource fork contains CODE resources for the executable code and other kinds of resources for icons, dialog boxes, and so on. A complete treatment of resources and forks is given in Inside Macintosh. To connect resources to an executable application, rez, the resource compiler, may be used. The rez command may be invoked even prior to running bamp. The ada and bamp commands only affect a file’s CODE resources, while rez affects all others. Non-CODE resource descriptions are typically kept in a file whose extension is .r.

Note that misapplying rez could result in strangely behaving or unuseable applications. If a problem with a program’s resources occurs, it is best to delete the entire executable program file and then relink with bamp and re-rez with rez.

The default MPW application icon (hand writing in diamond) applies unless one supplies a custom icon resource of resource type ICN#. Resources may be customized with the resedit program, for example to modify icons, without recompiling with ada or relinking with bamp. However, if an icon is changed, the desktop must be “rebuilt” to put the change into effect. Rebuilding the desktop resets the Finder’s otherwise permanent records of file attributes so that icon resource changes are made visible. To rebuild the desktop, hold down the command and option keys as one reboots (when pulling down Restart in the Special menu)

8. To mark an executable program file as a Macintosh application, the “bundle” file attribute must be set. This is done with the setfile command, as in this example:

 setfile -a B sample

Note that the “B” above must be a capital B.

Setting the file type to APPL is not sufficient to identify an executable program file as a Macintosh application; the bundle attribute must be used if non- CODE resources are supplied with an application.

It is possible to create an application by using bamp -app without associating additional resources with the program or setting the bundle attribute, if Text_IO is used to interact with the user. The style of interaction that is then used is not typical of Macintosh applications, however.


By following the recommendations given in this report, “double-clickable” Macintosh application programs can be written in Ada. Although at present, a bit more effort is required to create an Ada application than is required to create a Pascal or C application, the introduction of the Ada Toolbox binding later in 1988 should ameliorate that.


This report was developed originally for a seminar on Macintosh Ada given October 9, 1988 by Edward V. Berard, President of EVB Software Engineering, Inc. At the time that this report was being written, Mr. Berard contributed a list of discussion points and some key definitions.


•Inside Macintosh, Addison-Wesley, 1985.

• Macintosh Technical Notes #164 and #166, Apple Computer, Inc., 1987.

• MPW 2.0.2 Reference Manual, Apple Computer, Inc., 1987.

• MPW C 2.0.2 Reference Manual, Apple Computer, Inc., 1987.

• Reference Manual for the Ada Programming Language (ANSI/MIL-STD-1815A-1983), United States Department of Defense, 1983.

• Meridian AdaVantage Compiler User’s Guide, Meridian Software Systems, Inc., 1988.

• AdaVantage Product Release Notes, Meridian Software Systems, Inc., 1988.

• The C Programming Language, Kernighan & Ritchie, Prentice-Hall, 1978.


Community Search:
MacTech Search:

Software Updates via MacUpdate

Microsoft Office 2016 16.11 - Popular pr...
Microsoft Office 2016 - Unmistakably Office, designed for Mac. The new versions of Word, Excel, PowerPoint, Outlook, and OneNote provide the best of both worlds for Mac users - the familiar Office... Read more
Adobe Photoshop CC 2018 19.1.2 - Profess...
Photoshop CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Photoshop customer). Adobe Photoshop CC 2018, the industry standard... Read more
Adobe Dreamweaver CC 2018 -...
Dreamweaver CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Dreamweaver customer). Adobe Dreamweaver CC 2018 allows you to... Read more
Adobe Flash Player - Plug-in...
Adobe Flash Player is a cross-platform, browser-based application runtime that provides uncompromised viewing of expressive applications, content, and videos across browsers and operating systems.... Read more
Drive Genius 5.2.0 - $79.00
Drive Genius features a comprehensive Malware Scan. Automate your malware protection. Protect your investment from any threat. The Malware Scan is part of the automated DrivePulse utility. DrivePulse... Read more
MegaSeg 6.0.6 - Professional DJ and radi...
MegaSeg is a complete solution for pro audio/video DJ mixing, radio automation, and music scheduling with rock-solid performance and an easy-to-use design. Mix with visual waveforms and Magic... Read more
ffWorks 1.0.7 - Convert multimedia files...
ffWorks (was iFFmpeg), focused on simplicity, brings a fresh approach to the use of FFmpeg, allowing you to create ultra-high-quality movies without the need to write a single line of code on the... Read more
Dash 4.1.5 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
Evernote 7.0.3 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
jAlbum Pro 15.3 - Organize your digital...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. You can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly... Read more

Latest Forum Discussions

See All

All the best games on sale for iPhone an...
It might not have been the greatest week for new releases on the App Store, but don't let that get you down, because there are some truly incredible games on sale for iPhone and iPad right now. Seriously, you could buy anything on this list and I... | Read more »
Everything You Need to Know About The Fo...
In just over a week, Epic Games has made a flurry of announcements. First, they revealed that Fortnite—their ultra-popular PUBG competitor—is coming to mobile. This was followed by brief sign-up period for interested beta testers before sending out... | Read more »
The best games that came out for iPhone...
It's not been the best week for games on the App Store. There are a few decent ones here and there, but nothing that's really going to make you throw down what you're doing and run to the nearest WiFi hotspot in order to download it. That's not to... | Read more »
Death Coming (Games)
Death Coming Device: iOS Universal Category: Games Price: $1.99, Version: (iTunes) Description: --- Background Story ---You Died. Pure and simple, but death was not the end. You have become an agent of Death: a... | Read more »
Hints, tips, and tricks for Empires and...
Empires and Puzzles is a slick match-stuff RPG that mixes in a bunch of city-building aspects to keep things fresh. And it's currently the Game of the Day over on the App Store. So, if you're picking it up for the first time today, we thought it'd... | Read more »
What You Need to Know About Sam Barlow’s...
Sam Barlow’s follow up to Her Story is #WarGames, an interactive video series that reimagines the 1983 film WarGames in a more present day context. It’s not exactly a game, but it’s definitely still interesting. Here are the top things you should... | Read more »
Pixel Plex Guide - How to Build Better T...
Pixel Plex is the latest city builder that has come to the App Store, and it takes a pretty different tact than the ones that came before it. Instead of being in charge of your own city by yourself, you have to work together with other players to... | Read more »
Fortnite Will Be Better Than PUBG on Mob...
Before last week, if you asked me which game I prefer between Fortnite Battle Royale and PlayerUnknown’s Battlegrounds (PUBG), I’d choose the latter just about 100% of the time. Now that we know that both games are primed to hit our mobile screens... | Read more »
Siege of Dragonspear (Games)
Siege of Dragonspear 2.5.12 Device: iOS Universal Category: Games Price: $9.99, Version: 2.5.12 (iTunes) Description: Experience the Siege of Dragonspear, an epic Baldur’s Gate tale, filled with with intrigue, magic, and monsters.... | Read more »
7 Wonders Guide - Should You Buy The Lea...
The fantastic mobile version of 7 Wonders just got updated with an expansion that adds Leaders to the game. This new content adds a whole layer of depth to the game, but before you spend $1.99 to buy it blindly, check out this breakdown of exactly... | Read more »

Price Scanner via

B&H drops prices on 15″ MacBook Pros up t...
B&H Photo has dropped prices on new 2017 15″ MacBook Pros, now up to $300 off MSRP and matching Adorama’s price drop yesterday. Shipping is free, and B&H charges sales tax for NY & NJ... Read more
Apple restocks Certified Refurbished 2017 13″...
Apple has restocked Certified Refurbished 2017 13″ 2.3GHz MacBook Pros for $200-$230 off MSRP. A standard Apple one-year warranty is included with each MacBook, models receive new outer cases, and... Read more
13″ Space Gray Touch Bar MacBook Pros on sale...
Adorama has new 2017 13″ Space Gray Touch Bar MacBook Pros on sale for $150 off MSRP. Shipping is free, and Adorama charges sales tax in NY & NJ only: – 13″ 3.1GHz/256GB Space Gray MacBook Pro (... Read more
Best deal of the year on 15″ Apple MacBook Pr...
Adorama has New 2017 15″ MacBook Pros on sale for up to $300 off MSRP. Shipping is free, and Adorama charges sales tax in NJ and NY only: – 15″ 2.8GHz Touch Bar MacBook Pro Space Gray (MPTR2LL/A): $... Read more
Save $100-$150+ on 13″ Touch Bar MacBook Pros...
B&H Photo has 13″ Touch Bar MacBook Pros on sale for $100-$150 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13″ 3.1GHz/256GB Space Gray MacBook Pro... Read more
Current deals on 27″ Apple iMacs, models up t...
B&H Photo has 27″ iMacs on sale for up to $150 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 27″ 3.8GHz iMac (MNED2LL/A): $2149 $150 off MSRP – 27″ 3... Read more
Thursday Deal: 13″ 2.3GHz MacBook Pro for $11...
B&H Photo has the 13″ 2.3GHz/128GB Space Gray MacBook Pro on sale for $100 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13-inch 2.3GHz/128GB Space... Read more
How to save $100-$190 on 10″ & 12″ iPad P...
Apple is now offering Certified Refurbished 2017 10″ and 12″ iPad Pros for $100-$190 off MSRP, depending on the model. An Apple one-year warranty is included with each model, and shipping is free: –... Read more
Silver 12″ 1.3GHz MacBook on sale at B&H...
B&H Photo has the 2017 12″ 1.3GHz Silver MacBook on sale for $1399.99 including free shipping plus sales tax for NY & NJ residents only. Their price is $200 off MSRP, and it’s the lowest... Read more
Amazon offers 21″ Apple iMacs for up to $150...
Amazon 21″ iMacs on sale today for $50-$150 off MSRP, depending on the model. Shipping is free: – 21″ 3.4GHz 4K iMac (MNE02LL/A): $1349.99 $150 off MSRP – 21″ 3.0GHz iMac (MNDY2LL/A): $1199 $100 off... Read more

Jobs Board

Data Scientist, *Apple* Ecosystem (AMP Anal...
# Data Scientist, Apple Ecosystem (AMP Analytics) Job Number: 113428728 Santa Clara Valley, California, United States Posted: 24-Jan-2018 Weekly Hours: 40.00 **Job Read more
*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 113523441 Orange, CA, California, United States Posted: 21-Feb-2018 Weekly Hours: 40.00 **Job Summary** Are you passionate Read more
*Apple* Professional Learning Specialist - A...
# Apple Professional Learning Specialist Job Number: 113456892 Englewood, NJ, New Jersey, United States Posted: 02-Feb-2018 Weekly Hours: 40.00 **Job Summary** The Read more
*Apple* Retail Online, Senior Financial Anal...
# Apple Retail Online, Senior Financial Analyst Job Number: 57228835 Santa Clara Valley, California, United States Posted: 12-Feb-2018 Weekly Hours: 40.00 **Job Read more
Site Reliability Engineer, *Apple* Pay - Ap...
# Site Reliability Engineer, Apple Pay Job Number: 113356036 Santa Clara Valley, California, United States Posted: 12-Jan-2018 Weekly Hours: 40.00 **Job Summary** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.