TweetFollow Us on Twitter

XCMD ANSI Library
Volume Number:6
Issue Number:6
Column Tag:Programmer's Forum

XCMD ANSI Library

By Gerry H. Kenner, David Burggraaf, Salt Lake City, UT

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

XCMD ANSI Library

[Gerry Kenner is a conservative senior citizen who has been working with computers and writing scientific papers since 1962 when the era first began. David Burggraaf is a newcomer to the field who got his first computer (a Sinclair) in 1980 and hasn’t stopped being excited since. Suffice it to say that most of the ideas and all of the work involved in this project were done by David.]

With their fixed methods of entering, retrieving and manipulating data, code resource packages appear to be the ideal system of object oriented programming. In this case, the object is the code resource. The popularity of this concept is shown by the use of code resources under different names by 4th Dimension™(external objects), Excel™ (DDLs) and Hypercard™ (XCMDs and XFCNs). Further, pioneer systems for using code resources in standalone programs are becoming available, the first example being Serius89™ but other programs are not far behind.

A problem with this type of programming is that the libraries must be replicated whenever they are used in different code resources. Further, when doing code resources at least some compilers link in all functions in a library and not just the ones being used. This is in contrast to the smart linking which occurs when standalone applications are generated. Experience has shown us that the size of most code resources can be reduced by 50% while some can be reduced by as much as 70% or more if the library routines are removed.

This paper reports on a method for installing the libraries and a jump table to access them as a separate code resources and then using a simple series of calls to access them from other code resources (Hypercard XCMDs in this case).

The Project

The project consisted of putting all the library functions in two code resources of type “LIB “ called CodeLib and FCodeLib. Two code resources were used because the dispatch routines for functions which return arguments longer than 32 bits are different from the cases where the return value will fit in register D0. Included in each library is the code of the library functions and a dispatch routine (main()) to provide access to them. The “LIB “ type resources are loaded into Hypercard or stacks using ResEdit.

The .h file

The CodeLib.h file includes the necessary definitions and macros for setting up the libraries in XCMD projects. Included are the list of index variables for each function call (i.e., CLatoi, CLatol, etc.), macro definitions for redefining return parameters and library function call names (#define atoi(str) ((**idispatch) (CLatoi,(char*)(str))), and typedef void (**Vfunch) (CodeLib,...);, etc.) and the macro calls which are added to the XCMD project for incorporating the above material in source code.

Perhaps the best method for understanding the contents of this file is to follow the compilation and execution of the main routine of the XCMD following the addition of the special library code. First of all, the contents of CodeLib.h are read in. In addition to declaring the macros and index variables, this file defines the handles VFunch, IFunch, etc and declares extern global variables of these types (dispatch, idispatch, etc). When executed the macro CODELIB legitimitizes the extern declaration of these variables by declaring them within the XCMD.

LOADCODELIB() is a function which appears as follows when unfolded.

/* 1 */

LOADCODELIB()
if (!initCodeLib())
 return;
else
 HLock(dispatch);
if (!initFCodeLib())
 HUnlock(dispatch);
 return;
else
 HLock(ddispatch);

Its function is to determine whether the libraries are present, get handles to them and then lock the handles so the libraries won’t move. Otherwise it returns with nothing being done. The task of getting the handles is done by initCodeLib() and initFCodeLib. The initCodeLib macro is expanded to show how this is done.

/* 2 */

initCodeLib()
fdispatch = (Ffunch)GetResource(‘LIB ‘, 18000);
pdispatch = (Pfunch)fdispatch;
cdispatch = (Cfunch)pdispatch;
ldispatch = (Lfunch)cdispatch;
idispatch = (Ifunch)ldispatch;
dispatch = (Vfunch)idispatch;

Note that all the handles point to the same address.

With the above code in place, execution of a code line such as

/* 3 */

 TempInt = atoi(TempStr);

will result in the following at compilation time.

/* 4 */

 TempInt = ((**idispatch)(CLatoi, (char*)TempStr)));

When executed, this code will pass the address of idispatch, the value of the index CLatoi and the contents of TempStr to the library code resource.

A Special Case

