New LEAP Facilities

1. DATUM is now slightly more flexible and will now take itemvar
   assignment expressions as arguments. The type will be determined
   from the type of the leftmost itemvar in the assignment.
   For example:

	STRING ITEMVAR S;
		ITEMVAR Z;

	DATUM (S ←Z ← COP (A⊗B)) ← "1";
	
   will believe that the item returned from COP(A⊗B) is a string item
   and will assign to its datum the string "1". Note that no conversion
   of datum-type is actually done and that if the item if not really
   a string item, disastrous unpredictable things may happen.

2. A procedure has been written that will produce symbolic listings
   of the allocated items, their datums, and the associations which
   currently exist. To use this procedure include the following 
   declarations in your program:

	REQUIRE "LP4MAT.REL[LEP,JRL]" LOAD_MODULE;
	EXTERNAL PROCEDURE LP4MAT;

   You may call this procedure by simply executing the statement:

	LP4MAT;

   The first thing the procedure does is to type the message:

	OUTPUT FILENAME?

   If you respond by typing the letters "T", "T", "Y", (note they must
   be upper case) followed by a carriage return, the listing will be
   typed on your console, otherwise your response will be interpreted
   as a disk filename and the output will be directed to that file.
   Note that LP4MAT will do a ENTER on this file and will close
   the file before exiting so this file should not be used for any
   other purpose.

   LP4MAT will print the pname (or a string like "CVI(item#)", if the
   item has no pname) followed by the DATUM type and the value of
   the DATUM. Then all associations will be printed in a symbolic format.
   It will then do the same for the GLOBAL model (hand-eye system) if
   the GLOBAL model exists.

3. A procedure has been written which will dump the current LEAP
   data structure to a binary device (disk, mag tape) in a format
   which may later be read in by the procedure described below in (4).
   To use this procedure include the following declarations in your
   program.

	REQUIRE "LPDUMP.REL[LEP,JRL]" LOAD_MODULE;
	EXTERNAL PROCEDURE LPDUMP(STRING FNAME;DEVICE;INTEGER WORLDS;
		BOOLEAN PROCEDURE FILTER);

   The parameters are the filename, the device (DSK etc), an integer
   which is a code which says which parts of LEAP are to be dumped
   (local model, global model, or both); and a filter which screens
   out undesired items;

   The WORLDS codes are:
	
	1 - DUMP local model only.
        2 - DUMP global model only.
        3 - DUMP both models.

   The filter is a user written BOOLEAN PROCEDURE which has a single
   REFERENCE itemvar parameter. LPDUMP will apply the filter to
   every possible item and will dump only those items which cause the
   filter to return the value TRUE. Items which do not pass the filter
   will not be output as elements of set or list datums, and any 
   association which contains an item which does not pass the filter
   will not be output. 

   For example say we wanted to dump only those items which have
   not been deleted (normally we dump even those items which have
   been deleted to aid in debugging programs which do not erase
   all the associations involving an item which is deleted).
   A filter we could use to screen out deleted items is:

	BOOLEAN PROCEDURE MYFILT(REFERENCE ITEMVAR X);
	BEGIN RETURN(TYPEIT(X)≠0);
	      COMMENT RECALL THAT TYPEIT OF AN UNALLOCATED ITEM,
		      OR A DELETED ITEM NOT YET REALLOCATED IS 0;
	END;
   The call to LPDUMP might then look like:
	
	LPDUMP("LEAPMD","DSK",1,MYFILT);

   For global model users, we may wish to dump the local model but
   not dump any associations or list datum elements which contain
   global items. A filter to do this is:

	BOOLEAN PROCEDURE NOGLOB(REFERNCE ITEMVAR X);
	BEGIN RETURN(TYPEIT(X)≠0 ∧ ¬IFGLOBAL(X));
	END;

   An error message is given if any bracketed triple is written which
   contains an item which does not pass the filter. To avoid this
   a more complicated filter may be given such as:

        RECURSIVE BOOLEAN PROCEDURE MYFILT2(REFERENCE ITEMVAR X);
	BEGIN IF (TYPEIT(X)=2) THEN
		BEGIN "BRACKETED TRIPLE"
		       ITEMVAR Q,R,S;
		       Q← FIRST(X);
		       R← SECOND(X);
		       S← THIRD(X);
		       RETURN(MYFILT2(Q)∧MYFILT2(R)∧MYFILT2(S));
		END ELSE RETURN(TYPEIT(X)≠0));
	END;

	RECURSIVE BOOLEAN PROCEDURE NOGLOB2(REFERENCE ITEMVAR X);
	BEGIN INTEGER I;
	      ITEMVAR Q,R,S;
	      IF IFGLOBAL(X)∨TYPEIT(X)=0 THEN RETURN(FALSE)
		ELSE IF I = 2 THEN
			BEGIN "BRACKETED TRIPLE"
				Q←FIRST(X);
				R←SECOND(Y);
				S←THIRD(Z);
			 	RETURN(NOGLOB2(Q)∧NOGLOB2(R)∧NOGLOB2(S));
			END ELSE RETURN(TRUE);
	END;

   As the use of bracketed triples is relatively rare, the user can
   normally use just the non-recursive filters above.
