HP48 Libraries
Dan Vacca
the Programmer's Reference Guide - but I still don't fully understand HP48
Libraries. I've seen many postings asking for info, but few postings
actually describing libraries in any detail. Perhaps, they should be
described in FAQ.
Anyway, I had someone put tetris on my calculator :-) and unfortunately I
didn't watch how he did it. My questions:
1. What exactly is a library (a particular area of memory containing a
program, which is refenced by the library address?).
2. How does one create a library?
3. How does one get an existing library onto the stack (in a useable
format for transfer to another HP48)?
4. What are the advantages of using a library?
5. Why is there so little documentation on libraries?
I have figured out how to ATTACH, DETACH, PURGE libraries from the
postings on this user group, but that's all so far. I hope this posting is
appropriate and apologize if it isn't.
Dan Vacca
--------------------------------------------------------
Department of Physics
University of Waterloo, Canada
dva...@physics.watstar.uwaterloo.ca
--------------------------------------------------------
Alex Ramos
: Anyway, I had someone put tetris on my calculator :-) and unfortunately I
: didn't watch how he did it. My questions:
: 1. What exactly is a library (a particular area of memory containing a
: program, which is refenced by the library address?).
A library is a collection of objects that can be acessed much faster
than a directory, because the objects are fixed. (sorry, this is a
poor explanation). Sort of a frozen directory, one might say (?).
: 2. How does one create a library?
With my RPL#+ Package. one only needs to specify "xROMID" at the top of
the source code, and then "COMMAND" or "NULLNAME" for each subroutine, de-
pending on wheter you want it to be visible or not (a library can have
'subroutines' (objects) that are not accessible to the user).
: 3. How does one get an existing library onto the stack (in a useable
: format for transfer to another HP48)?
A usable format for transfer is putting it on a variable, not on the stack.
: 4. What are the advantages of using a library?
Speed and neatness. (no messy directories to fool with)
: 5. Why is there so little documentation on libraries?
Because there isn't very much to be said about them.
: I have figured out how to ATTACH, DETACH, PURGE libraries from the
: postings on this user group, but that's all so far. I hope this posting is
: appropriate and apologize if it isn't.
That's all there is to it if you are going to *use* libraries.
If you want to *write* one, it's another story.
----------------------------------------------------------------------------
| Alex Ramos | Fala-se Portugues, tche!
ra...@engr.latech.edu | Electrical Engineering | Se habla Espanol, mui mal.
| LA Tech Univ. | English spoken here, barely
----------------------------------------------------------------------------
Douglas R. Cannon
>I've checked the FAQ, I've checked the User Manuals, I went out and bought
>the Programmer's Reference Guide - but I still don't fully understand HP48
>Libraries. I've seen many postings asking for info, but few postings
>actually describing libraries in any detail. Perhaps, they should be
>described in FAQ.
Yep. It's being worked on...
>Anyway, I had someone put tetris on my calculator :-) and unfortunately I
>didn't watch how he did it. My questions:
>1. What exactly is a library (a particular area of memory containing a
> program, which is refenced by the library address?).
I will follow-up to this follow-up with a great article posted in January
by Charles Patton (from HP). This article is also available on the EduCalc
goodies disk #8. It may not answer all your questions about libaries, and
I would also refer you to the documentation for the USRLIB.EXE program
(also written by HP). I don't recommend using the USRLIB program, but
I highly recommend that you read the docs. They are very informative, and
available on goodies disk #1.
>2. How does one create a library?
Again, read the usrlib docs... but do all your library creating with
Detlef Mueller's <-LIB-> program (Goodies disk #8). It is a GREAT utility,
and the best I have seen.
>3. How does one get an existing library onto the stack (in a useable
> format for transfer to another HP48)?
>4. What are the advantages of using a library?
See below... I have attached a little doc that I created for my Diamonds game
when I realized many people around campus had no idea how to transfer and
install libraries.
>5. Why is there so little documentation on libraries?
It's around (on the goodies disks) but sometimes hard to come by.
Hope this helps!
-Doug Cannon
P.S. If you need a copy of diamonds, you can get one via anonymous ftp
at wuarchive.wustl.edu//systems/hp/hp48/comp.sources.hp48/diamonds.mf
Goodies disks at wuarchive.wustl.edu//systems/hp/hp48/EduCalc
P.P.S. if any of you gurus (or otherwise) finds errors in the doc below,
please let me know so that I can correct them. (Like if I lied about the
libraries, or something...)
-----------------------------------------------------------------------------
Miscelaneous Library Info:
-----------------------------------------------------------------------------
1- Why is Diamonds a Library?
2- How do I purge Diamonds from my HP48?
3- How do I transfer Diamonds to another HP48?
4- How do I install Diamonds if my memory is limited (i.e. anywhere from
< 1Kb to < 12Kb free when Diamonds has been transferred).
Answers:
-----------------------------
1- Why is Diamonds a Library?
This is a good question, especially if you don't own any RAM cards.
If you own an HP48S, or an HP48SX with no RAM cards, then having Diamonds
in library form is more of a pain than anything else. However, if you
own a RAM card, then you can store Diamonds on the card, and have the
card write-protected, and still execute Diamonds! This means that it
is impossible to have it accidentally erased from memory, yet you can
still use it.
Another advantage to using a library, is that it allows me to "hide" some
of the internal programs used in Diamonds. This way you only have access
to the "safe" programs, or the ones that were intended to be executed
directly.
----------------------------------------
2- How do I purge Diamonds from my HP48?
You can either read your manual about libraries, and the purging thereof,
or follow the simple steps below.
First of all, if you have not ATTACHed Diamonds to any sub-directory, then
it is only attached to your HOME directory. Diamonds attaches itself to
your HOME directory. You can not use a library unless it is ATTACHed
somewhere. You can not purge a library unless it is DETACHed from every
place that it was ATTACHed. Diamonds should only be ATTACHed to the HOME
directory.
Do the following:
HOME ; to get to your HOME directory
860 DETACH ; to detach library # 860 (Diamonds) from the HOME directory
:0: 860 PURGE ; to purge the library # 860 from port # 0
If you own a RAM card, then you will need to say
:1: 860 PURGE ; if Diamonds is on a RAM card plugged into port 1
:2: 860 PURGE ; if Diamonds is on a RAM card plugged into port 2
Port #0 is the port number assigned to the 32Kb of built-in RAM.
----------------------------------------------
3- How do I transfer Diamonds to another HP48?
Normally, a library object that is stored in a port can not be transmitted
through the serial port (IR or wire). However, there is some software
available that will allow you to do this. Brian Maguire wrote a program
called PSND which will send an object from a port. It is a great program,
and works well (only 156 bytes!). You can find it on the EduCalc goodies
disk #7.
If you would prefer a manual method, (or don't have access to PSND), then
the following will also work:
First, you need to make a copy of the library and store it in your VAR menu.
:0:860 RCL (to recall the lib to the stack)
'D.LIB' STO (to store it in the current directory)
(see below if you don't have enough RAM for this step)
Now you can send it like any normal object:
'D.LIB' SEND
Remember, if the Diamonds library is stored in a port other than 0, then
use 1 or 2 for the correct port number. Also, be sure to set up your
'IOPAR' variable (using the I/O setup menu) so that it looks like this:
IR/wire: IR
ASCII/binary: binary
baud: 9600
parity: none 0
checksum type: 3 (doesn't matter for binary transfers)
translate code:1 (doesn't matter for binary transfers)
Set up the receiving HP48 identically, and press 'RECV', then run the
little sending program above.
If you don't have enough RAM for this manual method, then you need to get
a copy of PSND. This is a similar problem to when you are trying to install
the lib. You must have two copies of it present at once, and if you don't
have 24Kb, then you just can't do it (to my knowledge) without PSND.
PSND eliminates the need to have two copies.
------------------------------------------------------------------------
4- How do I install Diamonds if my memory is limited (i.e. anywhere from
< 1Kb to < 12Kb free when Diamonds has been transferred).
First of all, Diamonds 1.2 is 11.8 Kbytes, so if you don't have at least
12Kb free before you install Diamonds, then it is impossible. You will
have to free up enough RAM first.
If you just barely have 12Kb RAM free (or anything less than 24Kb) then
you will notice that after you transfer Diamonds to your HP, you can't
store it in port 0. (I am assuming that if you don't have much free RAM,
then you don't have a RAM card either.)
The problem is, once you transfered Diamonds, the transfer software created
a copy of Diamonds in your current directory. When you recall this to
the stack and type 0 [STO] you are trying to store a second copy in RAM.
If you don't have an extra 12Kb lying around, then this is impossible.
Follow the steps below (very carefully!) to install Diamonds:
These steps assume that the Diamonds library is stored under the name,
'DIAM.LIB' in your current directory. If yours is stored under a
different name, then use that one instead in the steps.
- Recall the library to the stack normally. ('DIAM.LIB' RCL)
- Purge the variable from your current directory. The only copy of
Diamonds should now be on the stack (DON'T DROP IT!) Type:
'DIAM.LIB' PURGE to purge the variable.
- Now type 0 [STO] and you're done!
I have successfully completed the above proceedure when I had only 800
bytes RAM free. (Diamonds already existed as a variable in my HOME
directory). Theoretically this method should work regardless of how
much RAM you have free.
Douglas R. Cannon
in libraries. It is very informative.
From: char...@hpcvra.cv.hp.com (Charles Patton)
Newsgroups: comp.sys.hp48
Subject: Re: Library Trouble
Date: 18 Jan 93
Organization: Hewlett-Packard Co., Corvallis, OR, USA
Since it is difficult to understand remember syntax without semantics, and
since no one has ever (to my knowledge) made clear to the public at large (or
even to developers, for that matter) what was the _intended_ usage of the
attach/configure options are, it is not surprising that it all remains a
little mysterious. So, here goes..
** What is the ATTACH/DETACH stuff?
During the design of the RPL system in '83-'84, we envisioned that plug-ins
could, and would, serve several distinct functions and and have
correspondingly distinct needs.
One such function would be to provide a unified, customized, "application
environment" dedicated to a single purpose and providing both functionality
and "templates" in the ROM. A good example of this would be a spreadsheet
application with ready-made forms in ROM which could be customized with
minimal RAM usage (...think about what that entails!...) Such an application
would clearly require RAM resources dedicated to it, provide for customized
interpretation of keywords, commands, etc., and yet not interfere with other
such applications (even copies of itself!) From this idea we developed the
notion of a CONTEXT - a RAM/ROM pair consisting of a ROMPART and a RAMPART
linked together. From the usual user's point of view, this is simply a
subdirectory, but from a library's ( a.k.a ROMPART's ) point of view, the
subdirectory is to be considered an extension of the library, and could
contain data and other RAM resources necessary to the operation of the
application.
In this kind of "application environment" the user would not "run a program"
but rather change to the relevant context (subdirectory) where all operations
would be interpreted according to the information in that context, without
conflicting with other "application environments" assignments or resources. I
know of no such "application environments" currently extant for the '48,
although all the tools necessary to make them are around.
The ATTACH keyword keyword joins a subdirectory (RAMPART) with a library
(ROMPART) to create such an interpretation context, but if the resources are
not used by the library, the advantages (other than avoiding conflicts) are
rather small. Since the subdirectory "belongs" to the library after
attachment, the attachement is not broken until the system is specifically
directed to do so (hence the DETACH keyword.)
Obviously, it would be advantageous to allow for a single library to "own" any
number of subdirectories, say one for each spreadsheet, document, or whatever.
On the other hand, it would defeat the idea of conflict-avoidance to have
multiple libraries own (and hence be required to share) a given sub-directory.
Thus only one library can be attached to a given sub-directory.....except the
"HOME" directory (a.k.a. SYS RAMROM PAIR)....
Which brings me to a second function envisioned for libraries: localization
and its relatives. We anticipated the need to produced multi-lingual versions
of the machine as well as providing for system-wide re-definition of
high-level aspects of the machine. In order to be able to be re-defined
on-the-fly, these aspects of the machine (Hash tables for converting text to
and from commands, and Message tables for defining standarized messages) must,
at the very least, have "hooks" in RAM.
These "hooks" for Hash and Message tables are provided in the ROMPART of the
HOME directory. Unlike subdirectories, the HOME directory can have multiple
libraries "attached" (although "attached" here cannot have same expectation of
exclusive ownership) and with each library attachment, a slot for the
library's Hash and Message table is allocated and filled, by default, with the
library's own Hash and Message tables. These, however, can be overwritten with
alternative versions at a later time.
A moment's thought will reveal to you that if you plug in two libraries, one
to localize the machine to, say, Finnish, and the other to localize it to
Spanish, at most one of these libraries can succeed. They are obliged to
"compete" over the fixed resources, and this competition normally occurs at
warmstart, when a complete inventory of libraries is taken, the HOME ROMPART
is cleared and re-created anew, and each library is asked, in turn, if there
is anything it would like to do.
Another kind of library we expected was a system extension attempting to be as
much like the system (including providing for localization, etc.) as possible.
They would attach themselves to the HOME directory and do little else, simply
extending or revising the keyword set. Such libraries have the greatest
potential for conflicts and unexpected side-effects, since the system is
tightly integrated and consistency needs to be maintained, but there is no
mechanism for negotiation at the time of the configuration poll.
A final kind of library we expect was the "run-of-the-mill" kind with a few
utilities on board, but nothing fancy. Note that it is not necessary to have a
library attached either to the HOME directory or to any sub-directory for the
purposes of finding, executing, or displaying any word in any library found
during the last inventory of libraries. The only aspect of normal library
operation which requires an attachment is the process of automatically
associating a library object with a typed-in name (so-called "compilation".)
This process, however, is modulated by things other than library attachment.
In particular, any object in the current directory with takes precedence over
any library object of the same name, no matter where attached.
We expected these run-of-the-mill libraries, then, to take routes, other than
attachement, to providing access to their utilities, routes which have fewer
potential conflicts. One such method would be to let the user attach the
library as desired. Another method would be for the library, in response to
the configuration poll, to create suitably named variables in RAM, each
variable consisting of a "rom-pointer" to one of the library words.
In summary...
We expected that application-environment libraries would take this opportunity
to check that there was at least one of its environments around, and if not,
to create one... AND THAT'S ALL!!
We expected that localization libraries would redefine the relevant Hash and
Message tables, with the "winner" of any competition being determined by the
order in which they are polled as to their preferences.
We expected system-extension libraries, carefully designed and few in number,
to attach themselves to the HOME directory in the same manner as the main
system libraries, thus allowing localization of these system extensions.
We expected the bulk of the libraries to not attach themselves anywhere at
all, but either allow the user to attach as desired, or create RAM-based
access to their contents, or follow some other convention which didn't require
attachment.
What has occurred, however, is that the bulk of the libraries, following the
system library examples, and having little other guidance from our end of the
street, have chosen to attach themselves automatically to the HOME directory
insuring a maximum of confusion and conflicts.
**What's the difference between attaching and configuring?
As noted above, the system takes an inventory of libraries in the machine at
various times (such as, whenever the machine is turned on.) Because we need to
keep close track of various aspects of the libraries, including their
location, only libraries in the controlled-access area of the ports (port0,
port1, and port2) are inventoried. For this reason, you must store a library
in one of the ports in order to have its existence recognized by the machine.
All libraries which have been found at the last inventory are polled when the
machine is being re-configured. This happens, for example, whenever a new
library is found, or an old one is found missing, during the inventory. This
poll allows the libraries to configure themselves, as described above. During
this time they may, or may not, attach themselves to a directory or
subdirectory.
*******************************************************
** Charles M. Patton **
** **
** char...@cv.hp.com **
** the usual disclaimers apply **
*******************************************************