An exception to the above ease of use are function calls such as sprintf which pass variable numbers of arguments. In these cases, the definitions in the CodeLib.h file serve as templates for inserting the code manually. For instance, the definition of sprintf(s,f) is ((**idispatch)(CLsprintf, (s), (f), ...)). When a statement such as sprintf(TempStr, “Good Day”) is encountered the programmer must replace it manually with ((**idispatch) (CLsprintf, TempStr, “Good Day”) using the definition as a guide.

CodeLibDispatch.c

This file shares the CodeLib.h file except it does not include the NOCODELIB definitions for redefining the library function call names. Addressing the library functions is taken care of by declaring the following code before the main routine is called.

/* 5 */

typedef void (*Function)(void);
FunctionfuncTable[ROUTINES + 1]

where the value of ROUTINES was declared in CodeLib.h. Values are assigned to the funcTable variable within the main routine as follows.

/* 6 */

funcTable[CLdispatchErr]=dispatchErr;
funcTable[CLatoi]=(Function)atoi;
funcTable[CLatol]=(Function)atol;
funcTable[CLsprintf]=(Function)sprintf;
funcTable[CLsrand]=(Function)srand;
funcTable[CLstrcpy]=(Function)strcpy;

It would be nice if these could be declared statically, but we have not been able to figure out a method for doing it.

There are two segments of assembly language code. The first segment replaces the calls RememberA4() and SetUpA4() which are not used because they shift things around on the stack. This code stores the current value of A4 and replaces it with the address of the main routine which is stored in A0 when the code is called. The second assembly language segment is a glue routine for configuring the stack before jumping to the desired library function.

/* 7 */

 asm  {
 move.l (a7)+, returnAddr;/*save return address*/
 move.w (a7)+, a1; /*remove index*/
 lea funcTable, a0;/*do jump to indexed subroutine*/
 jsr ([0,a0,a1.w*4],0);
 move.w a1, -(a7); /*restore stack and return*/
 move.l returnAddr, -(a7);
 move.l oldA4, a4; /*restore a4  */
 }

It removes the return address and saves it before doing a jsr to the requested funcTable entry after which it is put back on the stack. The index value is also removed from the stack, placed in a1 for use as an offset and then replaced on the stack at the end of the call. The last line of code restores the old value of a4.

General

Note that there are six dispatch types although only four are used in this code. The remaining two are for functions which return floats and structures. Further functions can be added to by using the formats given. We have included the code of a sample Hypercard XCMD which uses the libraries or of a Hypercard stack to exercise the XCMD. Other examples are left as an exercise for the reader.

This project is written with THINK C. Similar code would be difficult though possible to implement in Pascal. An important point to note if you are using calls which use floating point arithmetic or call the printf type functions is that the standard ANSI-A4 library does not include floating point functions nor math functions. The math functions are gained by adding math.c to the ANSI-A4 library project. Floating point capabilities are added by opening the ansi-config.h file which is found in the source code of the ANSI-A4 project and commenting out the line #define _NOFLOATING_ and then recompiling the project under a different name such as ANSI-A4(f). Another point to remember is that other functions such as qsort and atof are also not part of the ANSI-A4 project and must be added if they are to be used.

If you have any questions David can be reached on internet at BURGGRAAF @ cc.utah.edu.

Installation Instructions:

1. Install the Library code resource wherever it is needed, i.e., as a code resource in your Hypercard stack.

2. Include the “CodeLib.h” header file before any of the functions in the code library are called.

3. Enter the line

CODELIB;

before any function in the library is called. It must be typed outside of any function. It is a preprocessor declaration of the necessary global variables.

4. If they are not already part of your code put in the instructions RememberA0, SetUpA4 and RestoreA4, so that the above global variables can be used.

5. In the main function, at the beginning type the line.

LOADCODELIB();

This should be the first function call other than functions which setup registers for global variable access. (i.e., SetupA4()).

6. In the main function, at the end enter the line.

UNLOADCODELIB();

7. If present, remove any duplicate libraries which are present in your project.

8. Build the project.

Listing:  CodeLib.h

#ifndef _CODE_LIB_
#define _CODE_LIB_
typedef enum
 {
 CLdispatchErr=0,
 CLatoi,
 CLatol,
 CLsprintf,
 CLsrand,
 CLstrcpy,
 CLsqrt=1 /*Double/struct lib */
 } CodeLib;

#define ROUTINES 5
#define FROUTINES  1

#ifndef NOCODELIBDEF
#define atoi(str) ((**idispatch)(CLatoi,(char *)(str)))
#define atol(str) ((**ldispatch)(CLatol,(char *)(str)))
#define sprintf(s,f) ((**idispatch)(CLsprintf,(s),(f),...))
#define srand(s) ((**dispatch)(CLsrand,(unsigned)(s)))
#define strcpy(s1,s2) ((char *)((**pdispatch)(CLstrcpy,(char*)(s1),(char 
*)(s2))))
#define sqrt(d) ((**ddispatch)(CLsqrt, (double)(d)))
#endif NOCODELIBDEF

