Chapter 6, Part I.  Operation of REC.
Chapter 6, Part II.  User-supplied Extensions
:		Ch. 6, Part I.  Operation of REC.


	The execution of REC for running programs interactively is initiated 
by a command line which simply contains the name of the desired REC compiler 
(which may be REC80, REC80, REC80F, REC86F or REC87, depending on the 
processor used and whether floating point arithmetic is desired).  If a 
command line containing only, say, REC80F is given to CP/M, execution begins 
with the following message displayed on the console (REC80 produces a similar 
display):

			REC(8080)/ICUAP
		 Universidad Autonoma de Puebla
			    [date]

		 CPL ccccc
		 PDL ppppp
		 WS  wwww
		 Stk ssss

		 REC80F>


	ICUAP means "Institute of Sciences of the Autonomous University of 
Puebla", [date] is the date of the REC version being executed, ccccc, ppppp, 
wwww and ssss are decimal numbers indicating the sizes in bytes of the areas 
available for compilation, pushdown list, workspace and machine stack, 
respectively.  (When REC86 or REC86F are executed, additional data in 
hexadecimal is displayed giving the segment base and length for each of the 
four memory segments used by these compilers.)

	"REC80F>" in the above example is the prompt indicating that REC is 
ready to read and execute a program.  The program may be entered in one or 
more lines terminated by carriage returns (ASCII CR); REC starts execution of 
the compiled program as soon as it recognizes the final right parenthesis or 
brace.  When entering programs in this manner, care has to be taken to ensure 
that all parentheses, braces, brackets and quotation marks (single and double 
quotes) are correctly balanced; this is why the interactive execution of REC 
is only recommended for testing simple programs or program fragments.







	As stated in Chapter 3, the execution of REC may also include 
additional data on the command line, in which case REC takes the first 
paramater on the command line tail to be the name of a file containing the 
program whose compilation and execution is desired; the given name should 
not contain an explicit extension, because the extension REC is always 
assumed; the command line

		REC80 EXAMPLE

causes REC to compile and execute EXAMPLE.REC.  When REC is executed in this 
manner, no display occurs on the console other than what the compiled REC 
program itself produces; when this program's execution ends, REC returns 
control of the computer to operating system.  If the file named on the 
command line does not exist, REC returns to the operating system with no 
further indication of the error.

	Under MS-DOS, the filename is searched in the current directory, and 
if not found, in each directory listed in the PATH environment variable, 
provided it has been given a value.  If not found anywhere, REC will display 
the last pathname whose opening was attempted.

:		Ch. 6, Part II.  User-supplied Extensions.

	One letter of the ASCII alphabet, X, has been set aside to provide 
