[49G] $EXTPRG documentation
Carsten Dominik
Here is some documentation about the message handler in libraries and
how it can be used. Let me know if you find any mistakes.
- Carsten
The library message handler
===========================
Libraries on the HP49G can contain a message handler. This program is
called by the operating system on various occasions, to give the
library a chance to modify menus, provide online help for its commands
and other actions.
When creating a library from a directory, the reserved variable
$EXTPRG can contain the name of an ID in the directory which will
later become a rompointer in the library. This rompointer must be a
program which accepts a BINT on level one (the message) and, depending
upon the specific message, other arguments on higher stack levels.
The message handler as described here works only from ROM 1.19-6
onwards. Earlier ROMs implemented only part of this functionality.
Menu extensions
---------------
The majority of messages can be used to extend some builtin menus.
Among these are the APPS choose menu, several other choose menus, the
SEARCH, GOTO and Tools submenus in the editor menu etc. When the
message handler is called to extend a menu, the current menu is on the
stack either as a list or as a meta. The program can then modify this
menu and return it. So the stack diagram for menu extensions is
either
( { {"label" action} ...} #msg \-> modified_list #msg ) or
( { "l1" ac1 } ... { "lN" acN } N #meg \-> modified_meta #msg )
The message BINT stays on the stack, so that the message handler of
another library can be called immediately to do its work in the same
way.
The following menus on the HP49G can be extended using library
messages.
#msg Menu Menu Type
------------------------------------------------------------------
BINT0 APPS list
BINT1 Main STAT menu list
BINT2 Hypothesis submenu in STAT list
BINT3 Confidence Interval submenu in STAT menu list
BINT4 Finance menu list
BINT5 Numeric Solver menu list
BINT6 Time menu list
BINT8 Games (in APPS) meta
BINT11 Editor SEARCH menu (when flag -117 is clr) list
BINT12 Editor TOOLS menu (when flag -117 is clr) list
BINT13 Editor GOTO (when flag -117 is clr) list
BINT14 Editor SEARCH menu (when flag -117 is set) meta
BINT15 Editor TOOLS menu (when flag -117 is set) meta
BINT16 Editor GOTO (when flag -117 is set) meta
As an example, we show a message handler of a library with ROMID 1234.
This handler will add the whole library menu to the APPS menu, and a
particular rompointer to the Games menu. When adding to the APPS
menu, the example also makes sure that the new item is numbered just
like the other items in the APPS menu.
::
ZERO OVER#=case
::
SWAPINCOMP (Save #msg (ZERO), explode list)
#1+DUP #.$ (Make index for my entry)
".My Library" !append$ (Add name to index number)
' :: % 1234. InitMenu% ; (action: set my menu)
TWO{}N (Make list from label and action)
SWAP P{}N SWAP (add new entry, get the ZERO back)
;
EIGHT OVER#=case
::
DROP (drop the message)
{ "PlayMe" ROMPTR 4D2 0 } (my new entry for games menu)
SWAP#1+ (add to meta)
EIGHT (need the message also on exit)
;
;
Online Help for library commands
--------------------------------
On the HP49G, all the CAS commands have a short help text which can be
displayed from the catalog, or with the SDIAG command in the Emacs
library. When the catalog choose box highlights a CAS command, the
menu under the choose box has an additional button, the HELP button.
Pressing this button shows the corresponding help text. External
libraries can provide help for their commands in a similar way, using
the message handler and messages NINE and TEN. Message NINE is a
query if the library provides help for a given rompointer. The stack
diagram is
( romptr FALSE NINE \-> romptr TRUE/FALSE NINE )
where the TRUE/FALSE on stack level two indicates if the library is
prepared to provide help for the rompointer level 3. This message is
used to determine if the HELP button in the CATalog should be turned on.
Message TEN is then used to actually display the help when the user
presses the HELP button. The stack diagram here is
( romptr TEN \-> FALSE )
Before pushing FALSE, the message handler should display the help
text.
The following example is a message handler which provides a short help
string for every visible command in the library.
::
NINE #=casedrop
:: DROPTRUE NINE ; (we have help for all rompointers)
TEN #=casedrop
::
DUP DECOMP$ NEWLINE&$ SWAP (save the command name as a string)
ROMPTR># SWAPDROP (get index of rompointer in lib)
{ (list of help strings)
"Help text for romptr 0"
"Help text for romptr 1"
...
"Help text for romptr N" (the last visible rompointer)
}
SWAP#1+ NTHCOMPDROP (extract the correct help string)
&$ (Add the command name)
FALSE SWAP ViewStrObject (display the text)
;
;
Note that ViewStrObject pushes FALSE on the stack, which is the
required return value of message TEN. The message handler gets a bit
more complicated if help is only provided for a few rompointers. Then
the handler of message NINE must check the rompointer against a list,
and message TEN must use Lookup or something similar to extract the
help text. You can use the OT49 library in such cases. Instead of
simply displaying a string, message TEN can also do more complicated
things, like launching a whole application to provide help.
The library menu message
------------------------
If the menu of a library is invoked via the LIBS menu (rightshift 2),
the romid of this library is sent to the message handler of the
library. The library may use this for easter eggs-like stuff (display
an icon (see for example the LIBMAN library), do something funny with
the menu (e.g. LTool) or play a melody. It can also change the menu
settings, for example to provide functionality for the shifted menu
buttons (e.g. ConstTools).
The stack diagram for this message is
( #romid \-> #romid )
The following example is the message handler of a library # 60F and it
temporarily displays a copyright notice when the library menu is
selected.
::
# 60F OVER#=case
::
ZEROZERO
"(c) 2001 Some Author"
$>grob XYGROBDISP
SetDA1Temp
;
;
Peter Geelhoed
> Here is some documentation about the message handler in libraries and
> how it can be used.
Great, this had become somewhat of a FAQ, I trust that with this document all the
"How do I get my library in APPS" questions are history
--
This message was written with 100% recycled electrons
Pivo
Veli-Pekka Nousiainen
news:3BF9042C...@student.tnw.tudelft.nl...
> Carsten Dominik wrote:
>
> > Here is some documentation about the message handler in libraries and
> > how it can be used.
>
> Great, this had become somewhat of a FAQ, I trust that with this document
all the
>
> "How do I get my library in APPS" questions are history
Qs like "How do I get rid of the 23 apps in my menu"
start pouring in.
Use APPSMAN from Wolfgang Rautenberg...
Just my 3_cEuro...
VPN
This message was written with 100% fresh positrons
Jean-Yves Avenard
I wish I did it myself
Jean-Yves
"Carsten Dominik" <dom...@astro.uva.nl> wrote in message
news:qzuu1vr...@sand.science.uva.nl...
Detlef Mueller
>> [..message handler doc..]
>
> Excellent !!
>
> I wish I did it myself
Too late ! But don't worry, there's a _lot_ left for you to document ! ;)
Bye,
Detlef
--
`What a depressingly stupid machine' Detlef Mueller
-- Marvin Detlef[DOT]M[AT]hamburg[DOT]de
http://mein.hamburg.de/homepage/grendel
Wolfgang Rautenberg
> Jean-Yves Avenard wrote
> > I wish I did it myself
> Too late ! But don't worry, there's a _lot_ left for you to document ! ;)
For instance, to complete Carsten's preliminary analysis
of the System Choose Engine FPTR 2 72, applied, e.g., in
LIBman (last version 4.2002 on my site). I took me over a
week of hard work to realize the "dance of choose boxes"
(Carsten Dominik), seen if pressing LBox in LIBman. Why?
Because of lack of information on the involved message
handling of FPTR 2 72, still more involved than $EXTPRG.
LIBman is the first tool able to show HELP on library
commands outside the catalog CAT in a general setting.
- Wolfgang
Carsten Dominik
WR> LIBman is the first tool able to show HELP on library
WR> commands outside the catalog CAT in a general setting.
No, this was SDIAG in Emacs :-)
- Carsten
Wolfgang Rautenberg
> Wolfgang Rautenberg writes:
> WR> LIBman is the first tool able to show HELP on library
> WR> commands outside the catalog CAT in a general setting.
>
> No, this was SDIAG in Emacs :-)
Pardon, Carsten is right. I myself discovered a bug
in Emacs version 1.07 (meanwhile fixed) concerning
HELP, and Carsten a deeply hidden bug in the first
anouncement of LIBman a week ago. Sclerosis :-)
- Wolfgang
Jean-Yves Avenard
"Detlef Mueller" <I_hat...@dont.even.try> wrote in message
news:OZvK7.539$F46.1...@news.uswest.net...
> Too late ! But don't worry, there's a _lot_ left for you to document ! ;)
>
And to spare you all the fun ? Nah, I'm not that mean...
It's all about fun and discoveries...
Jean-Yves
Georg Zotti
> Great, this had become somewhat of a FAQ, I trust that with this document all the
> "How do I get my library in APPS" questions are history
Not all. I still would like to know how to do it with the HPTools, version 3.
Is there an SLOAD line for it?
--
Georg Zotti
e912...@student.tuwien.ac.at
Peter Geelhoed
Georg Zotti schreef:
> Peter Geelhoed <p.f.ge...@student.tnw.tudelft.nl> wrote:
>
> > Great, this had become somewhat of a FAQ, I trust that with this document all the
>
> > "How do I get my library in APPS" questions are history
>
> Not all. I still would like to know how to do it with the HPTools, version 3.
>
> Is there an SLOAD line for it?
I never used SLOAD for the 49, I guess it is mainly a 48 compiler
so there will not be a $extprg command.
If you like I can write a little code that you can run on your 49
to make an $extprg into an already compiled lib.
Let me know.
Thomas Rast
>
> I never used SLOAD for the 49, I guess it is mainly a 48 compiler
> so there will not be a $extprg command.
> If you like I can write a little code that you can run on your 49
> to make an $extprg into an already compiled lib.
Why not use something like
CON(5) #0C5D0 * I hope that's the right one
CON(5) =DOROMP
CON(3) romid
CON(3) command
just after the message table offset. You'd probably have to insert it at
the very beginning of the source.
Thomas
--
Thomas Rast "If you cannot convince them,
t.r...@iname.com confuse them."
ICQ# 103670088 -- Harry S. Truman
Georg Zotti
> Why not use something like
> [...]
> just after the message table offset. You'd probably have to insert it at
> the very beginning of the source.
Ah, so the EXTPRG is defined in an extended library header immediately
after the message table and just references another ROMPTR ?
Thanks, I might try this one and write a script that patches
the MAKEROM results.
--
Georg Zotti
e912...@student.tuwien.ac.at
Georg Zotti
> Georg Zotti schreef:
>> Not all. I still would like to know how to do it with the HPTools, version 3.
>>
>> Is there an SLOAD line for it?
> I never used SLOAD for the 49, I guess it is mainly a 48 compiler
> so there will not be a $extprg command.
It was the old way of development on the PC, and I still use it
for my huge Urania project.
> If you like I can write a little code that you can run on your 49
> to make an $extprg into an already compiled lib.
Hey, this sounds fine! I think more people would like to see that!
But I think I will try to follow Thomas Rast's hint first.
Thanks again!
--
Georg Zotti
e912...@student.tuwien.ac.at
Thomas Rast
>
> Ah, so the EXTPRG is defined in an extended library header immediately
> after the message table and just references another ROMPTR ?
Yes. But it's actually after the *config* offset (I always make the same
mistakes :-/ ). Also, the constant is #0C5D0. So the library structure
must be:
5 =DOLIB
5 size
2 # of characters
.. name
2 # of characters (unless 0)
3 library ID
5 hash table offset
5 message table offset
5 link table offset
5 config object offset
5 #0C5D0
5 =DOROMP
3 romid
3 command number
.. contents
4 CRC
Georg Zotti
> Georg Zotti wrote:
>>
>> Ah, so the EXTPRG is defined in an extended library header immediately
>> after the message table and just references another ROMPTR ?
> Yes. But it's actually after the *config* offset (I always make the same
> mistakes :-/ ). Also, the constant is #0C5D0. So the library structure
> must be:
> ...
Great! Now this last mystery seems solved for me.