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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Logic Pro X 10.1.1 - Music creation and...
Apple Logic Pro X is the most advanced version of Logic ever. Sophisticated new tools for professional songwriting, editing, and mixing are built around a modern interface that's designed to get... Read more
VLC Media Player 2.2.0 - Popular multime...
VLC Media Player is a highly portable multimedia player for various audio and video formats (MPEG-1, MPEG-2, MPEG-4, DivX, MP3, OGG, ...) as well as DVDs, VCDs, and various streaming protocols. It... Read more
Sound Studio 4.7.8 - Robust audio record...
Sound Studio lets you easily record and professionally edit audio on your Mac. Easily rip vinyls and digitize cassette tapes, or record lectures and voice memos. Prepare for live shows with live... Read more
LibreOffice 4.4.1.2 - Free, open-source...
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
Freeway Pro 7.0.3 - Drag-and-drop Web de...
Freeway Pro lets you build websites with speed and precision... without writing a line of code! With its user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of... Read more
Cloud 3.3.0 - File sharing from your men...
Cloud is simple file sharing for the Mac. Drag a file from your Mac to the CloudApp icon in the menubar and we take care of the rest. A link to the file will automatically be copied to your clipboard... Read more
Cyberduck 4.6.5 - 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
Firefox 36.0 - Fast, safe Web browser. (...
Firefox for Mac offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals and... Read more
Thunderbird 31.5.0 - Email client from M...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
VOX 2.4 - Music player that supports man...
VoxIt just sounds better! The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features & support for all audio formats you should ever need... Read more

Get The Whole Story – Lone Wolf Complete...
Get The Whole Story – Lone Wolf Complete is Now Available and On Sale Posted by Jessica Fisher on February 27th, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Who Wore it Best? The Counting Dead vs....
Like it or not, the “clicker” genre, popularized by cute distractions like Candy Box and Cookie Clicker, seems like it’s here to stay. So Who Wore it Best? takes a look at two recent examples: The Counting Dead and AdVenture Capitalist. | Read more »
Card Crawl, the Mini Deck Building Game,...
Card Crawl, the Mini Deck Building Game, is Coming Soon Posted by Jessica Fisher on February 27th, 2015 [ permalink ] Tinytouchtales and Mexer have announced their new game, | Read more »
Witness an all new puzzle mechanic in Bl...
Well, BlastBall MAX is not one of those games and is bucking trends such as timers, elements of randomness, and tacked-on mechanics in favor of pure puzzle gameplay. When you first boot up the game you’ll see a grid made up of squares that are each... | Read more »
This Princess Has a Dragon and She isn’t...
This Princess Has a Dragon and She isn’t Afraid to Useit. | Read more »
Mecha Showdown Review
Mecha Showdown Review By Lee Hamlet on February 27th, 2015 Our Rating: :: IN A SPINUniversal App - Designed for iPhone and iPad Mecha Showdown replaces traditional buttons with a slot machine mechanic in this robot fighting game,... | Read more »
Reliance Games and Dreamworks Unveil Rea...
Reliance Games and Dreamworks Unveil Real Steel Champions Posted by Ellis Spice on February 27th, 2015 [ permalink ] Reliance Games and Dreamworks have announced that a third game in | Read more »
Sum Idea Review
Sum Idea Review By Jennifer Allen on February 27th, 2015 Our Rating: :: TAXING NUMBERSUniversal App - Designed for iPhone and iPad Sum Idea is a fairly charming but taxing puzzle game.   | Read more »
A New Badland Update Brings Daydream Lev...
A New Badland Update Brings Daydream Levels to Co-Op Posted by Ellis Spice on February 27th, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Slashing Demons Review
Slashing Demons Review By Lee Hamlet on February 27th, 2015 Our Rating: :: IT'S A LONG WAY TO THE TOPUniversal App - Designed for iPhone and iPad Slashing Demons lacks the depth or scope to take it beyond the point of being just... | Read more »

Price Scanner via MacPrices.net

Save up to $600 with Apple refurbished Mac Pr...
The Apple Store is offering Apple Certified Refurbished Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more
Updated Mac Price Trackers
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: - 15″ MacBook Pros - 13″ MacBook... Read more
Apple CEO Tim Cook to Deliver 2015 George Was...
Apple CEO Tim Cook will deliver the George Washington University’s Commencement address to GWU grads on May 17, at which time he will also be awarded an honorary doctorate of public service from the... Read more
Apple restocks refurbished Mac minis for up t...
The Apple Store has restocked Apple Certified Refurbished 2014 Mac minis, with models available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz... Read more
Save up to $50 on iPad Air 2s, NY tax only, f...
 B&H Photo has iPad Air 2s on sale for $50 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $469.99 $30 off - 64GB iPad Air 2 WiFi: $549 $50 off - 128GB iPad Air 2... Read more
16GB iPad Air 2 on sale for $447, save $52
Walmart has the 16GB iPad Air 2 WiFi on sale for $446.99 on their online store for a limited time. Choose free shipping or free local store pickup (if available). Sale price for online orders only,... Read more
iMacs on sale for up to $205 off MSRP
B&H Photo has 21″ and 27″ iMacs on sale for up to $205 off MSRP including free shipping plus NY sales tax only: - 21″ 1.4GHz iMac: $1029 $70 off - 21″ 2.7GHz iMac: $1199 $100 off - 21″ 2.9GHz... Read more
Apple Takes 89 Percent Share of Global Smartp...
According to the latest research from Strategy Analytics, global smartphone operating profit reached US$21 billion in Q4 2014. The Android operating system captured a record-low 11 percent global... Read more
New Travel Health App “My Travel Health” iOS...
Rochester, Minnesota based Travel Health and Wellness LLC has announced that its new iOS app help safeguard the user’s health when traveling abroad — “My Travel Health” is now available on the Apple... Read more
Sale! MacBook Airs for up to $115 off MSRP
B&H Photo has MacBook Airs on sale for up to $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 11″ 128GB MacBook Air: $799 100 off MSRP - 11″ 256GB MacBook Air: $999 $100... Read more

Jobs Board

Sr. Technical Services Consultant, *Apple*...
**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional 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
*Apple* Pay - Site Reliability Engineer - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*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
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.