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.]

Abstract

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

Introduction

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:

--3

package QuickDraw is
  -- lengthy sequence of type definitions
 type GrafPtr is ... 
 procedure InitGraf ( thePort : out GrafPtr );
private
 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:

--4

with machine code;

package body QuickDraw is

 procedure InitGraf ( thePort : out GrafPtr ) is
 begin
  -- 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:

--5

        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:

--6

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.
private
 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:

--8

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:

#9

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.ads pkg.adb  
 {ADA}  pkg.ads 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 quickdraw.ads 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:

#10

make -f Makefile > tmp
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.ads 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.

Conclusion

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.

Acknowledgements

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.

Bibliography

•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.

 
AAPL
$118.93
Apple Inc.
-0.07
MSFT
$47.81
Microsoft Corpora
+0.06
GOOG
$541.83
Google Inc.
+1.46

MacTech Search:
Community Search:

Software Updates via MacUpdate

Adobe Photoshop Elements 13.0 - Consumer...
Adobe Photoshop Elements 12--the #1 selling consumer photo editing software--helps you edit pictures with powerful, easy-to-use options and share them via print, the web, Facebook, and more.Version... Read more
Skype 7.2.0.412 - Voice-over-internet ph...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more
HoudahSpot 3.9.6 - Advanced file search...
HoudahSpot is a powerful file search tool built upon MacOS X Spotlight. Spotlight unleashed Create detailed queries to locate the exact file you need Narrow down searches. Zero in on files Save... Read more
RapidWeaver 6.0.3 - Create template-base...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
iPhoto Library Manager 4.1.10 - Manage m...
iPhoto Library Manager lets you organize your photos into multiple iPhoto libraries. Separate your high school and college photos from your latest summer vacation pictures. Or keep some photo... Read more
iExplorer 3.5.1.9 - View and transfer al...
iExplorer is an iPhone browser for Mac lets you view the files on your iOS device. By using a drag and drop interface, you can quickly copy files and folders between your Mac and your iPhone or... Read more
MacUpdate Desktop 6.0.3 - Discover and i...
MacUpdate Desktop 6 brings seamless 1-click installs and version updates to your Mac. With a free MacUpdate account and MacUpdate Desktop 6, Mac users can now install almost any Mac app on macupdate.... Read more
SteerMouse 4.2.2 - Powerful third-party...
SteerMouse is an advanced driver for USB and Bluetooth mice. It also supports Apple Mighty Mouse very well. SteerMouse can assign various functions to buttons that Apple's software does not allow,... Read more
iMazing 1.1 - Complete iOS device manage...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
PopChar X 7.0 - Floating window shows av...
PopChar X helps you get the most out of your font collection. With its crystal-clear interface, PopChar X provides a frustration-free way to access any font's special characters. Expanded... Read more

Latest Forum Discussions

See All