typedef void (**Vfunch)(CodeLib,...);
typedef int (**Ifunch)(CodeLib,...);
typedef long (**Lfunch)(CodeLib,...);
typedef char (**Cfunch)(CodeLib,...);
typedef float (**Ffunch)(CodeLib,...);
typedef double (**Dfunch)(CodeLib,...);
typedef void *(**Pfunch)(CodeLib,...);

#define CODELIB Vfunch dispatch;Ifunch idispatch;Lfunch ldispatch;Cfunch 
cdispatch;Ffunch fdispatch;Dfunch ddispatch;Pfunch pdispatch;
#ifndef NOTLLIB
#define initCodeLib() (dispatch=(Vfunch)(idispatch=(Ifunch)(ldispatch=(Lfunch)(cdispatch=( 
Cfunch)(pdispatch=(Pfunch)(fdispatch=(Ffunch)GetResource(‘LIB ‘, 18000)))))))
#else
#define initcodeLib() 1
#endif CODELIB

#ifndef NOFLOATLIB
#define initFCodeLib() (ddispatch=(Dfunch)GetResource(‘LIB ‘, 18001))
#else
#define initFCodeLib() 1
#endif NOFLOATLIB

#define LOADCODELIB() {if (!initCodeLib()) return;else HLock(dispatch);if 
(!initFCodeLib()) {HUnlock(dispatch);return;}else HLock(ddispatch);}
#define UNLOADCODELIB() {HUnlock(dispatch);HUnlock(ddispatch);}

extern Vfunch dispatch;
extern Ifunch idispatch;
extern Lfunch ldispatch;
extern Cfunch cdispatch;
extern Ffunch fdispatch;
extern Dfunch ddispatch;
extern Pfunch pdispatch;
#endif
Listing:  CodeLibDispatch.c

#include <stdio.h>
#include <string.h>
#include <stdlib.h>

#define NOCODELIBDEF
#include “CodeLib.h”

typedef void (*Function)(void);

long returnAddr, oldA4;
int funcIndex;
void dispatchErr(void);
Function funcTable[ROUTINES+1];
 
void main(void)
 { /* CodeLib routine*/
 asm  {
 move.l a4, a1;  /*setup a4 */
 move.l a0, a4;
 move.l a1, oldA4;
 };
 funcTable[CLdispatchErr]=dispatchErr;
 funcTable[CLatoi]=(Function)atoi;
 funcTable[CLatol]=(Function)atol;
 funcTable[CLsprintf]=(Function)sprintf;
 funcTable[CLsrand]=(Function)srand;
 funcTable[CLstrcpy]=(Function)strcpy;
 asm  {
 move.l (a7)+, returnAddr;/*save return address*/
 move.w (a7)+, a1; /*remove index  */
 lea funcTable, a0;/*do jump to indexed subroutine*/
 jsr ([0,a0,a1.w*4],0);
 move.w a1, -(a7); /*restore stack and return*/
 move.l returnAddr, -(a7);
 move.l oldA4, a4; /*restore a4  */
 }
 UnloadA4Seg(0L);
 } /* Main*/

void dispatchErr(void)
 {
 SysBeep(5);
 }
Listing:  FCodeLibDispatch.c

#include <math.h>

#define NOCODELIBDEF
#include “CodeLib.h”

typedef void (*Function)(void);

long returnAddr, oldA4, returnStruct;
int funcIndex;
void dispatchErr(void);
Function funcTable[FROUTINES+1];
 
void main(void)
 { /*CodeLib routine*/
 asm  {
 move.l a4, a1;  /*setup a4 */
 move.l a0, a4;
 move.l a1, oldA4;
 };
 funcTable[CLdispatchErr]=dispatchErr;
 funcTable[CLsqrt]=(Function)sqrt;
 asm  {
 move.l (a7)+, returnAddr;/*save return address*/
 move.l (a7)+, returnStruct;/*save return StructPtr*/
 move.w (a7)+, a1; /*remove index  */
 move.l returnStruct, -(a7);/*put return StructPtr*/
 lea funcTable, a0;/*do jump to indexed subroutine*/
 jsr ([0,a0,a1.w*4],0);
 move.l (a7)+, returnStruct;/*get return structPtr*/
 move.w a1, -(a7); /*restore stack and return*/
 move.l returnStruct, -(a7);
 move.l returnAddr, -(a7);
 move.l oldA4, a4; /*restore a4  */
 }
 UnloadA4Seg(0L);
 } /* Main*/

