Date: Tuesday, November 22, 1994
From: ftg0673@tamsun.tamu.edu
  Re: LIB->DIR & DIR->LIB                                                  

--> S/SX/G/GX

[Note: Pro-Hackit is kinda obsolete now that its functionality is
incorporated into the HACK library.  But here it is anyhow, for the
HP48 Hacker Historians out there.  Complete documentation for HACKIT
can be found on GD9; the following is Rick's comments about the new
DIR->L and LIB->D commands.  -jkh-]

Now look... here's the deal.  LIB->DIR was my first stab at an assembly
language version and it is beta.  There are 2 known bugs; the first of
which was easy to find, the second was reported by at least a couple of
testers, but I have not been able to isolate the damn thing even after
an extensive search.


		Bug #1: XLIBs in the configuration routine
		are not convertered to GLOBAL IDENTITIES.

		BUG #2: XLIBs from other libraries may in
		fact cause problems during the conversion
		process.  The results are not known since
		I've never been able to reproduce the bug.


The bottom line is LIB->DIR is fairly safe, but I'll surely reconstruct
it at least once or twice before declaring it no longer beta.  There's
also an additional feature which might require attention, and has to do
with an enhancement made to DIR->LIB that will be explained next.

DIR->LIB has no known bugs, and is my second full blown rewrite of this
assembly language version.  Essentially it is USRLIB.EXE for the 48 in
as far as its functionality is concerned, so the USRLIB.EXE docs should
provide an excellent reference for DIR->LIB.  An additional feature is
included in this version, and which I reluctantly mention.  A directive
was added to allow the user to hide XLIB names without destroying them
in the conversion process.  For clarity I changed the functionality for
a pre-existing directive.  The result of this action served to confuse
those users already familiar with USRLIB.EXE, and consequently it later
was restored to its original functionality.  Now the new directive has
exchanged places with the old, and is named $NULL.  Although the change
was not made in LIB->DIR since it's scheduled for reconstruction in the
near future.  Here's the header file from the DIR->LIB source module to
explain the functionality:


	TITLE Directory-to-Library Conversion, Version 3.0
