From: charliep@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                                 **
**                                                   **
** charliep@cv.hp.com                                **
**      the usual disclaimers apply                  **
*******************************************************