void dispatchErr(void)
 {
 SysBeep(5);
 }

Listing: testCodeLib.c

#include “CodeLib.h”
#include “HyperXCmd.h”
#include “SetUpA4.h”

CODELIB;

pascal void main(XCmdBlockPtr paramPtr)
{
 int    TempInt1, TempInt2;
 unsigned int  Seed;
 long   TempLong;
 StringHandle  TempHdl;
 double TempDouble1, TempDouble2;
 Ptr    TempPtr;
 Str255 TempStr;
 
 RememberA0();
 SetUpA4();
 LOADCODELIB();
 TempHdl = (StringHandle)NewHandle(256);
 TempPtr = *(paramPtr->params[0]);
 TempInt1 = atoi((char*)TempPtr);
 TempPtr = *(paramPtr->params[1]);
 TempLong = atol((char*)TempPtr);
 TempInt2 = (int)TempLong;
 TempInt1 = TempInt1 * TempInt2;
 TempDouble2 = (double)TempInt1;
 TempDouble1 = sqrt(TempDouble2);
 Seed = (unsigned int)TempDouble1;
 srand(Seed);
 (**idispatch)(CLsprintf,TempStr, “The square root of %d is %.2g.”,
 TempInt1, TempDouble1);
 strcpy(*TempHdl, TempStr);
 paramPtr->returnValue = (Handle)TempHdl;
 
 UNLOADCODELIB();
 RestoreA4();
}

 
AAPL
$97.67
Apple Inc.
+0.64
MSFT
$44.50
Microsoft Corpora
+0.10
GOOG
$589.02
Google Inc.
-4.33

MacTech Search:
Community Search:

Software Updates via MacUpdate