** begin DIR->LIB ***********************************************
*****************************************************************
**
** NAME: DIR->LIB
**
** ENTRY: rrp
**
** EXIT: library
**
** ABSTRACT: Converts a directory to a library data structure.
**
** MODULE HISTORY:
**
** Written			09/18/93	Rick Grevelle
** Reconstructed		10/25/93	Rick Grevelle
** First speedup		11/14/93	Rick Grevelle
**
** DETAIL:
**
** 5 distinct loops are utilized in this conversion process, one
** of which is a multi-pass loop that may make additional sweeps
**
** Most of the required work occurs prior to the final pass that
** is responsible for the actual directory-to-library conversion
**
** The duties performed by each of these loops are the following
**
** 1) SUM_TBL computes the amount of memory to allocate in order
**    to support the master HASH table used to build the library
**
** 2) STATUS! determines the status of each non-null IDNT within
**    the source directory in the following hierarchical fashion
**
**    a) $OMIT    - IDNTs in this list will be excluded
**
**    b) $HIDDEN  - IDNTs in this list lose thier names
**
**    c) $NULL    - IDNTs in this list keep thier names
**		    but do not appear in the menu pages
**
**    d) $VISIBLE - IDNTs in this list keep thier names
**		    and generate menu labels in library
**
** 3) NUMBER! assigns the XLIB number each IDNT will have in the
**    result library in the reverse order of the above hierarchy
**
** 4) SUM_RRP computes the amount of memory to allocate in order
**    to support the various components in the resulting library
**
** 5) SET_LIB performs all the mundane library conversion chores
**
**
**		    Example Directory Structure
**		    ###########################
**
**
**  A(0)----B(0)----DIR1----C(0)----D(0)----DIR2----E(0)----F(0)
**		     |			     |
**	 	     |			     |
**  A(1)----B(1)----DIR3----DIR4    A(2)----B(2)----DIR5----DIR6
**		     |	     |			     |	     |
**		     |	     |			     |	     |
**	   A(3)----B(3)	     |		   A(5)----B(5)	     |
**			     |				     |
**			     |				     |
**		   A(4)----B(4)			   A(6)----B(6)
**
**
**		    Example HASH TABLE Structure
**		    ############################
**
**		   02A4E			prolog
**		   lllll			length
**		   s*xxx			F(0)
**		   s*xxx			E(0)
**	    ------>ppppp ----->			A(0) offset
**	   |    -->ppppp -->  |			A(2) offset
**	   |   |   s*xxx   |  |			B(6)
**	   |   |   s*xxx   |  |			A(6)
**	   |   <-- bbbbb   |  |			END6 offset
**	   |    -->ppppp -->  |			A(2) offset
**	   |   |   s*xxx   |  |			B(5)
**	   |   |   s*xxx   |  |			A(5)
**	   |   <-- bbbbb   |  |			END5 offset
**	   |	   s*xxx   |  |			B(2)
**	   |	   s*xxx<--   |			A(2)
**	   <------ bbbbb      |			END2 offset
**		   s*xxx      |			D(0)
**		   s*xxx      |			C(0)
**	    ------>ppppp ----->			A(0) offset
**	   |    -->ppppp -->  |			A(1) offset
**	   |   |   s*xxx   |  |			B(4)
**	   |   |   s*xxx   |  |			A(4)
**	   |   <-- bbbbb   |  |			END4 offset
**	   |    -->ppppp -->  |			A(1) offset
**	   |   |   s*xxx   |  |			B(3)
**	   |   |   s*xxx   |  |			A(3)
**	   |   <-- bbbbb   |  |			END3 offset
**	   |	   s*xxx   |  |			B(1)
**	   |	   s*xxx<--   |			A(1)
**	   <------ bbbbb      |			END1 offset
**	  	   s*xxx      |			B(0)
**		   s*xxx<-----			A(0)
**		   00000			(00) offset
**		   11111			(01) offset
**		   22222			(02) offset
**		   33333			(03) offset
**		   44444			(04) offset
**		   55555			(05) offset
**		   66666			(06) offset
**		   77777			(07) offset
**		   88888			(08) offset
**		   99999			(09) offset
**		   AAAAA			(10) offset
**		   BBBBB			(11) offset
**		   CCCCC			(12) offset
**		   DDDDD			(13) offset
**		   EEEEE			(14) offset
**		   FFFFF			(15) offset
**		   nnnnn			$TITLE
**		   hhh**			$ROMID
**		   nnnnn			$CONFIG
**		   nnnnn			LINK table
**		   nnnnn			$MESSAGE
**		   nnnnn			HASH table
**		   **
**
**
**			    LEGEND
**			    ######
**
**	     bbbbb = back pointer for end of directory
**
**	     nnnnn = hexadecimal value or nibble count
**
**	     ppppp = forward offset that points to the
**                   1st variable up 1 directory level
**
**	     hhh   = hexadecimal ROMID (must be < 7FF)
**
**	     s     = status (i.e. $HIDDEN, $NULL, etc)
**
**	     *     = unused nibble
**
**
*****************************************************************
*****************************************************************


One final caveat; DIR->LIB and LIB->DIR allocate memory from within the
code objects.  This is a big fat no-no if the program is run in TEMPOB
and could result in problems.  While this can be easily fixed, it's yet
to be done due to time constraints.  Surely this will be taken care of
when LIB->DIR is reconstructed.

DIR->LIB and LIB->DIR can be found on the last menu page of the library
that follows.  Additionally the library contains a small collection of
previously released hacking tools.  This library is machine independent
with the exception of port 2 in the 48GX due to the TEMPOB caveat just
described.

Rick Grevelle
ftg0673@tamsun.tamu.edu