Turbo Toolbox/Turbo_Toolbox.iso/sharew/exoten/rec/rec6.hlp

Text File | 1990-10-26 | 11.0 KB | 278 lines

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]