Vienna 3.0.0 RC 2 :be5265e: - RSS and At...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
VLC Media Player 2.1.5 - 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
Default Folder X 4.6.7 - Enhances Open a...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click... Read more
TinkerTool 5.3 - Expanded preference set...
TinkerTool is an application that gives you access to additional preference settings Apple has built into Mac OS X. This allows to activate hidden features in the operating system and in some of the... Read more
Audio Hijack Pro 2.11.0 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more
Intermission 1.1.1 - Pause and rewind li...
Intermission allows you to pause and rewind live audio from any application on your Mac. Intermission will buffer up to 3 hours of audio, allowing users to skip through any assortment of audio... Read more
Autopano Giga 3.6 - Stitch multiple imag...
Autopano Giga allows you to stitch 2, 20, or 2,000 images. Version 3.0 integrates impressive new features that will definitely make you adopt Autopano Pro or Autopano Giga: Choose between 9... Read more
Airfoil 4.8.7 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
Microsoft Remote Desktop 8.0.8 - Connect...
With Microsoft Remote Desktop, you can connect to a remote PC and your work resources from almost anywhere. Experience the power of Windows with RemoteFX in a Remote Desktop client designed to help... Read more
xACT 2.30 - Audio compression toolkit. (...
xACT stands for X Aaudio Compression Toolkit, an application that encodes and decodes FLAC, SHN, Monkey’s Audio, TTA, Wavpack, and Apple Lossless files. It also can encode these formats to MP3, AAC... Read more

Latest Forum Discussions

See All

This Week at 148Apps: July 21-25, 2014
Another Week of Expert App Reviews   At 148Apps, we help you sort through the great ocean of apps to find the ones we think you’ll like and the ones you’ll need. Our top picks become Editor’s Choice, our stamp of approval for apps with that little... | Read more »
Reddme for iPhone - The Reddit Client (...
Reddme for iPhone - The Reddit Client 1.0 Device: iOS iPhone Category: News Price: $.99, Version: 1.0 (iTunes) Description: Reddme for iPhone is an iOS 7-optimized Reddit client that offers a refreshing new way to experience Reddit... | Read more »
Jacob Jones and the Bigfoot Mystery : Ep...
Jacob Jones and the Bigfoot Mystery : Episode 2 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Jacob Jones is back in Episode 2 of one of Apples 'Best of 2013' games and an App Store... | Read more »
New Trailer For Outcast Odyssey, A New K...
New Trailer For Outcast Odyssey, A New Kind of Card Battler Posted by Jennifer Allen on July 25th, 2014 [ permalink ] Out this Fall is a new kind of card battle game: Outcast Odyssey. | Read more »
Hay Day – Tip, Tricks, Strategies, and C...
Recently got into Supercell’s other huge hit, Hay Day and could do with some advice on what to do? We’ve got you covered with some helpful trips and tricks to bear in mind! Ticking Along One of the key things to keep in mind while building up that... | Read more »
Monster Head Review
Monster Head Review By Nadia Oxford on July 25th, 2014 Our Rating: :: FEEDING TIMEUniversal App - Designed for iPhone and iPad Racking up a high score with Monster Head is trickier than it first appears. The appeal wears out fairly... | Read more »
Garfield: Survival of the Fattest Coming...
Garfield: Survival of the Fattest Coming to iOS this Fall Posted by Jennifer Allen on July 25th, 2014 [ permalink ] Who loves lasagna? Me. Also everyone’s favorite grumpy fat cat, Garfield. | Read more »
Happy Flock Review
Happy Flock Review By Andrew Fisher on July 25th, 2014 Our Rating: :: HERD IT ALL BEFOREUniversal App - Designed for iPhone and iPad Underneath the gloss of Happy Flock’s visuals is a game of very little substance. It’s cute, but... | Read more »
Square Register Updates Adds Offline Pay...
Square Register Updates Adds Offline Payments Posted by Ellis Spice on July 25th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Looking For Group – Hearthstone’s Curse...
For the first time since its release (which has thankfully been a much shorter window for iPad players than their PC counterparts), Blizzard’s wildly successful Hearthstone: Heroes of Warcraft CCG is sporting some brand new content: the single... | Read more »

Price Scanner via MacPrices.net

Record Mac Shipments In Q2/14 Confound Analys...
A Seeking Alpha Trefis commentary notes that Apple’s fiscal Q3 2014 results released July 22, beat market predictions on earnings, although revenues were slightly lower than anticipated. Apple’s Mac’... Read more
Intel To Launch Core M Silicon For Use In Not...
Digitimes’ Monica Chen and Joseph Tsai, report that Intel will launch 14nm-based Core M series processors specifically for use in fanless notebook/tablet 2-in-1 models in Q4 2014, with many models to... Read more
Apple’s 2014 Back to School promotion: $100 g...
 Apple’s 2014 Back to School promotion includes a free $100 App Store Gift Card with the purchase of any new Mac (Mac mini excluded), or a $50 Gift Card with the purchase of an iPad or iPhone,... Read more
iMacs on sale for $150 off MSRP, $250 off for...
Best Buy has iMacs on sale for up to $160 off MSRP for a limited time. Choose free home shipping or free instant local store pickup (if available). Prices are valid for online orders only, in-store... Read more
Mac minis on sale for $100 off MSRP, starting...
Best Buy has Mac minis on sale for $100 off MSRP. Choose free shipping or free instant local store pickup. Prices are for online orders only, in-store prices may vary: 2.5GHz Mac mini: $499.99 2.3GHz... Read more
Global Tablet Market Grows 11% in Q2/14 Notwi...
Worldwide tablet sales grew 11.0 percent year over year in the second quarter of 2014, with shipments reaching 49.3 million units according to preliminary data from the International Data Corporation... Read more
New iPhone 6 Models to Have Staggered Release...
Digitimes’ Cage Chao and Steve Shen report that according to unnamed sources in Apple’s upstream iPhone supply chain, the new 5.5-inch iPhone will be released several months later than the new 4.7-... Read more
New iOS App Helps People Feel Good About thei...
Mobile shoppers looking for big savings at their favorite stores can turn to the Goodshop app, a new iOS app with the latest coupons and deals at more than 5,000 online stores. In addition to being a... Read more
Save on 5th generation refurbished iPod touch...
The Apple Store has Apple Certified Refurbished 5th generation iPod touches available starting at $149. Apple’s one-year warranty is included with each model, and shipping is free. Many, but not all... Read more
What Should Apple’s Next MacBook Priority Be;...
Stabley Times’ Phil Moore says that after expanding its iMac lineup with a new low end model, Apple’s next Mac hardware decision will be how it wants to approach expanding its MacBook lineup as well... 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
WW Sales Program Manager, *Apple* Online St...
**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
Lead Software Engineer, *Apple* Online Stor...
**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
Manager, *Apple* Fullfillment Operation (AF...
…cross-functional teams to drive the highest level of program management quality for Apple . You will help plan launch strategy and demand generation programs with Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.