4. The procedure which may be used to recover the LEAP data
   structures dumped by LPDUMP is called LPREAD. The user
   should include the following declarations within programs
   using LPREAD.

	REQUIRE "LPREAD.REL[LEP,JRL]" LOAD_MODULE;
	EXTERNAL PROCEDURE LPREAD(STRING FNAME,DEVICE; INTEGER MODE);

   The parameters are the filename and binary device name,(the same
   as when LPDUMP was executed) and a mode to determine how the
   items which are read in should be treated.

   The MODE codes are:

	1 - all items read in are considered to be different than any
	    items declared or allocated within the calling program.
	    If an inputed item has a pname which is not in use by
	    any already existing item, it receives that pname. Otherwise
	    the inputed item will have no pname.

	2 - items read in are considered to be the same as items already
	    existing if the pnames are the same, otherwise the items
	    read in are considered to be different. The datums read in
	    will replace the datum of the previously existing item.

	3 - The same as 2 except the datum of the existing item is retained.

5. As the above new procedures depend greatly on pnames, it is probably 
   worthwhile to refresh our memories as to how pnames work.

   A pname (or printname) is a non-null string which has been associated
   with a given item. No two items may have the same pname and any item
   may have at most one pname. Pnames are associated with items in two
   ways:
	1. Inclusion of a REQUIRE n PNAMES statement gives all declared
	   items following that statement their identifiers as pnames.
	   For example:

		ITEM X;
		REQUIRE 100 PNAMES;
		ITEM Y;

	   would give the item Y the pname "Y" but give no pname to the item
	   X as its declaration precedes the REQUIRE statement.
	   The "n" in the REQUIRE statement is an estimate of how many
	   printnames may be needed at a single time. The better your
	   estimate, the less storage overhead will be involved, but if your
	   estimate is less that 50 it will be treated as if it were 50.
	   Note that "n" must be positive.

	2. The built-in procedure NEW_PNAME will associate printnames with
	   items at runtime.
		
		NEW_PNAME(X,"X");

	   will associate the pname "X" with the item X. If the item already
	   has a pname a warning will be issued. This is the only way that
	   items allocated by NEW can receive pnames.

   To delete the pname of an item we simply execute the procedure DEL_PNAME.

	DEL_PNAME(X);

   would delete the pname (if any) of the item X. A DEL_PNAME is
   automatically done when an item is deleted.

   To find the item with a given pname we execute the itemvar function CVSI.

	itmvr ← CVSI("X",FLAG);

   The first parameter to CVSI is the pname being looked for, and the second
   is a BOOLEAN variable. This variable is set to FALSE if an item exists
   with the pname and to TRUE if no such pname exists. If the FLAG is TRUE
   the value returned is garbage and should not be used.

   To find the pname of a given item we execute the string function CVIS.
	
	stvar ← CVIS(itmvr,FLAG);

   The first parameter is the item whose pname we desire and the second
   is again a BOOLEAN variable which will be set to TRUE if no pname for that
   item exists and FALSE if one did exist.

LEAP BREAKPOINTS


	LEAP breakpoints are a much neglected feature which enable
the user to monitor all MAKEs and ERASEs. A LEAP breakpoint is a
procedure which is called whenever a MAKE or ERASE is executed and
which is given the three items which are involved in the association
as its parameters.

	For example, say we wished to monitor all MAKEs and ERASEs involving
items contained in the SET named TRACE_SET and print out the three
elements of the association involved in the MAKE or ERASE.
We could write the following two procedures to be used as breakpoints.

	PROCEDURE MAKE_TRACE(ITEMVAR A,O,V);
	BEGIN INTEGER FLAG;
	      IF A ε TRACE_SET ∨ O ε TRACE_SET ∨ V ε TRACE_SET THEN
			OUTSTR('15&'12&"MAKE:"&CVIS(A,FLAG)&" ⊗ " &
				CVIS(O,FLAG)& " ≡ " CVIS(V,FLAG));
	END;

	PROCEDURE ERASE_TRACE(ITEMVAR A,0,V);
	BEGIN INTEGER FLAG;
	      IF A ε TRACE_SET ∨ O ε TRACE_SET ∨ V ε TRACE_SET THEN
			OUTSTR('15&'12&"ERASE:"&CVIS(A,FLAG)&" ⊗ " &
				CVIS(O,FLAG)& " ≡ " CVIS(V,FLAG));
	END;

To tell the LEAP runtime system that we wanted these procedures to be
called when MAKEs and ERASEs were executed we would execute the
following statements:


	BRKMAK(MAKE_TRACE); "SET UP MAKE BREAK_POINT"
	BRKERS(ERASE_TRACE); "SET UP ERASE BREAK_POINT"

Note that if there were already breakpoint procedures set up the
above statements would  destroy all memory that they were once breakpoints
That is, there is not a stack of breakpoint routines.

To tell the LEAP runtimes that we no longer want the breakpoint procedures
executed on MAKEs and ERASEs we would execute the procedure:

	BRKOFF; "Remove MAKE and ERASE breakpoints if any"

NOTE: BRKOFF,BRKMAK,BRKERS are not predeclared, therefore the user must
include the following declarations:

	EXTERNAL PROCEDURE BRKMAK(PROCEDURE P);
	EXTERNAL PROCEDURE BRKERS(PROCEDURE P);
	EXTERNAL PROCEDURE BRKOFF;
Any procedure may be used as a breakpoint procedure as long as it
only has three VALUE itemvar parameters.

Also note that the procedure is executed before the MAKE or ERASE is 
executed. If an ERASE which will erase several associations: such as

	ERASE ANY⊗X≡Y;

is executed, the ERASE breakpoint procedure will be called with the
three item components of each association to be erased.


We envision that breakpoint procedures will become important with
the coming of events. That is, a user may wish to cause an event
whenever an association satisfying certain criteria is made.

Any suggestions as to how the breakpoint facility may be improved
will be appreciated.