🚀 go-pugleaf

Read Croft's accompanying documentation, and read the Assembler Programmer's
Guide in inside mac for details of argument passing.  In fact, it is
probably necessary to print out a copy of the SUMacC mactrap.s file and look
CAREFULLY at what it does to your arguments.

In fact, much of the confusion can be traced to the fact that Inside Mac was
written from a pascal point of view.  Pascal "protects" the programmer from
details like the fact that ANY structure of size 4 bytes or larger gets passed
as a pointer-to-structure, be it VAR or not.  Atomic data of length 4
(longs, pointers) get passed directly in the stack unless they are VAR.

A far more painful set of problems stems from the fact that the C string
convention - i.e. terminated by '\0' - and the Mac ROM convention - first
byte contains length - are terribly incompatible.  SUMacC strives to isolate
you from the difference by translating strings on-the-fly.  You have available:

	p2cstr (cp)	- translates pascal to C string in place
	c2pstr (cp)	- translates C to pascal string in place
	isapstr (cp)	- marks cp as a string mactrap should NOT try to
			  translate.

The problem is that SUMacC -- at least the beta version, the latest I have --
does not and probably cannot do the whole job, so one winds up looking at
the SUMacC toolbox definitions a lot.  The following, in particular, are
things to watch out for:

	- only one string argument can be translated by mactrap.  Routines like
	  ParamText which take 4 string arguments have to have isapstr() used
	  on at least three of them.  (Has this been corrected?).  In passing,
	  a trick: any ParamText arguments you don't use can be passed as
	  isapstr ("") -- the empty string is the only one common to the two
	  string conventions!

	- any argument mactrap treats as VPS must be passed as a C string, and
	  is always translated on the way back as well.  NumToString is an
	  example.

	- strings passed as part of a larger structure -- e.g. the fName member
	  of the SFReply struct in the Standard File Package -- will always
	  follow the pascal convention.  This is a good example of something
	  SUMacC should not even try to work around.

	- the mac's OSType -- i.e. the 4-character type and creator ID's --
	  should always be passed as a pointer to a C string: mactrap handles
	  these specially, passing the first four chars as a long.

Sorry this got long-winded -- the string convention incompatibility has been
the single most frustrating factor in using SUMacC.  Watch for it.

Finally, I must say that overall I am VERY pleased with the SUMacC environment.
The above comments are not to be taken as criticism of Bill Croft and the
others who took on a difficult task and carried it off VERY well.  Rather,
I want to warn others about a largely-inescapable irritation with trying to
use C for the Mac.  It hasn't stopped me, or driven me to pascal or a Lisa...

=Ned=