Mystery Case Files: Dire Grove, Sacred G...
Mystery Case Files: Dire Grove, Sacred Grove HD Review By Jennifer Allen on November 28th, 2014 Our Rating: iPad Only App - Designed for the iPad A decent new installment for the popular Mystery Case Files series.   | Read more »
Castaway Paradise – Tips, Tricks, and St...
Ahoy there, castaways: Were you curious about our own thoughts regarding this pristine shipwreck? Check out our Castaway Paradise review! Castaway Paradise is out for iOS, finally giving mobile gamers the opportunity to enjoy the idyllic lifestyle... | Read more »
Castaway Paradise VIP Subs are on Sale f...
Castaway Paradise VIP Subs are on Sale for a Limited Time, and a Special Holiday Update is Coming Soon Posted by Rob Rich on November 28th, 2014 [ | Read more »
Primitive Review
Primitive Review By Jordan Minor on November 28th, 2014 Our Rating: :: FOLK ARTUniversal App - Designed for iPhone and iPad True to its name, Primitive is about as straightforward as runners get.   | Read more »
7 tips to get ahead of the competition i...
7 tips to get ahead of the competition in Dynasty of Dungeons Posted by Simon Reed on November 28th, 2014 [ permalink ] Playcrab has launched their action-packed new dungeon crawler, Dynasty of Dungeons, today. | Read more »
Master of Tea Kung Fu Review
Master of Tea Kung Fu Review By Jordan Minor on November 28th, 2014 Our Rating: :: ONE DROP RULESUniversal App - Designed for iPhone and iPad Master of Tea Kung Fu is a creative and complex caffeinated brawler.   | Read more »
Monster Strike Review
Monster Strike Review By Campbell Bird on November 28th, 2014 Our Rating: :: BILLIARD STRATEGYUniversal App - Designed for iPhone and iPad Collect monsters and battle by flinging them across the battlefield in this strangely... | Read more »
Proun+ Review
Proun+ Review By Jennifer Allen on November 28th, 2014 Our Rating: :: TWITCHY RACINGUniversal App - Designed for iPhone and iPad Twitchy racing aplenty in Proun+, an enjoyably tricky title.   | Read more »
Lucha Amigos (Games)
Lucha Amigos 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Forget Ninja Turtles, and meet Wrestlers Turtles! Crazier, Spicier and…Bouncier! Sling carapaces of 7 Luchadores to knock all... | Read more »
Record of Agarest War Zero (Games)
Record of Agarest War Zero 1.0 Device: iOS Universal Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: HyperDevbox Holiday Turkey Black Friday Special Pricing! To celebrate the opening of the holiday season HyperDevbox... | Read more »

Price Scanner via MacPrices.net

Up To 75% Off Infovole Text Apps Over Black F...
Infovole’s entire range of apps, including the Textkraft family of word processors for iPads and iPhones, is being offered at 50-75% off over the Black Friday and Cyber Monday weekend. The five-day... Read more
Black Friday: Up to $60 off Mac minis, NY tax...
 B&H Photo has new 2014 Mac minis on sale for up to $60 off MSRP as part of their Black Friday sale. Shipping is free, and B&H charges NY sales tax only: - 1.4GHz Mac mini: $449.99 $50 off... Read more
Black Friday: 27-inch 5K iMac for $2299, save...
 B&H Photo continues to offer Black Friday sale prices on the 27″ 3.5GHz 5K iMac, in stock today and on sale for $2299 including free shipping plus NY sales tax only. Their price is $200 off MSRP... Read more
Karalux Announces 24K Gold-Plated iPhone 6
Karalux, a Vietnam-based jewellery firm, has launched a unique 24 karat gold-plated iPhone 6 version with gold-cast monolithic dragon on its back panel. The real 24 karat gold plated enclosure doesn’... Read more
Black Friday: 13-inch 2.6GHz Retina MacBook P...
 B&H Photo has lowered their price for the 13″ 2.6GHz/128GB Retina MacBook Pro to $1159 for Black Friday. That’s $140 off MSRP, and it’s the lowest price for this model (except for Apple’s $1099... Read more
View all the Black Friday sales on our Mac Pr...
We’ve updated our Mac Price Trackers with the latest information on prices, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. View Black Friday sale prices at a... Read more
Black Friday: 11-inch MacBook Air for $779, s...
 Best Buy has lowered their price for the 2014 11″ 1.4GHz/128GB MacBook Air to $779.99 for Black Friday. That’s $120 off MSRP. Choose free shipping or free local store pickup (if available). Sale... Read more
Apple Store Black Friday sale for 2014: $100...
BLACK FRIDAY The Apple Store has posted their Black Friday deals for 2014. Receive a $100 PRODUCT(RED) branded iTunes gift card with the purchase of select Macs, $50 with iPads, and $25 with iPods,... Read more
Black Friday: 15% off iTunes Gift Cards
Staples is offering 15% off $50 and $100 iTunes Gift Cards on their online store as part of their Black Friday sale. Click here for more information. Shipping is free. Best Buy is offering $100... Read more
BEVL Releases Dock Tailored for iPhone 6 and...
Seattle based BEVL has released their first product: an iPhone dock that is divergent in build quality, rock-solid function and visual simplicity to complement the iPhone. BEVL is now accepting... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**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
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Retail - Multiple Positions (US) - A...
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
*Apple* Solutions Consultant (ASC) - Apple (...
**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
*Apple* Solutions Consultant (ASC) - Apple (...
**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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.