access to user-defined operators (other than those defined as subroutines in 
REC).  The compilation of X requires that it be followed by a character that 
becomes a part of the calling sequence generated by the compiler (in the 
style of @x); this character is analyzed by the run-time subroutine provided 
by the user to identify the particular operator whose execution is desired.  
Specifically, Xa is compiled as an operator, with the following calling 
sequence:

		CALL	LIBO
		DB	'a'

	The user-written extension must contain the entry point LIBO (which 
in the case of REC80 and REC80F must appear in an ENTRY directive if an 
assembler like Microsoft's M80 is used), and this program must be relinked 
with the rest of the REC compiler (reassembled in case one uses ASM86 to 
assemble REC86 or REC86F). Further on an example is given of the basic code 
required for implementing operator X.



	The REC80 source program is divided into five modules:

	- REC80, which contains the compiling routines,
	- PDL80, which contains the PDL predicates and operators,
	- MKV80, which contains the workspace operators and predicates,
	- LIB80, which contains the definition for predicate x, and
	- FXT80, which contains tables, the CP/M interface and the initializing
		 routine; all other modules must precede this one in memory.

	Once M80 has assembled the above four modules, the executable module 
REC80.COM is produced by the command line

	L80 MKV80,PDL80,REC80,LIB80,FXT80/E,REC80/N

	REC80F consists of seven modules, to wit,

	- FLT80F, which contains binary-ASCII and ASCII-binary 
		  conversion routines,
	- ATH80F, which contains the arithmetic operators, and

REC80F, PDL80F, MKV80F, LIB80F and FXT80F, which contain functions similar
to the analogously named REC80 modules.

	Analogously to REC80, the assembled modules may be linked with L80 to 
create a REC80F executable module with the following command line, which 
generates the file REC80F.COM:

	L80 MKV80F,PDL80F,ATH80F,FLT80F,REC80F,LIB80F,FXT80F/E,REC80F/N

	Notice that FXT80F must again be the very last module.

	For the 8086 versions, REC86 and REC86F, we have used CP/M-86's 
assembler ASM86.  Even though the source programs for these compilers are 
kept in 5 and 7 separate modules, respectively, ASM86 assembles all modules 
together directed by an additional small module containing only INCLUDE 
directives.  Thus, to assemble REC86, ASM86 is requested to assemble a file 
REC86.A86, containing the following:

			CSEG
			INCLUDE PDL86.A86
			INCLUDE MKV86.A86
			INCLUDE REC86A.A86
			INCLUDE LIB86.A86
			INCLUDE FXT86.A86
			END

	The source module containing the compilation routines of REC is now 
called REC86A; this is done so that ASM86 will produce, from the assembly of 
the above small program, a file named REC86.H86, from which the executable 
module REC86.CMD can be generated by GENCMD, a utility program provided by 
CP/M-86.  The computer system on which REC86 was developed has 256kbytes of 
memory, of which 192k are contiguous and start at address 00000H and the 
remaining 64k start at address F0000H.  The command line we have used to 
generate REC86.CMD is the following:

GENCMD REC86 CODE[M1000] DATA[M1000] EXTRA[A0F000,M0FFF] STACK[M0C00]

which allocates 64k for the code segment (which includes the compiler 
itself), 64k for the data segment (including REC's PDL and the compilation, 
variable and subroutine tables), 64k for the extra segment (containing the 
workspace) and 48k for the 8086's machine stack.  The remaining 16k are used 
by CP/M-86.

	To end our description of the standard REC compilers, we note that 
the assembly of REC86F is similar to that of REC86, but in this case the 
small module whose assembly is requested to ASM86 is called REC86F.A86 and 
contains the following lines:


			CSEG
			INCLUDE PDL86F.A86
			INCLUDE MKV86F.A86
			INCLUDE ATH86F.A86
			INCLUDE FLT86F.A86
			INCLUDE REC86FA.A86
			INCLUDE LIB86F.A86
			INCLUDE FXT86F.A86
			END

	The generation of the executable module REC86F.CMD is accomplished by 
executing GENCMD with a command line entirely analogous to the one given for 
REC86.

	Generation of the MS-DOS REC compilers requires only two simple 
command lines:

			MASM REC8x
			LINK REC8x

where REC8x is REC86, REC86F or REC87; prompts by MASM and LINK are answered 
by pressing return.

	Suppose now that a user wants to add to REC80 the operators X0, X1, 
X2, X3 and X4, and that any other predicate of the form Xa should effect an 
immediate return.  The user would then provide a new module, say UOP80.MAC, 
which would contain the following program (in which the explicit processes 
represented by the five new operators are omitted): 

	ENTRY	LIBO	;Declare LIBO to be an entry point
;
LIBO:	POP	H	;Pick up the return addr (calling seq. pointer)
	MOV	A,M	;Copy the character from the calling sequence
	INX	H	;Get the actual return address 
	PUSH	H	;push it back on the stack
	CPI	'5'	;Is the char. less than or equal to ASCII 5?
	RNC		;exit if not
	SUI	'0'	;Is the char. greater than or equal to 0?
	RC		;exit if not
;
;	Notice that register A now contains a value between 0 and 4
;
	ADD	A	;Multiply A by 2,
	MOV	C,A	;pass on to C,
	MVI	B,0	;extend to 2 bytes with a zero in B.

	LXI	H,TAB	;The origin in the table of addresses
;			;of subroutines X0 to X4
	DAD	B	;added to BC gives the address in the table
;			;of the desired subroutine's entry address
	MOV	E,M	;which we copy to DE
	INX	H
	MOV	D,M
	XCHG		;pass on to HL
	PCHL		;and we jump to it.
;
TAB:	DW	ZERO	;ZERO is the address of the subroutine for X0
	DW	ONE	;ONE is X1's entry point
	DW	TWO	; and so forth
	DW	THREE
	DW	FOUR
;
ZERO:	...		;Here we insert the instructions which carry
;			;out the function associated with X0,
;
ONE:	...		;In a similar manner for X1,
;
TWO:	...		;X2,

;
THREE:	...		;X3
;
FOUR:	...		;and X4.
;
	END

	This module is assembled with M80 and linked to make an executable 
module as follows:

	L80 UOP80,MKV80,PDL80,REC80,LIB80,FXT80/E,UREC80/N

where the new executable module's name is UREC80.COM.


	To close the chapter, let us mention the predicate xa, which provides 
a way to call predicates added to a REC program using operator C after its 
execution has begun.  xa operates in a manner similar to @a in the sense that 
it calls a predicate whose address is in a table indexed by the ASCII 
character a; the difference is that @ always refers to a fixed table, whereas 
the table referenced by x may be changed.


	x@ is a predicate which takes, like @@, an argument from the PDL; if 
it is a single byte, it is assumed to be an ASCII character to be used as an 
index to the current table (for instance, '$'x@ has the same effect as x$).  
However, if the PDL argument is a two-byte value, it must be the address of a 
new table (whose indices are the ASCII characters exclamation point (!) 
through tilde (~)), from which predicate x will take execution addresses in 
subsequent uses, and until a new table is given by a further execution of x@ 
with a two-byte argument.

	At the start of REC's execution, predicate x refers to the same table 
as @, so that xa and @a produce the same result.  Once the table referenced 
by x is changed, it is possible to reset it to the initial state by the use 
of '!'$x@, since '!'$ places on the PDL the address of the portion of the 
table of subroutines (called by @) starting at character "!".  Note that the 
mechanism whereby braces ({ and }, see Chapter 1) deactivate external 
definitions to activate internal ones only affects the table used by @ and 
not that referenced by x, if the latter table is different from the former.

	This predicate has been used in the CONVERT compiler to effect 
automatic inclusion of programs from a library when execution of a Convert 
program is begun.

:[REC5-6.HLP]
[(c) G. Cisneros, 1985, 1990]
