XCMD Limitations

[Scott Raney]

On Fri, 25 Oct 2002 <benr_mc at cogapp.com> wrote:

> In the meantime Kevin Miller confirmed that the supported list of callbacks
> is defined as the 1.2 spec, and the magic of google (after I'd searched a
> huge box with 10 years of Apple Developer CDs - apparently I didn't keep
> them going back far enough!) located an old copy of the glue.  I've now
> implemented some headers to switch out the newer calls, recoded the ones
> that were needed, the external is working fine.
> 
> But I'm still confused as to which of the HC callbacks are supported.  The
> 1.2 spec that I found lists 27.  Of these, only 11 are in the MetaCard
> "XCmdGlue.h" - but I know that my external is using at least some of the
> others, eg ZeroToPas.

Right: we didn't put the rest in the MC external API because they're
either standard C library routines, or are only needed by routines
written in Pascal (which the MC external API doesn't support).

>  Perhaps Scott wishes to deprecate the others in
> externals written specifically for MC/Rev - fair enough.  But that still
> leaves anyone with an existing external to modify (possibly to make
> cross-compatible with MC and HC) somewhat in the dark.  So I still think it
> would be nice to
> 
>     a) get a definitive list of the HC compatible callbacks that are
> supported, in addition to the MC-specific ones

As I've stated before, this is the HC 1.2 API, and includes the
conversion routines for Pascal strings and such.  Don't know where
you'd find this list now, given that it's circa 1989 (we have the
original 1.2 HC doc that has it), but here's the list directly out of
the engine source:
xreqSendCardMessage
xreqEvalExpr
xreqStringLength
xreqStringMatch
xreqSendHCMessage
xreqZeroBytes
xreqPasToZero
xreqZeroToPas
xreqStrToLong
xreqStrToNum:
xreqStrToBool
xreqStrToExt
xreqLongToStr
xreqNumToStr
xreqNumToHex
xreqBoolToStr
xreqExtToStr
xreqGetGlobal
xreqSetGlobal
xreqGetFieldByName
xreqGetFieldByNum
xreqGetFieldByID
xreqSetFieldByName
xreqSetFieldByNum
xreqSetFieldByID
xreqStringEqual
xreqReturnToPas
xreqScanToReturn
xreqScanToZero

You can also find this list in the file "HyperXCmd.h" if you can find
that file for HC 1.2 or earlier.  I can only find 2.X versions which
have lots of other stuff that we can't support because it's specific
to the architecture of HyperCard (e.g., external windows, TextEdit
handles, their debugger, etc.)

>     b) if the engine handled an unsupported callback more gracefully.

It does what the API spec specifies, which is to return xresNotImp for
unsupported functions.  Of course you probably won't find too many
externals that handle this correctly given that so few of them were
ever tested with anything other than HC.

> Just as background, since a number of people suggested this shouldn't be
> necessary.  The situation is that we've got a project doing an upgrade to a
> system we created some years ago.  One part that needs modification is a
> HyperCard stack that does a huge data munge every month or so, taking some
> 4-6 hours in total.  I proposed moving this stack into MC (actually Rev)
> first, and the upgrade on that version; on the basis of speed, better
> ongoing support, etc.  The problem is that there is of course a limited
> budget and some outcomes in terms of new functionaliy that have to be
> achieved; and the transition obviously has risk factors.  I therefore
> negotiated a strictly capped budget to attempt the transition; if I can't
> prove that all problems have been solved by the time I've spent that, we're
> just going to stick to making changes to the existing system.  Unfortunately
> because of the lack of information (= my lack of knowledge) about exactly
> what should work in the XFCN, and the fact that when an unsupported call was
> made the entire machine froze, so that the process of investigation was
> incredibly drawn out, I've blown a lot of the budget just getting past this
> particular hurdle.

Debugging externals is a nightmare in the best of cases.  Debugging
where you're intimate with the details of neither the host nor the
external borders on hopeless.  About the only recommendation I have
for working through this is to do your development on OS X where at
least you can answer your email while you're waiting for your classic
box to reboot ;-)
  Regards,
    Scott

> thanks again to all who helped,
> 
>   Ben Rubinstein               |  Email: benr_mc at cogapp.com
>   Cognitive Applications Ltd   |  Phone: +44 (0)1273-821600
>   http://www.cogapp.com        |  Fax  : +44 (0)1273-728866

********************************************************
Scott Raney  raney at metacard.com  http://www.metacard.com
MetaCard: You know, there's an easier way to do that...